Provided by: openafs-client_1.8.0~pre5-1ubuntu1.2_amd64 bug

NAME

       backup_dump - Creates a dump (dumps a volume set at a particular dump level)

SYNOPSIS

       backup dump [-volumeset <volume set name>]
           [-dump <dump level name>]
           [-portoffset <TC port offset>]
           [-at <date/time to start dump>+]
           [-append] [-dryrun | -n]
           [-file <load file>] [-localauth]
           [-cell <cell name>] [-help]

       backup dump [-v <volume set name>]
           [-d <dump level name>]
           [-p <TC port offset>]
           [-at <Date/time to start dump>+] [-ap] [-dryrun | -n]
           [-f <load file>] [-l] [-c <cell name>]
           [-h]

DESCRIPTION

       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 executes the 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 /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.

   Initiating different types of dump operations
       To initiate a dump operation that is to start as soon as the relevant Tape Coordinator is
       available, provide only the -volumeset, -dump, -portoffset, and optionally -append
       options. To schedule a single backup 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. The 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 appropriate).

       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 -dryrun 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 -dryrun flag with the options to be used on the actual command.

   How the Backup System executes a dump operation
       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 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.

       •   A name of the form volume_set_name.dump_level_name.tape_index, where 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 tape.

       •   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 the tape.

       •   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 -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:

       •   All dumps in the old dump set must be expired. The Backup System always checks
           expiration dates, even when name checking is disabled.

       •   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 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.

CAUTIONS

       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 Administration Guide 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 -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.

OPTIONS

       -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 flag.

       -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 argument.

       -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 -file argument.

       -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.

       -append
           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.

       -dryrun | -n
           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 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 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
           -dryrun options.

       -localauth
           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 backup(8).

       -help
           Prints the online help for this command. All other valid options are ignored.

OUTPUT

       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 header:

          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:

          Starting dump.

       If the issuer includes the -dryrun 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.

EXAMPLES

       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:
          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 -dryrun
          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

PRIVILEGE REQUIRED

       The issuer must be listed in the /etc/openafs/server/UserList file on 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 the -localauth flag is included, the issuer
       must instead be logged on to a server machine as the local superuser "root".

SEE ALSO

       butc(5), backup(8), backup_adddump(8), backup_addvolentry(8), backup_addvolset(8),
       backup_diskrestore(8), backup_labeltape(8), backup_volrestore(8), butc(8)

COPYRIGHT

       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.