Import Upstream version 1.8.5

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

=head1 NAME

backup_adddump - Defines a dump level in the dump hierarchy

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<backup adddump> S<<< B<-dump> <I<dump level name>>+ >>>
    S<<< [B<-expires> <I<expiration date>>+] >>>
    [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]

B<backup addd> S<<< B<-d> <I<dump level name>>+ >>> 
    S<<< [B<-e> <I<expiration date>>+] >>>
    [B<-l>] S<<< [B<-c> <I<cell name>>] >>> [B<-h>]

=for html
</div>

=head1 DESCRIPTION

The B<backup adddump> command creates one or more dump levels in the dump
hierarchy stored in the Backup Database, and optionally assigns an
expiration date to each one. All of the dump levels in the Backup Database
collectively constitute the dump hierarchy.

Use the B<-expires> argument to associate an expiration date with each
dump level. When the Backup System subsequently creates a dump at the dump
level, it uses the specified value to derive the dump's expiration date,
which it records on the label of the tape (or backup data file). The
Backup System refuses to overwrite a tape until after the latest
expiration date of any dump that the tape contains, unless the B<backup
labeltape> command is used to relabel the tape. If a dump level does not
have an expiration date, the Backup System treats dumps created at the
level as expired as soon as it creates them.

(Note that the Backup System does not automatically remove a dump's record
from the Backup Database when the dump reaches its expiration date, but
only if the tape that contains the dump is recycled or relabeled. To
remove expired and other obsolete dump records, use the B<backup
deletedump> command.)

Define either an absolute or relative expiration date:

=over 4

=item *

An absolute expiration date defines the month/day/year (and, optionally,
hour and minutes) at which a dump expires. If the expiration date predates
the dump creation time, the Backup System immediately treats the dump as
expired.

=item *

A relative date defines the number of years, months, or days (or a
combination of the three) after the dump's creation that it expires. When
the Backup System creates a dump at the dump level, it calculates an
actual expiration date by adding the relative date to the start time of
the dump operation.

=back

=head1 OPTIONS

=over 4

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

Names each dump level to add to the dump hierarchy. Precede full dump
level names with a slash (for example, C</full>). Indicate an incremental
dump level by preceding it with an ordered list of the dump levels
directly above it in the hierarchy (its parent dump levels); use the slash
as a separator. The parent dump levels must already exist. For example,
the dump levels C</full> and C</full/incremental1> must exist when the
incremental dump level C</full/incremental1/incremental2> is created.

Dump level names can have any number of levels, but cannot exceed 256
characters in length, including the slashes. The maximum length for any
single level (the text between slashes) is 28 characters, not including
the preceding slash.

All alphanumeric characters are allowed in dump level names. Do not use
the period (C<.>), however, because it is the separator between the volume
set name and dump level name in the dump name assigned automatically by
the B<backup dump> command. It is best not to include other metacharacters
either; if using them, enclose them in double quotes (C<" ">) when issuing
the B<backup adddump> command outside interactive mode.

=item B<-expires> <I<expiration date>>+

Defines the absolute or relative expiration date to associate with each
dump level named by the B<-dump> argument. Absolute expiration dates have
the following format:

   [at] {NEVER | <mm>/<dd>/<yyyy> [<hh>:<MM>] }

where the optional word at is followed either by the string C<NEVER>,
which indicates that dumps created at the dump level never expire, or by a
date value with a required portion (<mm> for month, <dd> for day, and
<yyyy> for year) and an optional portion (<hh> for hours and <MM> for
minutes).

Omit the I<hh:MM> portion to use the default of midnight (00:00 hours), or
provide a value in 24-hour format (for example, C<20:30> is 8:30 p.m.).
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 command interpreter automatically
reduces later dates to the maximum value.

Relative expiration dates have the following format:

   [in] [<years>y] [<months>m] [<days>d]

where the optional word in is followed by at least one of a number of
years (maximum C<9999>) followed by the letter C<y>, a number of months
(maximum C<12>) followed by the letter C<m>, or a number of days (maximum
C<31>) followed by the letter C<d>. If providing more than one of the
three, list them in the indicated order. If the date that results from
adding the relative expiration value to a dump's creation time is later
than the latest possible date in the UNIX time representation, the Backup
System automatically reduces it to that date.

=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 EXAMPLES

The following command defines a full dump called C</1999> with a relative
expiration date of one year:

   % backup adddump -dump /1999 -expires in 1y

The following command defines an incremental dump called
C</sunday1/monday>1 with a relative expiration date of 13 days:

   % backup adddump -dump /sunday1/monday1 -expires in 13d

The following command defines two dump incremental dump levels,
C</Monthly/Week1> and C</Monthly/Week2>. Their parent, the full dump level
C</Monthly>, must already exist. The expiration date for both levels is
12:00 a.m. on 1 January 2000.

   % backup adddump -dump /Monthly/Week1 /Monthly/Week2 -expires at 01/01/2000

=head1 PRIVILEGE REQUIRED

The issuer must be listed in the F</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser C<root> if the B<-localauth> flag is
included.

=head1 SEE ALSO

L<backup(8)>,
L<backup_deldump(8)>,
L<backup_deletedump(8)>,
L<backup_listdumps(8)>,
L<backup_setexp(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.