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
<volume set name
<dump level name
<TC port offset
<Date/time to start dump
< cell name
The backup dump
command either dumps the volume set specified by the
argument at the dump level specified by the -dump
argument and creates a Backup Database dump record about it, or executes the
dump instructions listed in the file named by the -file
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
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
set of tapes that contain one or more dumps is called a dump set
first dump in a dump set is its initial dump
, and any dumps
subsequently added to the dump set (by use of the -append
. Creating appended dumps is optional, and appended dumps
can be of different volume sets, and at different dump levels, than the
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
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
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 initiate a dump operation that is to start as soon as the relevant Tape
Coordinator is available, provide only the -volumeset
, and optionally -append
options. To schedule a
single backup dump
command to execute in the future, also include the
argument to specify the start time.
To append a dump to an existing dump set, include the -append
Backup System imposes the following conditions on appended dumps:
- If writing to tape, the Tape Coordinator checks that it is
the final one in a dump set for which there are complete and valid tape
and dump records in the Backup Database. If not, it rejects the tape and
requests an acceptable one. The operator can use the -dbadd
argument to the backup scantape command to insert the necessary
records into the database.
- The most recent dump on the tape or in the backup data file
must have completed successfully.
- The dump set must begin with an initial dump that is
recorded in the Backup Database. If there are no dumps on the tape, then
the Backup System treats the dump operation as an initial dump and imposes
the relevant requirements (for example, checks the AFS tape name if
To schedule multiple dump operations, list the operations in the file named by
argument. Optionally include the -at
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
commands in the file can include any of the backup dump
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
Before beginning a dump operation, the Backup System verifies that there is a
Backup Database entry for the volume set, dump level, and port offset. 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 in interactive mode by using
the backup jobs
command; terminate them with the 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 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
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
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.
- A name of the form
volume_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 a multitape dump set. As an example, the first tape in a
dump set for which the initial dump is of volume set "user" at
the dump level "/sunday2/monday" has AFS tape name
"user.monday.1". If the label records this type of AFS tape
name, the Backup System retains the AFS tape name and writes the dump to
- The string "<NULL>", which usually
indicates that a backup operator has used the backup labeltape
command to write a label on the tape, but did not include the -name
argument to assign an AFS tape name. Presumably, the operator did include
the -pname argument to assign a permanent name. If the label
records a "<NULL>" value, the Backup System constructs and
records on the label the appropriate AFS tape name, and writes the dump on
- No value at all, because the tape has never been labeled or
used in the Backup System. As when the AFS tape name is
"<NULL>", the Backup System 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 Coordinator reads
the capacity recorded on the tape's label (placed there by including the
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
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:
- All dumps in the old dump set must be expired. The Backup
System always checks expiration dates, even when name checking is
- If the tape to be recycled does not have a permanent name
and name checking is enabled, then the AFS tape name derived from the new
initial dump's volume set name and dump level name must match the AFS tape
name already recorded on the label.
- The tape cannot already have data on it that belongs to the
dump currently being performed, because that implies that the operator or
automated tape device has not removed the previous tape from the drive, or
has mistakenly reinserted it. The Tape Coordinator generates the following
message and attempts 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
impossible to restore data from the current dump. The Tape Coordinator
generates the following 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 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
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
file, or if the issuer of the
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 a dump operation is interrupted or fails for any reason, data from all
volumes written to tape before the interrupt are valid can be used in a
restore operation. The Backup Database includes an entry for the failed dump
and for each volume that was successfully dumped. See the OpenAFS
for information on dealing with interrupted dumps.
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
argument to the backup diskrestore
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
flag on the backup
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.
- -volumeset <volume set name>
- Names the volume set to dump. The -dump argument
must be provided along with this one; do not combine them with the
-file argument. If using a temporary volume set, the vos
dump command must be issued within the interactive session in which
the backup addvolset command was issued with the -temporary
- -dump <dump level name>
- Specifies the complete pathname of the dump level at which
to dump the volume set. The -volumeset argument must be provided
along with this one; do not combine them with the -file
- -portoffset <TC port offset>
- Specifies the port offset number of the Tape Coordinator
handling the tapes for this operation. It must be provided unless the
default value of 0 (zero) is appropriate; do not combine it with the
- -at <date/time to start dump>
- Specifies the date and time in the future at which to run
the command, or to read the file named by the -file argument.
Provide a value in the format mm/dd/yyyy [hh:MM], where the
month ( mm), day (dd), and year ( yyyy) are required.
Valid values for the year range from 1970 to 2037; higher values are not
valid because the latest possible date in the standard UNIX representation
is in February 2038. The Backup System automatically reduces any later
date to the maximum value.
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.
- Appends the dump onto the end of a tape that already
contains data from another dump. However, if the tape is not in fact part
of an existing dump set, the Backup System creates a new dump set using
the parameters of this dump. If the tape is not the last tape in the dump
set, the Tape Coordinator prompts for insertion of the appropriate tape.
Do not combine this 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 this argument with the -file argument.
- -file <load file>
- Specifies the local disk or AFS pathname of a file
containing backup commands. The Backup System reads the file
immediately, or at the time specified by the -at argument if it is
provided. A partial pathname is interpreted relative to the current
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.
- Constructs a server ticket using a key from the local
/etc/openafs/server/KeyFile file. The backup command
interpreter presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
-cell argument. For more details, see backup(8).
- -cell <cell name>
- Names the cell in which to run the command. Do not combine
this argument with the -localauth flag. For more details, see
- Prints the online help for this command. All other valid
options are ignored.
The command interpreter first generates a list of the volumes to be included in
the dump by matching the entries in the volume set against the volumes listed
in the Volume Location Database (VLDB). It prints the list following the
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:
identifies each volume by name and volume ID
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.
The following command dumps the volumes in the volume set called
"user" at the dump level "/full/sunday2/monday". The
issuer places the necessary tapes in the device with port offset 5.
% backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5
Preparing to dump the following volumes:
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:
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
The issuer must be listed in the /etc/openafs/server/UserList
every machine where the Backup Server or Volume Location (VL) Server is
running, and on every file server machine that houses an affected volume. If
flag is included, the issuer must instead be logged on
to a server 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 was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.