backup dump [-v <volume set name>]
[-d <dump level name>]
[-p <TC port offset>]
[-at <Date/time to start dump>+] [-ap] [-n]
[-f <load file>] [-l] [-c <cell name>]
(If the "FILE YES" instruction appears in the /var/lib/openafs/backup/CFG_device_name file on the Tape Coordinator machine associated with the specified port offset, then the Backup System dumps data to the backup data file listed for that port offset in the Tape Coordinator's /var/lib/openafs/backup/tapeconfig file, rather than to tape. For the sake of clarity, the following text refers to tapes only, but the Backup System handles backup data files in much the same way.)
The term dumping refers to copying a collection of data to tape or a backup data file, and the resulting collection is termed a dump. The set of tapes that contain one or more dumps is called a dump set. The first dump in a dump set is its initial dump, and any dumps subsequently added to the dump set (by use of the -append argument) are appended dumps. Creating appended dumps is optional, and appended dumps can be of different volume sets, and at different dump levels, than the initial dump.
A full dump, created at a full dump level in the dump hierarchy, contains all of the data that existed at the time of the dump in the volumes belonging to the volume set. An incremental dump, created at an incremental dump level, contains only data that has changed since the volume set was dumped at the incremental level's parent dump level (the dump level immediately above the incremental level in the hierarchy), which can be a full or incremental level. More specifically, an incremental dump includes only the files and directories that have modification timestamps later than the clone date of the volume included at the parent dump level. For backup and read-only volumes, the clone date is the time at which the volume was cloned from its read/write source before being included in the parent dump; for read/write volumes, it represents the time at which the volume was locked for inclusion in the parent dump. The clone date appears in the clone date field of the output from the backup volinfo command. As an example, an incremental dump at the "/full/week1/thursday" level includes only files and directories that have changed since the volume set was dumped at the "/full/week1" level.
To append a dump to an existing dump set, include the -append flag. The Backup System imposes the following conditions on appended dumps:
To schedule multiple dump operations, list the operations in the file named by the -file argument. Optionally include the -at argument to specify when the backup command interpreter reads the file; otherwise it reads it immediately. Do not combine the -file argument with the command's first three arguments or the -append or -n flags. The commands in the file can include any of the backup dump command's arguments, including the -at argument to schedule them to run even later in the future.
To generate a list of the volumes included in a dump, without actually dumping them, combine the -n flag with the options to be used on the actual command.
After obtaining the list of volumes to dump from the Volume Location (VL) Server, the Backup System sorts the list by site (server and partition). It groups volumes from the same site together in the dump to minimize the number of times the operator must change tapes during restore operations.
The dependence of an incremental dump on its parent means that a valid parent dump must already exist for the Backup System to create its child incremental dump. If the Backup System does not find a record of a dump created at the immediate parent dump level, it looks in the Backup Database for a dump created at one level higher in the hierarchy, and so on, up to the full dump level if necessary. It creates an incremental dump at the level one below the lowest valid parent dump set that it finds. If it fails to find even a full dump, it dumps the volume set at the full dump level.
If the Backup System is unable to access a volume during a dump operation, it skips the volume and dumps the remaining volumes from the volume set. Possible reasons a volume is inaccessible include server machine or process outages, or that the volume was moved between the time the Volume Location (VL) Server generated the list of sites for the volume in the volume set and the time the Backup System actually attempts to dump the data in it. After the first dumping pass, the Backup System attempts to dump each volume it skipped. If it still cannot dump a volume and the "ASK NO" instruction does not appear in the CFG_device_name file, it queries the operator as to whether it needs to attempt to dump the volume again, omit the volume from the dump, or halt the dump operation altogether. When prompted, the operator can attempt to solve whatever problem prevented the Backup System from accessing the volumes. If the "ASK NO" instruction appears in the CFG_device_name file, the Backup System omits the volume from the dump.
Before scheduling a dump operation, the Backup System verifies that the date specified by the -at argument is in the future, and checks the validity of the volume set, dump level and port offset as for a regular dump operation. It checks the validity of the parameters again just before actually running the scheduled operation.
Before writing an initial dump to a tape that does not have a permanent name on the label, the Backup System checks that the AFS tape name on the label is acceptable. If desired, disable name checking by including the "NAME_CHECK NO" instruction in the CFG_device_name file.
If AFS tape name checking is enabled, the Backup System accepts the following three types of values for the AFS tape name. If the name on the label does not conform, the Backup System obtains a tape with an acceptable label by invoking the "MOUNT" instruction in the CFG_device_name file or prompting the operator.
To determine how much data it can write to a tape, the Tape Coordinator reads the capacity recorded on the tape's label (placed there by including the -size argument to the backup labeltape command). If the label's capacity field is empty, the Tape Coordinator uses the capacity recorded for the specified port offset in the local tapeconfig file. If the capacity field in the tapeconfig file is also empty, the Tape Coordinator uses the maximum capacity of 2 TB.
During a dump operation, the Tape Coordinator tracks how much data it has written and stops shortly before it reaches what it believes is the tape's capacity. If it is in the middle of writing the data for a volume when it reaches that point, it writes a special marker that indicates an interrupted volume and continues writing the volume on the next tape. It can split a volume this way during both an initial and an appended dump, and the fact that the volume resides on multiple tapes is automatically recorded in the Backup Database.
If the tape is actually larger than the expected capacity, then the Tape Coordinator simply does not use the excess tape. If the tape is smaller than the expected capacity, the Tape Coordinator can reach the end-of-tape (EOT) unexpectedly while it is writing data. If the Tape Coordinator is in the middle of the writing data from a volume, it obtains a new tape and rewrites the entire contents of the interrupted volume to it. The data from the volume that was written to the previous tape remains there, but is never used.
The Backup System allows recycling of tapes (writing a new dump set over an old dump set that is no longer needed), but imposes the following conditions:
Can't overwrite tape containing the dump in progress
Can't overwrite the parent dump I<parent_name> (I<parent_dump_ID>)
To recycle a tape before all dumps on it have expired or if the AFS tape name is wrong, use the backup labeltape command to overwrite the tape's label and remove all associated tape and dump records from the Backup Database.
The Tape Coordinator's default response to this command is to access the first tape by invoking the "MOUNT" instruction in the CFG_device_name file, or by prompting the backup operator to insert the tape if there is no "MOUNT" instruction. However, if the "AUTOQUERY NO" instruction appears in the CFG_device_name file, or if the issuer of the butc command included the -noautoquery flag, the Tape Coordinator instead expects the tape to be in the device already. If it is not, the Tape Coordinator invokes the "MOUNT" instruction or prompts the operator. It also invokes the "MOUNT" instruction or prompts for any additional tapes needed to complete the dump operation; the issuer must arrange to provide them.
If dumping to tape rather than a backup data file, it is best to use only compatible tape devices (ones that can read the same type of tape). Using compatible devices greatly simplifies restore operations. The -portoffset argument to the backup diskrestore and backup volsetrestore commands accepts multiple port offset numbers, but the Backup System uses the first listed port offset when restoring all full dumps, the second port offset when restoring all level 1 dumps, and so on. At the very least, use compatible tape devices to perform dumps at each level. If compatible tape devices are not used, the backup volrestore command must be used to restore one volume at a time.
Valid (unexpired) administrative tokens must be available to the backup command interpreter both when it reads the file named by the -file argument and when it runs each operation listed in the file. Presumably, the issuer is scheduling dumps for times when no human operator is present, and so must arrange for valid tokens to be available on the local machine. One option is to issue all commands (or run all scripts) on file server machines and use the -localauth flag on the backup and vos commands. To protect against improper access to the machine or the tokens, the machine must be physically secure (perhaps even more protected than a Tape Coordinator machine monitored by a human operator during operation). Also, if an unattended dump requires multiple tapes, the operator must properly configure a tape stacker or jukebox and the device configuration file.
When the command is issued in regular (non-interactive) mode, the command shell prompt does not return until the dump operation completes. To avoid having to open additional connections, issue the command in interactive mode, especially when including the -at argument to schedule dump operations.
The hour and minutes (hh:MM) are optional, but if provided must be in 24-hour format (for example, the value "14:36" represents 2:36 p.m.). If omitted, the time defaults to midnight (00:00 hours).
As an example, the value 04/23/1999 20:20 schedules the command for 8:20 p.m. on 23 April 1999.
Place each backup dump command on its own line in the indicated file, using the same syntax as for the command line, but without the word backup at the start of the line. Each command must include a value for the -volumeset and -dump arguments, and for the -portoffset argument unless the default value of 0 is appropriate. Commands in the file can also include any of the backup dump command's optional options. In the following example file, the first command runs as soon as the Backup System reads the file, whereas the other commands are themselves scheduled; the specified date and time must be later than the date and time at which the Backup System reads the file.
dump user /sunday1/wednesday -port 1 dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999 dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append
Do not combine this argument with the -volumeset, -dump, -portoffset, -append, or -n options.
Preparing to dump the following volumes:
The following message then indicates that the command interpreter has passed the dump request to the appropriate Tape Coordinator for processing:
If the issuer includes the -n flag, the output is of the following form:
Starting dump of volume set '<volume set>' (dump set '<dump level>') Total number of volumes : <number dumped> Would have dumped the following volumes: <list_of_volumes>
where list_of_volumes identifies each volume by name and volume ID number.
If the Tape Coordinator is unable to access a volume, it prints an error message in its window and records the error in its log and error files.
% backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5 Preparing to dump the following volumes: user.jones.backup 387623900 user.pat.backup 486219245 user.smith.backup 597315841 . . . . Starting dump.
The following command displays the list of volumes to be dumped when the user dumps the "sys_sun" volume set at the "/full" dump level.
% backup dump -volumeset sys_sun -dump /full -n Starting dump of volume set 'sys_sun' (dump set '/full') Total number of volumes: 24 Would have dumped the following volumes: sun4x_56 124857238 sun4x_56.bin 124857241 . . . . sun4x_55 124857997 . . . .
The following command schedules a dump of the volumes in the volume set "user" at the dump level "/sunday2/monday1" for 11:00 p.m. on 14 June 1999. The appropriate Tape Coordinator has port offset 0 (zero), so that argument is omitted.
% backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00
This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.