doc/man-pages/pod8/backup_adddump.pod

   1 =head1 NAME
   2
   3 backup adddump - Defines a dump level in the dump hierarchy
   4
   5 =head1 SYNOPSIS
   6
   7 B<backup adddump> B<-dump> <I<dump level name>>+
   8     [B<-expires> <I<expiration date>>+]
   9     [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
  10
  11 B<backup addd> B<-d> <I<dump level name>>+ [B<-e> <I<expiration date>>+]
  12     [B<-l>] [B<-c> <I<cell name>>] [B<-h>]
  13
  14 =head1 DESCRIPTION
  15
  16 The B<backup adddump> command creates one or more dump levels in the dump
  17 hierarchy stored in the Backup Database, and optionally assigns an
  18 expiration date to each one. All of the dump levels in the Backup Database
  19 collectively constitute the dump hierarchy.
  20
  21 Use the B<-expires> argument to associate an expiration date with each
  22 dump level. When the Backup System subsequently creates a dump at the dump
  23 level, it uses the specified value to derive the dump's expiration date,
  24 which it records on the label of the tape (or backup data file). The
  25 Backup System refuses to overwrite a tape until after the latest
  26 expiration date of any dump that the tape contains, unless the B<backup
  27 labeltape> command is used to relabel the tape. If a dump level does not
  28 have an expiration date, the Backup System treats dumps created at the
  29 level as expired as soon as it creates them.
  30
  31 (Note that the Backup System does not automatically remove a dump's record
  32 from the Backup Database when the dump reaches its expiration date, but
  33 only if the tape that contains the dump is recycled or relabeled. To
  34 remove expired and other obsolete dump records, use the B<backup
  35 deletedump> command.)
  36
  37 Define either an absolute or relative expiration date:
  38
  39 =over 4
  40
  41 =item *
  42
  43 An absolute expiration date defines the month/day/year (and, optionally,
  44 hour and minutes) at which a dump expires. If the expiration date predates
  45 the dump creation time, the Backup System immediately treats the dump as
  46 expired.
  47
  48 =item *
  49
  50 A relative date defines the number of years, months, or days (or a
  51 combination of the three) after the dump's creation that it expires. When
  52 the Backup System creates a dump at the dump level, it calculates an
  53 actual expiration date by adding the relative date to the start time of
  54 the dump operation.
  55
  56 =back
  57
  58 =head1 OPTIONS
  59
  60 =over 4
  61
  62 =item B<-dump> <I<dump level name>>+
  63
  64 Names each dump level to add to the dump hierarchy. Precede full dump
  65 level names with a slash (for example, C</full>). Indicate an incremental
  66 dump level by preceding it with an ordered list of the dump levels
  67 directly above it in the hierarchy (its parent dump levels); use the slash
  68 as a separator. The parent dump levels must already exist. For example,
  69 the dump levels C</full> and C</full/incremental1> must exist when the
  70 incremental dump level C</full/incremental1/incremental2> is created.
  71
  72 Dump level names can have any number of levels, but cannot exceed 256
  73 characters in length, including the slashes. The maximum length for any
  74 single level (the text between slashes) is 28 characters, not including
  75 the preceding slash.
  76
  77 All alphanumeric characters are allowed in dump level names. Do not use
  78 the period (C<.>), however, because it is the separator between the volume
  79 set name and dump level name in the dump name assigned automatically by
  80 the B<backup dump> command. It is best not to include other metacharacters
  81 either; if using them, enclose them in double quotes (C<" ">) when issuing
  82 the B<backup adddump> command outside interactive mode.
  83
  84 =item B<-expires> <I<expiration date>>+
  85
  86 Defines the absolute or relative expiration date to associate with each
  87 dump level named by the B<-dump> argument. Absolute expiration dates have
  88 the following format:
  89
  90    [at] {NEVER | <mm>/<dd>/<yyyy> [<hh>:<MM>] }
  91
  92 where the optional word at is followed either by the string C<NEVER>,
  93 which indicates that dumps created at the dump level never expire, or by a
  94 date value with a required portion (<mm> for month, <dd> for day, and
  95 <yyyy> for year) and an optional portion (<hh> for hours and <MM> for
  96 minutes).
  97
  98 Omit the I<hh:MM> portion to use the default of midnight (00:00 hours), or
  99 provide a value in 24-hour format (for example, C<20:30> is 8:30 p.m.).
 100 Valid values for the year range from C<1970> to C<2037>; higher values are
 101 not valid because the latest possible date in the standard UNIX
 102 representation is in February 2038. The command interpreter automatically
 103 reduces later dates to the maximum value.
 104
 105 Relative expiration dates have the following format:
 106
 107    [in] [<years>y] [<months>m] [<days>d]
 108
 109 where the optional word in is followed by at least one of a number of
 110 years (maximum C<9999>) followed by the letter C<y>, a number of months
 111 (maximum C<12>) followed by the letter C<m>, or a number of days (maximum
 112 C<31>) followed by the letter C<d>. If providing more than one of the
 113 three, list them in the indicated order. If the date that results from
 114 adding the relative expiration value to a dump's creation time is later
 115 than the latest possible date in the UNIX time representation, the Backup
 116 System automatically reduces it to that date.
 117
 118 =item B<-localauth>
 119
 120 Constructs a server ticket using a key from the local
 121 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
 122 it to the Backup Server, Volume Server and VL Server during mutual
 123 authentication. Do not combine this flag with the B<-cell> argument. For
 124 more details, see L<backup(8)>.
 125
 126 =item B<-cell> <I<cell name>>
 127
 128 Names the cell in which to run the command. Do not combine this argument
 129 with the B<-localauth> flag. For more details, see L<backup(8)>.
 130
 131 =item B<-help>
 132
 133 Prints the online help for this command. All other valid options are
 134 ignored.
 135
 136 =back
 137
 138 =head1 EXAMPLES
 139
 140 The following command defines a full dump called C</1999> with a relative
 141 expiration date of one year:
 142
 143    % backup adddump -dump /1999 -expires in 1y
 144
 145 The following command defines an incremental dump called
 146 C</sunday1/monday>1 with a relative expiration date of 13 days:
 147
 148    % backup adddump -dump /sunday1/monday1 -expires in 13d
 149
 150 The following command defines two dump incremental dump levels,
 151 C</Monthly/Week1> and C</Monthly/Week2>. Their parent, the full dump level
 152 C</Monthly>, must already exist. The expiration date for both levels is
 153 12:00 a.m. on 1 January 2000.
 154
 155    % backup adddump -dump /Monthly/Week1 /Monthly/Week2 -expires at 01/01/2000
 156
 157 =head1 PRIVILEGE REQUIRED
 158
 159 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 160 machine where the Backup Server is running, or must be logged onto a
 161 server machine as the local superuser C<root> if the B<-localauth> flag is
 162 included.
 163
 164 =head1 SEE ALSO
 165
 166 L<backup(8)>,
 167 L<backup_deldump(8)>,
 168 L<backup_deletedump(8)>,
 169 L<backup_listdumps(8)>,
 170 L<backup_setexp(8)>
 171
 172 =head1 COPYRIGHT
 173
 174 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 175
 176 This documentation is covered by the IBM Public License Version 1.0.  It was
 177 converted from HTML to POD by software written by Chas Williams and Russ
 178 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.