Managing ObjectStore

osbackup: Backing Up Databases

 The osbackup utility copies specified databases to another on-line location or to tape. See also Overview of the Backup/Restore Facility.

Syntax

osbackup [options] -i incremental-record-file -f backup-image-file 

[-f backup-image-file]... pathname ... 



-i 
incremental-
record-file 

Required. Specifies the incremental record file, a file that contains information about those databases that have been backed up and when they were backed up. The osbackup utility uses this information to determine the clusters within a database that have been modified since the last backup at a lower level. The utility then backs up only modified clusters. The incremental record file is comparable to the archive record file for osarchiv.

Performing a backup at any level for which no previous information exists is equivalent to doing a level 0 backup for that database. 



-f backup-
image-file 

Specifies the location of the backup image. 

You can specify a local file or a locally mounted file.

You can specify a tape device that is directly accessible from the host on which you are running osbackup. You cannot specify a remote tape device.

You can repeat the -f option with a new backup-image-file to create a multifile backup. When you do this, specify the -s option to indicate the size of each backup-image-file. For example:

osbackup -s 1m -f back1 -f back2 -f back3 db1 db2  db3
ObjectStore tries to back up the databases to the back1, back2, and back3 files. The utility prompts for additional file names if 1 MB per file is not sufficient.





 On UNIX systems, you can specify -f - (hyphen) to indicate stdout. This allows you to pipe osbackup output directly to the osrestore utility.

On Windows NT systems, you specify a tape device with this syntax, \\.\Tape0, the standard Windows NT name for the first tape drive.



pathname... 

Specifies a database or directory to be backed up. You can specify one or more pathnames. Pathnames can be on different Servers.

Options
-a
Aborts the backup operation if the utility cannot open the backup device. This raises an exception that indicates the problem.

The default is that if the backup utility fails to open the backup device, it displays a message and waits for you to correct the problem.

Examples of failure to open the backup device are having a write-protected tape or not having a tape loaded.

 
-b -blocking-factor
Specifies a blocking factor to use for tape input and output. The blocking factor is in units of 512-byte blocks. This parameter is ignored for regular files. The default on UNIX is 126 blocks. The maximum blocking factor is 512 blocks.

 
-B size
Specifies the size of the buffer used by the Servers contacted by osbackup. size is a number optionally appended with k, m, or g to indicate kilobytes, megabytes, or gigabytes respectively. If no letter is given, m is presumed. For example, -B 1024k, -B 1m, and -B 1 each specify a maximum buffer size of 1 MB. The default value is 1 MB. 

-I import-file
Specifies the name of a file that contains a list of either file or rawfs database pathnames. The osbackup utility backs up the databases in this list. If you specify "-" as the import file name, osbackup reads from standard input.

The list contains one pathname per line. Leading and trailing white space is ignored.

If you specify the -I (uppercase I) option, you can also specify additional pathnames on the command line.

 
-l- level
Lowercase L specifies the level of the backup. Specify an integer from 0 to 9. Files that have been modified since the last backup at a lower level are copied to the backup image. For example, suppose that you did a level 2 backup on Monday, followed by a level 4 backup on Tuesday. A subsequent level 3 backup on Wednesday would contain all files modified or added since the level 2 (Monday) backup.

Backup is incremental at the cluster level, meaning that a cluster is only backed up if it has been modified since the last backup at a lower level. A level 0 backup (the default) backs up all clusters in all specified databases. 

-r
Instructs osbackup to descend into any rawfs directories specified on the command line, adding all rawfs databases found to the list of databases to be backed up. By default, only databases in the specified directory are backed up. When backing up file databases, specifying the -r option has no effect. You must explicitly specify each file database.

 
-s- size
Sets the size of the volume being dumped to. The osbackup utility prompts you to insert a new tape or specify a new backup image file after it writes the amount of data specified by size.

You can specify k, m, or g to indicate that size is in units of kilobytes, megabytes (the default), or gigabytes. For example, -s 1024k, -s 1m, and -s 1 each specify a maximum backup image size of 1 MB.

You can use this option with the -f option to perform a multivolume backup.

This option is mainly for use when you are backing up to a tape device, because end-of-media cannot be detected reliably on some systems.

On Solaris 2, the -s option is not required because the end of the tape is reliably signaled to the application without any loss of data. On other systems, if you do not specify -s, the osbackup utility terminates when it reaches the end of the tape.

 
-S exec_command_name
Specifies the pathname of a command to be executed when the osbackup utility reaches the end of the media. This command should mount the next volume before returning. The exit status from this command must be 0 or the backup operation aborts. Note that this option is an uppercase S.

Description

 When backing up databases, ObjectStore takes advantage of any operations already being performed by the Server on behalf of various client applications. This reduces the cost of performing the backup. The osbackup utility gives priority to databases that are already open at the time the backup starts and, within a database, to those sectors that are being actively used.

When backup starts, osbackup determines those clusters that require backup, builds a map that describes this data, and sets itself up to intercept read and write requests to and from these sectors. Any time the Server reads a sector of interest to the backup process that has not already been backed up, osbackup allows the read to proceed and makes a copy of the data at that time. Similarly, write requests are intercepted and delayed long enough for osbackup to retrieve the transaction-consistent data first. Otherwise, the backup process operates in the background, retrieving data as efficiently as possible.

Considerations

You can mix file databases and rawfs databases in the set of databases to be backed up.

Backing up a
rawfs directory

When you specify a rawfs directory, osbackup backs up all databases in the directory. When you specify the -r option, osbackup also backs up all databases in all subdirectories, subsubdirectories, and so on.

Backing up file databases

When backing up file databases, you must explicitly specify the name of each database with the pathname argument or in an import file, specified with the -I (uppercase I) option.

Specifying an incremental record file

If you do not specify an incremental record file for your backup, osbackup creates one using a default pathname.

If a file of this name already exists, it is written over and data in it is lost. For this reason, it is recommended that you use the -i option to provide a unique name for the incremental record file.

Compacted databases

When you run the oscompact utility on a database, it has the potential to modify each cluster in the database. When you back up a database after compacting it, the osbackup utility copies each modified cluster; this might be the entire database. Consequently, you might want to compact databases before you perform a full backup.

Examples of Backing Up Databases

% osls -l vancouver::/foo.db

-rw-rw-r-- smith odi     231424 Dec 20 16:17 vancouver::/foo.db
%

Full backup of
rawfs database
to three files

% osbackup -i ./inc -f ./s1 -f ./s2 -f ./s3 -s 80k vancouver::/foo.db

Writing backup volume #1 (./s1)...
Archiving 452 sectors in database vancouver::/foo.db.
Closing volume #1 (./s1).
Auto switching to volume #2 (./s2).
Writing backup volume #2 (./s2)...
Closing volume #2 (./s2).
Auto switching to volume #3 (./s3).
Writing backup volume #3 (./s3)...
Closing volume #3 (./s3).
%
If you do not specify enough files, you are prompted as follows:

% osbackup -i ./inc -f ./s1 -f ./s2 -f ./s3 -s 10k vancouver::/mdltst1.db

Writing backup volume #1 (./s1)...
Closing volume #1 (./s1).
Auto switching to volume #2 (./s2).
Writing backup volume #2 (./s2)...
Closing volume #2 (./s2).
Auto switching to volume #3 (./s3).
Writing backup volume #3 (./s3)...
Archiving 913 sectors in database vancouver::/mdltst1.db.
Closing volume #3 (./s3).
Please enter the pathname of the next file to use for backup.

Full backup of
rawfs database
to existing image

% osls vancouver::/

dbdir/
foo.db

% osls vancouver::/dbdir

bar.db
foo.db

% touch ./img <-- create file to demonstrate problem 
% osbackup -f ./img -i ./inc vancouver::/foo.db

Error encountered while opening file ./img (File ./img already exists. 
Cannot archive to an existing file.)

Do you wish to try_again? (yes/no): yes
Please enter the pathname of the next file to use for backup. ./img2
Writing backup volume #1 (./img2)...
Archiving 452 sectors in database vancouver::/foo.db.
Closing volume #1 (./img2).

Full backup of directory

% osbackup -f ./img -i ./inc -r vancouver::/

Writing backup volume #1 (./img)...
Archiving 452 sectors in database vancouver::/dbdir/bar.db.
Archiving 452 sectors in database vancouver::/dbdir/foo.db.
Archiving 452 sectors in database vancouver::/foo.db.
Closing volume #1 (./img).

Full backup of databases listed in import file

% cat ./import_file

vancouver::/foo.db
/vancouver1/dbdir/foo.db
%

% osbackup -f ./img -i ./inc -I ./import_file

Writing backup volume #1 (./img)...
Archiving 452 sectors in database vancouver:/vancouver1/dbdir/foo.db.
Archiving 452 sectors in database vancouver::/foo.db.
Closing volume #1 (./img).
%

Using an import
file and specifying
a pathname

% osbackup -f ./img -i ./inc -I ./import_file vancouver::/dbdir/foo.db

Writing backup volume #1 (./img)...
Archiving 452 sectors in database vancouver:/vancouver1/dbdir/foo.db.
Archiving 452 sectors in database vancouver::/dbdir/foo.db.
Archiving 452 sectors in database vancouver::/foo.db.
Closing volume #1 (./img).
%

Incremental backups of a rawfs database

% $OS_ROOTDIR/bin/osbackup -f ./img0 -i ./inc -l 0 
vancouver::/foo.db

Writing backup volume #1 (./img0)...
Archiving 452 sectors in database vancouver::/foo.db.
Closing volume #1 (./img0).

% $OS_ROOTDIR/bin/osbackup -f ./img1 -i ./inc -l 1 
vancouver::/foo.db

Writing backup volume #1 (./img1)...
Closing volume #1 (./img1).

% $OS_ROOTDIR/bin/osbackup -f ./img2 -i ./inc -l 2 
vancouver::/foo.db

Writing backup volume #1 (./img2)...
Closing volume #1 (./img2).

% osrm vancouver::/foo.db

Restoring from incremental backups

% $OS_ROOTDIR/bin/osrestore -f ./img0

Recovering from volume #1 (./img0)...
Restoring 452 sectors to database "vancouver::/foo.db"
Recovered to time Tue Jan 12 15:50:10 1999
Do you wish to restore from any additional incremental backups? 
(yes/no):

yes

Closing volume #1 (./img0).
Please enter the pathname of the next file from which to restore.

./img1

Recovering from volume #2 (./img1)...
Recovered to time Tue Jan 12 15:50:21 1999
Do you wish to restore from any additional incremental backups? 
(yes/no):

yes

Closing volume #2 (./img1).
Please enter the pathname of the next file from which to restore.

./img2

Recovering from volume #3 (./img2)...
Recovered to time Tue Jan 12 15:50:41 1999
Do you wish to restore from any additional incremental backups? 
(yes/no):

no

Closing volume #3 (./img2).
%

API

 None



[previous] [next]

Copyright © 1999 Object Design, Inc. All rights reserved.

Updated: 03/11/99 11:19:07