Section: AFS Command Reference (8)
backup dump - Creates a dump (dumps a volume set at a particular dump level)
<volume set name
<dump level name
<TC port offset
<date/time to start dump
+] >>> [-append
] >>> [-localauth
] >>> [-help
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] >>>
The backup dump
command either dumps the volume set specified by the-volumeset
argument at the dump level specified by the -dump
argument and creates a Backup Database dump record about it, or executesthe dump instructions listed in the file named by the -file
argument. The Tape Coordinator indicated by the -portoffset
argument(or on each command in the file) executes the operation.
(If the FILE YES instruction appears in the/usr/afs/backup/CFG_device_name file on the Tape Coordinator machineassociated with the specified port offset, then the Backup System dumpsdata to the backup data file listed for that port offset in the TapeCoordinator's /usr/afs/backup/tapeconfig file, rather than to tape. Forthe sake of clarity, the following text refers to tapes only, but theBackup System handles backup data files in much the same way.)
The term dumping refers to copying a collection of data to tape or abackup data file, and the resulting collection is termed a dump. Theset of tapes that contain one or more dumps is called a dump set. Thefirst dump in a dump set is its initial dump, and any dumpssubsequently added to the dump set (by use of the -append argument) areappended dumps. Creating appended dumps is optional, and appendeddumps can be of different volume sets, and at different dump levels, thanthe 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 thevolumes belonging to the volume set. An incremental dump, created at anincremental dump level, contains only data that has changed since thevolume set was dumped at the incremental level's parent dump level (thedump level immediately above the incremental level in the hierarchy),which can be a full or incremental level. More specifically, anincremental dump includes only the files and directories that havemodification timestamps later than the clone date of the volumeincluded at the parent dump level. For backup and read-only volumes, theclone date is the time at which the volume was cloned from its read/writesource before being included in the parent dump; for read/write volumes,it represents the time at which the volume was locked for inclusion in theparent dump. The clone date appears in the clone date field of theoutput from the backup volinfo command. As an example, an incrementaldump at the /full/week1/thursday level includes only files anddirectories that have changed since the volume set was dumped at the/full/week1 level.
Initiating different types of dump operations
To initiate a dump operation that is to start as soon as the relevant TapeCoordinator is available, provide only the -volumeset
, and optionally -append
options. To schedule a singlebackup dump
command to execute in the future, also include the -at
argument to specify the start time.
To append a dump to an existing dump set, include the -append flag. TheBackup System imposes the following conditions on appended dumps:
- If writing to tape, the Tape Coordinator checks that it is the final onein a dump set for which there are complete and valid tape and dump recordsin the Backup Database. If not, it rejects the tape and requests anacceptable one. The operator can use the -dbadd argument to thebackup scantape command to insert the necessary records into thedatabase.
- The most recent dump on the tape or in the backup data file must havecompleted successfully.
- The dump set must begin with an initial dump that is recorded in theBackup Database. If there are no dumps on the tape, then the Backup Systemtreats the dump operation as an initial dump and imposes the relevantrequirements (for example, checks the AFS tape name if appropriate).
To schedule multiple dump operations, list the operations in the filenamed by the -file argument. Optionally include the -at argument tospecify when the backup command interpreter reads the file; otherwiseit reads it immediately. Do not combine the -file argument with thecommand's first three arguments or the -append or -n flags. Thecommands in the file can include any of the backup dump command'sarguments, including the -at argument to schedule them to run evenlater in the future.
To generate a list of the volumes included in a dump, without actuallydumping them, combine the -n flag with the options to be used on theactual command.
How the Backup System executes a dump operation
Before beginning a dump operation, the Backup System verifies that thereis a Backup Database entry for the volume set, dump level, and portoffset. If the command is correctly formed and issued in interactive mode,it is assigned a job number and added to the jobs list. List jobs ininteractive mode by using the backup jobs
command; terminate them withthe backup kill
After obtaining the list of volumes to dump from the Volume Location (VL)Server, the Backup System sorts the list by site (server andpartition). It groups volumes from the same site together in the dump tominimize the number of times the operator must change tapes during restoreoperations.
The dependence of an incremental dump on its parent means that a validparent dump must already exist for the Backup System to create its childincremental dump. If the Backup System does not find a record of a dumpcreated at the immediate parent dump level, it looks in the BackupDatabase for a dump created at one level higher in the hierarchy, and soon, up to the full dump level if necessary. It creates an incremental dumpat the level one below the lowest valid parent dump set that it finds. Ifit fails to find even a full dump, it dumps the volume set at the fulldump 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 volumeset. Possible reasons a volume is inaccessible include server machine orprocess outages, or that the volume was moved between the time the VolumeLocation (VL) Server generated the list of sites for the volume in thevolume set and the time the Backup System actually attempts to dump thedata in it. After the first dumping pass, the Backup System attempts todump each volume it skipped. If it still cannot dump a volume and theASK NO instruction does not appear in the CFG_device_name file,it queries the operator as to whether it needs to attempt to dump thevolume again, omit the volume from the dump, or halt the dump operationaltogether. When prompted, the operator can attempt to solve whateverproblem prevented the Backup System from accessing the volumes. If theASK NO instruction appears in the CFG_device_name file, theBackup System omits the volume from the dump.
Before scheduling a dump operation, the Backup System verifies that thedate specified by the -at argument is in the future, and checks thevalidity of the volume set, dump level and port offset as for a regulardump operation. It checks the validity of the parameters again just beforeactually running the scheduled operation.
Before writing an initial dump to a tape that does not have a permanentname on the label, the Backup System checks that the AFS tape name on thelabel is acceptable. If desired, disable name checking by including theNAME_CHECK NO instruction in the CFG_device_name file.
If AFS tape name checking is enabled, the Backup System accepts thefollowing three types of values for the AFS tape name. If the name on thelabel does not conform, the Backup System obtains a tape with anacceptable label by invoking the MOUNT instruction in theCFG_device_name file or prompting the operator.
- A name of the form volume_set_name.dump_level_name.tape_index, wherevolume_set_name matches the value of the -volumeset argument,dump_level_name matches the last element in the pathname value of the-dump argument, and tape_index reflects the tape's place in amultitape dump set. As an example, the first tape in a dump set for whichthe initial dump is of volume set user at the dump level/sunday2/monday has AFS tape name user.monday.1. If the labelrecords this type of AFS tape name, the Backup System retains the AFS tapename and writes the dump to the tape.
- The string < <NULL >>, which usually indicates that a backup operatorhas used the backup labeltape command to write a label on the tape, butdid not include the -name argument to assign an AFS tapename. Presumably, the operator did include the -pname argument toassign a permanent name. If the label records a < <NULL >> value, theBackup System constructs and records on the label the appropriate AFS tapename, and writes the dump on the tape.
- No value at all, because the tape has never been labeled or used in theBackup System. As when the AFS tape name is < <NULL >>, the BackupSystem constructs and records on the label the appropriate AFS tape name,and writes the dump on the tape.
To determine how much data it can write to a tape, the Tape Coordinatorreads the capacity recorded on the tape's label (placed there by includingthe -size argument to the backup labeltape command). If the label'scapacity field is empty, the Tape Coordinator uses the capacity recordedfor the specified port offset in the local tapeconfig file. If thecapacity field in the tapeconfig file is also empty, the TapeCoordinator uses the maximum capacity of 2 TB.
During a dump operation, the Tape Coordinator tracks how much data it haswritten and stops shortly before it reaches what it believes is the tape'scapacity. If it is in the middle of writing the data for a volume when itreaches that point, it writes a special marker that indicates aninterrupted volume and continues writing the volume on the next tape. Itcan split a volume this way during both an initial and an appended dump,and the fact that the volume resides on multiple tapes is automaticallyrecorded in the Backup Database.
If the tape is actually larger than the expected capacity, then the TapeCoordinator simply does not use the excess tape. If the tape is smallerthan the expected capacity, the Tape Coordinator can reach the end-of-tape(EOT) unexpectedly while it is writing data. If the Tape Coordinator is inthe middle of the writing data from a volume, it obtains a new tape andrewrites the entire contents of the interrupted volume to it. The datafrom the volume that was written to the previous tape remains there, butis never used.
The Backup System allows recycling of tapes (writing a new dump set overan old dump set that is no longer needed), but imposes the followingconditions:
- All dumps in the old dump set must be expired. The Backup System alwayschecks expiration dates, even when name checking is disabled.
- If the tape to be recycled does not have a permanent name and namechecking is enabled, then the AFS tape name derived from the new initialdump's volume set name and dump level name must match the AFS tape namealready recorded on the label.
- The tape cannot already have data on it that belongs to the dump currentlybeing performed, because that implies that the operator or automated tapedevice has not removed the previous tape from the drive, or has mistakenlyreinserted it. The Tape Coordinator generates the following message andattempts to obtain another tape:
Can't overwrite tape containing the dump in progress
- The tape cannot contain data from a parent dump of the current(incremental) dump, because overwriting a parent dump makes it impossibleto restore data from the current dump. The Tape Coordinator generates thefollowing message and attempts to obtain another tape:
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 tapename is wrong, use the backup labeltape command to overwrite the tape'slabel and remove all associated tape and dump records from the BackupDatabase.
The Tape Coordinator's default response to this command is to access thefirst tape by invoking the MOUNT instruction in theCFG_device_name file, or by prompting the backup operator to insertthe tape if there is no MOUNT instruction. However, if the AUTOQUERYNO instruction appears in the CFG_device_name file, or if theissuer of the butc command included the -noautoquery flag, the TapeCoordinator instead expects the tape to be in the device already. If it isnot, the Tape Coordinator invokes the MOUNT instruction or prompts theoperator. It also invokes the MOUNT instruction or prompts for anyadditional tapes needed to complete the dump operation; the issuer mustarrange to provide them.
If a dump operation is interrupted or fails for any reason, data from allvolumes written to tape before the interrupt are valid can be used in arestore operation. The Backup Database includes an entry for the faileddump and for each volume that was successfully dumped. See the IBM AFSAdministration Guide
for information on dealing with interrupted dumps.
If dumping to tape rather than a backup data file, it is best to use onlycompatible tape devices (ones that can read the same type of tape). Usingcompatible devices greatly simplifies restore operations. The-portoffset argument to the backup diskrestore and backupvolsetrestore commands accepts multiple port offset numbers, but theBackup System uses the first listed port offset when restoring all fulldumps, the second port offset when restoring all level 1 dumps, and soon. At the very least, use compatible tape devices to perform dumps ateach level. If compatible tape devices are not used, the backupvolrestore command must be used to restore one volume at a time.
Valid (unexpired) administrative tokens must be available to the backupcommand interpreter both when it reads the file named by the -fileargument and when it runs each operation listed in the file. Presumably,the issuer is scheduling dumps for times when no human operator ispresent, and so must arrange for valid tokens to be available on the localmachine. One option is to issue all commands (or run all scripts) on fileserver machines and use the -localauth flag on the backup and voscommands. To protect against improper access to the machine or the tokens,the machine must be physically secure (perhaps even more protected than aTape Coordinator machine monitored by a human operator duringoperation). Also, if an unattended dump requires multiple tapes, theoperator must properly configure a tape stacker or jukebox and the deviceconfiguration file.
When the command is issued in regular (non-interactive) mode, the commandshell prompt does not return until the dump operation completes. To avoidhaving to open additional connections, issue the command in interactivemode, especially when including the -at argument to schedule dumpoperations.
- -volumeset <volume set name>
- Names the volume set to dump. The -dump argument must be provided alongwith this one; do not combine them with the -file argument. If using atemporary volume set, the vos dump command must be issued within theinteractive session in which the backup addvolset command was issuedwith the -temporary flag.
- -dump <dump level name>
- Specifies the complete pathname of the dump level at which to dump thevolume set. The -volumeset argument must be provided along with thisone; do not combine them with the -file argument.
- -portoffset <TC port offset>
- Specifies the port offset number of the Tape Coordinator handling thetapes for this operation. It must be provided unless the default value of0 (zero) is appropriate; do not combine it with the -file argument.
- -at <date/time to start dump>
- Specifies the date and time in the future at which to run the command, orto read the file named by the -file argument. Provide a value in theformat mm/dd/yyyy [hh:MM], where the month (mm), day (dd), andyear (yyyy) are required. Valid values for the year range from 1970to 2037; higher values are not valid because the latest possible datein the standard UNIX representation is in February 2038. The Backup Systemautomatically reduces any later date to the maximum value.
The hour and minutes (hh:MM) are optional, but if provided must be in24-hour format (for example, the value 14:36 represents 2:36 p.m.). Ifomitted, the time defaults to midnight (00:00 hours).
As an example, the value 04/23/1999 20:20 schedules the command for 8:20p.m. on 23 April 1999.
- Appends the dump onto the end of a tape that already contains data fromanother dump. However, if the tape is not in fact part of an existing dumpset, the Backup System creates a new dump set using the parameters of thisdump. If the tape is not the last tape in the dump set, the TapeCoordinator prompts for insertion of the appropriate tape. Do not combinethis argument with the -file argument.
- Displays the names of volumes to be included in the indicated dump,without actually performing the dump operation. Do not combine thisargument with the -file argument.
- -file <load file>
- Specifies the local disk or AFS pathname of a file containing backupcommands. The Backup System reads the file immediately, or at the timespecified by the -at argument if it is provided. A partial pathname isinterpreted relative to the current working directory.
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 wordbackup at the start of the line. Each command must include a value forthe -volumeset and -dump arguments, and for the -portoffsetargument unless the default value of 0 is appropriate. Commands in thefile can also include any of the backup dump command's optionaloptions. In the following example file, the first command runs as soon asthe Backup System reads the file, whereas the other commands arethemselves scheduled; the specified date and time must be later than thedate 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 -appendDo not combine this argument with the -volumeset, -dump,-portoffset, -append, or -n options.
- Constructs a server ticket using a key from the local/usr/afs/etc/KeyFile file. The backup command interpreter presentsit to the Backup Server, Volume Server and VL Server during mutualauthentication. Do not combine this flag with the -cell argument. Formore details, see the backup(8) manpage.
- -cell <cell name>
- Names the cell in which to run the command. Do not combine this argumentwith the -localauth flag. For more details, see the backup(8) manpage.
- Prints the online help for this command. All other valid options areignored.
The command interpreter first generates a list of the volumes to beincluded in the dump by matching the entries in the volume set against thevolumes listed in the Volume Location Database (VLDB). It prints the listfollowing the header:
Preparing to dump the following volumes:
The following message then indicates that the command interpreter haspassed the dump request to the appropriate Tape Coordinator forprocessing:
If the issuer includes the -n
flag, the output is of the followingform:
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>
identifies each volume by name and volume IDnumber.
If the Tape Coordinator is unable to access a volume, it prints an errormessage in its window and records the error in its log and error files.
The following command dumps the volumes in the volume set called user
at the dump level /full/sunday2/monday
. The issuer places the necessarytapes in the device with port offset 5.
% 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 theuser dumps the sys_sun
volume set at the /full
% 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 setuser
at the dump level /sunday2/monday1
for 11:00 p.m. on 14 June1999. The appropriate Tape Coordinator has port offset 0 (zero), so thatargument is omitted.
% backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00
The issuer must be listed in the /usr/afs/etc/UserList
file on everymachine where the Backup Server or Volume Location (VL) Server is running,and on every file server machine that houses an affected volume. If the-localauth
flag is included, the issuer must instead be logged on to aserver machine as the local superuser root
IBM Corporation 2000. <http://www.ibm.com/
> All Rights Reserved.
This documentation is covered by the IBM Public License Version 1.0. It wasconverted from HTML to POD by software written by Chas Williams and RussAllbery, based on work by Alf Wachsmann and Elizabeth Cassell.
- Initiating different types of dump operations
- How the Backup System executes a dump operation
- PRIVILEGE REQUIRED
- SEE ALSO
This document was created byman2html,using the manual pages.