Automating Informix Startup: the dbstart.informix.sh Script

Not having a global configuration file makes a lot of things more difficult, one of them being backups.  When writing a shell script to back up all Informix instances on a given machine, how do you know what instances to back up?  You can't ask Informix, which definitely does not know about the other instances.  I would like to suggest a different method of starting Informix that would also make backups easier.  Let's start with the basics.

In order for an Informix database to be started up after a system reboot, a startup script must be placed somewhere in /etc.  Startup scripts are run by root, and therefore should be owned by root and placed in a directory that root controls.  A startup script in /etc should not be calling a startup script in informix's home directory.  However, this creates an extra task for both the SAs and DBAs.  The DBA must find a SA every time he wants to add a new instance to the startup script.  The SAs would rather not have to do this, but they don't want root running shell scripts found in informix's home directory.  The SAs are also normally in charge of backups, and this is one way to find out that there is a new instance to back up.

How does Oracle accomplish this task?  It's as simple as the oratab file. The start-up scripts are in a directory owned by root, and the oratab file is in a directory owned by the oracle ID.  The start-up script starts up any instances in the oratab file that have a "Y" in the third field.  All a DBA needs to do to have a new instance started is add the instance to that the oratab file.  This also gives backup scripts a great place to start.  For example, the oraback.sh utility automatically backs up any instances that it finds in the oratab file.

Sure, it's possible for a DBA to create and start up a new instance that does not get put into the oratab file.  However, if the oratab file is being used to both start up and back up Oracle, DBAs will get into the habit of putting new instances there.  Otherwise, they will continually have to start the instances manually and the instances will also never get backed up.  

With a little practice, Informix DBAs can be shown to do the same thing that Oracle DBAs do with the oratab file…   I present the inftab file, an Informix version of Oracle’s oratab file.

The inftab File

#  This file is used by the startup, shutdown and backup scripts
#  Provided in "Unix Backup & Recovery," O'Reilly & Assoc., Inc.
#
#  Author: W. Curtis Preston
#
#  Use a colon, ':', as the field terminator
#  Lines that begin with a octothorpe, or pound sign, (#) are comments.
#
#  Entries should follow this form:
#      $ONCONFIG:$INFORMIXDIR:<N|Y>:
#
#  The first field is the Informix Server name
#  The second field is the INFORMIXDIR variable that the Informix server uses
#  A Y in the third field indicates if this instance should be started
#  automatically after a system reboot.
#  The fourth field is where logical logs will go.  If you want to go
#  to disk, put a directory name.  If you want to go to tape, put the
#  device file of the tape drive here.
#
#  Multiple lines with the same $ONCONFIG variable are not allowed.
#
crash:/informix:Y:/informix/logical

Figure 13-1: A sample inftab file

The dbstart.informix.sh script in Figure 13-2 acts very much like Oracle's dbstart script (see Chapter 14).  It starts by reading the inftab file to determine the names of all instances.  Then it either starts or stops each of the instances that have a Y specified in the third field.  It also calls rclogs.sh for each of those instances.  Rclogs.sh, discussed later, automatically starts continuous backups in the background.

#!/bin/sh
#

INFTAB=/informix/etc/inftab

Usage()
{
 echo "Usage: [dbshut|dbstart] [start|stop]"
 echo "\n(Either this script must be called with the name of dbshut or dbstart,"
 echo "or it must be called with a start or stop argument.)"
 echo "\nIf called by the name dbstart, or with the argment of 'start,'"
 echo "it will start all Informix instances listed in $INFTAB"
 echo "\nIf called by the name dbshut, or with the argument of 'stop,'"
 echo "it will STOP all Informix instances listed in $INFTAB."
}
 

#This script starts up all instance on this box specified in $INFTAB
#It is of the form:
#$ONCONFIG:$INFORMIXDIR:<Y|N>

SCRIPT=`basename $0`

if [ $SCRIPT != dbstart -a "$1" != start ] ; then
 if [ $SCRIPT != dbshut -a "$1" != stop ] ; then
  Usage
  exit
 fi
fi

WHO=`id | awk -F'(' '{print $2}' | awk -F')' '{print $1}' `

if [ "$WHO" = root ] ; then
  su informix -c $0 $*
  exit $?
fi

grep -v '^#' $INFTAB \
|while read LINE
do

 STARTUP=`echo $LINE|cut -d: -f3`
 TBCONFIG=`echo $LINE|cut -d: -f1`
 ONCONFIG=`echo $LINE|cut -d: -f1`
INFORMIXDIR=`echo $LINE|cut -d: -f2`
 #INFORMIXSERVER and ONCONFIG can be different, so get it from the onconfig file
 INFORMIXSERVER=`grep DBSERVERNAME $INFORMIXDIR/etc/$ONCONFIG|awk '{print $2}'`

 BINDIR=$INFORMIXDIR/local/bin
 PATH=$INFORMIXDIR/bin:$BINDIR:$PATH
 export TBCONFIG ONCONFIG INFORMIXSERVER INFORMIXDIR PATH BINDIR

 if [ `basename $0` = dbstart -o "$1" = start ] ; then
  if [ "$STARTUP" = "Y" ] ; then
   echo "Starting Informix Instance $ONCONFIG"
   oninit
   [ -f $BINDIR/rclogs.sh ] && rclogs.sh start
  else
   echo "NOT Starting Informix Instance $ONCONFIG.  (No 'Y' in $INFTAB.)"
  fi
 else
  echo "Stopping Informix Instance $ONCONFIG"
  [ -f $BINDIR/rclogs.sh ] && rclogs.sh stop
  onmode -ky
 fi

done
Figure 13-2: The dbstart.informix.sh script

An inftab file provides a single point for all global Informix activities.  The difficult part is getting in the habit of using one.  However, if all startup, backup, and monitoring scripts base their actions on the inftab file, it will get used soon enough.  The DBAs will be happy because they can change a single file that they own, and Informix will automatically start up, back up, and monitor a new instance.  The SAs will be happy because they won't have to worry about changing a root-owned shell script every time a new instance is created.

Installing the dbstart.informix.sh script

Install the files 

$ ln dbstart.informix.sh dbstart
$ ln dbstart.informix.sh dbstop

Copy inftab into a directory that the informix user ID can write to (e.g., $INFORMIXDIR/etc).  (They can be placed in the same directory as the other files, but do not need to be.)

If you plan to use rclogs.sh with dbstart.informix.sh, you need to read about it later in this chapter, and to configure it as well.

Edit the inftab file 

onconfig_file:$INFORMIXDIR:Y|N:log_destination
onconfig_file

The first field should be the relative name of the onconfig file for that instance (e.g., prod, not $INFORMIXDIR/etc/prod).

$INFORMIXDIR

The second field should contain the value for the $INFORMIXDIR variable for that instance.

Y|N

If you are also using dbstart.informix.sh, placing a Y in the third field causes dbstart to automatically start this instance after a reboot.  (Please note that the "Y" is case sensitive.)

Some DBAs prefer to start their Informix instances manually.  If you wish to use dbstart.informix.sh but do not want the instances to start automatically, simply set this field to "N."

log_destination

If you are using rclogs.sh, the fourth field should contain the value that you want to use for the archive log destination.  This can be a directory or device name.  (If it is a directory, make sure that it is writable by informix.)

Edit the dbstart.informix.sh script 

Change the startup files 

Automating Archives with ontape: the infback.sh Utility

Why automating ontape is difficult

LEVEL=0
ontape -s <<EOF >/tmp/logfile
$LEVEL

EOF
Figure 13-17: Calling ontape with a here document

Ontape now accepts the use of a –L level argument, but it still requires you to respond to a prompt after executing the command. Ontape can still give you difficulties if you use the above syntax.

The method shown in Figure 13-17 is often mentioned in FAQs and other books, but it does not work on every version of Informix.  The method that does always seem to work is shown in Figure 13-18:

LEVEL=0
echo "$LEVEL

"| ontape -s | head -100 > /tmp/logfile
Figure 13-18: A more reliable way to call ontape

There are two differences between the methods shown in Figures 13-17 and 13-18.  The first difference is the way in which the answers are passed to ontape; Method 2 seems to be a little more robust.  The second difference between the two methods is the addition of the head command in the second one.  The head command is not required, but is a good precaution in case the backup device becomes full. Here’s why: once ontape detects that the backup device is full, it prompts for a second tape.  It is not very easy to answer provide a second tape and answer this prompt without using a program such as expect .  (There is a way to answer prompts like this by redirecting stdin and stdout to named pipes, but that can be really tricky with ontape.  Ontape prompts repeatedly for the second tape and things get pretty ugly very quickly.)  The head command keeps this repeated prompting from happening, since it truncates the output to 100 lines, but once the 100 lines have been reached, ontape aborts.

How infback.sh works

infback.sh

This is the main backup program that looks at the configuration files to decide how and what to back up.

rclogs.sh

This program is another main program that automates continuous backups of the logical logs using ontape -c.

infback.conf

This file is used by infback.sh to specify how, when, and what to back up.

inftab

This file lists all Informix instances on a machine.  It is used by dbstart.informix.sh, rclogs.sh and infback.sh to determine what instances are on the machine.

localpath.sh, rempath.sh, config.guess

These files accompany these other programs, and assist them in determining what commands to run on various Unix platforms.

• Uses a global tabulation file (inftab) to list all Informix instances
• Uses a global configuration file (infback.conf) to configure backups
• Automatically performs full or incremental backups of all instances found in inftab
• Optionally performs full or incremental backups of any instances listed on the command line
• Can write archives  to disk or tape
• Sends email, notifying of the success or failure of the backup
• Backs up databases that reside on raw partitions or filesystems

With no arguments

With arguments specifying backup parameters

With at as the first argument, with or without backup parameter arguments

When infback.sh runs

If infback.sh determines that it is not supposed to skip the backup, it then needs to determine what instances to back up ($INSTANCE_LIST), what level backup to run ($LEVEL) and what device to use ($DEVICE).  How infback.sh does this depends on which arguments (if any) it receives.
If infback.sh is called with no arguments

If called with no arguments:

infback.sh looks at the third field in infback.conf to determine what level of backup to run.  That field specifies the full backup day.  If today is the full backup day, then it performs a level 0 archive.  If it is not today, it performs a level 1 archive.  Infback.sh then looks at fields six and seven of infback.conf to get the name of the device server and device that it should backup to.  Finally, it looks at inftab for a list of instances to back up.

If infback.sh is called with arguments specifying backup parameters

$ infback.sh level [device|host:device] [instancea instanceb ...]

it will determine its level and device from the arguments.  If it also receives a list of instances to backup, it will use that as the list of instances.  If not, it determines the list of instances to backup by listing each instance list in inftab.  The arguments and their possible values are as follows:

level

This should be a valid level for an Informix archive (0,1, or 2).

device | host:device

This should be a valid device name or directory name.  It can also be hostname:device (e.g., apollo:/dev/rmt/0cbn).

[instancea instanceb ...]

These arguments are optional.  You may specify one or more Informix instances to back up.  Specifying no instances causes infback.sh to backup all instances listed in inftab.

If infback.sh is called with “at” as the first argument

$ infback.sh at 

infback.sh sets the $TIME variable so that the backups take place at a specified time.  If it is a level 0  backup, infback.sh sets the $TIME variable to the value in field 4.  If it is a level 1 backup, it sets the $TIME variable to the value in field 5.  Infback.sh  then schedules an at job that will perform the backup at the time specified by $TIME. If there were other arguments given after the at argument, those arguments are passed to the scheduled run of infback.sh.  When the at job runs infback.sh, it will then determine what and how to backup based on the arguments (if any) that it was given.

The backup begins

If there is a value specified in infback.conf for $COMPRESS, infback.sh creates a named pipe called $INFORMIXDIR/$INSTANCE.level.$LEVEL.fifo, and changes TAPEDEV to that filename. It does this using onmonitor, so the change will be effective immediately.  After creating the named pipe and telling ontape to use it, it calls compress and tells it to read from the named pipe, compress the data, and write it to the location specified as the original device.  Infback.sh then calls either ontape or tbtape, depending on the version of Informix you are running , passing it the appropriate level.  It checks the status of the backup command and, if backing up to disk, compresses the backup file.

If there is no value specified for $COMPRESS, infback.sh sets TAPEDEV to $DEVICE_SERVER:$DEVICE_FILE using onmonitor.  It then calls ontape to perform the archive to the specified device.

Installing infback.sh and its configuration files

Copy infback.sh, localpath.sh, rempath.sh, and config.guess into the same directory  (e.g., $INFORMIXDIR/local/bin) and make sure that they are executable.   
Copy inftab and infback.conf into a directory that Informix can write to (e.g., $INFORMIXDIR/etc).  Infback.sh needs to be able to write to this directory for the "skip" feature to work.  Inftab and infback.conf can be placed in the same directory as the other files, but they do not need to be.

Editing the infback.sh configuration files

Editing infback.conf

hostname.master

Replace hostname with the base hostname.  For example, if the hostname is apollo.domain.com, this field should contain apollo.master.

full_day

This is the day of the week that full backups should run.  (All other days of the week will receive level 1 backups.)

full_time

If using the at argument, this is the time that the program should schedule level 0 backups.  Suppose that it says 1900, and the full backup day is Mon.  At 1500 on Monday, there is a cron job that runs infback.sh at.  That will see that Monday is a full backup day, and schedule an at job to run at 1900.

inc_time

If using the at argument, this is the time that the program should schedule level 1 backups.

device_server

Set this to the hostname of the server that contains the backup device.  If it is the same as this host, enter the base hostname only (just like in the first field).  For all other hosts, use the FQDN if it is appropriate.

archive_dest

This should be set to a device or directory that will contain all archives.  If it is a directory, make sure that it is writable by informix.  Also, if it is a directory, infback.sh will create a subdirectory for each instance inside this directory.

allow_ids

This is a '|' separated list of user ids that are allowed to run infback.sh.  This is usually only informix.

mail_ids

This is a comma-separated list of user IDs that should receive mail about the success of infback.sh

Editing infback.sh

DEBUG=

Set this to "Y" if you want to see debug information for all functions (i.e. turns on set -x).

BINDIR=

Set this to the directory where you copied the backup programs (e.g., $INFORMIXDIR/local/bin)

LOGDIR=

Set this to the directory where you want infback.sh to log its information (e.g., $INFORMIXDIR /log).

LOG=

Set this to the full path of the name of the logfile you want it to use (e.g., $LOGDIR/infback.log).

INFCONF=

Set this to the full path of infback.conf  (e.g., $INFORMIXDIR/etc/infback.conf).

INFORMIX=

Set this to the user that owns the informix instance (usually informix).

INFTAB=

Set this to the full path of inftab (e.g., $INFORMIXDIR/etc/inftab)

TMP=

Set this to the directory you want infback.sh to use for temporary files.

Preback

Anything that is put inside this function will be executed prior to running the backup.

Postback

Anything that is put inside this function will be executed when the backups are finished.

Centralized configuration

Scheduling backups

0 17 * * * /informix/local/bin/infback.sh at

This specifies to run the script with the at argument at 5 P.M.  This causes infback.sh to look at the infback.conf file to determine what level of backup to run, and what time to run it.  It will then schedule an at job for the appropriate time.

The reason for keeping the entry as late as possible is to allow the DBAs to make changes to infback.conf.  Since infback.sh does not look at the file until 5 P.M., they can change tonight's backup time or skip tonight's backups by changing the file any time before then.

Automating Continuous Backups: the rclogs.sh Utility

The next thing that rclogs.sh does is check to see if there are any ontape -c backups running for this instance.  If so, it stops them.  If rclogs.sh was called with the stop argument, it then exits.  If it was called with the start argument, it then needs to "swap tapes."  If backing up to disk, rclogs.sh moves the continuous backup file to a date/time-stamped file and creates an empty file for the next ontape -c session.  If backing up to tape, this program cannot be run from cron; it must be run manually from a terminalbecause once it stops the ontape -c session, it can only notify the operator running the program to swap the tape, and wait for notification that this has been done. Once rclogs.sh knows that the tape has been swapped, it will start a new ontape -c session in the background.  It then queries Informix to verify that continuous backups are running, and sends notification of success or failure.

Installing rclogs.sh and its configuration files

Editing rclogs.sh and its configuration files

Check the site-specific section at the top of rclogs.sh and make sure that all the values are appropriate for your environment.  The following values are found there:

DEBUG=

Set this to "Y" if you wish to see debug information (set -x).

INFTAB=

Set this to the full path of your inftab file.

COMPRESS=

Set this to the compression command that you wish to use (e.g., gzip).

COMPSUFF=

If you change the compression command from the default value of "compress," then you need to change this value.  It is the suffix that your compression command uses (e.g., use gz for gzip).

BINDIR=

Set this to the location of infback.sh and the other programs (e.g., $INFORMIXDIR/local/bin).

THRESHHOLD=

This should be set to a percentage between 50 and 100 if you are backing up to disk.  Once the filesystem specified by $ARCHIVEDEST is this full, it does some extra cleanup and notify you.

TMP=

Set this to the directory that you wish to use for temporary files.

INFORMIXDIR=

This can normally be left alone, since it is determined from inftab.

ONCONFIGFILE=

This can also normally be left alone, but if you have a unique location for your onconfig files, specify it here.

ARCHIVE_DEST=

This is also determined by looking at inftab.

INFORMIXSERVER=

This is automatically determined by looking at the onconfig file.

LOGDIR=

Set this to a directory that you want to use for logs (e.g., $INFORMIXDIR/logs).

LOG_FILE=

Set this to the name of the log file that you wish to use.

PATH=

You normally should not need to change this.

DBAS=

If you've already specified the use of infback.conf, the value of this field is determined from there.  If not, you can specify a list of mail IDs to mail to.  (Enclose them within quotes if there is more than one.)

Testing the rclogs.sh program

• With the stop argument to make sure that it stops the appropriate logs. 
• With the start argument to make sure it creates the file and starts the ontape -c process. 
• Multiple times with the start argument, and make sure that it stops and starts the appropriate logs.

Scheduling backups

00,30 * * * * /informix/local/bin/rclogs.sh start

Using the Scripts Together