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