Automating Backups: The oraback.sh Script

There is a program that performs cold and hot backups of Oracle, and it is currently being used by hundreds of companies around the world -- oraback.sh.  It is written in the Bourne shell, which is compatible with every Unix system.  By using GNU's config.guess script, the list of Unix platforms that it runs on is perhaps limitless.  The only thing that oraback.sh assumes is that the oratab file is properly configured; by default, oraback.sh automatically backs up every instance listed there.  Oraback.sh supports these features:

  • Backs up to disk or tape
  • Automatic detection of database configuration
  • Backs up databases on filesystems or raw partitions
  • Multitasking, which can reduce backup time by up to 75% 
  • Mail-based success and  error notification
Oraback.sh can back up from one or more of the instances in oratab.  To back up all instances, run it with no arguments:

$ oraback.sh

To back up one or more instances, run it with those ORACLE_SIDs as arguments:

$ oraback.sh ORACLE SID1 ORACLE SIDn

To schedule a backup for the time specified in oraback.conf (described later in this section), run it with the at argument:

$ oraback.sh at

You may also combine these arguments together:

$ oraback.sh at ORACLE SID1 ORACLE SIDn

to specify both a backup time and the instances to be backed up.

Installing oraback.sh

To install oraback.sh, first put oraback.sh, config.guess, and localpath.sh in one directory, then check the following values in the site-specific section at the top of the script.  They must be changed to fit the environment.
BINDIR
Should be set to where oraback.sh is installed.
ORATAB
Should be set to the name and location of Oracle's oratab file.
ORACONF 
Should be set to the name and location of the oraback.conf file. (It must be located in a directory that Oracle can write to.)
Review and confirm all other preference variables in the site-specific section, including ORADIR, TMP, LOG, and PATH.  Also verify:
  • Which instances are using archiving
  • Oracle can create directories in the filesystem that that is being used for backups (specified in the oratab file)

Configuring and customizing oraback.sh

Oraback.conf is the main configuration file for oraback.sh. A normal oraback.conf file contains a hostname.master line that specifies several options such as which users are authorized to perform the backup, what backup device should be used, and on what days/times and cold/hot backup should be performed.  If you specify oraback.sh with the at argument, it is the hostname.master line that oraback.sh uses to find the dates and times to run the backups. The hostname.master line is described below.

hostname.master:[skip]:Cold Day:Cold Time:Hot Time:[tape device]:users:Parallelism:Backup Dir:Y::user ids:

The above fields are described below:

Field 1: hostname.master
This system's hostname generated by uname -n or hostname, minus it’s domain name.  (e.g. apollo.domain.com becomes apollo.)
Field 2: [skip]
If you want all backups skipped on this host tonight, put skip here.
Field 3: Cold Day
The day on which oraback.sh should do cold backups.  This can be a day of the week (Fri) or month (03). If there is a blank in this field, cold backups will never be performed.
Field 4: Cold Time
The time of the day (using a 24-hour clock) to do cold backups.
Field 5: Hot Time
The time of the day (using a 24-hour clock) to do hot backups.
Field 6: [Tape Device]
No-rewind tape device, to back up to tape.  (Blank for disk-only backup.) 
Field 7: [Users]
A "|" separated list of user names permitted to run svrmgr and this script, such as oracle|dba (Blank allows only Oracle.) 
Field 8: [Parallelism]
The number of simultaneous data file copies to run.  (Blank=1.) 
Field 9: Backup dir
Must be set to a directory or filesystem that has enough room for a compressed copy of all database files.  If  backing up to tape, this doesn't need to be that much, but it still needs some space on disk. This is because it still uses this directory to back up the control files and redo logs.
Field 10:[Y]
A Y means to compress the files before they are written to tape or disk.
Field 11: mail ids
Set this to a comma-delimited list of mail ids to mail success or failure to (e.g., dba@herworkstation.com, root)
In addition, there are four predefined functions, unused by default, which are listed in the site-specific section of oraback.sh.  These are listed below, with their respective usage times:
Preback
The Preback  function runs before entire backup starts.
Preshut
The Preshut  function runs before shutdown of each instance.
Poststart
The Poststart function runs after startup of each instance.
Postback
The Postback  function runs after entire backup finishes.
Using these functions is very simple.  For example, to restart orasrv after an instance is restarted (with a script called rc.orasrv.sh,) change the Poststart function to read:

Poststart(){
rc.orasrv.sh
}
 

Deciding what or if to backup

Before actually running the backup, oraback.sh checks oraback.conf to determine:
  • Whether the user running the backup is oracle, or is a valid user (listed in field 7 of oraback.conf).  If the user id running the backup is not a valid user, the script will not continue. 
  • If it is a valid user, oraback.sh then looks to see whether the word skip is in field 2.  If so, it skips the backup once, and removes the word skip from oraback.conf.  (This allows a DBA to manually skip tonight's backup, but does not allow the DBA to accidentally disable backups forever.)
The script then does one of the following, depending on which arguments (if any) it receives:
 
  • It backs up everything
If given no arguments, it performs a backup of all instances listed in Oracle's oratab file.
$ oraback.sh 
 
  • It backs up selected instances
If given one or more instance names (ORACLE_SIDs, or SIDs for short) as arguments, the script performs a backup of each of them.
$ oraback.sh ORACLE_SID1 ORACLE_SIDn 
  • It schedules a backup for later
If called with at as an argument (this is what would be in cron), the script checks oraback.conf to see whether the day in field 3 (the cold backup day field) is today.  If so, it sets the variable $TIME to the time in field 4.  If not, it sets $TIME to the time in field 5. The script then schedules an at job that will run oraback.sh at the time specified by $TIME.

$ oraback.sh at 
 

Deciding where and how to back up

Oraback.sh then checks the hostname.master line in oraback.conf to find out if: (a) there is a tape device in field 6.  If so, it labels the tape, making sure the no-rewind device is being used; and (b) there is a number in field 8.  If so, it will perform that many simultaneous copies of database files.

Next, oraback.sh asks Oracle questions that will determine how (or if) the SID will be backed up.  It asks if

  • The instance is online.  If so, oraback.sh makes a set of configuration files needed later
  • Archiving is running
  • The instance is excluded from hot backup
  • This is a cold backup.  If so, it shuts down the instance.
The script assumes that all instances want hot backups (though you may specify cold backups), which requires automatic archiving of redo logs.  Oraback.sh warns if any instances do not have automatic archiving turned on.  It continues to complain until this situation is corrected or oraback.conf is customized for that instance.  (You do this by editing oraback.conf.)

If it’s a hot backup

If the instance is online, logs are on, and the instance is not excluded from hot backups, then the script:
  1. Puts each tablespace into backup mode by using the svrmgrl command begin backup. 
  2. Copies that tablespace's files to the backup device
  3. Takes the tablespace out of backup mode with the svrmgrl command end backup 
These three steps are the core of the hot backup.  While the tablespace is in backup mode, the files can be safely backed up.

The script supports simultaneous copying of individual data files to dramatically increase the speed of the backup.  Depending on how many files there are per tablespace, there may be one or more tablespaces in backup mode at once.  This is done in order to perform the number of concurrent file copies (using dd) that are specified in field 8 of oraback.conf, if you are using this feature.

After all data files are backed up

Next, the script forces a checkpoint and archive log switch, which causes the online redo log to be sent to an archived redo log.  It should be noted that it forces a log switch using the command alter sytem archive log current, instead of the older alter system switch logfile.  The reason for this is that switching log files does just that, switches the log file and immediately returns the svrmgr prompt.  The archive log current command waits until the copy of the old redo log to its archived location is done before it returns the prompt.  This is because the next thing the script is going to do is to copy this archived redo log to the backup location for safekeeping.  If we used the old command, we might by copying it from the archived log location while it is being created.  That way we are assured that the file we are copying is stable.

The script then backs up the control files to disk using both svrmgr and a manual copy.  The manual copy is just for the paranoid; it's not a supported method of backing up the control file .  Finally, the script makes copies of the essential redo logs and compresses them.  (Essential logs are those that span the time of the backup.)  If the backup device is a tape, it then backs up all files that were sent to disk to the tape device.

If it’s a cold backup

If the instance is offline, oraback.sh only needs to copy the data files to the backup device.  The script then backs up the control files and redo logs the same way it does during a hot backup.  This is perhaps the only time that manually copying the control files and online redo logs does any good.  That's because one could use these files to do a restore of the database to this point, without it ever knowing what happened.  To do that, all the control files and online redo logs would be needed.

Special cases

If the instance is online, but archiving is off, oraback.sh checks oraback.conf for a line that reads:

HOST:ORACLE_SID:NOARCHIVELOG:[offline|nohotbackups]

If that line is not found, oraback.sh complains and sends you mail.  That is because archiving must be on in order to do hot backups.  If the line is found, it looks for the word offline on that same line.  This tells oraback.sh that this instance is not supposed to have archive logs running, and it should always do an offline, or cold, backup of this instance.  If it sees the word offline, oraback.sh shuts down the instance, performs a cold backup, and then restarts the instance.  (This is one of the ways to customize oraback.sh for different instances.)

If the instance is online, oraback.sh also looks for a line in oraback.conf that reads:

HOST:ORACLE_SID:::nohotbackup

This tells oraback.sh that although ORACLE_SID qualifies for a hot backup (it has archiving on), oraback.sh should not do hot backups of this instance.  This is best suited for a development database, where the weekly cold backup is sufficient.  If this line is found, the script skips this instance when performing a hot backup.

Customizing backups of an instance

If there is an instance that will not run archiving or hot backups, put a line in oraback.conf that starts with:
hostname:ORACLE_SID::::
  1. Put NOARCHIVELOG in field 3 if the instance does not use archiving.
  2. Put offline in field 4 if the instance does not use archiving, and oraback.sh should do a cold backup done every time.
  3. Put nohotbackups in field 5 to skip hot backups for this instance.  (It will only be backed up when cold backups run).

Testing Oraback.sh

For testing, select a small instance and run the following command as Oracle:

$ /usr/local/bin/oraback.sh <instance>

Be aware that if the word offline is in oraback.conf, or if the day that is specified for cold backups is today, the instance will be shut down!
If this test functions properly, put an entry in Oracle's cron or in the at system.  Add a cron entry that contains the command /usr/local/bin/oraback.sh at, schedule to run at around 12:00.  It checks the oraback.conf and schedules an at job that will perform the backup.

Using Oraback.sh

The best way to use this program is to have one single oraback.conf file that is NFS-mounted or shared to all Oracle systems.  That way, all cron or at entries can run at 15:00, and backup configuration changes (system-wide or otherwise) can be made by editing one file.  For example, to cause all Oracle backups to be skipped tonight, instead of having to edit a number of cron or at entries, edit this one file before 15:00.  That way, it will see the word skip in there and not run backups that evening.  (It will, however, take this word out so backups will run tomorrow night.)

Set the SUCCESSMAIL flag to Y, to be mailed every time oraback.sh backup runs, successful or otherwise.  That allows a quick email check in the morning to see that all backups ran successful.  Simply check the subject line, since it will say ERROR if oraback.sh had any kind of errors.