doc/man-pages/pod8/backup_setexp.pod

   1 =head1 NAME
   2
   3 backup_setexp - Sets the expiration date for existing dump levels.
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<backup setexp> S<<< B<-dump> <I<dump level name>>+ >>>
  11     S<<< [B<-expires> <I<expiration date>>+] >>> [B<-localauth>]
  12     S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]
  13
  14 B<backup se> 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 setexp> command sets or changes the expiration date
  24 associated with each specified dump level, which must already exist in the
  25 dump hierarchy.
  26
  27 Use the B<-expires> argument to associate an expiration date with each
  28 dump level. When the Backup System subsequently creates a dump at the dump
  29 level, it uses the specified value to derive the dump's expiration date,
  30 which it records on the label of the tape (or backup data file). The
  31 Backup System refuses to overwrite a tape until after the latest
  32 expiration date of any dump that the tape contains, unless the B<backup
  33 labeltape> command is used to relabel the tape. If a dump level does not
  34 have an expiration date, the Backup System treats dumps created at the
  35 level as expired as soon as it creates them.
  36
  37 (Note that the Backup System does not automatically remove a dump's record
  38 from the Backup Database when the dump reaches its expiration date, but
  39 only if the tape that contains the dump is recycled or relabeled. To
  40 remove expired and other obsolete dump records, use the B<backup
  41 deletedump> command.)
  42
  43 Define either an absolute or relative expiration date:
  44
  45 =over 4
  46
  47 =item *
  48
  49 An absolute expiration date defines the month/day/year (and, optionally,
  50 hour and minutes) at which a dump expires. If the expiration date predates
  51 the dump creation time, the Backup System immediately treats the dump as
  52 expired.
  53
  54 =item *
  55
  56 A relative date defines the number of years, months, or days (or a
  57 combination of the three) after the dump's creation that it expires. When
  58 the Backup System creates a dump at the dump level, it calculates an
  59 actual expiration date by adding the relative date to the start time of
  60 the dump operation.
  61
  62 =back
  63
  64 If the command is used to change an existing expiration date associated
  65 with a dump level, the new date applies only to dumps created after the
  66 change. Existing dumps retain the expiration date assigned at the time
  67 they were created.
  68
  69 =head1 OPTIONS
  70
  71 =over 4
  72
  73 =item B<-dump> <I<dump level name>>+
  74
  75 Specifies the full pathname of each dump level to assign the expiration
  76 date specified by the B<-expires> argument.
  77
  78 =item B<-expires> <I<expiration date>>+
  79
  80 Defines the absolute or relative expiration date to associate with each
  81 dump level named by the B<-dump> argument. Absolute expiration dates have
  82 the following format:
  83
  84    [at] {NEVER | <mm>/<dd>/<yyyy> [<hh>:<MM>] }
  85
  86 where the optional word at is followed either by the string C<NEVER>,
  87 which indicates that dumps created at the dump level never expire, or by a
  88 date value with a required portion (<mm> for month, <dd> for day, and
  89 <yyyy> for year) and an optional portion (<hh> for hours and <MM> for
  90 minutes).
  91
  92 Omit the <hh>:<MM> portion to use the default of midnight (00:00 hours),
  93 or provide a value in 24-hour format (for example, C<20:30> is 8:30 p.m.).
  94 Valid values for the year range from C<1970> to C<2037>; higher values are
  95 not valid because the latest possible date in the standard UNIX
  96 representation is in February 2038. The command interpreter automatically
  97 reduces later dates to the maximum value.
  98
  99 Relative expiration dates have the following format:
 100
 101    [in] [<years>y] [<months>m] [<days>d]
 102
 103 where the optional word in is followed by at least one of a number of
 104 years (maximum C<9999>) followed by the letter C<y>, a number of months
 105 (maximum C<12>) followed by the letter C<m>, or a number of days (maximum
 106 C<31>) followed by the letter C<d>. If providing more than one of the
 107 three, list them in the indicated order. If the date that results from
 108 adding the relative expiration value to a dump's creation time is later
 109 than the latest possible date in the UNIX time representation, the Backup
 110 System automatically reduces it to that date.
 111
 112 =item B<-localauth>
 113
 114 Constructs a server ticket using a key from the local
 115 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
 116 it to the Backup Server, Volume Server and VL Server during mutual
 117 authentication. Do not combine this flag with the B<-cell> argument. For
 118 more details, see L<backup(8)>.
 119
 120 =item B<-cell> <I<cell name>>
 121
 122 Names the cell in which to run the command. Do not combine this argument
 123 with the B<-localauth> flag. For more details, see L<backup(8)>.
 124
 125 =item B<-help>
 126
 127 Prints the online help for this command. All other valid options are
 128 ignored.
 129
 130 =back
 131
 132 =head1 EXAMPLES
 133
 134 The following example associates an absolute expiration date of 10:00
 135 p.m. on 31 December 1999 with the dump level C</1998/december>:
 136
 137    % backup setexp -dump /1998/december -expires at 12/31/1999 22:00
 138
 139 The following example associates a relative expiration date of 7 days with
 140 the two dump levels C</monthly/week1> and C</monthly/week2>:
 141
 142    % backup setexp -dump /monthly/week1 /monthly/week -expires 7d
 143
 144 =head1 PRIVILEGE REQUIRED
 145
 146 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
 147 machine where the Backup Server is running, or must be logged onto a
 148 server machine as the local superuser C<root> if the B<-localauth> flag is
 149 included.
 150
 151 =head1 SEE ALSO
 152
 153 L<backup(8)>,
 154 L<backup_adddump(8)>,
 155 L<backup_deldump(8)>,
 156 L<backup_listdumps(8)>
 157
 158 =head1 COPYRIGHT
 159
 160 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 161
 162 This documentation is covered by the IBM Public License Version 1.0.  It was
 163 converted from HTML to POD by software written by Chas Williams and Russ
 164 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.