doc/xml/AdminReference/sect8/backup_setexp.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="backup_setexp8">
   3   <refmeta>
   4     <refentrytitle>backup setexp</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>backup setexp</refname>
   9     <refpurpose>Sets the expiration date for existing dump levels.</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">backup setexp</emphasis> <emphasis role="bold">-dump</emphasis> &lt;<emphasis>dump level name</emphasis>&gt;+
  14         [<emphasis role="bold">-expires</emphasis> &lt;<emphasis>expiration date</emphasis>&gt;+] [<emphasis role="bold">-localauth</emphasis>]
  15         [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-help</emphasis>]</para>
  16
  17     <para><emphasis role="bold">backup se</emphasis> <emphasis role="bold">-d</emphasis> &lt;<emphasis>dump level name</emphasis>&gt;+ [<emphasis role="bold">-e</emphasis> &lt;<emphasis>expiration date</emphasis>&gt;+]
  18         [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-h</emphasis>]</para>
  19
  20   </refsect1>
  21   <refsect1>
  22     <title>Description</title>
  23     <para>The <emphasis role="bold">backup setexp</emphasis> command sets or changes the expiration date
  24     associated with each specified dump level, which must already exist in the
  25     dump hierarchy.</para>
  26
  27     <para>Use the <emphasis role="bold">-expires</emphasis> 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 <emphasis role="bold">backup
  33     labeltape</emphasis> 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.</para>
  36
  37     <para>(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 <emphasis role="bold">backup
  41     deletedump</emphasis> command.)</para>
  42
  43     <para>Define either an absolute or relative expiration date:</para>
  44
  45     <itemizedlist>
  46       <listitem>
  47         <para>An absolute expiration date defines the month/day/year (and, optionally,
  48         hour and minutes) at which a dump expires. If the expiration date predates
  49         the dump creation time, the Backup System immediately treats the dump as
  50         expired.</para>
  51
  52       </listitem>
  53       <listitem>
  54         <para>A relative date defines the number of years, months, or days (or a
  55         combination of the three) after the dump's creation that it expires. When
  56         the Backup System creates a dump at the dump level, it calculates an
  57         actual expiration date by adding the relative date to the start time of
  58         the dump operation.</para>
  59
  60       </listitem>
  61     </itemizedlist>
  62     <para>If the command is used to change an existing expiration date associated
  63     with a dump level, the new date applies only to dumps created after the
  64     change. Existing dumps retain the expiration date assigned at the time
  65     they were created.</para>
  66
  67   </refsect1>
  68   <refsect1>
  69     <title>Options</title>
  70     <variablelist>
  71       <varlistentry>
  72         <term><emphasis role="bold">-dump</emphasis> &lt;<emphasis>dump level name</emphasis>&gt;+</term>
  73         <listitem>
  74           <para>Specifies the full pathname of each dump level to assign the expiration
  75           date specified by the <emphasis role="bold">-expires</emphasis> argument.</para>
  76
  77         </listitem>
  78       </varlistentry>
  79       <varlistentry>
  80         <term><emphasis role="bold">-expires</emphasis> &lt;<emphasis>expiration date</emphasis>&gt;+</term>
  81         <listitem>
  82           <para>Defines the absolute or relative expiration date to associate with each
  83           dump level named by the <emphasis role="bold">-dump</emphasis> argument. Absolute expiration dates have
  84           the following format:</para>
  85
  86 <programlisting>
  87    [at] {NEVER | &amp;lt;mm&amp;gt;/&amp;lt;dd&amp;gt;/&amp;lt;yyyy&amp;gt; [&amp;lt;hh&amp;gt;:&amp;lt;MM&amp;gt;] }
  88
  89 </programlisting>
  90             <para>where the optional word at is followed either by the string <computeroutput>NEVER</computeroutput>,
  91             which indicates that dumps created at the dump level never expire, or by a
  92             date value with a required portion (&lt;mm&gt; for month, &lt;dd&gt; for day, and
  93             &lt;yyyy&gt; for year) and an optional portion (&lt;hh&gt; for hours and &lt;MM&gt; for
  94             minutes).</para>
  95
  96             <para>Omit the &lt;hh&gt;:&lt;MM&gt; portion to use the default of midnight (00:00 hours),
  97             or provide a value in 24-hour format (for example, <computeroutput>20:30</computeroutput> is 8:30 p.m.).
  98             Valid values for the year range from <computeroutput>1970</computeroutput> to <computeroutput>2037</computeroutput>; higher values are
  99             not valid because the latest possible date in the standard UNIX
 100             representation is in February 2038. The command interpreter automatically
 101             reduces later dates to the maximum value.</para>
 102
 103             <para>Relative expiration dates have the following format:</para>
 104
 105 <programlisting>
 106    [in] [&amp;lt;years&amp;gt;y] [&amp;lt;months&amp;gt;m] [&amp;lt;days&amp;gt;d]
 107
 108 </programlisting>
 109               <para>where the optional word in is followed by at least one of a number of
 110               years (maximum <computeroutput>9999</computeroutput>) followed by the letter <computeroutput>y</computeroutput>, a number of months
 111               (maximum <computeroutput>12</computeroutput>) followed by the letter <computeroutput>m</computeroutput>, or a number of days (maximum
 112               <computeroutput>31</computeroutput>) followed by the letter <computeroutput>d</computeroutput>. 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.</para>
 117
 118             </listitem>
 119           </varlistentry>
 120           <varlistentry>
 121             <term><emphasis role="bold">-localauth</emphasis></term>
 122             <listitem>
 123               <para>Constructs a server ticket using a key from the local
 124               <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">backup</emphasis> command interpreter presents
 125               it to the Backup Server, Volume Server and VL Server during mutual
 126               authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument. For
 127               more details, see <link linkend="backup8">backup(8)</link>.</para>
 128
 129             </listitem>
 130           </varlistentry>
 131           <varlistentry>
 132             <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
 133             <listitem>
 134               <para>Names the cell in which to run the command. Do not combine this argument
 135               with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="backup8">backup(8)</link>.</para>
 136
 137             </listitem>
 138           </varlistentry>
 139           <varlistentry>
 140             <term><emphasis role="bold">-help</emphasis></term>
 141             <listitem>
 142               <para>Prints the online help for this command. All other valid options are
 143               ignored.</para>
 144
 145             </listitem>
 146           </varlistentry>
 147         </variablelist>
 148       </refsect1>
 149       <refsect1>
 150         <title>Examples</title>
 151         <para>The following example associates an absolute expiration date of 10:00
 152         p.m. on 31 December 1999 with the dump level <computeroutput>/1998/december</computeroutput>:</para>
 153
 154 <programlisting>
 155    % backup setexp -dump /1998/december -expires at 12/31/1999 22:00
 156
 157 </programlisting>
 158           <para>The following example associates a relative expiration date of 7 days with
 159           the two dump levels <computeroutput>/monthly/week1</computeroutput> and <computeroutput>/monthly/week2</computeroutput>:</para>
 160
 161 <programlisting>
 162    % backup setexp -dump /monthly/week1 /monthly/week -expires 7d
 163
 164 </programlisting>
 165           </refsect1>
 166           <refsect1>
 167             <title>Privilege Required</title>
 168             <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on every
 169             machine where the Backup Server is running, or must be logged onto a
 170             server machine as the local superuser <computeroutput>root</computeroutput> if the <emphasis role="bold">-localauth</emphasis> flag is
 171             included.</para>
 172
 173           </refsect1>
 174           <refsect1>
 175             <title>See Also</title>
 176             <para><link linkend="backup8">backup(8)</link>,
 177             <link linkend="backup_adddump8">backup_adddump(8)</link>,
 178             <link linkend="backup_deldump8">backup_deldump(8)</link>,
 179             <link linkend="backup_listdumps8">backup_listdumps(8)</link></para>
 180
 181           </refsect1>
 182           <refsect1>
 183             <title>Copyright</title>
 184             <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 185
 186             <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 187             converted from HTML to POD by software written by Chas Williams and Russ
 188             Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 189
 190           </refsect1>
 191         </refentry>