doc/xml/AdminReference/sect8/backup_volsetrestore.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="backup_volsetrestore8">
   3   <refmeta>
   4     <refentrytitle>backup volsetrestore</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>backup volsetrestore</refname>
   9     <refpurpose>Restores all volumes in a volume set</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">backup volsetrestore</emphasis> [<emphasis role="bold">-name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;]
  14         [<emphasis role="bold">-file</emphasis> &lt;<emphasis>file name</emphasis>&gt;] [<emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;+]
  15         [<emphasis role="bold">-extension</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;] [<emphasis role="bold">-n</emphasis>]
  16         [<emphasis role="bold">-localauth</emphasis>] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;] [<emphasis role="bold">-help</emphasis>]</para>
  17
  18     <para><emphasis role="bold">backup vols</emphasis> [<emphasis role="bold">-na</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;] [<emphasis role="bold">-f</emphasis> &lt;<emphasis>file name</emphasis>&gt;]
  19         [<emphasis role="bold">-p</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;+] [<emphasis role="bold">-e</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;]
  20         [<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>
  21
  22   </refsect1>
  23   <refsect1>
  24     <title>Description</title>
  25     <para>The <emphasis role="bold">backup volsetrestore</emphasis> command restores the complete contents of a
  26     group of read/write volumes to the file system, by restoring data from the
  27     last full dump and all subsequent incremental dumps of each volume.  It is
  28     most useful for recovering from loss of data on multiple partitions, since
  29     it can restore each of a defined set of volumes to a different site.</para>
  30
  31     <para>(If the <computeroutput>FILE YES</computeroutput> instruction appears in the
  32     <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file associated with the specified
  33     port offset, then the <emphasis role="bold">backup volsetrestore</emphasis> command restores data from
  34     the backup data file listed for that port offset in the Tape Coordinator's
  35     <replaceable>/usr/afs/backup/tapeconfig</replaceable> file, instead of from tape. For the sake of
  36     clarity, the following text refers to tapes only, but the Backup System
  37     handles backup data files in much the same way.)</para>
  38
  39     <para>If restoring one or more volumes to a single site only, it is usually more
  40     efficient to use the <emphasis role="bold">backup volrestore</emphasis> command. If restoring all
  41     volumes that resided on a single partition, it is usually more efficient
  42     to use the <emphasis role="bold">backup diskrestore</emphasis> command.</para>
  43
  44     <para>Indicate the volumes to restore by providing either the <emphasis role="bold">-name</emphasis> argument
  45     or the <emphasis role="bold">-file</emphasis> argument:</para>
  46
  47     <itemizedlist>
  48       <listitem>
  49         <para>The <emphasis role="bold">-name</emphasis> argument names a volume set. The Backup System restores all
  50         volumes listed in the Volume Location Database (VLDB) that match the
  51         server, partition, and volume name criteria defined in the volume set's
  52         volume entries, and for which dumps are available. It restores the volumes
  53         to their current site (machine and partition), and by default overwrites
  54         the existing volume contents.</para>
  55
  56         <para>It is not required that the volume set was previously used to back up
  57         volumes (was used as the <emphasis role="bold">-volumeset</emphasis> option to the <emphasis role="bold">backup dump</emphasis>
  58         command). It can be defined especially to match the volumes that need to
  59         be restored with this command, and that is usually the better
  60         choice. Indeed, a <emphasis>temporary</emphasis> volume set, created by including the
  61         <emphasis role="bold">-temporary</emphasis> flag to the <emphasis role="bold">backup addvolset</emphasis> command, can be especially
  62         useful in this context. A temporary volume set is not added to the Backup
  63         Database and exists only during the current interactive backup session,
  64         which is suitable if the volume set is needed only to complete the single
  65         restore operation initialized by this command.</para>
  66
  67         <para>The reason that a specially defined volume set is probably better is that
  68         volume sets previously defined for use in dump operations usually match
  69         the backup version of volumes, whereas for a restore operation it is best
  70         to define volume entries that match the base (read/write) name. In that
  71         case, the Backup System searches the Backup Database for the newest dump
  72         set that includes either the read/write or the backup version of the
  73         volume. If, in contrast, a volume entry explicitly matches the volume's
  74         backup or read-only version, the Backup System restores dumps of that
  75         volume version only.</para>
  76
  77       </listitem>
  78       <listitem>
  79         <para>The <emphasis role="bold">-file</emphasis> argument names a file that lists specific volumes and the
  80         site to which to restore each. The volume name must match the name used in
  81         Backup Database dump records rather than in the VLDB, if they differ,
  82         because the Backup System does not look up volumes in the VLDB. The
  83         specified site can be different than the volume's current one; in that
  84         case, the Backup System removes the current version of the volume and
  85         updates the volume's location information in the VLDB.</para>
  86
  87       </listitem>
  88     </itemizedlist>
  89     <para>If all of the full and incremental dumps of all relevant volumes were not
  90     written to a type of tape that a single Tape Coordinator can read, use the
  91     <emphasis role="bold">-portoffset</emphasis> argument to list multiple port offset numbers in the order
  92     in which the tapes are needed (first list the port offset for the full
  93     dump, second the port offset for the level 1 incremental dump, and so
  94     on). This implies that the full dumps of all relevant volumes must have
  95     been written to a type of tape that the first Tape Coordinator can read,
  96     the level 1 incremental dumps to a type of tape the second Tape
  97     Coordinator can read, and so on. If dumps are on multiple incompatible
  98     tape types, use the <emphasis role="bold">backup volrestore</emphasis> command to restore individual
  99     volumes, or use this command after defining new volume sets that group
 100     together volumes that were dumped to compatible tape types. For further
 101     discussion, see the <emphasis>IBM AFS Administration Guide</emphasis>.</para>
 102
 103     <para>By default, the Backup System overwrites the contents of an existing
 104     volume with the restored data. To create a new volume to house the
 105     restored version instead, use the <emphasis role="bold">-extension</emphasis> argument. The Backup
 106     System derives the new volume's name by adding the specified extension to
 107     the read/write base name, and creates a new VLDB entry. The command does
 108     not affect the existing volume in any way. However, if a volume with the
 109     specified extension also already exists, the command overwrites it.</para>
 110
 111     <para>The <emphasis role="bold">-n</emphasis> flag produces a list of the volumes to be restored if the <emphasis role="bold">-n</emphasis>
 112     flag were not included, without actually restoring any volumes. See
 113     <link linkend="OUTPUT">OUTPUT</link> for a detailed description of the output, and suggestions on how
 114     to combine it most effectively with the <emphasis role="bold">-file</emphasis> and <emphasis role="bold">-name</emphasis> arguments.</para>
 115
 116     <para>The execution time for a <emphasis role="bold">backup volsetrestore</emphasis> command depends on the
 117     number of volumes to be restored and the amount of data in them, but it
 118     can take hours to restore a large number of volumes. One way to reduce the
 119     time is to run multiple instances of the command simultaneously, either
 120     using the <emphasis role="bold">-name</emphasis> argument to specify disjoint volume sets for each
 121     command, or the <emphasis role="bold">-file</emphasis> argument to name files that list different
 122     volumes. This is possible if there are multiple available Tape
 123     Coordinators that can read the required tapes. Depending on how the
 124     volumes to be restored were dumped to tape, specifying disjoint volume
 125     sets can also reduce the number of tape changes required.</para>
 126
 127     <para>The Tape Coordinator's default response to this command is to access the
 128     first tape it needs by invoking the <computeroutput>MOUNT</computeroutput> instruction in the local
 129     <replaceable>/usr/afs/backup/CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable> file, or by prompting the backup
 130     operator to insert the tape if there is no <computeroutput>MOUNT</computeroutput> instruction. However,
 131     if the <computeroutput>AUTOQUERY NO</computeroutput> instruction appears in the <replaceable>CFG_</replaceable><emphasis>device_name</emphasis><replaceable></replaceable>
 132     file, or if the issuer of the <emphasis role="bold">butc</emphasis> command included the <emphasis role="bold">-noautoquery</emphasis>
 133     flag, the Tape Coordinator instead expects the tape to be in the device
 134     already. If it is not, or is the wrong tape, the Tape Coordinator invokes
 135     the <computeroutput>MOUNT</computeroutput> instruction or prompts the operator. It also invokes the
 136     <computeroutput>MOUNT</computeroutput> instruction or prompts for any additional tapes needed to
 137     complete the restore operation; the backup operator must arrange to
 138     provide them.</para>
 139
 140   </refsect1>
 141   <refsect1>
 142     <title>Options</title>
 143     <variablelist>
 144       <varlistentry>
 145         <term><emphasis role="bold">-name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;</term>
 146         <listitem>
 147           <para>Names a volume set to restore. The Backup System restores all of the
 148           volumes listed in the VLDB that match the volume set's volume
 149           entries. Provide this argument or the <emphasis role="bold">-file</emphasis> argument, but not both.</para>
 150
 151         </listitem>
 152       </varlistentry>
 153       <varlistentry>
 154         <term><emphasis role="bold">-file</emphasis> &lt;<emphasis>file name</emphasis>&gt;</term>
 155         <listitem>
 156           <para>Specifies the full pathname of a file that lists one or more volumes and
 157           the site (file server machine and partition) to which to restore each.
 158           Use either this argument or the <emphasis role="bold">-name</emphasis> argument, but not both.</para>
 159
 160           <para>Each volume's entry must appear on its own (unbroken) line in the file,
 161           and have the following format:</para>
 162
 163 <programlisting>
 164     &amp;lt;machine&amp;gt; &amp;lt;partition&amp;gt; &amp;lt;volume&amp;gt; [&amp;lt;comments&amp;gt; ...]
 165
 166 </programlisting>
 167             <para>where</para>
 168
 169             <variablelist>
 170               <varlistentry>
 171                 <term>&lt;machine&gt;</term>
 172                 <listitem>
 173                   <para>Names the file server machine to which to restore the volume.</para>
 174
 175                 </listitem>
 176               </varlistentry>
 177               <varlistentry>
 178                 <term>&lt;partition&gt;</term>
 179                 <listitem>
 180                   <para>Names the partition to which to restore the volume.</para>
 181
 182                 </listitem>
 183               </varlistentry>
 184               <varlistentry>
 185                 <term>&lt;volume&gt;</term>
 186                 <listitem>
 187                   <para>Names the volume to restore. It is generally best to specify the base
 188                   (read/write) name of each volume. In this case, the Backup System searches
 189                   the Backup Database for the newest dump set that includes a dump of either
 190                   the read/write or the backup version of the volume. It restores the dumps
 191                   of that version of the volume, starting with the most recent full
 192                   dump. If, in contrast, the name explicitly includes the <computeroutput>.backup</computeroutput> or
 193                   <computeroutput>.readonly</computeroutput> extension, the Backup System restores dumps of that volume
 194                   version only.</para>
 195
 196                 </listitem>
 197               </varlistentry>
 198               <varlistentry>
 199                 <term>&lt;comments&gt; ...</term>
 200                 <listitem>
 201                   <para>Is any other text. The Backup System ignores any text on each line that
 202                   appears after the volume name, so this field can be used for notes helpful
 203                   to the backup operator or other administrator.</para>
 204
 205                 </listitem>
 206               </varlistentry>
 207             </variablelist>
 208             <para>Do not use wildcards (for example, <computeroutput>.*</computeroutput>) in the &lt;machine&gt;, &lt;partition&gt;,
 209             or &lt;volume&gt; fields. It is acceptable for multiple lines in the file to
 210             name the same volume, but the Backup System processes only the first of
 211             them.</para>
 212
 213           </listitem>
 214         </varlistentry>
 215         <varlistentry>
 216           <term><emphasis role="bold">-extension</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;</term>
 217           <listitem>
 218             <para>Creates a new volume for each volume specified by the <emphasis role="bold">-name</emphasis> or <emphasis role="bold">-file</emphasis>
 219             argument, to house the restored data from that volume.  The Backup System
 220             derives the new volume's name by appending the specified string to the
 221             read/write base name, and creates a new VLDB volume entry. It preserves
 222             the contents of each existing volume. Any string other than <computeroutput>.readonly</computeroutput>
 223             or <computeroutput>.backup</computeroutput> is acceptable, but the combination of the base name and
 224             extension cannot exceed 22 characters in length. To use a period to
 225             separate the extension from the name, specify it as the first character of
 226             the string (as in <computeroutput>.rst</computeroutput>, for example).</para>
 227
 228           </listitem>
 229         </varlistentry>
 230         <varlistentry>
 231           <term><emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;+</term>
 232           <listitem>
 233             <para>Specifies one or more port offset numbers (up to a maximum of 128), each
 234             corresponding to a Tape Coordinator to use in the operation. If there is
 235             more than one value, the Backup System uses the first one when restoring
 236             the full dump of each volume, the second one when restoring the level 1
 237             incremental dump of each volume, and so on. It uses the final value in the
 238             list when restoring dumps at the corresponding depth in the dump hierarchy
 239             and all dumps at lower levels.</para>
 240
 241             <para>Provide this argument unless the default value of 0 (zero) is appropriate
 242             for all dumps. If <computeroutput>0</computeroutput> is just one of the values in the list, provide it
 243             explicitly in the appropriate order.</para>
 244
 245           </listitem>
 246         </varlistentry>
 247         <varlistentry>
 248           <term><emphasis role="bold">-n</emphasis></term>
 249           <listitem>
 250             <para>Displays a list of the volumes to be restored if the flag were not
 251             included, without actually restoring them. <link linkend="OUTPUT">OUTPUT</link> details the format of
 252             the output. When combined with the <emphasis role="bold">-name</emphasis> argument, its output is easily
 253             edited for use as input to the <emphasis role="bold">-file</emphasis> argument on a subsequent <emphasis role="bold">backup
 254             volsetrestore</emphasis> command.</para>
 255
 256           </listitem>
 257         </varlistentry>
 258         <varlistentry>
 259           <term><emphasis role="bold">-localauth</emphasis></term>
 260           <listitem>
 261             <para>Constructs a server ticket using a key from the local
 262             <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The <emphasis role="bold">backup</emphasis> command interpreter presents
 263             it to the Backup Server, Volume Server and VL Server during mutual
 264             authentication. Do not combine this flag with the <emphasis role="bold">-cell</emphasis> argument. For
 265             more details, see <link linkend="backup8">backup(8)</link>.</para>
 266
 267           </listitem>
 268         </varlistentry>
 269         <varlistentry>
 270           <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
 271           <listitem>
 272             <para>Names the cell in which to run the command. Do not combine this argument
 273             with the <emphasis role="bold">-localauth</emphasis> flag. For more details, see <link linkend="backup8">backup(8)</link>.</para>
 274
 275           </listitem>
 276         </varlistentry>
 277         <varlistentry>
 278           <term><emphasis role="bold">-help</emphasis></term>
 279           <listitem>
 280             <para>Prints the online help for this command. All other valid options are
 281             ignored.</para>
 282
 283           </listitem>
 284         </varlistentry>
 285       </variablelist>
 286     </refsect1>
 287     <refsect1>
 288       <title>Output</title>
 289       <para>If the <emphasis role="bold">-n</emphasis> flag is not provided, the command displays a unique task ID
 290       number for the operation, in two places:</para>
 291
 292       <itemizedlist>
 293         <listitem>
 294           <para>In the shell window, directly following the command line.</para>
 295
 296         </listitem>
 297         <listitem>
 298           <para>In the Tape Coordinator window, if the butc process was started at debug
 299           level 1.</para>
 300
 301         </listitem>
 302       </itemizedlist>
 303       <para>The task ID number is not the same as the job ID number displayed by the
 304       <emphasis role="bold">backup jobs</emphasis> command when the <emphasis role="bold">backup volsetrestore</emphasis> command is issued
 305       in interactive mode. The Backup System does not assign either type of ID
 306       number until the restoration process actually begins.</para>
 307
 308       <para>When the <emphasis role="bold">-n</emphasis> flag is included, no task ID or job ID numbers are reported
 309       because none are assigned. Instead, the output begins with a count of the
 310       number of volumes to be restored, followed by a line for each dump of a
 311       volume. For each volume, the line representing the most recent full dump
 312       appears first, and lines for any subsequent incremental dumps follow,
 313       ordered by dump level. The lines for a given volume do not necessarily
 314       appear all together, however.</para>
 315
 316       <para>The format of each line is as follows (the output is shown here on two
 317       lines only for legibility reasons):</para>
 318
 319 <programlisting>
 320    &amp;lt;machine&amp;gt; &amp;lt;partition&amp;gt; &amp;lt;volume_dumped&amp;gt; # as &amp;lt;volume_restored&amp;gt;; \
 321        &amp;lt;tape_name&amp;gt; (&amp;lt;tape_ID&amp;gt;); pos &amp;lt;position_number&amp;gt;; &amp;lt;date&amp;gt;
 322
 323 </programlisting>
 324         <para>where</para>
 325
 326         <variablelist>
 327           <varlistentry>
 328             <term>&lt;machine&gt;</term>
 329             <listitem>
 330               <para>Names the file server machine that currently houses the volume, as listed
 331               in the VLDB.</para>
 332
 333             </listitem>
 334           </varlistentry>
 335           <varlistentry>
 336             <term>&lt;partition&gt;</term>
 337             <listitem>
 338               <para>Names the partition that currently houses the volume, as listed in the
 339               VLDB.</para>
 340
 341             </listitem>
 342           </varlistentry>
 343           <varlistentry>
 344             <term>&lt;volume_dumped&gt;</term>
 345             <listitem>
 346               <para>Specifies the version (read/write or backup) of the volume that was
 347               dumped, as listed in the Backup Database.</para>
 348
 349             </listitem>
 350           </varlistentry>
 351           <varlistentry>
 352             <term>&lt;volume_restored&gt;</term>
 353             <listitem>
 354               <para>Specifies the name under which to restore the volume. The Backup System
 355               only restores data to read/write volumes. If the <emphasis role="bold">-extension</emphasis> argument is
 356               included, then the specified extension appears on the name in this field
 357               (for example, <computeroutput>user.pat.rst</computeroutput>).</para>
 358
 359             </listitem>
 360           </varlistentry>
 361           <varlistentry>
 362             <term>&lt;tape_name&gt;</term>
 363             <listitem>
 364               <para>Names the tape containing the dump of the volume, from the Backup
 365               Database. If the tape has a permanent name, it appears here; otherwise, it
 366               is the AFS tape name.</para>
 367
 368             </listitem>
 369           </varlistentry>
 370           <varlistentry>
 371             <term>&lt;tape_ID&gt;</term>
 372             <listitem>
 373               <para>The tape ID of the tape containing the dump of the volume, from the Backup
 374               Database.</para>
 375
 376             </listitem>
 377           </varlistentry>
 378           <varlistentry>
 379             <term>&lt;position_number&gt;</term>
 380             <listitem>
 381               <para>Specifies the dump's position on the tape (for example, <computeroutput>31</computeroutput> indicates
 382               that 30 volume dumps precede the current one on the tape). If the dump was
 383               written to a backup data file, this number is the ordinal of the 16
 384               KB-offset at which the volume's data begins.</para>
 385
 386             </listitem>
 387           </varlistentry>
 388           <varlistentry>
 389             <term>&lt;date&gt;</term>
 390             <listitem>
 391               <para>The date and time when the volume was dumped.</para>
 392
 393             </listitem>
 394           </varlistentry>
 395         </variablelist>
 396         <para>One way to generate a file for use as input to the <emphasis role="bold">-file</emphasis> argument is to
 397         combine the <emphasis role="bold">-name</emphasis> and <emphasis role="bold">-n</emphasis> options, directing the output to a
 398         file. The <emphasis>IBM AFS Administration Guide</emphasis> section on using the Backup
 399         System to restore data explains how to edit the file as necessary before
 400         using it as input to the <emphasis role="bold">-file</emphasis> argument.</para>
 401
 402         <para>The output of this command includes only volumes for which the Backup
 403         Database includes at least one dump record. The command interpreter
 404         generates a message on the standard error stream about volumes that do not
 405         have dump records but either are listed in the file named by the <emphasis role="bold">-file</emphasis>
 406         argument, or appear in the VLDB as a match to a volume entry in the volume
 407         set named by the <emphasis role="bold">-name</emphasis> argument.</para>
 408
 409       </refsect1>
 410       <refsect1>
 411         <title>Examples</title>
 412         <para>The following command restores all volumes included in entries in the
 413         volume set named <computeroutput>data.restore</computeroutput>, which was created expressly to restore
 414         data to a pair of file server machines on which all data was corrupted due
 415         to a software error. All volumes are restored to the sites recorded in
 416         their entries in the VLDB.</para>
 417
 418 <programlisting>
 419    % backup volsetrestore -name data.restore
 420    Starting restore
 421    backup: task ID of restore operation: 112
 422    backup: Finished doing restore
 423
 424 </programlisting>
 425           <para>The following command restores all volumes that have entries in the file
 426           named <replaceable>/tmp/restore</replaceable>:</para>
 427
 428 <programlisting>
 429    % backup volsetrestore -file /tmp/restore
 430    Starting restore
 431    backup: task ID of restore operation: 113
 432    backup: Finished doing restore
 433
 434 </programlisting>
 435             <para>The <replaceable>/tmp/restore</replaceable> file has the following contents:</para>
 436
 437 <programlisting>
 438    fs1.abc.com b user.pat
 439    fs1.abc.com b user.terry
 440    fs1.abc.com b user.smith
 441    fs2.abc.com c user.jones
 442           .         .     .
 443           .         .     .
 444
 445 </programlisting>
 446             </refsect1>
 447             <refsect1>
 448               <title>Privilege Required</title>
 449               <para>The issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable> file on every
 450               machine where the Backup Server or Volume Location (VL) Server is running,
 451               and on every file server machine that houses an affected volume. If the
 452               <emphasis role="bold">-localauth</emphasis> flag is included, the issuer must instead be logged on to a
 453               server machine as the local superuser <computeroutput>root</computeroutput>.</para>
 454
 455             </refsect1>
 456             <refsect1>
 457               <title>See Also</title>
 458               <para><link linkend="butc5">butc(5)</link>,
 459               <link linkend="backup8">backup(8)</link>,
 460               <link linkend="backup_addvolentry8">backup_addvolentry(8)</link>,
 461               <link linkend="backup_addvolset8">backup_addvolset(8)</link>,
 462               <link linkend="backup_diskrestore8">backup_diskrestore(8)</link>,
 463               <link linkend="backup_dump8">backup_dump(8)</link>,
 464               <link linkend="backup_volrestore8">backup_volrestore(8)</link>,
 465               <link linkend="butc8">butc(8)</link></para>
 466
 467             </refsect1>
 468             <refsect1>
 469               <title>Copyright</title>
 470               <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 471
 472               <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 473               converted from HTML to POD by software written by Chas Williams and Russ
 474               Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 475
 476             </refsect1>
 477           </refentry>