Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / doc / man-pages / pod8 / backup_dump.pod

=head1 NAME

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

=head1 SYNOPSIS

=for html
<div class="synopsis">

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

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

=for html
</div>

=head1 DESCRIPTION

The B<backup dump> command either dumps the volume set specified by the
B<-volumeset> argument at the dump level specified by the B<-dump>
argument and creates a Backup Database dump record about it, or executes
the dump instructions listed in the file named by the B<-file>
argument. The Tape Coordinator indicated by the B<-portoffset> argument
(or on each command in the file) executes the operation.

(If the C<FILE YES> instruction appears in the
F</usr/afs/backup/CFG_I<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 F</usr/afs/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 I<dumping> refers to copying a collection of data to tape or a
backup data file, and the resulting collection is termed a I<dump>. The
set of tapes that contain one or more dumps is called a I<dump set>. The
first dump in a dump set is its I<initial dump>, and any dumps
subsequently added to the dump set (by use of the B<-append> argument) are
I<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 I<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 I<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 I<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 I<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 I<clone date> field of the
output from the B<backup volinfo> command. As an example, an incremental
dump at the C</full/week1/thursday> level includes only files and
directories that have changed since the volume set was dumped at the
C</full/week1> level.

=head2 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 B<-volumeset>, B<-dump>,
B<-portoffset>, and optionally B<-append> options. To schedule a single
B<backup dump> command to execute in the future, also include the B<-at>
argument to specify the start time.

To append a dump to an existing dump set, include the B<-append> flag. The
Backup System imposes the following conditions on appended dumps:

=over 4

=item *

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 B<-dbadd> argument to the
B<backup scantape> command to insert the necessary records into the
database.

=item *

The most recent dump on the tape or in the backup data file must have
completed successfully.

=item *

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

=back

To schedule multiple dump operations, list the operations in the file
named by the B<-file> argument. Optionally include the B<-at> argument to
specify when the B<backup> command interpreter reads the file; otherwise
it reads it immediately. Do not combine the B<-file> argument with the
command's first three arguments or the B<-append> or B<-dryrun> flags. The
commands in the file can include any of the B<backup dump> command's
arguments, including the B<-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 B<-dryrun> flag with the options to be used on the
actual command.

=head2 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 B<backup jobs> command; terminate them with
the B<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
C<ASK NO> instruction does not appear in the F<CFG_I<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
C<ASK NO> instruction appears in the F<CFG_I<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 B<-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
C<NAME_CHECK NO> instruction in the F<CFG_I<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 C<MOUNT> instruction in the
F<CFG_I<device_name>> file or prompting the operator.

=over 4

=item *

A name of the form I<volume_set_name.dump_level_name.tape_index>, where
I<volume_set_name> matches the value of the B<-volumeset> argument,
I<dump_level_name> matches the last element in the pathname value of the
B<-dump> argument, and I<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 C<user> at the dump level
C</sunday2/monday> has AFS tape name C<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.

=item *

The string C<< <NULL> >>, which usually indicates that a backup operator
has used the B<backup labeltape> command to write a label on the tape, but
did not include the B<-name> argument to assign an AFS tape
name. Presumably, the operator did include the B<-pname> argument to
assign a permanent name. If the label records a C<< <NULL> >> value, the
Backup System constructs and records on the label the appropriate AFS tape
name, and writes the dump on the tape.

=item *

No value at all, because the tape has never been labeled or used in the
Backup System. As when the AFS tape name is C<< <NULL> >>, the Backup
System constructs and records on the label the appropriate AFS tape name,
and writes the dump on the tape.

=back

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 B<-size> argument to the B<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 F<tapeconfig> file. If the
capacity field in the F<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:

=over 4

=item *

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

=item *

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.

=item *

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

=item *

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

=back

To recycle a tape before all dumps on it have expired or if the AFS tape
name is wrong, use the B<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 C<MOUNT> instruction in the
F<CFG_I<device_name>> file, or by prompting the backup operator to insert
the tape if there is no C<MOUNT> instruction.  However, if the C<AUTOQUERY
NO> instruction appears in the F<CFG_I<device_name>> file, or if the
issuer of the B<butc> command included the B<-noautoquery> flag, the Tape
Coordinator instead expects the tape to be in the device already. If it is
not, the Tape Coordinator invokes the C<MOUNT> instruction or prompts the
operator. It also invokes the C<MOUNT> instruction or prompts for any
additional tapes needed to complete the dump operation; the issuer must
arrange to provide them.

=head1 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 I<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
B<-portoffset> argument to the B<backup diskrestore> and B<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 B<backup
volrestore> command must be used to restore one volume at a time.

Valid (unexpired) administrative tokens must be available to the B<backup>
command interpreter both when it reads the file named by the B<-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 B<-localauth> flag on the B<backup> and B<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 B<-at> argument to schedule dump
operations.

=head1 OPTIONS

=over 4

=item B<-volumeset> <I<volume set name>>

Names the volume set to dump. The B<-dump> argument must be provided along
with this one; do not combine them with the B<-file> argument. If using a
temporary volume set, the B<vos dump> command must be issued within the
interactive session in which the B<backup addvolset> command was issued
with the B<-temporary> flag.

=item B<-dump> <I<dump level name>>

Specifies the complete pathname of the dump level at which to dump the
volume set. The B<-volumeset> argument must be provided along with this
one; do not combine them with the B<-file> argument.

=item B<-portoffset> <I<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 B<-file> argument.

=item B<-at> <I<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 B<-file> argument. Provide a value in the
format I<mm/dd/yyyy> [I<hh:MM>], where the month (I<mm>), day (I<dd>), and
year (I<yyyy>) are required. Valid values for the year range from C<1970>
to C<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 (I<hh:MM>) are optional, but if provided must be in
24-hour format (for example, the value C<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.

=item B<-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 B<-file> argument.

=item B<-dryrun> | B<-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 B<-file> argument.

=item B<-file> <I<load file>>

Specifies the local disk or AFS pathname of a file containing B<backup>
commands. The Backup System reads the file immediately, or at the time
specified by the B<-at> argument if it is provided. A partial pathname is
interpreted relative to the current working directory.

Place each B<backup dump> command on its own line in the indicated file,
using the same syntax as for the command line, but without the word
B<backup> at the start of the line. Each command must include a value for
the B<-volumeset> and B<-dump> arguments, and for the B<-portoffset>
argument unless the default value of 0 is appropriate. Commands in the
file can also include any of the B<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 B<-volumeset>, B<-dump>,
B<-portoffset>, B<-append>, or B<-dryrun> options.

=item B<-localauth>

Constructs a server ticket using a key from the local
F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
it to the Backup Server, Volume Server and VL Server during mutual
authentication. Do not combine this flag with the B<-cell> argument. For
more details, see L<backup(8)>.

=item B<-cell> <I<cell name>>

Names the cell in which to run the command. Do not combine this argument
with the B<-localauth> flag. For more details, see L<backup(8)>.

=item B<-help>

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

=back

=head1 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 B<-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 I<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.

=head1 EXAMPLES

The following command dumps the volumes in the volume set called C<user>
at the dump level C</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 C<sys_sun> volume set at the C</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
C<user> at the dump level C</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

=head1 PRIVILEGE REQUIRED

The issuer must be listed in the F</usr/afs/etc/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
B<-localauth> flag is included, the issuer must instead be logged on to a
server machine as the local superuser C<root>.

=head1 SEE ALSO

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

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