| 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. |