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