doc/xml/AdminReference/sect8/backup_volrestore.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="backup_volrestore8">
   3   <refmeta>
   4     <refentrytitle>backup volrestore</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>backup volrestore</refname>
   9     <refpurpose>Restores one or more volumes</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">backup volrestore</emphasis> <emphasis role="bold">-server</emphasis> &lt;<emphasis>destination machine</emphasis>&gt;
  14         <emphasis role="bold">-partition</emphasis> &lt;<emphasis>destination partition</emphasis>&gt;
  15         <emphasis role="bold">-volume</emphasis> &lt;<emphasis>volume(s) to restore</emphasis>&gt;+
  16         [<emphasis role="bold">-extension</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;]
  17         [<emphasis role="bold">-date</emphasis> &lt;<emphasis>date from which to restore</emphasis>&gt;+]
  18         [<emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offsets</emphasis>&gt;+] [<emphasis role="bold">-n</emphasis>]
  19         [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-help</emphasis>]</para>
  20
  21     <para><emphasis role="bold">backup volr</emphasis> <emphasis role="bold">-s</emphasis> &lt;<emphasis>destination machine</emphasis>&gt;
  22         <emphasis role="bold">-pa</emphasis> &lt;<emphasis>destination partition</emphasis>&gt; <emphasis role="bold">-v</emphasis> &lt;<emphasis>volume(s) to restore</emphasis>&gt;+
  23         [<emphasis role="bold">-e</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;]
  24         [<emphasis role="bold">-d</emphasis> &lt;<emphasis>date from which to restore</emphasis>&gt;+] [<emphasis role="bold">-po</emphasis> &lt;<emphasis>TC port offsets</emphasis>&gt;+]
  25         [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-l</emphasis>] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-h</emphasis>]</para>
  26
  27   </refsect1>
  28   <refsect1>
  29     <title>Description</title>
  30     <para>The <emphasis role="bold">backup volrestore</emphasis> command restores the contents of one or more
  31     volumes to the site indicated by the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
  32     arguments. Use the command either to overwrite the contents of existing
  33     volumes with the restored data or to create new volumes while retaining
  34     the existing ones. The specified site does not have to be the current site
  35     for the volumes.</para>
  36
  37     <para>(If the <computeroutput>FILE YES</computeroutput> instruction appears in the
  38     <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file associated with the specified
  39     port offset, then the <emphasis role="bold">backup volrestore</emphasis> command restores data from the
  40     backup data file listed for that port offset in the Tape Coordinator's
  41     <replaceable>/usr/afs/backup/tapeconfig</replaceable> file, rather than from tape. For the sake of
  42     clarity, the following text refers to tapes only, but the Backup System
  43     handles backup data files in much the same way.)</para>
  44
  45     <para>The command's arguments can be combined as indicated:</para>
  46
  47     <itemizedlist>
  48       <listitem>
  49         <para>To preserve a volume's current contents and also create a new volume to
  50         house the restored version, use the <emphasis role="bold">-extension</emphasis> argument.  The Backup
  51         System creates the new volume on the server and partition named by the
  52         <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, assigns it the same name as the
  53         current volume with the addition of the specified extension, and creates a
  54         new Volume Location Database (VLDB) entry for it.  Creating a new volume
  55         enables the administrator to compare the two versions.</para>
  56
  57       </listitem>
  58       <listitem>
  59         <para>To overwrite a volume's existing contents with the restored version, omit
  60         the <emphasis role="bold">-extension</emphasis> argument, and specify the site as indicated:</para>
  61
  62         <itemizedlist>
  63           <listitem>
  64             <para>To retain the current site, specify it with the <emphasis role="bold">-server</emphasis> and
  65             <emphasis role="bold">-partition</emphasis> arguments.</para>
  66
  67           </listitem>
  68           <listitem>
  69             <para>To move the volume to a different site while overwriting it, specify the
  70             new site with the <emphasis role="bold">-server</emphasis> argument, <emphasis role="bold">-partition</emphasis> argument, or
  71             both. The Backup System creates a new volume at that site, removes the
  72             existing volume, and updates the site information in the volume's VLDB
  73             entry. The backup version of the volume is not removed automatically from
  74             the original site, if it exists. Use the <emphasis role="bold">vos remove</emphasis> command to remove
  75             it and the <emphasis role="bold">vos backup</emphasis> command to create a backup version at the new
  76             site.</para>
  77
  78           </listitem>
  79         </itemizedlist>
  80       </listitem>
  81       <listitem>
  82         <para>To restore a volume that no longer exists in the file system, specify its
  83         name with the <emphasis role="bold">-volume</emphasis> argument and use the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
  84         arguments to place it at the desired site. The Backup System creates a new
  85         volume and new VLDB entry.</para>
  86
  87       </listitem>
  88     </itemizedlist>
  89     <para>In each case, the command sets each volume's creation date to the date and
  90     time at which it restores it. The creation date appears in the <computeroutput>Creation</computeroutput>
  91     field in the output from the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands.</para>
  92
  93     <para>If restoring all of the volumes that resided on a single partition, it is
  94     usually more efficient to use the <emphasis role="bold">backup diskrestore</emphasis> command. If
  95     restoring multiple volumes to many different sites, it can be more
  96     efficient to use the <emphasis role="bold">backup volsetrestore</emphasis> command.</para>
  97
  98     <para>By default, the backup volrestore command restores the most recent full
  99     dump and all subsequent incremental dumps for each volume, bringing the
 100     restored volumes to the most current possible state. To restore the
 101     volumes to their state at some time in the past, use the <emphasis role="bold">-date</emphasis>
 102     argument. The Backup System restores the most recent full dump and each
 103     subsequent incremental dump for which the <emphasis>clone date</emphasis> of the volume
 104     included in the dump is before the indicated date and time (the clone date
 105     timestamp appears in the <computeroutput>clone date</computeroutput> field of the output from the
 106     <emphasis role="bold">backup volinfo</emphasis> command). For backup and read-only volumes, the clone
 107     date represents the time at which the volume was copied from its
 108     read/write source; for read/write volumes, it represents the time at which
 109     the volume was locked for inclusion in the dump. The resemblance of a
 110     restored volume to its actual state at the indicated time depends on the
 111     amount of time that elapsed between the volume's clone date in the last
 112     eligible dump and the specified time.</para>
 113
 114     <para>If the <emphasis role="bold">-volume</emphasis> argument specifies the base (read/write) form of the
 115     volume name, the Backup System searches the Backup Database for the newest
 116     dump set that includes a dump of either the read/write or the backup
 117     version of the volume. It restores the dumps of that version of the
 118     volume, starting with the most recent full dump. If, in contrast, the
 119     volume name explicitly includes the <computeroutput>.backup</computeroutput> or <computeroutput>.readonly</computeroutput> extension,
 120     the Backup System restores dumps of the corresponding volume version only.</para>
 121
 122     <para>To generate a list of the tapes the Backup System needs to perform the
 123     restore operation, without actually performing it, combine the <emphasis role="bold">-n</emphasis> flag
 124     with the options to be used on the actual command.</para>
 125
 126     <para>If all of the full and incremental dumps of all relevant volumes were not
 127     written to a type of tape that a single Tape Coordinator can read, use the
 128     <emphasis role="bold">-portoffset</emphasis> argument to list multiple port offset numbers in the order
 129     in which the tapes are needed (first list the port offset for the full
 130     dump, second the port offset for the level 1 incremental dump, and so
 131     on). If restoring multiple volumes, the same ordered list of port offsets
 132     must apply to all of them. If not, either issue this command separately
 133     for each volume, or use the <emphasis role="bold">vos volsetrestore</emphasis> command after defining
 134     groups of volumes that were dumped to compatible tape types. For further
 135     discussion, see the <emphasis>IBM AFS Administration Guide</emphasis>.</para>
 136
 137     <para>The Tape Coordinator's default response to this command is to access the
 138     first tape it needs by invoking the <emphasis role="bold">MOUNT</emphasis> instruction in the local
 139     <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file, or by prompting the backup
 140     operator to insert the tape if there is no <computeroutput>MOUNT</computeroutput> instruction. However,
 141     if the <computeroutput>AUTOQUERY NO</computeroutput> instruction appears in the <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable>
 142     file, or if the issuer of the <emphasis role="bold">butc</emphasis> command included the <emphasis role="bold">-noautoquery</emphasis>
 143     flag, the Tape Coordinator instead expects the tape to be in the device
 144     already. If it is not, or is the wrong tape, the Tape Coordinator invokes
 145     the <computeroutput>MOUNT</computeroutput> instruction or prompts the operator. It also invokes the
 146     <computeroutput>MOUNT</computeroutput> instruction or prompts for any additional tapes needed to
 147     complete the restore operation; the backup operator must arrange to
 148     provide them.</para>
 149
 150   </refsect1>
 151   <refsect1>
 152     <title>Options</title>
 153     <variablelist>
 154       <varlistentry>
 155         <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>destination machine</emphasis>&gt;</term>
 156         <listitem>
 157           <para>Names the file server machine on which to restore each volume. If this
 158           argument and the <emphasis role="bold">-partition</emphasis> argument indicate a site other than the
 159           current site for each volume, and the <emphasis role="bold">-extension</emphasis> argument is not also
 160           provided, the Backup System removes the existing volumes from their
 161           current sites, places the restored contents at the specified site, and
 162           changes the site information in the volume's VLDB entry.</para>
 163
 164         </listitem>
 165       </varlistentry>
 166       <varlistentry>
 167         <term><emphasis role="bold">-partition</emphasis> &lt;<emphasis>destination partition</emphasis>&gt;</term>
 168         <listitem>
 169           <para>Names the partition to which to restore each volume. If this argument and
 170           the <emphasis role="bold">-server</emphasis> argument indicate a site other than the current site for
 171           each volume, and the <emphasis role="bold">-extension</emphasis> argument is not also provided, the
 172           Backup System removes the existing volumes from their current sites,
 173           places the restored contents at the specified site, and changes the site
 174           information in the volume's VLDB entry.</para>
 175
 176         </listitem>
 177       </varlistentry>
 178       <varlistentry>
 179         <term><emphasis role="bold">-volume</emphasis> &lt;<emphasis>volume to restore</emphasis>&gt;+</term>
 180         <listitem>
 181           <para>Names one or more volumes to restore, using the volume name as listed in
 182           the Backup Database. Provide the base (read/write) name of each volume to
 183           have the Backup System search the Backup Database for the newest dump set
 184           that includes a dump of either the read/write or the backup version of the
 185           volume; it restores the dumps of that version of the volume, starting with
 186           the most recent full dump. If, in contrast, a volume name explicitly
 187           includes the <computeroutput>.backup</computeroutput> or <computeroutput>.readonly</computeroutput> extension, the Backup System
 188           restores dumps of the corresponding volume version only.</para>
 189
 190         </listitem>
 191       </varlistentry>
 192       <varlistentry>
 193         <term><emphasis role="bold">-extension</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;</term>
 194         <listitem>
 195           <para>Creates a new volume to house the restored data, with a name derived by
 196           appending the specified string to each volume named by the <emphasis role="bold">-volume</emphasis>
 197           argument. The Backup System creates a new VLDB entry for the volume. Any
 198           string other than <computeroutput>.readonly</computeroutput> or <computeroutput>.backup</computeroutput> is acceptable, but the
 199           combination of the existing volume name and extension cannot exceed 22
 200           characters in length. To use a period to separate the extension from the
 201           name, specify it as the first character of the string (as in <computeroutput>.rst</computeroutput>, for
 202           example).</para>
 203
 204         </listitem>
 205       </varlistentry>
 206       <varlistentry>
 207         <term><emphasis role="bold">-date</emphasis> &lt;<emphasis>date from which to restore</emphasis>&gt;+</term>
 208         <listitem>
 209           <para>Specifies a date and optionally time; the restored volume includes data
 210           from dumps performed before the date only. Provide a value in the format
 211           <emphasis>mm/dd/yyyy</emphasis> [<emphasis>hh</emphasis>:<emphasis>MM</emphasis>], where the required <emphasis>mm/dd/yyyy</emphasis> portion
 212           indicates the month (<emphasis>mm</emphasis>), day (<emphasis>dd</emphasis>), and year (<emphasis>yyyy</emphasis>), and the
 213           optional <emphasis>hh:MM</emphasis> portion indicates the hour and minutes in 24-hour format
 214           (for example, the value <computeroutput>14:36</computeroutput> represents 2:36 p.m.). If omitted, the
 215           time defaults to 59 seconds after midnight (00:00:59 hours).</para>
 216
 217           <para>Valid values for the year range from <computeroutput>1970</computeroutput> to <computeroutput>2037</computeroutput>; higher values are
 218           not valid because the latest possible date in the standard UNIX
 219           representation is in February 2038. The command interpreter automatically
 220           reduces any later date to the maximum value.</para>
 221
 222           <para>If this argument is omitted, the Backup System restores all possible dumps
 223           including the most recently created.</para>
 224
 225         </listitem>
 226       </varlistentry>
 227       <varlistentry>
 228         <term><emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offest</emphasis>&gt;+</term>
 229         <listitem>
 230           <para>Specifies one or more port offset numbers (up to a maximum of 128), each
 231           corresponding to a Tape Coordinator to use in the operation. If there is
 232           more than one value, the Backup System uses the first one when restoring
 233           the full dump of each volume, the second one when restoring the level 1
 234           incremental dump of each volume, and so on. It uses the final value in the
 235           list when restoring dumps at the corresponding depth in the dump hierarchy
 236           and all dumps at lower levels.</para>
 237
 238           <para>Provide this argument unless the default value of 0 (zero) is appropriate
 239           for all dumps. If <computeroutput>0</computeroutput> is just one of the values in the list, provide it
 240           explicitly in the appropriate order.</para>
 241
 242         </listitem>
 243       </varlistentry>
 244       <varlistentry>
 245         <term><emphasis role="bold">-n</emphasis></term>
 246         <listitem>
 247           <para>Displays the list of tapes that contain the dumps required by the restore
 248           operation, without actually performing the operation.</para>
 249
 250         </listitem>
 251       </varlistentry>
 252       <varlistentry>
 253         <term><emphasis role="bold">-localauth</emphasis></term>
 254         <listitem>
 255           <para>Constructs a server ticket using a key from the local
 256           <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">backup</emphasis> command interpreter presents
 257           it to the Backup Server, Volume Server and VL Server during mutual
 258           authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument. For
 259           more details, see <link linkend="backup8">backup(8)</link>.</para>
 260
 261         </listitem>
 262       </varlistentry>
 263       <varlistentry>
 264         <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
 265         <listitem>
 266           <para>Names the cell in which to run the command. Do not combine this argument
 267           with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="backup8">backup(8)</link>.</para>
 268
 269         </listitem>
 270       </varlistentry>
 271       <varlistentry>
 272         <term><emphasis role="bold">-help</emphasis></term>
 273         <listitem>
 274           <para>Prints the online help for this command. All other valid options are
 275           ignored.</para>
 276
 277         </listitem>
 278       </varlistentry>
 279     </variablelist>
 280   </refsect1>
 281   <refsect1>
 282     <title>Output</title>
 283     <para>If the issuer includes the <emphasis role="bold">-n</emphasis> flag with the command, the following
 284     string appears at the head of the list of the tapes necessary to complete
 285     the restore operation.</para>
 286
 287 <programlisting>
 288    Tapes needed:
 289
 290 </programlisting>
 291     </refsect1>
 292     <refsect1>
 293       <title>Examples</title>
 294       <para>The following command restores the volume user.pat to partition <replaceable>/vicepa</replaceable>
 295       on machine <computeroutput>fs5.abc.com</computeroutput>:</para>
 296
 297 <programlisting>
 298    % backup volrestore -server fs5.abc.com -partition a -volume user.pat
 299
 300 </programlisting>
 301         <para>The following command restores the volumes <computeroutput>user.smith</computeroutput> and <computeroutput>user.terry</computeroutput>
 302         to partition <replaceable>/vicepb</replaceable> on machine <computeroutput>fs4.abc.com</computeroutput>, adding a <computeroutput>.rst</computeroutput>
 303         extension to each volume name and preserving the existing <computeroutput>user.smith</computeroutput>
 304         and <computeroutput>user.terry</computeroutput> volumes.  Only dumps created before 5:00 p.m. on 31
 305         January 1998 are restored. (The command is shown here on multiple lines
 306         only for legibility reasons.)</para>
 307
 308 <programlisting>
 309    % backup volrestore -server fs4.abc.com -partition b  \
 310                        -volume user.smith user.terry  \
 311                        -extension .rst -date 1/31/1998 17:00
 312
 313 </programlisting>
 314           <para>The following command restores the volume user.pat to partition <replaceable>/vicepb</replaceable>
 315           on machine <computeroutput>fs4.abc.com</computeroutput>. The Tape Coordinator with port offset 1 handles
 316           the tape containing the full dump; the Tape Coordinator with port offset 0
 317           handles all tapes containing incremental dumps. (The command is shown here
 318           on two lines only for legibility reasons.)</para>
 319
 320 <programlisting>
 321    % backup volrestore -server fs5.abc.com -partition a  \
 322                        -volume user.pat -portoffset 1 0
 323
 324 </programlisting>
 325           </refsect1>
 326           <refsect1>
 327             <title>Privilege Required</title>
 328             <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on every
 329             machine where the Backup Server or Volume Location (VL) Server is running,
 330             and on every file server machine that houses an affected volume. If the
 331             <emphasis role="bold">-localauth</emphasis> flag is included, the issuer must instead be logged on to a
 332             server machine as the local superuser <computeroutput>root</computeroutput>.</para>
 333
 334           </refsect1>
 335           <refsect1>
 336             <title>See Also</title>
 337             <para><link linkend="butc5">butc(5)</link>,
 338             <link linkend="backup8">backup(8)</link>,
 339             <link linkend="backup_dump8">backup_dump(8)</link>,
 340             <link linkend="backup_diskrestore8">backup_diskrestore(8)</link>,
 341             <link linkend="backup_volsetrestore8">backup_volsetrestore(8)</link>,
 342             <link linkend="butc8">butc(8)</link>,
 343             <link linkend="vos_backup1">vos_backup(1)</link>,
 344             <link linkend="vos_remove1">vos_remove(1)</link></para>
 345
 346           </refsect1>
 347           <refsect1>
 348             <title>Copyright</title>
 349             <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 350
 351             <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 352             converted from HTML to POD by software written by Chas Williams and Russ
 353             Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 354
 355           </refsect1>
 356         </refentry>