<?xml version="1.0" encoding="UTF-8"?>
<chapter id="HDRWQ283">
  <title>Backing Up and Restoring AFS Data</title>

  <para>The instructions in this chapter explain how to back up and restore AFS data and to administer the Backup Database. They
  assume that you have already configured all of the Backup System components by following the instructions in <link
  linkend="HDRWQ248">Configuring the AFS Backup System</link>.</para>

  <sect1 id="HDRWQ284">
    <title>Summary of Instructions</title>

    <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>

    <informaltable frame="none">
      <tgroup cols="2">
        <colspec colwidth="70*" />

        <colspec colwidth="30*" />

        <tbody>
          <row>
            <entry>Enter interactive mode</entry>

            <entry><emphasis role="bold">backup (interactive)</emphasis></entry>
          </row>

          <row>
            <entry>Leave interactive mode</entry>

            <entry><emphasis role="bold">(backup) quit</emphasis></entry>
          </row>

          <row>
            <entry>List operations in interactive mode</entry>

            <entry><emphasis role="bold">(backup) jobs</emphasis></entry>
          </row>

          <row>
            <entry>Cancel operation in interactive mode</entry>

            <entry><emphasis role="bold">(backup) kill</emphasis></entry>
          </row>

          <row>
            <entry>Start Tape Coordinator</entry>

            <entry><emphasis role="bold">butc</emphasis></entry>
          </row>

          <row>
            <entry>Stop Tape Coordinator</entry>

            <entry>&lt;<emphasis role="bold">Ctrl-c</emphasis>&gt;</entry>
          </row>

          <row>
            <entry>Check status of Tape Coordinator</entry>

            <entry><emphasis role="bold">backup status</emphasis></entry>
          </row>

          <row>
            <entry>Back up data</entry>

            <entry><emphasis role="bold">backup dump</emphasis></entry>
          </row>

          <row>
            <entry>Display dump records</entry>

            <entry><emphasis role="bold">backup dumpinfo</emphasis></entry>
          </row>

          <row>
            <entry>Display volume's dump history</entry>

            <entry><emphasis role="bold">backup volinfo</emphasis></entry>
          </row>

          <row>
            <entry>Scan contents of tape</entry>

            <entry><emphasis role="bold">backup scantape</emphasis></entry>
          </row>

          <row>
            <entry>Restore volume</entry>

            <entry><emphasis role="bold">backup volrestore</emphasis></entry>
          </row>

          <row>
            <entry>Restore partition</entry>

            <entry><emphasis role="bold">backup diskrestore</emphasis></entry>
          </row>

          <row>
            <entry>Restore group of volumes</entry>

            <entry><emphasis role="bold">backup volsetrestore</emphasis></entry>
          </row>

          <row>
            <entry>Verify integrity of Backup Database</entry>

            <entry><emphasis role="bold">backup dbverify</emphasis></entry>
          </row>

          <row>
            <entry>Repair corruption in Backup Database</entry>

            <entry><emphasis role="bold">backup savedb</emphasis> and <emphasis role="bold">backup restoredb</emphasis></entry>
          </row>

          <row>
            <entry>Delete dump set from Backup Database</entry>

            <entry><emphasis role="bold">backup deletedump</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </sect1>

  <sect1 id="HDRWQ286">
    <title>Using the Backup System's Interfaces</title>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>interfaces</secondary>
    </indexterm>

    <para>When performing backup operations, you interact with three Backup System components: <itemizedlist>
        <listitem>
          <para>You initiate backup operations by issuing commands from the <emphasis role="bold">backup</emphasis> suite. You can
          issue the commands in a command shell (or invoke them in a shell script) on any AFS client or server machine from which
          you can access the <emphasis role="bold">backup</emphasis> binary. In the conventional configuration, the binary resides
          in the <emphasis role="bold">/usr/afs/bin</emphasis> directory on a server machine and the <emphasis
          role="bold">/usr/afsws/etc</emphasis> directory on a client machine.</para>

          <para>The suite provides an <emphasis>interactive mode</emphasis>, in which you can issue multiple commands over a
          persistent connection to the Backup Server and the Volume Location (VL) Server. Interactive mode has several convenient
          features. For a discussion and instructions, see <link linkend="HDRWQ288">Using Interactive and Regular Command
          Mode</link>.</para>

          <para>Note that some operating systems include a <emphasis role="bold">backup</emphasis> command of their own. You must
          configure machines that run such an operating system to ensure that you are accessing the desired <emphasis
          role="bold">backup</emphasis> binary.</para>
        </listitem>

        <listitem>
          <para>Before you perform a backup operation that involves reading or writing to a tape device or backup data file, you
          must open a dedicated connection to the appropriate Tape Coordinator machine and start the Tape Coordinator (<emphasis
          role="bold">butc</emphasis>) process that handles the device or file. The <emphasis role="bold">butc</emphasis> process
          must continue to run over the dedicated connection as long as it is executing an operation or is to be available to
          execute one. For further discussion and instructions, see <link linkend="HDRWQ291">Starting and Stopping the Tape
          Coordinator Process</link>.</para>
        </listitem>

        <listitem>
          <para>The Backup Server (<emphasis role="bold">buserver</emphasis>) process must be running on database server machines,
          because most backup operations require accessing or changing information in the Backup Database. The <emphasis>OpenAFS
          Quick Beginnings</emphasis> explains how to configure the Backup Server.</para>
        </listitem>
      </itemizedlist></para>

    <para>For consistent Backup System performance, the AFS build level of all three binaries (<emphasis
    role="bold">backup</emphasis>, <emphasis role="bold">butc</emphasis>, and <emphasis role="bold">buserver</emphasis>) must match.
    For instructions on displaying the build level, see <link linkend="HDRWQ117">Displaying A Binary File's Build
    Level</link>.</para>

    <sect2 id="HDRWQ287">
      <title>Performing Backup Operations as the Local Superuser Root or in a Foreign Cell</title>

      <indexterm>
        <primary>AFSCELL environment variable</primary>
      </indexterm>

      <indexterm>
        <primary>variable</primary>

        <secondary>AFSCELL</secondary>
      </indexterm>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>running in foreign cell</secondary>
      </indexterm>

      <para>By default, the volumes and Backup Database involved in a backup operation must reside on server machines that belong to
      the cell named in the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> files on both the Tape Coordinator machine and
      the machine where you issue the <emphasis role="bold">backup</emphasis> command. Also, to issue most <emphasis
      role="bold">backup</emphasis> commands you must have AFS tokens for an identity listed in the local cell's <emphasis
      role="bold">/usr/afs/etc/UserList</emphasis> file (which by convention is the same on every server machine in a cell). You
      can, however, perform backup operations on volumes or the Backup Database from a foreign cell, or perform backup operations
      while logged in as the local superuser <emphasis role="bold">root</emphasis> rather than as a privileged AFS identity.</para>

      <para>To perform backup operations on volumes that reside in a foreign cell using machines from the local cell, you must
      designate the foreign cell as the cell of execution for both the Tape Coordinator and the <emphasis
      role="bold">backup</emphasis> command interpreter. Use one of the two following methods. For either method, you must also have
      tokens as an administrator listed in the foreign cell's <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file.
      <itemizedlist>
          <listitem>
            <para>Before issuing <emphasis role="bold">backup</emphasis> commands and the <emphasis role="bold">butc</emphasis>
            command, set the AFSCELL environment variable to the foreign cell name in both command shells.</para>
          </listitem>

          <listitem>
            <para>Include the <emphasis role="bold">-cell</emphasis> argument to the <emphasis role="bold">butc</emphasis> and all
            <emphasis role="bold">backup</emphasis> commands. If you include the argument on the <emphasis role="bold">backup
            (interactive)</emphasis> command, it applies to all commands issued during the interactive session.</para>
          </listitem>
        </itemizedlist></para>

      <para>To perform backup operations without having administrative AFS tokens, you must log on as the local superuser <emphasis
      role="bold">root</emphasis> on both the Tape Coordinator machine and the machine where you issue <emphasis
      role="bold">backup</emphasis> commands. Both machines must be server machines, or at least have a <emphasis
      role="bold">/usr/afs/etc/KeyFile</emphasis> file that matches the file on other server machines. Then include the <emphasis
      role="bold">-localauth</emphasis> argument on both the <emphasis role="bold">butc</emphasis> command and all <emphasis
      role="bold">backup</emphasis> commands (or the <emphasis role="bold">backup (interactive)</emphasis> command). The Tape
      Coordinator and <emphasis role="bold">backup</emphasis> command interpreter construct a server ticket using the server
      encryption key with the highest key version number in the local <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file,
      and present it to the Backup Server, Volume Server, and VL Server that belong to the cell named in the local <emphasis
      role="bold">/usr/afs/etc/ThisCell</emphasis> file. The ticket never expires.</para>

      <para>You cannot combine the <emphasis role="bold">-cell</emphasis> and <emphasis role="bold">-localauth</emphasis> options on
      the same command. Also, each one overrides the local cell setting defined by the AFSCELL environment variable or the <emphasis
      role="bold">/usr/vice/etc/ThisCell</emphasis> file.</para>
    </sect2>

    <sect2 id="HDRWQ288">
      <title>Using Interactive and Regular Command Mode</title>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>interactive mode</secondary>
      </indexterm>

      <indexterm>
        <primary>interactive mode (Backup System)</primary>

        <secondary>features</secondary>
      </indexterm>

      <para>The <emphasis role="bold">backup</emphasis> command suite provides an interactive mode, in which you can issue multiple
      commands over a persistent connection to the Backup Server and the VL Server. Interactive mode provides the following
      features: <itemizedlist>
          <listitem>
            <para>The <computeroutput>backup&gt;</computeroutput> prompt replaces the usual command shell prompt.</para>
          </listitem>

          <listitem>
            <para>You omit the initial <emphasis role="bold">backup</emphasis> string from command names. Type only the operation
            code and option names.</para>
          </listitem>

          <listitem>
            <para>You cannot issue commands that do not belong to the <emphasis role="bold">backup</emphasis> suite.</para>
          </listitem>

          <listitem>
            <para>If you assume an administrative AFS identity or specify a foreign cell as you enter interactive mode, it applies
            to all commands issued during the interactive session. See <link linkend="HDRWQ287">Performing Backup Operations as the
            Local Superuser Root or in a Foreign Cell</link>.</para>
          </listitem>

          <listitem>
            <para>You do not need to enclose shell metacharacters in double quotes.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>job ID numbers (Backup System)</primary>
      </indexterm>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>job ID numbers</secondary>

        <tertiary>about</tertiary>
      </indexterm>

      <para>When you initiate a backup operation in interactive mode, the Backup System assigns it a <emphasis>job ID
      number</emphasis>. You can display the list of current and pending operations with the <emphasis role="bold">(backup)
      jobs</emphasis> command, for which instructions appear in <link linkend="HDRWQ289">To display pending or running jobs in
      interactive mode</link>. (In both regular and interactive modes, the Tape Coordinator also assigns a <emphasis>task ID
      number</emphasis> to each operation you initiate with a <emphasis role="bold">backup</emphasis> command. You can track task ID
      numbers with the <emphasis role="bold">backup status</emphasis> command. See <link linkend="HDRWQ291">Starting and Stopping
      the Tape Coordinator Process</link>.)</para>

      <para>You can cancel an operation in interactive mode with the <emphasis role="bold">(backup) kill</emphasis> command, for
      which instructions appear in <link linkend="HDRWQ290">To cancel operations in interactive mode</link>. However, it is best not
      to interrupt a dump operation because the resulting dump is incomplete, and interrupting a restore operation can leave volumes
      in an inconsistent state, or even completely remove them from the server machine. For further discussion, see <link
      linkend="HDRWQ296">Backing Up Data</link> and <link linkend="HDRWQ306">Restoring and Recovering Data</link>.</para>

      <para>The <emphasis role="bold">(backup) jobs</emphasis> and <emphasis role="bold">(backup) kill</emphasis> commands are
      available only in interactive mode and there is no equivalent functionality in regular command mode.</para>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>interactive mode</secondary>

        <tertiary>entering</tertiary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup</secondary>

        <tertiary>to enter interactive mode</tertiary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup interactive</secondary>
      </indexterm>

      <indexterm>
        <primary>interactive mode (Backup System)</primary>

        <secondary>entering</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_325">
      <title>To enter interactive mode</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. Entering interactive mode does not itself require privilege, but most other <emphasis role="bold">backup</emphasis>
          commands do, and the AFS identity you assume when entering the mode applies to all commands you issue within it. If
          necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup (interactive)</emphasis> command at the system prompt. The
          <computeroutput>backup&gt;</computeroutput> prompt appears. You can include either, but not both, of the <emphasis
          role="bold">-localauth</emphasis> and <emphasis role="bold">-cell</emphasis> options, as discussed in <link
          linkend="HDRWQ287">Performing Backup Operations as the Local Superuser Root or in a Foreign Cell</link>. <programlisting>
   % <emphasis role="bold">backup</emphasis>
   backup&gt;
</programlisting></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>quit</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup quit</secondary>
      </indexterm>

      <indexterm>
        <primary>interactive mode (Backup System)</primary>

        <secondary>exiting</secondary>
      </indexterm>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>interactive mode</secondary>

        <tertiary>exiting</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="Header_326">
      <title>To exit interactive mode</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">quit</emphasis> command at the <computeroutput>backup&gt;</computeroutput> prompt.
          The command shell prompt reappears when the command succeeds, which it does only if there are no jobs pending or currently
          running. To display and cancel pending or running jobs, follow the instructions in <link linkend="HDRWQ289">To display
          pending or running jobs in interactive mode</link> and <link linkend="HDRWQ290">To cancel operations in interactive
          mode</link>. <programlisting>
   backup&gt; <emphasis role="bold">quit</emphasis>
   %
</programlisting></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>interactive mode (Backup System)</primary>

        <secondary>operations</secondary>

        <tertiary>displaying pending/running</tertiary>
      </indexterm>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>interactive mode</secondary>

        <tertiary>displaying pending/running operations</tertiary>
      </indexterm>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>job ID numbers</secondary>

        <tertiary>displaying</tertiary>
      </indexterm>

      <indexterm>
        <primary>job ID numbers (Backup System)</primary>

        <secondary>displaying</secondary>
      </indexterm>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>jobs</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup jobs</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ289">
      <title>To display pending or running jobs in interactive mode</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">jobs</emphasis> command at the <computeroutput>backup&gt;</computeroutput> prompt.
          <programlisting>
   backup&gt; <emphasis role="bold">jobs</emphasis>
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">j</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">jobs</emphasis>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>The output always includes the expiration date and time of the tokens that the <emphasis role="bold">backup</emphasis>
      command interpreter is using during the current interactive session, in the following format:</para>

      <programlisting>
   date   time: TOKEN EXPIRATION
</programlisting>

      <para>If the execution date and time specified for a scheduled dump operation is later than <emphasis>date time</emphasis>,
      then its individual line (as described in the following paragraphs) appears below this line to indicate that the current
      tokens will not be available to it.</para>

      <para>If the issuer of the <emphasis role="bold">backup</emphasis> command included the <emphasis
      role="bold">-localauth</emphasis> flag when entering interactive mode, the line instead reads as follows:</para>

      <programlisting>
   :  TOKEN NEVER EXPIRES
</programlisting>

      <para>The entry for a scheduled dump operation has the following format:</para>

      <programlisting>
   Job job_ID:  timestamp:  dump  volume_set  dump_level
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">job_ID</emphasis></term>

            <listitem>
              <para>Is a job identification number assigned by the Backup System.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">timestamp</emphasis></term>

            <listitem>
              <para>Indicates the date and time the dump operation is to begin, in the format month/date/year hours:minutes (in
              24-hour format)</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">volume_set</emphasis></term>

            <listitem>
              <para>Indicates the volume set to dump.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">dump_level</emphasis></term>

            <listitem>
              <para>Indicates the dump level at which to perform the dump operation.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <para>The line for a pending or running operation of any other type has the following format:</para>

      <programlisting>
   Job job_ID:  operation  status
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">job_ID</emphasis></term>

            <listitem>
              <para>Is a job identification number assigned by the Backup System.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">operation</emphasis></term>

            <listitem>
              <para>Identifies the operation the Tape Coordinator is performing, which is initiated by the indicated command:
              <variablelist>
                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>Dump</computeroutput> (dump name)</emphasis></term>

                    <listitem>
                      <para>Initiated by the <emphasis role="bold">backup dump</emphasis> command. The dump name has the following
                      format:</para>

                      <para>volume_set_name<emphasis role="bold">.</emphasis>dump_level_name</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>Restore</computeroutput></emphasis></term>

                    <listitem>
                      <para>Initiated by the <emphasis role="bold">backup diskrestore</emphasis>, <emphasis role="bold">backup
                      volrestore</emphasis>, or <emphasis role="bold">backup volsetrestore</emphasis> command.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>Labeltape</computeroutput> (tape_label)</emphasis></term>

                    <listitem>
                      <para>Initiated by the <emphasis role="bold">backup labeltape</emphasis> command. The tape_label is the name
                      specified by the <emphasis role="bold">backup labeltape</emphasis> command's <emphasis
                      role="bold">-name</emphasis> or <emphasis role="bold">-pname</emphasis> argument.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>Scantape</computeroutput></emphasis></term>

                    <listitem>
                      <para>Initiated by the <emphasis role="bold">backup scantape</emphasis> command.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>SaveDb</computeroutput></emphasis></term>

                    <listitem>
                      <para>Initiated by the <emphasis role="bold">backup savedb</emphasis> command.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>RestoreDb</computeroutput></emphasis></term>

                    <listitem>
                      <para>Initiated by the <emphasis role="bold">backup restoredb</emphasis> command.</para>
                    </listitem>
                  </varlistentry>
                </variablelist></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">status</emphasis></term>

            <listitem>
              <para>Indicates the job's current status in one of the following messages. If no message appears, the job is either
              still pending or has finished. <variablelist>
                  <varlistentry>
                    <term><emphasis role="bold">number <computeroutput>Kbytes, volume volume_name</computeroutput></emphasis></term>

                    <listitem>
                      <para>For a running dump operation, indicates the number of kilobytes copied to tape or a backup data file so
                      far, and the volume currently being dumped.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold">number <computeroutput>Kbytes, restore.volume</computeroutput></emphasis></term>

                    <listitem>
                      <para>For a running restore operation, indicates the number of kilobytes copied into AFS from a tape or a
                      backup data file so far.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[abort requested]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The <emphasis role="bold">(backup) kill</emphasis> command was issued, but the termination signal has
                      yet to reach the Tape Coordinator.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[abort sent]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The operation is canceled by the <emphasis role="bold">(backup) kill</emphasis> command. Once the Backup
                      System removes an operation from the queue or stops it from running, it no longer appears at all in the output
                      from the command.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[butc contact lost]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The <emphasis role="bold">backup</emphasis> command interpreter cannot reach the Tape Coordinator. The
                      message can mean either that the Tape Coordinator handling the operation was terminated or failed while the
                      operation was running, or that the connection to the Tape Coordinator timed out.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[done]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The Tape Coordinator has finished the operation.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[drive wait]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The operation is waiting for the specified tape drive to become free.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[operator wait]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The Tape Coordinator is waiting for the backup operator to insert a tape in the drive.</para>
                    </listitem>
                  </varlistentry>
                </variablelist></para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>interactive mode (Backup System)</primary>

        <secondary>operations</secondary>

        <tertiary>canceling pending/running</tertiary>
      </indexterm>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>interactive mode</secondary>

        <tertiary>canceling operations</tertiary>
      </indexterm>

      <indexterm>
        <primary>job ID numbers (Backup System)</primary>

        <secondary>operations</secondary>

        <tertiary>canceling</tertiary>
      </indexterm>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>kill</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup kill</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ290">
      <title>To cancel operations in interactive mode</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">jobs</emphasis> command at the <computeroutput>backup&gt;</computeroutput> prompt,
          to learn the job ID number of the operation you want to cancel. For details, see <link linkend="HDRWQ289">To display
          pending or running jobs in interactive mode</link>. <programlisting>
   backup&gt; <emphasis role="bold">jobs</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">(backup) kill</emphasis> command to cancel the operation. <programlisting>
   backup&gt; <emphasis role="bold">kill</emphasis> &lt;<emphasis>job ID or dump set name</emphasis>&gt;
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">k</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">kill</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">job ID or dump set name</emphasis></term>

                <listitem>
                  <para>Specifies either the job ID number of the operation to cancel, as reported by the <emphasis
                  role="bold">jobs</emphasis> command, or for a dump operation only, the dump name in the format
                  volume_set_name.dump_level_name.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="HDRWQ291">
      <title>Starting and Stopping the Tape Coordinator Process</title>

      <indexterm>
        <primary>Tape Coordinator (Backup System)</primary>

        <secondary>process</secondary>

        <tertiary>starting</tertiary>
      </indexterm>

      <para>Before performing a backup operation that reads from or writes to a tape device or backup data file, you must start the
      Tape Coordinator (<emphasis role="bold">butc</emphasis>) process that handles the drive or file. This section explains how to
      start, stop, and check the status of a Tape Coordinator process. To use these instructions, you must have already configured
      the Tape Coordinator machine and created a Tape Coordinator entry in the Backup Database, as instructed in <link
      linkend="HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</link>.</para>

      <indexterm>
        <primary>task ID numbers (Backup System)</primary>
      </indexterm>

      <indexterm>
        <primary>Tape Coordinator (Backup System)</primary>

        <secondary>task ID numbers</secondary>
      </indexterm>

      <para>The Tape Coordinator assigns a <emphasis>task ID number</emphasis> to each operation it performs. The number is distinct
      from the job ID number assigned by the <emphasis role="bold">backup</emphasis> command interpreter in interactive mode (which
      is discussed in <link linkend="HDRWQ288">Using Interactive and Regular Command Mode</link>). The Tape Coordinator reports the
      task ID number in its onscreen trace and in the messages that it writes to its log and error files. To view the task ID
      numbers of a Tape Coordinator's running or pending operations, issue the <emphasis role="bold">backup status</emphasis>
      command.</para>

      <indexterm>
        <primary>Tape Coordinator (Backup System)</primary>

        <secondary>starting</secondary>
      </indexterm>

      <indexterm>
        <primary>butc command</primary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>butc</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ292">
      <title>To start a Tape Coordinator process</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file of the cell in which the Tape Coordinator is to access volume data and the Backup Database. If necessary, issue the
          <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display
          the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>

          <para>Alternately, you can log into a file server machine as the local superuser <emphasis role="bold">root</emphasis> in
          Step <link linkend="LIWQ293">3</link>.</para>
        </listitem>

        <listitem>
          <para>Verify that you can write to the Tape Coordinator's log and error files in the local <emphasis
          role="bold">/usr/afs/backup</emphasis> directory (the <emphasis role="bold">TE_</emphasis>device_name and <emphasis
          role="bold">TL_</emphasis>device_name files). If the log and error files do not already exist, you must be able to insert
          and write to files in the <emphasis role="bold">/usr/afs/backup</emphasis> directory.</para>
        </listitem>

        <listitem id="LIWQ293">
          <para>Open a connection (using a command such as <emphasis role="bold">telnet</emphasis> or
          <emphasis role="bold">rlogin</emphasis>) to the Tape Coordinator machine that drives the tape device, or whose local disk
          houses the backup data file. The Tape Coordinator uses a devoted connection or window that must remain open for the Tape
          Coordinator to accept requests and while it is executing them.</para>

          <para>If you plan to include the <emphasis role="bold">-localauth</emphasis> flag to the <emphasis
          role="bold">butc</emphasis> command in the next step, log in as the local superuser <emphasis
          role="bold">root</emphasis>.</para>
        </listitem>

        <listitem id="LIWQ294">
          <para>Issue the <emphasis role="bold">butc</emphasis> command to start the Tape Coordinator. You
          can include either, but not both, of the <emphasis role="bold">-localauth</emphasis> and <emphasis
          role="bold">-cell</emphasis> options, as discussed in <link linkend="HDRWQ287">Performing Backup Operations as the Local
          Superuser Root or in a Foreign Cell</link>. <programlisting>
   % <emphasis role="bold">butc</emphasis> [&lt;<emphasis>port offset</emphasis>&gt;]  [<emphasis role="bold">-debuglevel</emphasis> &lt;<emphasis>trace level</emphasis>&gt;]  \
          [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cellname</emphasis>&gt;] [<emphasis role="bold">-noautoquery</emphasis>] [<emphasis
                role="bold">-localauth</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">butc</emphasis></term>

                <listitem>
                  <para>Must be typed in full.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">port offset</emphasis></term>

                <listitem>
                  <para>Specifies the Tape Coordinator's port offset number. You must provide this argument unless the default value
                  of <emphasis role="bold">0</emphasis> (zero) is appropriate.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-debuglevel</emphasis></term>

                <listitem>
                  <para>Specifies the type of trace messages that the Tape Coordinator writes to the standard output stream
                  (stdout). Provide one of the following three values, or omit this argument to display the default type of messages
                  (equivalent to setting a value of <emphasis role="bold">0</emphasis> [zero]): <itemizedlist>
                      <listitem>
                        <para><emphasis role="bold">0</emphasis>: The Tape Coordinator generates only the minimum number of messages
                        necessary to communicate with the backup operator, including prompts for insertion of additional tapes and
                        messages that indicate errors or the beginning or completion of operations.</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">1</emphasis>: In addition to the messages displayed at level <emphasis
                        role="bold">0</emphasis>, the Tape Coordinator displays the name of each volume being dumped or
                        restored.</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">2</emphasis>: In addition to the messages displayed at levels <emphasis
                        role="bold">0</emphasis> and <emphasis role="bold">1</emphasis>, the Tape Coordinator displays all of the
                        messages it is also writing to its log file (<emphasis
                        role="bold">/usr/afs/backup/TL_</emphasis>device_name).</para>
                      </listitem>
                    </itemizedlist></para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">cellname</emphasis></term>

                <listitem>
                  <para>Names the cell in which to perform the backup operations (the cell where the relevant volumes reside and the
                  Backup Server process is running). If you omit this argument, the Tape Coordinator uses its home cell, as defined
                  in the local <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file. Do not combine this argument with the
                  <emphasis role="bold">-localauth</emphasis> flag.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-noautoquery</emphasis></term>

                <listitem>
                  <para>Disables the Tape Coordinator's prompt for the first tape it needs for each operation. For a description of
                  the advantages and consequences of including this flag, see <link linkend="HDRWQ278">Eliminating the Search or
                  Prompt for the Initial Tape</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-localauth</emphasis></term>

                <listitem>
                  <para>Constructs a server ticket using a key from the local <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis>
                  file. The <emphasis role="bold">butc</emphasis> process presents it to the Backup Server, Volume Server, and VL
                  Server during mutual authentication. You must be logged into a file server machine as the local superuser
                  <emphasis role="bold">root</emphasis> to include this flag, and cannot combine it with the <emphasis
                  role="bold">-cell</emphasis> argument.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>Tape Coordinator (Backup System)</primary>

        <secondary>stopping</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_331">
      <title>To stop a Tape Coordinator process</title>

      <orderedlist>
        <listitem>
          <para>Enter an interrupt signal such as &lt;<emphasis role="bold">Ctrl-c</emphasis>&gt; over the dedicated connection to
          the Tape Coordinator.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>Tape Coordinator (Backup System)</primary>

        <secondary>status</secondary>

        <tertiary>displaying</tertiary>
      </indexterm>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>status</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup status</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ295">
      <title>To check the status of a Tape Coordinator process</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup status</emphasis> command. <programlisting>
   % <emphasis role="bold">backup status</emphasis> [&lt;<emphasis>TC port offset</emphasis>&gt;]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">st</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">status</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">TC port offset</emphasis></term>

                <listitem>
                  <para>Specifies the Tape Coordinator's port offset number. You must provide this argument unless the default value
                  of <emphasis role="bold">0</emphasis> (zero) is appropriate.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>The following message indicates that the Tape Coordinator is not currently performing an operation:</para>

      <programlisting>
   Tape coordinator is idle
</programlisting>

      <para>Otherwise, the output includes a message of the following format for each running or pending operation:</para>

      <programlisting>
   Task task_ID:  operation:   status
</programlisting>

      <para>where <variablelist>
          <varlistentry>
            <term><emphasis role="bold">task_ID</emphasis></term>

            <listitem>
              <para>Is a task identification number assigned by the Tape Coordinator. It begins with the Tape Coordinator's port
              offset number.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">operation</emphasis></term>

            <listitem>
              <para>Identifies the operation the Tape Coordinator is performing, which is initiated by the indicated command:
              <itemizedlist>
                  <listitem>
                    <para><computeroutput>Dump</computeroutput> (the <emphasis role="bold">backup dump</emphasis> command)</para>
                  </listitem>

                  <listitem>
                    <para><computeroutput>Restore</computeroutput> (the <emphasis role="bold">backup diskrestore</emphasis>,
                    <emphasis role="bold">backup volrestore</emphasis>, or <emphasis role="bold">backup volsetrestore</emphasis>
                    commands)</para>
                  </listitem>

                  <listitem>
                    <para><computeroutput>Labeltape</computeroutput> (the <emphasis role="bold">backup labeltape</emphasis>
                    command)</para>
                  </listitem>

                  <listitem>
                    <para><computeroutput>Scantape</computeroutput> (the <emphasis role="bold">backup scantape</emphasis>
                    command)</para>
                  </listitem>

                  <listitem>
                    <para><computeroutput>SaveDb</computeroutput> (the <emphasis role="bold">backup savedb</emphasis>
                    command)</para>
                  </listitem>

                  <listitem>
                    <para><computeroutput>RestoreDb</computeroutput> (the <emphasis role="bold">backup restoredb</emphasis>
                    command)</para>
                  </listitem>
                </itemizedlist></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">status</emphasis></term>

            <listitem>
              <para>Indicates the job's current status in one of the following messages. <variablelist>
                  <varlistentry>
                    <term><emphasis role="bold">number <computeroutput>Kbytes transferred, volume</computeroutput>
                    volume_name</emphasis></term>

                    <listitem>
                      <para>For a running dump operation, indicates the number of kilobytes copied to tape or a backup data file so
                      far, and the volume currently being dumped.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold">number <computeroutput>Kbytes, restore.volume</computeroutput></emphasis></term>

                    <listitem>
                      <para>For a running restore operation, indicates the number of kilobytes copied into AFS from a tape or a
                      backup data file so far.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[abort requested]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The <emphasis role="bold">(backup) kill</emphasis> command was issued, but the termination signal has
                      yet to reach the Tape Coordinator.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[abort sent]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The operation is canceled by the <emphasis role="bold">(backup) kill</emphasis> command. Once the Backup
                      System removes an operation from the queue or stops it from running, it no longer appears at all in the output
                      from the command.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[butc contact lost]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The <emphasis role="bold">backup</emphasis> command interpreter cannot reach the Tape Coordinator. The
                      message can mean either that the Tape Coordinator handling the operation was terminated or failed while the
                      operation was running, or that the connection to the Tape Coordinator timed out.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[done]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The Tape Coordinator has finished the operation.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[drive wait]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The operation is waiting for the specified tape drive to become free.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><emphasis role="bold"><computeroutput>[operator wait]</computeroutput></emphasis></term>

                    <listitem>
                      <para>The Tape Coordinator is waiting for the backup operator to insert a tape in the drive.</para>
                    </listitem>
                  </varlistentry>
                </variablelist></para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <para>If the Tape Coordinator is communicating with an XBSA server (a third-party backup utility that implements the Open
      Group's Backup Service API [XBSA]), the following message appears last in the output:</para>

      <programlisting>
   XBSA_program Tape coordinator
</programlisting>

      <para>where XBSA_program is the name of the XBSA-compliant program.</para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ296">
    <title>Backing Up Data</title>

    <indexterm>
      <primary>volume</primary>

      <secondary>backing up using Backup System</secondary>
    </indexterm>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>data</secondary>

      <tertiary>backing up/dumping</tertiary>
    </indexterm>

    <indexterm>
      <primary>dump set (Backup System)</primary>

      <secondary>creating</secondary>
    </indexterm>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>dumps, full and incremental defined</secondary>
    </indexterm>

    <indexterm>
      <primary>dump set (Backup System)</primary>

      <secondary>full dumps</secondary>
    </indexterm>

    <indexterm>
      <primary>dump set (Backup System)</primary>

      <secondary>incremental dumps</secondary>
    </indexterm>

    <indexterm>
      <primary>full dump</primary>
    </indexterm>

    <indexterm>
      <primary>incremental dump</primary>

      <secondary>creating with Backup System</secondary>
    </indexterm>

    <indexterm>
      <primary>backing up</primary>

      <secondary>data from AFS volumes</secondary>
    </indexterm>

    <indexterm>
      <primary>dumping</primary>

      <secondary>data</secondary>
    </indexterm>

    <indexterm>
      <primary>dumping</primary>

      <secondary>full dumps</secondary>
    </indexterm>

    <indexterm>
      <primary>dumping</primary>

      <secondary>incremental dumps</secondary>
    </indexterm>

    <para>This section explains how to use the <emphasis role="bold">backup dump</emphasis> command to back up AFS data to tape or
    to a backup data file. The instructions assume that you understand Backup System concepts and have already configured the Backup
    System according to the instructions in <link linkend="HDRWQ248">Configuring the AFS Backup System</link>. Specifically, you
    must already have: <itemizedlist>
        <listitem>
          <para>Decided whether to dump data to tape or to a backup data file, and configured the Tape Coordinator machine and Tape
          Coordinator process appropriately. See <link linkend="HDRWQ261">Configuring Tape Coordinator Machines and Tape
          Devices</link> and <link linkend="HDRWQ282">Dumping Data to a Backup Data File</link>.</para>
        </listitem>

        <listitem>
          <para>Defined a volume set that includes the volumes you want to dump together. See <link linkend="HDRWQ265">Defining and
          Displaying Volume Sets and Volume Entries</link>.</para>
        </listitem>

        <listitem>
          <para>Defined the dump level in the dump hierarchy at which you want to dump the volume set. If it is an incremental dump
          level, you must have previously created a dump at its parent level. See <link linkend="HDRWQ267">Defining and Displaying
          the Dump Hierarchy</link>.</para>
        </listitem>

        <listitem>
          <para>Created a device configuration file. Such a file is required for each tape stacker, jukebox device, or backup data
          file. You can also use it to configure the Backup System's automation features. See <link linkend="HDRWQ275">Automating
          and Increasing the Efficiency of the Backup Process</link>.</para>
        </listitem>
      </itemizedlist></para>

    <para>The most basic way to perform a dump operation is to create an initial dump of a single volume set as soon as the
    appropriate Tape Coordinator is available, by providing only the required arguments to the <emphasis role="bold">backup
    dump</emphasis> command. Instructions appear in <link linkend="HDRWQ301">To create a dump</link>. The command has several
    optional arguments that you can use to increase the efficiency and flexibility of your backup procedures: <itemizedlist>
        <listitem>
          <para>To append a dump to the end of a set of tapes that already contains other dumps, include the <emphasis
          role="bold">-append</emphasis> argument. Otherwise, the Backup System creates an initial dump. Appending dumps enables you
          to use a tape's full capacity and has other potentially useful features. For a discussion, see <link
          linkend="HDRWQ299">Appending Dumps to an Existing Dump Set</link>.</para>
        </listitem>

        <listitem>
          <para>To schedule one or more dump operations to run at a future time, include the <emphasis role="bold">-at</emphasis>
          argument. For a discussion and instructions, see <link linkend="HDRWQ300">Scheduling Dumps</link>.</para>
        </listitem>

        <listitem>
          <para>To initiate a number of dump operations with a single <emphasis role="bold">backup dump</emphasis> command, include
          the <emphasis role="bold">-file</emphasis> argument to name a file in which you have listed the commands. For a discussion
          and instructions, see <link linkend="HDRWQ299">Appending Dumps to an Existing Dump Set</link> and <link
          linkend="HDRWQ300">Scheduling Dumps</link>.</para>
        </listitem>

        <listitem>
          <para>To generate a list of the volumes to be included in a dump, without actually dumping them, combine the <emphasis
          role="bold">-n</emphasis> flag with the other arguments to be used on the actual command.</para>
        </listitem>
      </itemizedlist></para>

    <sect2 id="HDRWQ297">
      <title>Making Backup Operations More Efficient</title>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>suggestions for improving efficiency</secondary>
      </indexterm>

      <para>There are several ways to make dump operations more efficient, less prone to error, and less disruptive to your users.
      Several of them also simplify the process of restoring data if that becomes necessary. <itemizedlist>
          <listitem>
            <para>It is best not to dump the read/write or read-only version of a volume, because no other users or processes can
            access a volume while it is being dumped. Instead, shortly before the dump operation begins, create a backup version of
            each volume to be dumped, and dump the backup version. Creating a Backup version usually makes the source volume
            unavailable for just a few moments (during which access attempts by other processes are blocked but do not fail). To
            automate the creation of backup volumes, you can create a <emphasis role="bold">cron</emphasis> process in the <emphasis
            role="bold">/usr/afs/local/BosConfig</emphasis> file on one or more server machines, setting its start time at a
            sufficient interval before the dump operation is to begin. Include the <emphasis role="bold">-localauth</emphasis>
            argument to the <emphasis role="bold">vos backup</emphasis> or <emphasis role="bold">vos backupsys</emphasis> command to
            enable it to run without administrative tokens. For instructions, see <link linkend="HDRWQ162">To create and start a new
            process</link>.</para>
          </listitem>

          <listitem>
            <para>The volume set, dump level, and Tape Coordinator port offset you specify on the <emphasis role="bold">backup
            dump</emphasis> command line must be properly defined in the Backup Database. The Backup System checks the database
            before beginning a dump operation and halts the command immediately if any of the required entities are missing. If
            necessary, use the indicated commands: <itemizedlist>
                <listitem>
                  <para>To display volume sets, use the <emphasis role="bold">backup listvolsets</emphasis> command as described in
                  <link linkend="HDRWQ266">To display volume sets and volume entries</link>.</para>
                </listitem>

                <listitem>
                  <para>To display dump levels, use the <emphasis role="bold">backup listdumps</emphasis> command as described in
                  <link linkend="HDRWQ271">To display the dump hierarchy</link>.</para>
                </listitem>

                <listitem>
                  <para>To display port offsets, use the <emphasis role="bold">backup listhosts</emphasis> command as described in
                  <link linkend="HDRWQ264">To display the list of configured Tape Coordinators</link>.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>

          <listitem>
            <para>Ensure that a valid token corresponding to a privileged administrative identity is available to the Backup System
            processes both when the <emphasis role="bold">backup dump</emphasis> command is issued and when the dump operation
            actually runs (for a complete description or the necessary privileges, see <link linkend="HDRWQ260">Granting
            Administrative Privilege to Backup Operators</link>). This is a special concern for scheduled dumps. One alternative is
            to run <emphasis role="bold">backup</emphasis> commands (or the script that invokes them) and the <emphasis
            role="bold">butc</emphasis> command on server machines, and to include the <emphasis role="bold">-localauth</emphasis>
            argument on the command. In this case, the processes use the key with the highest key version number in the local
            <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file to construct a token that never expires. Otherwise, you must
            use a method to renew tokens before they expire, or grant tokens with long lifetimes. In either case, you must protect
            against improper access to the tokens by securing the machines both physically and against unauthorized network access.
            The protection possibly needs to be even stronger than when a human operator is present during the operations.</para>
          </listitem>

          <listitem>
            <para>Record tape capacity and filemark size values that are as accurate as possible in the Tape Coordinator's <emphasis
            role="bold">/usr/afs/backup/tapeconfig</emphasis> file and on the tape's label. For suggested values and a description
            of what can happen when they are inaccurate, see <link linkend="HDRWQ258">Configuring the tapeconfig File</link>.</para>
          </listitem>

          <listitem>
            <para>If an unattended dump requires multiple tapes, arrange to provide them by properly configuring a tape stacker or
            jukebox and writing a tape-mounting script to be invoked in the device's <emphasis
            role="bold">CFG_</emphasis>device_name file. For instructions, see <link linkend="HDRWQ277">Invoking a Device's Tape
            Mounting and Unmounting Routines</link>.</para>
          </listitem>

          <listitem>
            <para>You can configure any tape device or backup data file's <emphasis role="bold">CFG_</emphasis>device_name file to
            take advantage of the Backup System's automation features. See <link linkend="HDRWQ275">Automating and Increasing the
            Efficiency of the Backup Process</link>.</para>
          </listitem>

          <listitem>
            <para>When you issue a <emphasis role="bold">backup</emphasis> command in regular (noninteractive) mode, the command
            shell prompt does not return until the operation completes. To avoid having to open additional connections, issue the
            <emphasis role="bold">backup dump</emphasis> command in interactive mode, especially when including the <emphasis
            role="bold">-at</emphasis> argument to schedule dump operations.</para>
          </listitem>

          <listitem>
            <para>An incremental dump proceeds most smoothly if there is a dump created at the dump level immediately above the
            level you are using. If the Backup System does not find a Backup Database record for a dump created at the immediate
            parent level, it looks for a dump created at one level higher in the hierarchy, continuing up to the full dump level if
            necessary. It creates an incremental dump at the level one below the lowest valid parent dump that it finds, or even
            creates a full dump if that is necessary. This algorithm guarantees that the dump captures all data that has changed
            since the last dump, but has a couple of disadvantages. First, the Backup System's search through the database for a
            valid parent dump takes extra time. Second, the subsequent pattern of dumps can be confusing to a human operator who
            needs to restore data from them, because they were not performed at the expected dump levels.</para>

            <para>The easiest way to guarantee that a dump exists at the immediate parent level is always to perform dump operations
            on the predetermined schedule. To check that the parent dump exists, you can issue the <emphasis role="bold">backup
            dumpinfo</emphasis> command (as described in <link linkend="HDRWQ303">To display dump records</link>) and search for it
            in the output. Alternatively, issue the <emphasis role="bold">backup volinfo</emphasis> command (as described in <link
            linkend="HDRWQ304">To display a volume's dump history</link>) for a volume that you believe is in the parent
            dump.</para>
          </listitem>

          <listitem>
            <para>Always use dump levels from the same hierarchy (levels that are descendants of the same full level) when dumping a
            given volume set. The result of alternating between levels from different hierarchies can be confusing when you need to
            restore data or read dump records. It also increases the chance that changed data is not captured in any dump, or is
            backed up redundantly into more than one dump.</para>
          </listitem>

          <listitem>
            <para>Use permanent tape names rather than AFS tape names. You can make permanent names more descriptive than is allowed
            by an AFS tape name's strict format, and also bypass the name-checking step that the Backup System performs by default
            when a tape has an AFS tape name only. You can also configure the Tape Coordinator always to skip the check, however;
            for instructions and a description of the acceptable format for AFS tape names, see <link linkend="HDRWQ280">Eliminating
            the AFS Tape Name Check</link>.</para>
          </listitem>

          <listitem>
            <para>If you write dumps to tape, restore operations are simplest if all of your tape devices are compatible (can read
            the same type of tape, at the same compression ratios, and so on). If you must use incompatible devices, then at least
            use compatible devices for all dumps performed at dump levels that are at the same depth in their respective hierarchies
            (compatible devices for all dumps performed at a full dump level, compatible devices for all dumps performed at a level
            1 incremental dump level, and so on). The <emphasis role="bold">-portoffset</emphasis> argument to the <emphasis
            role="bold">backup diskrestore</emphasis> and <emphasis role="bold">backup volsetrestore</emphasis> commands accepts
            multiple port offset numbers, but uses the first listed port offset when restoring all full dumps, the second port
            offset when restoring all level 1 dumps, and so on. If you did not use compatible tape devices when creating dumps at
            the same depth in a hierarchy, you must restore one volume at a time with the <emphasis role="bold">backup
            volrestore</emphasis> command.</para>
          </listitem>

          <listitem>
            <para>In some cases, it makes sense to use a <emphasis>temporary</emphasis> volume set, which exists only within the
            context of the interactive session in which it is created and for which no record is created in the Backup Database. One
            suitable situation is when dumping a volume to tape in preparation for removing it permanently (perhaps because its
            owner is leaving the cell). In this case, you can define a volume entry that includes only the volume of interest
            without cluttering up the Backup Database with a volume set record that you are using only once.</para>
          </listitem>

          <listitem>
            <para>Do not perform a dump operation when you know that there are network, machine, or server process problems that can
            prevent the Backup System from accessing volumes or the Volume Location Database (VLDB). Although the Backup System
            automatically makes a number of repeated attempts to get to an inaccessible volume, the dump operation takes extra time
            and in some cases stops completely to prompt you for instructions on how to continue. Furthermore, if the Backup
            System's last access attempt fails and the volume is omitted from the dump, you must take extra steps to have it backed
            up (namely, the steps described just following for a halted dump operation). For a more complete description of how the
            Backup System makes repeated access attempts, see <link linkend="HDRWQ298">How Your Configuration Choices Influence the
            Dump Process</link>.</para>
          </listitem>

          <listitem>
            <para>Review the logs created by the Backup System as soon as possible after a dump operation completes, particularly if
            it ran unattended. They name any volumes that were not successfully backed up, among other problems. The Backup Server
            writes to the <emphasis role="bold">/usr/afs/logs/BackupLog</emphasis> file on the local disk of the database server
            machine, and you can use the <emphasis role="bold">bos getlog</emphasis> command to read it remotely if you wish; for
            instructions, see <link linkend="HDRWQ173">Displaying Server Process Log Files</link>. The Tape Coordinator writes to
            two files in the local <emphasis role="bold">/usr/afs/backup</emphasis> directory on the machine where it is running:
            the <emphasis role="bold">TE_</emphasis>device_name file records errors, and the <emphasis
            role="bold">TL_</emphasis>device_name file records both trace and error messages.</para>
          </listitem>

          <listitem>
            <para>Avoid halting a dump operation (for instance, by issuing the <emphasis role="bold">(backup) kill</emphasis>
            command in interactive mode), both because it introduces the potential for confusion and because recovering from the
            interruption requires extra effort. When a dump operation is interrupted, the volumes that were backed up before the
            halt signal is received are complete on the tape or in the backup data file, and are usable in restore operations. The
            records in the Backup Database about the volumes' dump history accurately show when and at which dump level they were
            backed up; to display the records, use the <emphasis role="bold">backup volinfo</emphasis> command as described in <link
            linkend="HDRWQ304">To display a volume's dump history</link>.</para>

            <para>However, there is no indication in the dump's Backup Database record that volumes were omitted; to display the
            record, use the <emphasis role="bold">backup dumpinfo</emphasis> command as described in <link linkend="HDRWQ303">To
            display dump records</link>. You must choose one of the following methods for dealing with the volumes that were not
            backed up before the dump operation halted. (Actually, you must make the same decision if the dump operation halts for
            reasons outside your control.) <itemizedlist>
                <listitem>
                  <para>You can take no action, waiting until the next regularly scheduled dump operation to back them up. At that
                  time, the Backup System automatically dumps them at the appropriate level to guarantee that the dump captures all
                  of the data that changed since the volume was last dumped. However, you are gambling that restoring the volume is
                  not necessary before the next dump operation. If restoration is necessary, you can restore the volume only to its
                  state at the time it was last included in a dump--you have lost all changes made to the volume since that
                  time.</para>
                </listitem>

                <listitem>
                  <para>You can discard the entire dump and run the dump operation again. To discard the dump, use the <emphasis
                  role="bold">backup labeltape</emphasis> command to relabel the tapes or backup data file, which automatically
                  removes all associated records from the Backup Database. For instructions, see <link linkend="HDRWQ272">Writing
                  and Reading Tape Labels</link>. If a long time has passed since the backup version of the volumes was created,
                  some of the source volumes have possibly changed. If that seems likely, reissue the <emphasis role="bold">vos
                  backup</emphasis> or <emphasis role="bold">vos backupsys</emphasis> command on them before redoing the dump
                  operation.</para>
                </listitem>

                <listitem>
                  <para>You can create a new volume set that includes the missed volumes and dump it at a full dump level (even if
                  you specify an incremental dump level, the Backup System uses the full dump level at the top of your specified
                  level's hierarchy, because it has never before backed up these volumes as part of the new volume set). The next
                  time you dump the original volume set, the Backup System automatically dumps the missed volumes at the level one
                  below the level it used the last time it dumped the volumes as part of the original volume set.</para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ298">
      <title>How Your Configuration Choices Influence the Dump Process</title>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>dump operation, overview</secondary>
      </indexterm>

      <para>This section provides an overview of the backup process, describing what happens at each stage both by default and as a
      result of your configuration choices, including the configuration instructions you include in the device-specific <emphasis
      role="bold">CFG_</emphasis>device_name file. For the sake of clarity, it tracks the progress of a single <emphasis
      role="bold">backup dump</emphasis> command that creates an initial dump. For a discussion of the slight differences in the
      procedure when you append or schedule dumps, see <link linkend="HDRWQ299">Appending Dumps to an Existing Dump Set</link> or
      <link linkend="HDRWQ300">Scheduling Dumps</link>.</para>

      <para>As a concrete example, the following description traces a dump of the volume set <emphasis role="bold">user</emphasis>
      at the <emphasis role="bold">/weekly/mon/tues/wed</emphasis> dump level. The <emphasis role="bold">user</emphasis> volume set
      has one volume entry that matches the backup version of all user volumes:</para>

      <programlisting>
        <emphasis role="bold">.*    .*    user.*\.backup</emphasis>
      </programlisting>

      <para>The dump level belongs to the following dump hierarchy.</para>

      <programlisting>
   /weekly
          /mon
              /tues
                   /wed
                       /thurs
                             /fri
</programlisting>

      <orderedlist>
        <listitem id="LIBKOV-BUTC">
          <para>You issue the <emphasis role="bold">butc</emphasis> command to start a Tape Coordinator
          to handle the dump operation. The Tape Coordinator does not have to be running when you issue the <emphasis
          role="bold">backup dump</emphasis> command, but must be active in time to accept the list of volumes to be included in the
          dump, when Step <link linkend="LIBKOV-VOLMATCHES">3</link> is completed. To avoid coordination problems, it is best to
          start the Tape Coordinator before issuing the <emphasis role="bold">backup dump</emphasis> command.</para>

          <para>As the Tape Coordinator initializes, it reads the entry in its local <emphasis
          role="bold">/usr/afs/backup/tapeconfig</emphasis> file for the port offset you specify on the <emphasis
          role="bold">butc</emphasis> command line. The entry specifies the name of the device to use, and the Tape Coordinator
          verifies that it can access it. It also reads the device's configuration file, <emphasis
          role="bold">/usr/afs/backup/CFG_</emphasis>device_name, if it exists. See Step <link linkend="LIBKOV-READCFG">6</link> for
          a description of how the instructions in the file influence the dump operation.</para>
        </listitem>

        <listitem>
          <para>You issue the <emphasis role="bold">backup dump</emphasis> command, specifying a volume set, dump level, and the
          same port offset number you specified on the <emphasis role="bold">butc</emphasis> command in Step <link
          linkend="LIBKOV-BUTC">1</link>. The Backup System verifies that they have correct Backup Database records and halts the
          operation with an error message if they do not.</para>

          <para>If you issue the command in interactive mode, the Backup System assigns the operation a job ID number, which you can
          use to check the operation's status or halt it by using the <emphasis role="bold">(backup) jobs</emphasis> or <emphasis
          role="bold">(backup) kill</emphasis> command, respectively. For instructions, see <link linkend="HDRWQ289">To display
          pending or running jobs in interactive mode</link> and <link linkend="HDRWQ290">To cancel operations in interactive
          mode</link>.</para>
        </listitem>

        <listitem id="LIBKOV-VOLMATCHES">
          <para>The Backup System works with the VL Server to generate a list of the volumes in the
          VLDB that match the name and location criteria defined in the volume set's volume entries. If a volume matches more than
          one volume entry, the Backup System ignores the duplicates so that the dump includes only one copy of data from the
          volume.</para>

          <para>To reduce the number of times you need to switch tapes during a restore operation, the Backup System sorts the
          volumes by server machine and partition, and during the dump operation writes the data from all volumes stored on a
          specific partition before moving to the next partition.</para>

          <para>As previously mentioned, it is best to back up backup volumes rather than read/write volumes, to avoid blocking
          users' access to data during the dump. To achieve this, you must explicitly include the <emphasis
          role="bold">.backup</emphasis> suffix on the volume names in volume entry definitions. For instructions, and to learn how
          to define volume entries that match multiple volumes, see <link linkend="HDRWQ265">Defining and Displaying Volume Sets and
          Volume Entries</link>.</para>

          <para>In the example, suppose that 50 volumes match the <emphasis role="bold">user</emphasis> volume set criteria,
          including three called <emphasis role="bold">user.pat.backup</emphasis>, <emphasis
          role="bold">user.terry.backup</emphasis>, and <emphasis role="bold">user.smith.backup</emphasis>.</para>
        </listitem>

        <listitem id="LIBKOV-CLONEDATE">
          <para>The Backup System next scans the dump hierarchy for the dump level you have
          specified on the <emphasis role="bold">backup dump</emphasis> command line. If it is a full level, then in the current
          operation the Backup System backs up all of the data in all of the volumes in the list obtained in Step <link
          linkend="LIBKOV-VOLMATCHES">3</link>.</para>

          <para>If the dump level is incremental, the Backup System reads each volume's dump history in the Backup Database to learn
          which of the parent levels in its pathname was used when the volume was most recently backed up as part of this volume
          set. In the usual case, it is the current dump level's immediate parent level.</para>

          <para>An incremental dump of a volume includes only the data that changed since the volume was included in the parent
          dump. To determine which data are eligible, the Backup System uses the concept of a volume's <emphasis>clone
          date</emphasis>. A read/write volume's clone date is when the Backup System locks the volume before copying its contents
          into a dump. A backup volume's clone date is the completion time of the operation that created it by cloning its
          read/write source volume (the operation initiated by a <emphasis role="bold">vos backup</emphasis> or <emphasis
          role="bold">vos backupsys</emphasis> command). A read-only volume's clone date is the time of the release operation
          (initiated by the <emphasis role="bold">vos release</emphasis> command) that completed most recently before the dump
          operation.</para>

          <para>More precisely then, an incremental dump includes only data that have a modification timestamp between the clone
          date of the volume included in the parent dump (the <emphasis>parent clone date</emphasis>) and the clone date of the
          volume to be included in the current dump (the <emphasis>current clone date</emphasis>).</para>

          <para>There are some common exceptions to the general rule that a volume's parent dump is the dump created at the
          immediate parent level: <itemizedlist>
              <listitem>
                <para>The volume did not exist at all at the time of the last dump. In this case, the Backup System automatically
                does a full dump of it.</para>
              </listitem>

              <listitem>
                <para>The volume did not match the volume set's name and location criteria at the time of the last dump. In this
                case, the Backup System automatically does a full dump of it, even if it was backed up recently (fully or
                incrementally) as part of another volume set. This redundancy is an argument for defining volume entries in terms of
                names rather than locations, particularly if you move volumes frequently.</para>
              </listitem>

              <listitem>
                <para>The volume was not included in the dump at the immediate parent level for some reason (perhaps a process,
                machine, or network access prevented the Backup System from accessing it). In this case, the Backup System sets the
                clone date to the time of the last dump operation that included the volume. If the volume was not included in a dump
                performed at any of the levels in the current level's pathname, the Backup System does a full dump of it.</para>
              </listitem>
            </itemizedlist></para>

          <para>In the example, the current dump level is <emphasis role="bold">/weekly/mon/tues/wed</emphasis>. The <emphasis
          role="bold">user.pat.backup</emphasis> and <emphasis role="bold">user.terry.backup</emphasis> volumes were included in the
          dump performed yesterday, Tuesday, at the <emphasis role="bold">/weekly/mon/tues</emphasis> level. The Backup System uses
          as their parent clone date 3:00 a.m. on Tuesday, which is when backup versions of them were created just before Tuesday's
          dump operation. However, Tuesday's dump did not include the <emphasis role="bold">user.smith.backup</emphasis> volume for
          some reason. The last time it was included in a dump was Monday, at the <emphasis role="bold">/weekly/mon</emphasis>
          level. The Backup System uses a parent clone date of Monday at 2:47 a.m., which is when a backup version of the volume was
          created just before the dump operation on Monday.</para>
        </listitem>

        <listitem>
          <para>If performing an incremental dump, the Backup System works with the Volume Server to prepare a list of all of the
          files in each volume that have changed (have modification timestamps) between the parent clone date and the current clone
          date. The dump includes the complete contents of every such file. If a file has not changed, the dump includes only a
          placeholder stub for it. The dump also includes a copy of the complete directory structure in the volume, whether or not
          it has changed since the previous dump.</para>

          <para>If none of the data in the volume has changed since the last dump, the Backup System omits the volume completely. It
          generates the following message in the Tape Coordinator window and log files:</para>

          <programlisting>
   Volume volume_name (volume_ID) not dumped - has not been modified 
      since last dump.
</programlisting>
        </listitem>

        <listitem id="LIBKOV-READCFG">
          <para>The Tape Coordinator prepares to back up the data. If there is a <emphasis
          role="bold">CFG_</emphasis>device_name file, the Tape Coordinator already read it in Step <link
          linkend="LIBKOV-BUTC">1</link>. The following list describes how the instructions in the file guide the Tape Coordinator's
          behavior at this point: <variablelist>
              <varlistentry>
                <term><emphasis role="bold">FILE</emphasis></term>

                <listitem>
                  <para>If this instruction is set to <emphasis role="bold">YES</emphasis>, the Tape Coordinator writes data to a
                  backup data file. The device_name field in the <emphasis role="bold">tapeconfig</emphasis> file must also specify
                  a filename for the dump to work properly. For further discussion and instructions on configuring a backup data
                  file, see <link linkend="HDRWQ282">Dumping Data to a Backup Data File</link>.</para>

                  <para>If it is set to <emphasis role="bold">NO</emphasis> or does not appear in the file, the Tape Coordinator
                  writes to a tape device.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">MOUNT and UNMOUNT</emphasis></term>

                <listitem>
                  <para>If there is a <emphasis role="bold">MOUNT</emphasis> instruction in the file, each time the Tape Coordinator
                  needs a new tape, it invokes the indicated script or program to mount a tape in the device's tape drive. There
                  must be a <emphasis role="bold">MOUNT</emphasis> instruction if you want to utilize a tape stacker or jukebox's
                  ability to switch between tapes automatically. If there is no <emphasis role="bold">MOUNT</emphasis> instruction,
                  the Tape Coordinator prompts the human operator whenever it needs a tape.</para>

                  <para>The <emphasis role="bold">AUTOQUERY</emphasis> instruction, which is described just following, modifies the
                  Tape Coordinator's tape acquisition procedure for the first tape it needs in a dump operation.</para>

                  <para>If there is an <emphasis role="bold">UNMOUNT</emphasis> instruction, then the Tape Coordinator invokes the
                  indicated script or program whenever it closes the tape device. Not all tape devices have a separate tape
                  unmounting routine, in which case the <emphasis role="bold">UNMOUNT</emphasis> instruction is not necessary. For
                  more details on both instructions, see <link linkend="HDRWQ277">Invoking a Device's Tape Mounting and Unmounting
                  Routines</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">AUTOQUERY</emphasis></term>

                <listitem>
                  <para>If this instruction is set to <emphasis role="bold">NO</emphasis>, the Tape Coordinator assumes that the
                  first tape needed for the dump operation is already in the tape drive. It does not use its usual tape acquisition
                  procedure as described in the preceding discussion of the <emphasis role="bold">MOUNT</emphasis> instruction. You
                  can achieve the same effect by including the <emphasis role="bold">-noautoquery</emphasis> flag to the <emphasis
                  role="bold">butc</emphasis> command.</para>

                  <para>If this instruction is absent or set to <emphasis role="bold">YES</emphasis>, the Tape Coordinator uses its
                  usual tape acquisition procedure even for the first tape. For more details, see <link
                  linkend="HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">BUFFERSIZE</emphasis></term>

                <listitem>
                  <para>If this instruction appears in the file, the Tape Coordinator sets its buffer size to the specified value
                  rather than using the default buffer size of 16 KB. For further discussion, see <link linkend="HDRWQ281">Setting
                  the Memory Buffer Size to Promote Tape Streaming</link>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>

          <para>If there is no <emphasis role="bold">CFG_</emphasis>device_name file, the Tape Coordinator writes data to a tape
          device and prompts the human operator each time it needs a tape (the only exception being the first tape if you include
          the <emphasis role="bold">-noautoquery</emphasis> flag to the <emphasis role="bold">butc</emphasis> command).</para>
        </listitem>

        <listitem id="LIBKOV-NAMECHECK">
          <para>The Tape Coordinator opens either a tape drive or backup data file at this point, as
          directed by the instructions in the <emphasis role="bold">CFG_</emphasis>device_name file (described in Step <link
          linkend="LIBKOV-READCFG">6</link>). The instructions also determine whether it invokes a mount script or prompts the
          operator. In Step <link linkend="LIBKOV-BUTC">1</link> the Tape Coordinator read in the device's capacity and filemark
          size from the <emphasis role="bold">tapeconfig</emphasis> file. It now reads the same values from the tape or backup data
          file's magnetic label, and overwrites the <emphasis role="bold">tapeconfig</emphasis> values if there is a
          difference.</para>

          <para>If creating an initial dump (as in the current example) and there is no permanent name on the label, the Tape
          Coordinator next checks that the AFS tape name has one of the three acceptable formats. If not, it rejects the tape and
          you must use the <emphasis role="bold">backup labeltape</emphasis> command to write an acceptable name. You can bypass
          this name-checking step by including the <emphasis role="bold">NAME_CHECK NO</emphasis> instruction in the <emphasis
          role="bold">CFG_</emphasis>device_name file. For discussion and a list of the acceptable AFS tape name values, see <link
          linkend="HDRWQ280">Eliminating the AFS Tape Name Check</link>.</para>
        </listitem>

        <listitem id="LIBKOV-EXPDATE">
          <para>For an initial dump, the Tape Coordinator starts writing at the beginning of the tape
          or backup dump file, overwriting any existing data. To prevent inappropriate overwriting, the Backup System first checks
          the Backup Database for any dump records associated with the name (permanent or AFS tape name) on the tape or backup dump
          file's label. It refuses to write to a backup data file that has unexpired dumps in it, or to a tape that belongs to a
          dump set with any unexpired dumps. To recycle a file or tape before all dumps have expired, you must use the <emphasis
          role="bold">backup labeltape</emphasis> command to relabel it. Doing so removes the Backup Database records of all dumps
          in the file or on all tapes in the dump set, which makes it impossible to restore data from any of the tapes. For more
          information on expiration dates, see <link linkend="HDRWQ270">Defining Expiration Dates</link>.</para>

          <para>The Tape Coordinator also checks for two other types of inappropriate tape reuse. The tape cannot already have data
          on it that belongs to the dump currently being performed, because that implies that the previous tape is still in the
          drive, or you have mistakenly reinserted it. The Tape Coordinator generates the following message and attempts to obtain
          another tape:</para>

          <programlisting>
   Can't overwrite tape containing the dump in progress
</programlisting>

          <para>The tape cannot contain data from a parent dump of the current (incremental) dump, because overwriting a parent dump
          makes it impossible to restore data from the current dump. The Tape Coordinator generates the following message and
          attempts to obtain another tape:</para>

          <programlisting>
   Can't overwrite the parent dump parent_name (parent_dump_ID)
</programlisting>
        </listitem>

        <listitem id="LIBKOV-WRITE">
          <para>The Tape Coordinator now writes data to the tape or backup data file. It uses the
          capacity and filemark size it obtained in Step <link linkend="LIBKOV-NAMECHECK">7</link> as it tracks how much more space
          is available, automatically using its tape acquisition procedure if the dump is not finished when it reaches the end of
          the tape. For a more detailed description, and a discussion of what happens if the Tape Coordinator reaches the physical
          end-of-tape unexpectedly, see <link linkend="HDRWQ258">Configuring the tapeconfig File</link>. Similarly, for instructions
          on configuring a backup data file to optimize recovery from unexpectedly running out of space, see Step <link
          linkend="LITAPECONFIG-FILE">6</link> in the instructions in <link linkend="HDRWQ282">Dumping Data to a Backup Data
          File</link>.</para>

          <para>If the Tape Coordinator cannot access a volume during the dump (perhaps because of a server process, machine, or
          network outage), it skips the volume and continues dumping all volumes that it can access. It generates an error message
          in the Tape Coordinator window and log file about the omitted volume. It generates a similar message if it discovers that
          a backup volume has not been recloned since the previous dump operation (that is, that the volume's current clone date is
          the same as its parent clone date):</para>

          <programlisting>
   Volume volume_name (volume_ID) not dumped - has not been re-cloned 
       since last dump.
</programlisting>

          <para>After completing a first pass through all of the volumes, it attempts to dump each omitted volume again. It first
          checks to see if the reason that the volume was inaccessible during the first pass is that it has been moved since the VL
          Server generated the list of volumes to dump in Step <link linkend="LIBKOV-VOLMATCHES">3</link>. If so, it dumps the
          volume from its new site. If the second attempt to access a volume also fails, the Tape Coordinator it generates the
          following message, prompting you for instruction on how to proceed:</para>

          <programlisting>
   Dump of volume volume_name (volume_ID) failed
   Please select action to be taken for this volume.
      r - retry, try dumping this volume again
      o - omit, this volume from this dump
      a - abort, the entire dump
</programlisting>

          <para>To increase the automation of the dump process, you can include the <emphasis role="bold">ASK NO</emphasis>
          instruction in the <emphasis role="bold">CFG_</emphasis>device_name file to suppress this prompt and have the Tape
          Coordinator automatically omit the volume from the dump.</para>

          <para>If you are tracking the dump as it happens, the prompt enables you to take corrective action. If the volume has not
          been recloned, you can issue the <emphasis role="bold">vos backup</emphasis> command. If the volume is inaccessible, you
          can investigate and attempt to resolve the cause.</para>

          <indexterm>
            <primary>dump ID numbers (Backup System)</primary>
          </indexterm>

          <indexterm>
            <primary>dumping</primary>

            <secondary>dump ID numbers</secondary>
          </indexterm>

          <indexterm>
            <primary>Backup System</primary>

            <secondary>dump ID number</secondary>

            <tertiary>assigning as part of dump operation</tertiary>
          </indexterm>

          <indexterm>
            <primary>Backup Database</primary>

            <secondary>dump records</secondary>

            <tertiary>creating as part of dump operation</tertiary>
          </indexterm>

          <indexterm>
            <primary>dump (Backup System)</primary>

            <secondary>creating Backup Database record</secondary>
          </indexterm>
        </listitem>

        <listitem>
          <para>If the tape or backup data file does not already have an AFS tape name, the Backup System constructs the appropriate
          one and records it on the label and in the Backup Database. It also assigns a dump name and ID number to the dump and
          records them in dump record that it creates in the Backup Database. For details on tape and dump names, see <link
          linkend="HDRWQ253">Dump Names and Tape Names</link>. For instructions on displaying dump records or a volume's dump
          history, or scanning the contents of a tape, see <link linkend="HDRWQ302">Displaying Backup Dump Records</link>.</para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="HDRWQ299">
      <title>Appending Dumps to an Existing Dump Set</title>

      <indexterm>
        <primary>dump (Backup System)</primary>

        <secondary>appended</secondary>

        <tertiary>creating</tertiary>
      </indexterm>

      <para>The AFS Backup System enables you to append dumps to the end of the final tape in a dump set by including the <emphasis
      role="bold">-append</emphasis> flag to the <emphasis role="bold">backup dump</emphasis> command. Appending dumps improves
      Backup System automation and efficiency in several ways: <itemizedlist>
          <listitem>
            <para>It maximizes use of a tape's capacity. An initial dump must always start on a new tape, but does not necessarily
            extend to the end of the final tape in the dump set. You can fill up the unused tape by appending one or more
            dumps.</para>
          </listitem>

          <listitem>
            <para>It can reduce the number of tapes and tape changes needed to complete a dump operation. Rather than performing a
            series of initial dumps first, instead begin with an initial dump and follow it immediately with several appended dumps.
            In this way you can write all dumps in the series to the same tape (assuming the tape is large enough to accommodate
            them all). If, in contrast, you perform all of the initial dumps first, each must begin on a new tape and you must
            switch tapes again if you then want to append dumps.</para>

            <para>You can either issue the appropriate series of <emphasis role="bold">backup dump</emphasis> commands at the
            interactive <computeroutput>backup&gt;</computeroutput> prompt, or record them in a file that you then name with the
            <emphasis role="bold">-file</emphasis> argument to the <emphasis role="bold">backup dump</emphasis> command. Appending
            dumps in this way enables you to run multiple unattended backup operations even without a tape stacker or jukebox, if
            all of the dumps fit on one tape.</para>
          </listitem>

          <listitem>
            <para>It can reduce the number of tape changes during a restore operation. For example, if you append all of the
            incremental dumps of a volume set to tapes in one dump set, then restoring a volume from the volume set requires a
            minimum number of tape changes. It is best not to append incremental dumps to a tape that contains the parent full dump,
            however: if the tape is lost or damaged, you lose all of the data from the volume.</para>

            <para>Although it can be efficient to group together appended dumps that are related, the Backup System does not require
            any relationship between the appended dumps on a tape or in a dump set.</para>
          </listitem>
        </itemizedlist></para>

      <para>When writing an appended dump, the Backup System performs most of the steps described in <link linkend="HDRWQ298">How
      Your Configuration Choices Influence the Dump Process</link>. Appended dumps do not have to be related to one another or the
      initial dump, so it skips Step <link linkend="LIBKOV-NAMECHECK">7</link>: there is no need to check that the AFS tape name
      reflects the volume set and dump level names in this case. It also skips Step <link linkend="LIBKOV-EXPDATE">8</link>. Because
      it is not overwriting any existing data on the tape, it does not need to check the expiration dates of existing dumps on the
      tape or in the file. Then in Step <link linkend="LIBKOV-WRITE">9</link> the Tape Coordinator scans to the end of the last dump
      on the tape or in the backup data file before it begins writing data.</para>

      <para>The Backup System imposes the following conditions on appended dumps: <itemizedlist>
          <listitem>
            <para>If writing to tape, the Tape Coordinator checks that it is the final one in a dump set for which there are
            complete and valid tape and dump records in the Backup Database. If not, it rejects the tape and requests an acceptable
            one. If you believe the tape has valid data on it, you can reconstruct the Backup Database dump records for it by using
            the <emphasis role="bold">-dbadd</emphasis> argument to the <emphasis role="bold">backup scantape</emphasis> command as
            instructed in <link linkend="HDRWQ305">To scan the contents of a tape</link>.</para>
          </listitem>

          <listitem>
            <para>The most recent dump on the tape or in the backup data file must have completed successfully.</para>
          </listitem>

          <listitem>
            <para>The dump set to which the tape or file belongs must begin with an initial dump that is recorded in the Backup
            Database. If there are no dumps on the current tape, then the Backup System treats the dump operation as an initial dump
            and imposes the relevant requirements (for example, checks the AFS tape name if appropriate).</para>
          </listitem>
        </itemizedlist></para>

      <para>As you append dumps, keep in mind that all of a dump set's dump and tape records in the Backup Database are indexed to
      the initial dump. If you want to delete an appended dump's record, you must delete the initial dump record, and doing so
      erases the records of all dumps in the dump set. Without those records, you cannot restore any of the data in the dump
      set.</para>

      <para>Similarly, all of the dumps in a dump set must expire before you can recycle (write a new initial dump to) any of the
      tapes in a dump set. Do not append a dump if its expiration date is later than the date on which you want to recycle any of
      the tapes in its dump set. To recycle a tape before the last expiration date, you must delete the initial dump's record from
      the Backup Database. Either use the <emphasis role="bold">backup labeltape</emphasis> command to relabel the tape as
      instructed in <link linkend="HDRWQ273">To label a tape</link>, or use the <emphasis role="bold">backup deletedump</emphasis>
      command to delete the record directly as instructed in <link linkend="HDRWQ322">To delete dump records from the Backup
      Database</link>.</para>

      <para>Although in theory you can append as many dumps as you wish, it generally makes sense to limit the number of tapes in a
      dump set (for example, to five), for these reasons: <itemizedlist>
          <listitem>
            <para>If an unreadable spot develops on one of the tapes in a dump set, it can prevent the Tape Coordinator from
            scanning the tape as part of a <emphasis role="bold">backup scantape</emphasis> operation you use to reconstruct Backup
            Database records. The Tape Coordinator can almost always scan the tape successfully up to the point of damage and can
            usually skip past minor damage. A scanning operation can start on any tape in a dump set, so damage on one tape does not
            prevent scanning of the others in the dump set. However, you can scan only the tapes that precede the damaged one in the
            dump set or the ones that follow the damaged one, but not both. (For more information on using tapes to reconstruct the
            information in the Backup Database, see <link linkend="HDRWQ305">To scan the contents of a tape</link>.)</para>

            <para>An unreadable bad spot can also prevent you from restoring a volume completely, because restore operations must
            begin with the full dump and continue with each incremental dump in order. If you cannot restore a specific dump, you
            cannot restore any data from later incremental dumps.</para>
          </listitem>

          <listitem>
            <para>If you decide in the future to archive one or more dumps, then you must archive the entire set of tapes that
            constitute the dump set, rather than just the ones that contain the data of interest. This wastes both tape and archive
            storage space. For more information on archiving, see <link linkend="HDRWQ269">Archiving Tapes</link>.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ300">
      <title>Scheduling Dumps</title>

      <para>By default, the Backup System starts executing a dump operation as soon as you enter the <emphasis role="bold">backup
      dump</emphasis> command, and the Tape Coordinator begins writing data as soon as it is not busy and the list of files to write
      is available. You can, however, schedule a dump operation to begin at a specific later time: <itemizedlist>
          <listitem>
            <para>To schedule a single dump operation, include the <emphasis role="bold">-at</emphasis> argument to specify its
            start time.</para>
          </listitem>

          <listitem>
            <para>To schedule multiple dump operations, list the operations in a file named by the <emphasis
            role="bold">-file</emphasis> argument and use the <emphasis role="bold">-at</emphasis> argument to specify when the
            <emphasis role="bold">backup</emphasis> command interpreter reads the file. If you omit the <emphasis
            role="bold">-at</emphasis> argument, the command interpreter reads the file immediately, which does not count as
            scheduling, but does allow you to initiate multiple dump operations in a single command. Do not combine the <emphasis
            role="bold">-file</emphasis> argument with the <emphasis role="bold">-volumeset</emphasis>, <emphasis
            role="bold">-dump</emphasis>, <emphasis role="bold">-portoffset</emphasis>, <emphasis role="bold">-append</emphasis>, or
            <emphasis role="bold">-n</emphasis> options.</para>

            <para>For file-formatting instructions, see the description of the <emphasis role="bold">-file</emphasis> argument in
            Step <link linkend="LIBKDUMP-SYNTAX">7</link> of <link linkend="HDRWQ301">To create a dump</link>.</para>
          </listitem>
        </itemizedlist></para>

      <para>The Backup System performs initial and appended dumps in the same manner whether they are scheduled or begin running as
      soon as you issue the <emphasis role="bold">backup dump</emphasis> command. The only difference is that the requirements for
      successful execution hold both at the time you issue the command and when the Backup System actually begins running it. All
      required Backup Database entries for volume sets, dump levels, and port offsets, and all dump and tape records must exist at
      both times. Perhaps more importantly, the required administrative tokens must be available at both times. See <link
      linkend="HDRWQ297">Making Backup Operations More Efficient</link>.</para>
    </sect2>

    <sect2 id="HDRWQ301">
      <title>To create a dump</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a
          connection to the appropriate Tape Coordinator machine and issue the <emphasis role="bold">butc</emphasis> command, for
          which complete instructions appear in <link linkend="HDRWQ292">To start a Tape Coordinator process</link>.
          <programlisting>
   % <emphasis role="bold">butc</emphasis> [&lt;<emphasis>port offset</emphasis>&gt;] [<emphasis role="bold">-noautoquery</emphasis>]
</programlisting></para>
        </listitem>

        <listitem>
          <para>If using a tape device, insert the tape.</para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup</emphasis> command to enter interactive mode. <programlisting>
   % <emphasis role="bold">backup</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Decide which volume set and dump level to use. If necessary, issue the <emphasis role="bold">backup
          listvolsets</emphasis> and <emphasis role="bold">backup listdumps</emphasis> commands to display the existing volume sets
          and dump levels. For complete instructions and a description of the output, see <link linkend="HDRWQ266">To display volume
          sets and volume entries</link> and <link linkend="HDRWQ271">To display the dump hierarchy</link>. <programlisting>
   backup&gt; <emphasis role="bold">listvolsets</emphasis>  [&lt;<emphasis>volume set name</emphasis>&gt;]
   backup&gt; <emphasis role="bold">listdumps</emphasis>
</programlisting></para>

          <para>If you want to use a temporary volume set, you must create it during the current interactive session. This can be
          useful if you are dumping a volume to tape in preparation for removing it permanently (perhaps because its owner is
          leaving the cell). In this case, you can define a volume entry that includes only the volume of interest without
          cluttering up the Backup Database with a volume set record that you are using only once. Complete instructions appear in
          <link linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</link>.</para>

          <programlisting>
   backup&gt;  <emphasis role="bold">addvolset</emphasis> &lt;<emphasis>volume set name</emphasis>&gt; <emphasis role="bold">-temporary</emphasis>
   backup&gt; <emphasis role="bold">addvolentry  -name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;  \
                        <emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt;  \
                        <emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;  \
                        <emphasis role="bold">-volumes</emphasis> &lt;<emphasis>volume name (regular expression)</emphasis>&gt;
</programlisting>
        </listitem>

        <listitem>
          <para>If you are creating an initial dump and writing to a tape or backup data file that does not have a permanent name,
          its AFS tape name must satisfy the Backup System's format requirements as described in <link
          linkend="HDRWQ280">Eliminating the AFS Tape Name Check</link>. If necessary, use the <emphasis role="bold">backup
          readlabel</emphasis> command to display the label and the <emphasis role="bold">backup labeltape</emphasis> command to
          change the names, as instructed in <link linkend="HDRWQ272">Writing and Reading Tape Labels</link>. You must also relabel
          a tape if you want to overwrite it and it is part of a dump set that includes any unexpired dumps, though this is not
          recommended. For a discussion of the appropriate way to recycle tapes, see <link linkend="HDRWQ268">Creating a Tape
          Recycling Schedule</link>.</para>

          <indexterm>
            <primary>backup commands</primary>

            <secondary>dump</secondary>
          </indexterm>

          <indexterm>
            <primary>commands</primary>

            <secondary>backup dump</secondary>
          </indexterm>
        </listitem>

        <listitem id="LIBKDUMP-SYNTAX">
          <para>Issue the <emphasis role="bold">backup dump</emphasis> command to dump the volume
          set. <itemizedlist>
              <listitem>
                <para>To create one initial dump, provide only the volume set name, dump level name, and port offset (if not
                zero).</para>
              </listitem>

              <listitem>
                <para>To create one appended dump, add the <emphasis role="bold">-append</emphasis> flag.</para>
              </listitem>

              <listitem>
                <para>To schedule a single initial or appended dump, add the <emphasis role="bold">-at</emphasis> argument.</para>
              </listitem>

              <listitem>
                <para>To initiate multiple dump operations, record the appropriate commands in a file and name it with the <emphasis
                role="bold">-file</emphasis> argument. Do not combine this argument with options other than the <emphasis
                role="bold">-at</emphasis> argument.</para>
              </listitem>
            </itemizedlist></para>

          <programlisting>
   backup&gt; <emphasis role="bold">dump</emphasis> &lt;<emphasis>volume set name</emphasis>&gt; &lt;<emphasis>dump level name</emphasis>&gt; [&lt;<emphasis>TC port offset</emphasis>&gt;]   \
                [<emphasis role="bold">-at</emphasis> &lt;<emphasis>Date/time to start dump</emphasis>&gt;+]  \
                [<emphasis role="bold">-append</emphasis>]  [<emphasis role="bold">-n</emphasis>] [<emphasis role="bold">-file</emphasis> &lt;<emphasis>load file</emphasis>&gt;]
</programlisting>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">dump</emphasis></term>

                <listitem>
                  <para>Must be typed in full.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume set name</emphasis></term>

                <listitem>
                  <para>Names the volume set to dump.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">dump level name</emphasis></term>

                <listitem>
                  <para>Specifies the complete pathname of the dump level at which to dump the volume set.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">TC port offset</emphasis></term>

                <listitem>
                  <para>Specifies the port offset number of the Tape Coordinator process that is handling the operation. You must
                  provide this argument unless the default value of 0 (zero) is appropriate.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-at</emphasis></term>

                <listitem>
                  <para>Specifies the date and time in the future at which to run the command, or to read the file named by the
                  <emphasis role="bold">-file</emphasis> argument. Provide a value in the format mm/dd/yyyy [hh:MM], where the month
                  (mm), day (dd), and year (yyyy) are required. Valid values for the year range from <emphasis
                  role="bold">1970</emphasis> to <emphasis role="bold">2037</emphasis>; higher values are not valid because the
                  latest possible date in the standard UNIX representation is in February 2038. The Backup System automatically
                  reduces any later date to the maximum value in 2038.</para>

                  <para>The hour and minutes (hh:MM) are optional, but if provided must be in 24-hour format (for example, the value
                  <emphasis role="bold">14:36</emphasis> represents 2:36 p.m.). If you omit them, the time defaults to midnight
                  (00:00 hours).</para>

                  <para>As an example, the value <emphasis role="bold">04/23/1999 20:20</emphasis> schedules the command for 8:20
                  p.m. on 23 April 1999.</para>

                  <note>
                    <para>A plus sign follows this argument in the command's syntax statement because it accepts a multiword value
                    which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates.
                    Provide only one date (and optionally, time) definition.</para>
                  </note>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-append</emphasis></term>

                <listitem>
                  <para>Creates an appended dump by scanning to the end of the data from one or more previous dump operations that
                  it finds on the tape or in the backup data file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-n</emphasis></term>

                <listitem>
                  <para>Displays the names of all volumes to be included in the indicated dump, without actually writing data to
                  tape or the backup data file. Combine this flag with the arguments you plan to use on the actual command, but not
                  with the <emphasis role="bold">-file</emphasis> argument.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-file</emphasis></term>

                <listitem>
                  <para>Specifies the local disk or AFS pathname of a file containing <emphasis role="bold">backup</emphasis>
                  commands. The Backup System reads the file immediately, or at the time specified by the <emphasis
                  role="bold">-at</emphasis> argument if it is provided. A partial pathname is interpreted relative to the current
                  working directory.</para>

                  <para>Place each <emphasis role="bold">backup dump</emphasis> command on its own line in the indicated file, using
                  the same syntax as for the command line, but without the word <emphasis role="bold">backup</emphasis> at the start
                  of the line. Each command must include the volume set name and dump level name arguments plus the TC port offset
                  argument if the default value of zero is not appropriate. Commands in the file can also include any of the
                  <emphasis role="bold">backup dump</emphasis> command's optional arguments, including the <emphasis
                  role="bold">-at</emphasis> argument (which must specify a date and time later than the date and time at which the
                  Backup System reads the file).</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>If you did not include the <emphasis role="bold">-noautoquery</emphasis> flag when you issued the <emphasis
          role="bold">butc</emphasis> command, or if the device's <emphasis role="bold">CFG_</emphasis>device_name configuration
          file includes the instruction <emphasis role="bold">AUTOQUERY YES</emphasis>, then the Tape Coordinator prompts you to
          place the tape in the device's drive. You have already done so, but you must now press &lt;<emphasis
          role="bold">Return</emphasis>&gt; to indicate that the tape is ready for labeling.</para>

          <para>If more than one tape is required, you must either include the <emphasis role="bold">MOUNT</emphasis> instruction in
          the <emphasis role="bold">CFG_</emphasis>device_name file and stock the corresponding stacker or jukebox with tapes, or
          remain at the console to respond to the Tape Coordinator's prompts for subsequent tapes.</para>
        </listitem>

        <listitem>
          <para>After the dump operation completes, review the Backup System's log files to check for errors. Use the <emphasis
          role="bold">bos getlog</emphasis> command as instructed in <link linkend="HDRWQ173">Displaying Server Process Log
          Files</link> to read the <emphasis role="bold">/usr/afs/logs/BackupLog</emphasis> file, and a text editor on the Tape
          Coordinator machine to read the <emphasis role="bold">TE_</emphasis>device_name and <emphasis
          role="bold">TL_</emphasis>device_name files in the local <emphasis role="bold">/usr/afs/backup</emphasis>
          directory.</para>

          <para>It is also a good idea to record the tape name and dump ID number on the exterior label of each tape.</para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ302">
    <title>Displaying Backup Dump Records</title>

    <para>The <emphasis role="bold">backup</emphasis> command suite includes three commands for displaying information about data
    you have backed up: <itemizedlist>
        <listitem>
          <para>To display information about one or more dump operations, such as the date it was performed and the number of
          volumes included, use the <emphasis role="bold">backup dumpinfo</emphasis> command as described in <link
          linkend="HDRWQ303">To display dump records</link>. You can display a detailed record of a single dump or more condensed
          records for a certain number of dumps, starting with the most recent and going back in time. You can specify the number of
          dumps or accept the default of 10.</para>
        </listitem>

        <listitem>
          <para>To display a volume's dump history, use the <emphasis role="bold">backup volinfo</emphasis> command as described in
          <link linkend="HDRWQ304">To display a volume's dump history</link>.</para>
        </listitem>

        <listitem>
          <para>To display information extracted from a tape or backup data file about the volumes it includes, use the <emphasis
          role="bold">backup scantape</emphasis> command. To create new dump and tape records in the Backup Database derived from
          the tape and dump labels, add the <emphasis role="bold">-dbadd</emphasis> flag. For instructions, see <link
          linkend="HDRWQ305">To scan the contents of a tape</link>.</para>
        </listitem>
      </itemizedlist></para>

    <indexterm>
      <primary>Backup Database</primary>

      <secondary>dump records</secondary>

      <tertiary>displaying</tertiary>
    </indexterm>

    <indexterm>
      <primary>dump (Backup System)</primary>

      <secondary>displaying Backup Database record</secondary>
    </indexterm>

    <indexterm>
      <primary>dump (Backup System)</primary>

      <secondary>ID number, displaying</secondary>
    </indexterm>

    <indexterm>
      <primary>backup commands</primary>

      <secondary>dumpinfo</secondary>
    </indexterm>

    <indexterm>
      <primary>commands</primary>

      <secondary>backup dumpinfo</secondary>
    </indexterm>

    <indexterm>
      <primary>Backup Database</primary>

      <secondary>dump ID numbers, displaying</secondary>
    </indexterm>

    <indexterm>
      <primary>dump ID number (Backup System)</primary>

      <secondary>displaying</secondary>
    </indexterm>

    <sect2 id="HDRWQ303">
      <title>To display dump records</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup dumpinfo</emphasis> command to list information about dumps recorded in the
          Backup Database. <programlisting>
   % <emphasis role="bold">backup dumpinfo</emphasis> [<emphasis role="bold">-ndumps</emphasis> &lt;<emphasis>no. of dumps</emphasis>&gt;]  [<emphasis
                role="bold">-id</emphasis> &lt;<emphasis>dump id</emphasis>&gt;]  [<emphasis role="bold">-verbose</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">dump</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">dumpinfo</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-ndumps</emphasis></term>

                <listitem>
                  <para>Displays the Backup Database record for each of the specified number of dumps, starting with the most recent
                  and going back in time. If the database contains fewer dumps than are requested, the output includes the records
                  for all existing dumps. Do not combine this argument with the <emphasis role="bold">-id</emphasis> argument or
                  <emphasis role="bold">-verbose</emphasis> flag; omit all three options to display the records for the last 10
                  dumps.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-id</emphasis></term>

                <listitem>
                  <para>Specifies the dump ID number of a single dump for which to display the Backup Database record. You must
                  include the <emphasis role="bold">-id</emphasis> switch. Do not combine this option with the <emphasis
                  role="bold">-ndumps</emphasis> or <emphasis role="bold">-verbose</emphasis> arguments; omit all three arguments to
                  display the records for the last 10 dumps.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-verbose</emphasis></term>

                <listitem>
                  <para>Provides more detailed information about the dump specified with the <emphasis role="bold">-id</emphasis>
                  argument, which must be provided along with it. Do not combine this flag with the <emphasis
                  role="bold">-ndumps</emphasis> option.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>If the <emphasis role="bold">-ndumps</emphasis> argument is provided, the output presents the following information in
      table form, with a separate line for each dump: <variablelist>
          <varlistentry>
            <term><emphasis role="bold"><computeroutput>dumpid</computeroutput></emphasis></term>

            <listitem>
              <para>The dump ID number.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>parentid</computeroutput></emphasis></term>

            <listitem>
              <para>The dump ID number of the dump's parent dump. A value of <computeroutput>0</computeroutput> (zero) identifies a
              full dump.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>lv</computeroutput></emphasis></term>

            <listitem>
              <para>The depth in the dump hierarchy of the dump level used to create the dump. A value of
              <computeroutput>0</computeroutput> (zero) identifies a full dump, in which case the value in the
              <computeroutput>parentid</computeroutput> field is also <computeroutput>0</computeroutput>. A value of
              <computeroutput>1</computeroutput> or greater indicates an incremental dump made at the corresponding level in the
              dump hierarchy.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>created</computeroutput></emphasis></term>

            <listitem>
              <para>The date and time at which the Backup System started the dump operation that created the dump.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>nt</computeroutput></emphasis></term>

            <listitem>
              <para>The number of tapes that contain the data in the dump. A value of <computeroutput>0</computeroutput> (zero)
              indicates that the dump operation was terminated or failed. Use the <emphasis role="bold">backup deletedump</emphasis>
              command to remove such entries.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>nvols</computeroutput></emphasis></term>

            <listitem>
              <para>The number of volumes from which the dump includes data. If a volume spans tapes, it is counted twice. A value
              of <computeroutput>0</computeroutput> (zero) indicates that the dump operation was terminated or failed; the value in
              the <computeroutput>nt</computeroutput> field is also <computeroutput>0</computeroutput> (zero) in this case.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>dump name</computeroutput></emphasis></term>

            <listitem>
              <para>The dump name in the form <programlisting>
   volume_set_name.dump_level_name (initial_dump_ID)
</programlisting></para>

              <para>where volume_set_name is the name of the volume set, and dump_level_name is the last element in the dump level
              pathname at which the volume set was dumped.</para>

              <para>The initial_dump_ID, if displayed, is the dump ID of the initial dump in the dump set to which this dump
              belongs. If there is no value in parentheses, the dump is the initial dump in a dump set that has no appended
              dumps.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <para>If the <emphasis role="bold">-id</emphasis> argument is provided alone, the first line of output begins with the string
      <computeroutput>Dump</computeroutput> and reports information for the entire dump in the following fields: <variablelist>
          <varlistentry>
            <term><emphasis role="bold"><computeroutput>id</computeroutput></emphasis></term>

            <listitem>
              <para>The dump ID number.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>level</computeroutput></emphasis></term>

            <listitem>
              <para>The depth in the dump hierarchy of the dump level used to create the dump. A value of
              <computeroutput>0</computeroutput> (zero) identifies a full dump. A value of <computeroutput>1</computeroutput> (one)
              or greater indicates an incremental dump made at the specified level in the dump hierarchy.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>volumes</computeroutput></emphasis></term>

            <listitem>
              <para>The number of volumes for which the dump includes data.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>created</computeroutput></emphasis></term>

            <listitem>
              <para>The date and time at which the dump operation began.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <para>If an XBSA server was the backup medium for the dump (rather than a tape device or backup data file), the following line
      appears next:</para>

      <programlisting>
   Backup Service: XBSA_program: Server: hostname
</programlisting>

      <para>where XBSA_program is the name of the XBSA-compliant program and hostname is the name of the machine on which the
      program runs.</para>

      <para>Next the output includes an entry for each tape that houses volume data from the dump. Following the string
      <computeroutput>Tape</computeroutput>, the first two lines of each entry report information about that tape in the following
      fields: <variablelist>
          <varlistentry>
            <term><emphasis role="bold"><computeroutput>name</computeroutput></emphasis></term>

            <listitem>
              <para>The tape's permanent name if it has one, or its AFS tape name otherwise, and its tape ID number in
              parentheses.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>nVolumes</computeroutput></emphasis></term>

            <listitem>
              <para>The number of volumes for which this tape includes dump data.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>created</computeroutput></emphasis></term>

            <listitem>
              <para>The date and time at which the Tape Coordinator began writing data to this tape.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <para>Following another blank line, the tape-specific information concludes with a table that includes a line for each volume
      dump on the tape. The information appears in columns with the following headings: <variablelist>
          <varlistentry>
            <term><emphasis role="bold"><computeroutput>Pos</computeroutput></emphasis></term>

            <listitem>
              <para>The relative position of each volume in this tape or file. On a tape, the counter begins at position 2 (the tape
              label occupies position 1), and increments by one for each volume. For volumes in a backup data file, the position
              numbers start with 1 and do not usually increment only by one, because each is the ordinal of the 16 KB offset in the
              file at which the volume's data begins. The difference between the position numbers therefore indicates how many 16 KB
              blocks each volume's data occupies. For example, if the second volume is at position 5 and the third volume in the
              list is at position 9, that means that the dump of the second volume occupies 64 KB (four 16-KB blocks) of space in
              the file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>Clone time</computeroutput></emphasis></term>

            <listitem>
              <para>For a backup or read-only volume, the time at which it was cloned from its read/write source. For a Read/Write
              volume, it is the same as the dump creation date reported on the first line of the output.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>Nbytes</computeroutput></emphasis></term>

            <listitem>
              <para>The number of bytes of data in the dump of the volume.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold"><computeroutput>Volume</computeroutput></emphasis></term>

            <listitem>
              <para>The volume name, complete with <computeroutput>.backup</computeroutput> or
              <computeroutput>.readonly</computeroutput> extension if appropriate.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <para>If both the <emphasis role="bold">-id</emphasis> and <emphasis role="bold">-verbose</emphasis> options are provided, the
      output is divided into several sections: <itemizedlist>
          <listitem>
            <para>The first section, headed by the underlined string <computeroutput>Dump</computeroutput>, includes information
            about the entire dump. The fields labeled <computeroutput>id</computeroutput>, <computeroutput>level</computeroutput>,
            <computeroutput>created</computeroutput>, and <computeroutput>nVolumes</computeroutput> report the same values (though
            in a different order) as appear on the first line of output when the <emphasis role="bold">-id</emphasis> argument is
            provided by itself. Other fields of potential interest to the backup operator are: <variablelist>
                <varlistentry>
                  <term><emphasis role="bold"><computeroutput>Group id</computeroutput></emphasis></term>

                  <listitem>
                    <para>The dump's <emphasis>group ID number</emphasis>, which is recorded in the dump's Backup Database record if
                    the <emphasis role="bold">GROUPID</emphasis> instruction appears in the Tape Coordinator's <emphasis
                    role="bold">/usr/afs/backup/CFG_</emphasis>tcid file when the dump is created.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><emphasis role="bold"><computeroutput>maxTapes</computeroutput></emphasis></term>

                  <listitem>
                    <para>The number of tapes that contain the dump set to which this dump belongs.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><emphasis role="bold"><computeroutput>Start Tape Seq</computeroutput></emphasis></term>

                  <listitem>
                    <para>The ordinal of the tape on which this dump begins in the set of tapes that contain the dump set.</para>
                  </listitem>
                </varlistentry>
              </variablelist></para>
          </listitem>

          <listitem>
            <para>For each tape that contains data from this dump, there follows a section headed by the underlined string
            <computeroutput>Tape</computeroutput>. The fields labeled <computeroutput>name</computeroutput>,
            <computeroutput>written</computeroutput>, and <computeroutput>nVolumes</computeroutput> report the same values (though
            in a different order) as appear on the second and third lines of output when the <emphasis role="bold">-id</emphasis>
            argument is provided by itself. Other fields of potential interest to the backup operator are: <variablelist>
                <varlistentry>
                  <term><computeroutput>expires</computeroutput></term>

                  <listitem>
                    <para>The date and time when this tape can be recycled, because all dumps it contains have expired.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><computeroutput>nMBytes Data</computeroutput> and <computeroutput>nBytes Data</computeroutput></term>

                  <listitem>
                    <para>Summed together, these fields represent the total amount of dumped data actually from volumes (as opposed
                    to labels, filemarks, and other markers).</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><computeroutput>KBytes Tape Used</computeroutput></term>

                  <listitem>
                    <para>The number of kilobytes of tape (or disk space, for a backup data file) used to store the dump data. It is
                    generally larger than the sum of the values in the <computeroutput>nMBytes Data</computeroutput> and
                    <computeroutput>nBytes Data</computeroutput> fields, because it includes the space required for the label, file
                    marks and other markers, and because the Backup System writes data at 16 KB offsets, even if the data in a given
                    block doesn't fill the entire 16 KB.</para>
                  </listitem>
                </varlistentry>
              </variablelist></para>
          </listitem>

          <listitem>
            <para>For each volume on a given tape, there follows a section headed by the underlined string
            <computeroutput>Volume</computeroutput>. The fields labeled <computeroutput>name</computeroutput>,
            <computeroutput>position</computeroutput>, <computeroutput>clone</computeroutput>, and
            <computeroutput>nBytes</computeroutput> report the same values (though in a different order) as appear in the table that
            lists the volumes in each tape when the <emphasis role="bold">-id</emphasis> argument is provided by itself. Other
            fields of potential interest to the backup operator are: <variablelist>
                <varlistentry>
                  <term><computeroutput>id</computeroutput></term>

                  <listitem>
                    <para>The volume ID.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><computeroutput>tape</computeroutput></term>

                  <listitem>
                    <para>The name of the tape containing this volume data.</para>
                  </listitem>
                </varlistentry>
              </variablelist></para>
          </listitem>
        </itemizedlist></para>

      <para>The following example command displays the Backup Database records for the five most recent dump operations.</para>

      <programlisting>
   % <emphasis role="bold">backup dump 5</emphasis>
      dumpid   parentid lv created          nt nvols dump name
   924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
   924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
   924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
   924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
   925033000          0 0  04/25/1999 05:36  2    73 sys.week
</programlisting>

      <indexterm>
        <primary>Backup Database</primary>

        <secondary>volume dump history</secondary>

        <tertiary>displaying</tertiary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>Backup System dump history, displaying</secondary>
      </indexterm>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>volinfo</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup volinfo</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ304">
      <title>To display a volume's dump history</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup volinfo</emphasis> command to display a volume's dump history.
          <programlisting>
   % <emphasis role="bold">backup volinfo</emphasis> &lt;<emphasis>volume name</emphasis>&gt;
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">voli</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">volinfo</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">volume name</emphasis></term>

                <listitem>
                  <para>Names the volume for which to display the dump history. If you dumped the backup or read-only version of the
                  volume, include the <emphasis role="bold">.backup</emphasis> or <emphasis role="bold">.readonly</emphasis>
                  extension.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>The output includes a line for each Backup Database dump record that mentions the specified volume, order from most to
      least recent. The output for each record appears in a table with six columns: <variablelist>
          <varlistentry>
            <term><computeroutput>dumpID</computeroutput></term>

            <listitem>
              <para>The dump ID of the dump that includes the volume.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><computeroutput>lvl</computeroutput></term>

            <listitem>
              <para>The depth in the dump hierarchy of the dump level at which the volume was dumped. A value of
              <computeroutput>0</computeroutput> indicates a full dump. A value of <computeroutput>1</computeroutput> or greater
              indicates an incremental dump made at the specified depth in the dump hierarchy.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><computeroutput>parentid</computeroutput></term>

            <listitem>
              <para>The dump ID of the dump's parent dump. A value of <computeroutput>0</computeroutput> indicates a full dump,
              which has no parent; in this case, the value in the <computeroutput>lvl</computeroutput> column is also
              <computeroutput>0</computeroutput>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><computeroutput>creation date</computeroutput></term>

            <listitem>
              <para>The date and time at which the Backup System started the dump operation that created the dump.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><computeroutput>clone date</computeroutput></term>

            <listitem>
              <para>For a backup or read-only volume, the time at which it was cloned from its read/write source. For a read/write
              volume, the same as the value in the <computeroutput>creation date</computeroutput> field.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><computeroutput>tape name</computeroutput></term>

            <listitem>
              <para>The name of the tape containing the dump: either the permanent tape name, or an AFS tape name in the format
              <emphasis>volume_set_name</emphasis>.<emphasis>dump_level_name</emphasis>.<emphasis>tape_index</emphasis> where
              <emphasis>volume_set_name</emphasis> is the name of the volume set associated with the initial dump in the dump set of
              which this tape is a part; <emphasis>dump_level_name</emphasis> is the name of the dump level at which the initial
              dump was backed up; <emphasis>tape_index</emphasis> is the ordinal of the tape in the dump set. Either type of name
              can be followed by a dump ID in parentheses; if it appears, it is the dump ID of the initial dump in the dump set to
              which this appended dump belongs.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <para>The following example shows part of the dump history of the backup volume <emphasis
      role="bold">user.smith.backup</emphasis>:</para>

      <programlisting>
   % <emphasis role="bold">backup volinfo user.smith.backup</emphasis>
   DumpID    lvl parentID  creation   date  clone date       tape name
   924600000 1   924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
   924514392 1   924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2 
   924427600 0           0 04/18/1999 05:26 04/18/1999 04:58 user_full_6 
       .     .      .         .       .       .      .         .
       .     .      .         .       .       .      .         .
</programlisting>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>scanning tapes</secondary>
      </indexterm>

      <indexterm>
        <primary>tape (Backup System)</primary>

        <secondary>scanning</secondary>
      </indexterm>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>dump history</secondary>

        <tertiary>recovering from tapes</tertiary>
      </indexterm>

      <indexterm>
        <primary>Backup Database</primary>

        <secondary>volume dump history</secondary>

        <tertiary>recovering from tapes</tertiary>
      </indexterm>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>volume dump history</secondary>

        <tertiary>recovering from tapes</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ305">
      <title>To scan the contents of a tape</title>

      <note>
        <para>The ability to scan a tape that is corrupted or damaged depends on the extent of the damage and what type of data is
        corrupted. The Backup System can almost always scan the tape successfully up to the point of damage. If the damage is minor,
        the Backup System can usually skip over it and scan the rest of the tape, but more major damage can prevent further
        scanning. A scanning operation does not have to begin with the first tape in a dump set, but the Backup System can process
        tapes only in sequential order after the initial tape provided. Therefore, damage on one tape does not prevent scanning of
        the others in the dump set, but it is possible to scan either the tapes that precede the damaged one or the ones that follow
        it, not both.</para>
      </note>

      <para>If you use the <emphasis role="bold">-dbadd</emphasis> flag to scan information into the Backup Database and the first
      tape you provide is not the first tape in the dump set, the following restrictions apply: <itemizedlist>
          <listitem>
            <para>If the first data on the tape is a continuation of a volume that begins on the previous (unscanned) tape in the
            dump set, the Backup System does not add a record for that volume to the Backup Database.</para>
          </listitem>

          <listitem>
            <para>The Backup System must read the marker that indicates the start of an appended dump to add database records for
            the volumes in it. If the first volume on the tape belongs to an appended dump, but is not immediately preceded by the
            appended-dump marker, the Backup System does not create a Backup Database record for it or any subsequent volumes that
            belong to that appended dump.</para>
          </listitem>
        </itemizedlist> <orderedlist>
          <listitem>
            <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
            file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
            linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
          </listitem>

          <listitem>
            <para>If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a
            connection to the appropriate Tape Coordinator machine and issue the <emphasis role="bold">butc</emphasis> command, for
            which complete instructions appear in <link linkend="HDRWQ292">To start a Tape Coordinator process</link>.
            <programlisting>
   % <emphasis role="bold">butc</emphasis> [&lt;<emphasis>port offset</emphasis>&gt;] [<emphasis role="bold">-noautoquery</emphasis>]
</programlisting></para>
          </listitem>

          <listitem>
            <para>If scanning a tape, place it in the drive.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">backup</emphasis> command to enter
            interactive mode. <programlisting>
   % <emphasis role="bold">backup</emphasis>
</programlisting></para>

            <indexterm>
              <primary>backup commands</primary>

              <secondary>scantape</secondary>
            </indexterm>

            <indexterm>
              <primary>commands</primary>

              <secondary>backup scantape</secondary>
            </indexterm>
          </listitem>

          <listitem>
            <para>Issue the <emphasis role="bold">backup scantape</emphasis> command to read the contents of the tape.
            <programlisting>
   backup&gt; <emphasis role="bold">scantape</emphasis> [<emphasis role="bold">-dbadd</emphasis>] [<emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;]
</programlisting></para>

            <para>where <variablelist>
                <varlistentry>
                  <term><emphasis role="bold">sc</emphasis></term>

                  <listitem>
                    <para>Is the shortest acceptable abbreviation of <emphasis role="bold">scantape</emphasis>.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><emphasis role="bold">-dbadd</emphasis></term>

                  <listitem>
                    <para>Constructs dump and tape records from the tape and dump labels in the dump and writes them into the Backup
                    Database.</para>
                  </listitem>
                </varlistentry>

                <varlistentry>
                  <term><emphasis role="bold">TC port offset</emphasis></term>

                  <listitem>
                    <para>Specifies the port offset number of the Tape Coordinator process that is handling the operation. You must
                    provide this argument unless the default value of 0 (zero) is appropriate.</para>
                  </listitem>
                </varlistentry>
              </variablelist></para>
          </listitem>

          <listitem>
            <para>If you did not include the <emphasis role="bold">-noautoquery</emphasis> flag when you issued the <emphasis
            role="bold">butc</emphasis> command, or the device's <emphasis role="bold">CFG_</emphasis>device_name configuration file
            includes the instruction <emphasis role="bold">AUTOQUERY YES</emphasis> instruction, then the Tape Coordinator prompts
            you to place the tape in the device's drive. You have already done so, but you must now press &lt;<emphasis
            role="bold">Return</emphasis>&gt; to indicate that the tape is ready for reading.</para>
          </listitem>
        </orderedlist></para>

      <para>To terminate a tape scanning operation, use a termination signal such as &lt;<emphasis
      role="bold">Ctrl-c</emphasis>&gt;, or issue the <emphasis role="bold">(backup) kill</emphasis> command in interactive mode. It
      is best not to interrupt the scan if you included the <emphasis role="bold">-dbadd</emphasis> argument. If the Backup System
      has already written new records into the Backup Database, then you must remove them before rerunning the scanning operation.
      If during the repeated scan operation the Backup System finds that a record it needs to create already exists, it halts the
      operation.</para>

      <para>For each dump on the tape, the output in the Tape Coordinator window displays the dump label followed by an entry for
      each volume. There is no output in the command window. The dump label has the same fields as the tape label displayed by the
      <emphasis role="bold">backup readlabel</emphasis> command, as described in <link linkend="HDRWQ272">Writing and Reading Tape
      Labels</link>. Or see the <emphasis>OpenAFS Administration Reference</emphasis> for a detailed description of the fields in
      the output.</para>

      <para>The following example shows the dump label and first volume entry on the tape in the device that has port offset
      2:</para>

      <programlisting>
   % <emphasis role="bold">backup scantape 2</emphasis>
   -- Dump label --
   tape name = monthly_guest
   AFS tape name = guests.monthly.3
   creationTime =  Mon Feb  1 04:06:40 1999
   cell = example.com
   size = 2150000 Kbytes
   dump path = /monthly
   dump id = 917860000
   useCount = 44
   -- End of dump label --
   -- volume --
   volume name: user.guest10.backup
   volume ID 1937573829
   dumpSetName: guests.monthly
   dumpID 917860000
   level 0
   parentID 0
   endTime 0
   clonedate Mon Feb  1 03:03:23 1999
</programlisting>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ306">
    <title>Restoring and Recovering Data</title>

    <indexterm>
      <primary>volume</primary>

      <secondary>restoring</secondary>

      <tertiary>using Backup System</tertiary>
    </indexterm>

    <indexterm>
      <primary>partition</primary>

      <secondary>restoring contents using Backup System</secondary>
    </indexterm>

    <indexterm>
      <primary>file server machine</primary>

      <secondary>restoring partitions using Backup System</secondary>
    </indexterm>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>restoring</secondary>

      <tertiary>data</tertiary>
    </indexterm>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>data</secondary>

      <tertiary>restoring</tertiary>
    </indexterm>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>data</secondary>

      <tertiary>recovering</tertiary>
    </indexterm>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>restores</secondary>

      <tertiary>full</tertiary>
    </indexterm>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>restores</secondary>

      <tertiary>date-specific</tertiary>
    </indexterm>

    <indexterm>
      <primary>full restores</primary>
    </indexterm>

    <indexterm>
      <primary>date-specific restores</primary>
    </indexterm>

    <indexterm>
      <primary>restoring</primary>

      <secondary>data using Backup System</secondary>
    </indexterm>

    <indexterm>
      <primary>Backup System</primary>

      <secondary>restoring</secondary>

      <tertiary>backed up data</tertiary>
    </indexterm>

    <para>The purpose of making backups is to enable you to recover when data becomes corrupted or is removed accidentally,
    returning the data to a coherent past state. The AFS Backup System provides three commands that restore varying numbers of
    volumes: <itemizedlist>
        <listitem>
          <para>To restore one or more volumes to a single site (partition on an AFS file server machine), use the <emphasis
          role="bold">backup volrestore</emphasis> command.</para>
        </listitem>

        <listitem>
          <para>To restore one or more volumes that are defined as a volume set, each to a specified site, use the <emphasis
          role="bold">backup volsetrestore</emphasis> command.</para>
        </listitem>

        <listitem>
          <para>To restore an entire partition (that is, all of the volumes that the VLDB lists as resident on it), use the
          <emphasis role="bold">backup diskrestore</emphasis> command.</para>
        </listitem>
      </itemizedlist></para>

    <para>The commands are suited to different purposes because they vary in the combinations of features they offer and in the
    requirements they impose. To decide which is appropriate for a specific restore operation, see the subsequent sections of this
    introduction: <link linkend="HDRWQ308">Using the backup volrestore Command</link>, <link linkend="HDRWQ310">Using the backup
    diskrestore Command</link>, and <link linkend="HDRWQ312">Using the backup volsetrestore Command</link>.</para>

    <sect2 id="HDRWQ307">
      <title>Making Restore Operations More Efficient</title>

      <para>The following comments apply to all types of restore operation: <itemizedlist>
          <listitem>
            <para>The Backup System begins by restoring the most recent full dump of a volume. As it restores subsequent incremental
            dumps, it alters the data in the full dump appropriately, essentially repeating the volume's change history. The
            <emphasis role="bold">backup diskrestore</emphasis> and <emphasis role="bold">backup volsetrestore</emphasis> commands
            always restore all incremental dumps, bringing a volume to its state at the time of the most recent incremental dump.
            You can use the <emphasis role="bold">backup volrestore</emphasis> command to return a volume to its state at a
            specified time in the past, by not restoring the data from incremental dumps performed after that time.</para>
          </listitem>

          <listitem>
            <para>The Backup System sets a restored volume's creation date to the date and time of the restore operation. The
            creation date appears in the <computeroutput>Creation</computeroutput> field of the output from the <emphasis
            role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands.</para>
          </listitem>

          <listitem>
            <para>When identifying the volumes to restore, it is best to specify the base (read/write) name. In this case, the
            Backup System searches the Backup Database for the most recent dump set that includes data from either the read/write or
            backup version of the volume, and restores dumps of that volume starting with the most recent full dump. If you include
            the <emphasis role="bold">.backup</emphasis> or <emphasis role="bold">.readonly</emphasis> extension on the volume name,
            the Backup System restores dumps of that version only. If it cannot find data dumped from that version, it does not
            perform the restoration even if another version was dumped.</para>
          </listitem>

          <listitem>
            <para>All three restoration commands accept the <emphasis role="bold">-n</emphasis> option, which generates a list of
            the volumes to be restored and the tapes or backup data files that contain the necessary dumps, without actually
            restoring data to AFS server partitions. This enables you to gather together the tapes before beginning the restore
            operation, even preloading them into a stacker or jukebox if you are using one.</para>
          </listitem>

          <listitem>
            <para>If you back up AFS data to tape, restoration is simplest if all of your tape devices are compatible, meaning that
            they can read the same type of tape, at the same compression ratios, and so on. (This suggestion also appears in <link
            linkend="HDRWQ297">Making Backup Operations More Efficient</link>, because by the time you need to restore data it is
            too late to implement it.) You can still restore multiple volumes with a single command even if data was backed up using
            incompatible devices, because the <emphasis role="bold">-portoffset</emphasis> argument to all three restoration
            commands accepts multiple values. However, the Backup System uses the first port offset listed when restoring the full
            dump of each volume, the next port offset when restoring the level 1 incremental dump of each volume, and so on. If you
            did not use a compatible tape device when creating the full dump of every volume (and at each incremental level too),
            you cannot restore multiple volumes with a single command. You must use the <emphasis role="bold">backup
            volrestore</emphasis> command to restore one volume at a time, or use the <emphasis role="bold">backup
            volsetrestore</emphasis> command after defining volume sets that group volumes according to the tape device used to dump
            them.</para>
          </listitem>

          <listitem>
            <para>During a restore operation, the Backup System uses instructions in the relevant <emphasis
            role="bold">CFG_</emphasis>device_name configuration file in much the same way as during a dump operation, as described
            in <link linkend="HDRWQ298">How Your Configuration Choices Influence the Dump Process</link>. It uses the <emphasis
            role="bold">MOUNT</emphasis>, <emphasis role="bold">UNMOUNT</emphasis>, <emphasis role="bold">AUTOQUERY</emphasis>,
            <emphasis role="bold">BUFFERSIZE</emphasis>, and <emphasis role="bold">FILE</emphasis> instructions just as for a dump
            operation. A difference for the <emphasis role="bold">BUFFERSIZE</emphasis> instruction is that the default buffer size
            overridden by the instruction is 32 KB for restore operations rather than the 16 KB used for dump operations. The Backup
            System does not use the <emphasis role="bold">NAME_CHECK</emphasis> instruction at all during restore operations. The
            <emphasis role="bold">ASK</emphasis> instruction controls whether the Backup System prompts you if it cannot restore a
            volume for any reason. If the setting is <emphasis role="bold">NO</emphasis>, it skips the problematic volume and
            restores as many of the other volumes as possible.</para>
          </listitem>

          <listitem>
            <para>Do not perform a restore operation when you know that there are network, machine, or server process problems that
            can prevent the Backup System from accessing volumes or the VLDB. Although the Backup System automatically makes a
            number of repeated attempts to restore a volume, the restore operation takes extra time and in some cases stops
            completely to prompt you for instructions on how to continue.</para>
          </listitem>

          <listitem>
            <para>Avoid halting a restore operation (for instance by issuing the <emphasis role="bold">(backup) kill</emphasis>
            command in interactive mode). If a restore operation is interrupted for any reason, including causes outside your
            control, reissue the same restoration command as soon as is practical; if an outage or other problem caused the
            operation to halt, do not continue until the system returns to normal.</para>

            <para>Any volume that is completely restored when the operation halts is online and usable, but very few volumes are
            likely to be in this state. When restoring multiple volumes at once, the Backup System restores the full dump of every
            volume before beginning the level 1 incremental restore for any of them, and so on, completing the restore of every
            volume at a specific incremental level before beginning to restore data from the next incremental level. Unless a volume
            was dumped at fewer incremental levels than others being restored as part of the same operation, it is unlikely to be
            complete.</para>

            <para>It is even more dangerous to interrupt a restore operation if you are overwriting the current contents of the
            volume. Depending on how far the restore operation has progressed, it is possible that the volume is in such an
            inconsistent state that the Backup System removes it entirely. The data being restored is still available on tape or in
            the backup data file, but you must take extra steps to re-create the volume.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ308">
      <title>Using the backup volrestore Command</title>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>restoring</secondary>

        <tertiary>backup data</tertiary>
      </indexterm>

      <indexterm>
        <primary>restoring</primary>

        <secondary>existing data</secondary>

        <tertiary>overwriting</tertiary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>overwriting contents during Backup System restore</secondary>
      </indexterm>

      <indexterm>
        <primary>restoring</primary>

        <secondary>existing data</secondary>

        <tertiary>preserving</tertiary>
      </indexterm>

      <indexterm>
        <primary>volume</primary>

        <secondary>preserving contents during Backup System restore</secondary>
      </indexterm>

      <indexterm>
        <primary>restoring</primary>

        <secondary>data</secondary>

        <tertiary>that no longer exists</tertiary>
      </indexterm>

      <para>The <emphasis role="bold">backup volrestore</emphasis> command is most appropriate when you need to restore a few
      volumes to a single site (partition on a file server machine). By default, it restores the volumes to their state at the time
      of the most recent dump operation (this is termed a <emphasis>full restore</emphasis>). You can also use the command to
      perform a <emphasis>date-specific restore</emphasis>, which restores only the dumps (full and incremental) performed before a
      specified date and time, leaving the volume in the state it was in at the time of the final relevant incremental dump. The
      <emphasis role="bold">backup diskrestore</emphasis> and <emphasis role="bold">backup volsetrestore</emphasis> commands can
      only perform full restores.</para>

      <para>You can restore data into a new copy of each volume rather than overwriting the current version, by including the
      <emphasis role="bold">-extension</emphasis> argument. After mounting the new volume in the filespace, you can compare the
      contents of the two and decide which to keep permanently.</para>

      <para>The following list summarizes how to combine the <emphasis role="bold">backup volrestore</emphasis> command's arguments
      to restore a volume in different ways: <itemizedlist>
          <listitem>
            <para>To perform a date-specific restore as described just previously, use the <emphasis role="bold">-date</emphasis>
            argument to specify the date and optionally time. The Backup System restores the most recent full dump and each
            subsequent incremental dump for which the clone date of the volume included in the dump is before the indicated date and
            time (for a definition of the clone date, see Step <link linkend="LIBKOV-CLONEDATE">4</link> in <link
            linkend="HDRWQ298">How Your Configuration Choices Influence the Dump Process</link>). You can combine this argument with
            the <emphasis role="bold">-extension</emphasis> argument to place the date-specific restore in a new volume.</para>
          </listitem>

          <listitem>
            <para>To move a volume to a new site as you overwrite its contents with the restored data, use the <emphasis
            role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, singly or in combination, to
            specify the new site rather than the current site. The Backup System creates a new volume at that site, removes the
            existing volume, and updates the site information in the volume's VLDB entry. The volume's backup version is not removed
            automatically from the original site, if it exists. Use the <emphasis role="bold">vos remove</emphasis> command to
            remove it and the <emphasis role="bold">vos backup</emphasis> command to create a backup version at the new site.</para>
          </listitem>

          <listitem>
            <para>To create a new volume to house the restored data, rather than overwriting an existing volume, use the <emphasis
            role="bold">-extension</emphasis> argument. The Backup System creates the new volume on the server and partition named
            by the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, derives its
            name by adding the extension to the name specified with the <emphasis role="bold">-volume</emphasis> argument, and
            creates a new VLDB entry for it. The command does not affect the existing volume in any way. However, if a volume with
            the specified extension also already exists, the command overwrites it. To make the contents of the new volume
            accessible, use the <emphasis role="bold">fs mkmount</emphasis> command to mount it. You can then compare its contents
            to those of the existing volume, to see which to retain permanently.</para>
          </listitem>

          <listitem>
            <para>To restore a volume that no longer exists on an AFS server partition, but for which you have backed up data,
            specify the name of the new volume with the <emphasis role="bold">-volume</emphasis> argument and use the <emphasis
            role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments to place it at the desired
            site. The Backup System creates a new volume and new VLDB entry.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>volrestore</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup volrestore</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ309">
      <title>To restore volumes with the backup volrestore command</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a
          connection to the appropriate Tape Coordinator machine and issue the <emphasis role="bold">butc</emphasis> command, for
          which complete instructions appear in <link linkend="HDRWQ292">To start a Tape Coordinator process</link>.
          <programlisting>
   % <emphasis role="bold">butc</emphasis> [&lt;<emphasis>port offset</emphasis>&gt;] [<emphasis role="bold">-noautoquery</emphasis>]
</programlisting></para>

          <para>Repeat the command for each Tape Coordinator if you are using more than one tape device.</para>
        </listitem>

        <listitem>
          <para>If using a tape device, insert the tape.</para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup</emphasis> command to enter interactive mode. <programlisting>
   % <emphasis role="bold">backup</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup volrestore</emphasis> command with the desired arguments. <programlisting>
   backup&gt; <emphasis role="bold">volrestore</emphasis> &lt;<emphasis>destination machine</emphasis>&gt; &lt;<emphasis>destination partition</emphasis>&gt;  \ 
                      <emphasis role="bold">-volume</emphasis> &lt;<emphasis>volume(s) to restore</emphasis>&gt;+  \
                      [<emphasis role="bold">-extension</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;]  \
                      [<emphasis role="bold">-date</emphasis> &lt;<emphasis>date from which to restore</emphasis>&gt;]  \
                      [<emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offsets</emphasis>&gt;+] [<emphasis
                role="bold">-n</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">volr</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">volrestore</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">destination machine</emphasis></term>

                <listitem>
                  <para>Names the file server machine on which to restore each volume. It does not have to be a volume's current
                  site.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">destination partition</emphasis></term>

                <listitem>
                  <para>Names the partition on which to restore each volume. It does not have to be a volume's current site.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-volume</emphasis></term>

                <listitem>
                  <para>Names each volume to restore. It is best to provide the base (read/write) name, for the reasons discussed in
                  <link linkend="HDRWQ307">Making Restore Operations More Efficient</link>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-extension</emphasis></term>

                <listitem>
                  <para>Creates a new volume to house the restored data, with a name derived by appending the specified string to
                  each volume named by the <emphasis role="bold">-volume</emphasis> extension. The Backup System preserves the
                  contents of the existing volume if it still exists. Do not use either of the <emphasis
                  role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extensions, which are reserved. The
                  combination of base volume name and extension cannot exceed 22 characters in length. If you want a period to
                  separate the extension from the name, specify it as the first character of the string (as in <emphasis
                  role="bold">.rst</emphasis>, for example).</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-date</emphasis></term>

                <listitem>
                  <para>Specifies a date and optionally time; the restored volume includes data from dumps performed before the date
                  only. Provide a value in the format mm/dd/yyyy [hh:MM], where the required mm/dd/yyyy portion indicates the month
                  (mm), day (dd), and year (yyyy), and the optional hh:MM portion indicates the hour and minutes in 24-hour format
                  (for example, the value <emphasis role="bold">14:36</emphasis> represents 2:36 p.m.). If omitted, the time
                  defaults to 59 seconds after midnight (00:00:59 hours).</para>

                  <para>Valid values for the year range from <emphasis role="bold">1970</emphasis> to <emphasis
                  role="bold">2037</emphasis>; higher values are not valid because the latest possible date in the standard UNIX
                  representation is in February 2038. The command interpreter automatically reduces any later date to the maximum
                  value.</para>

                  <note>
                    <para>A plus sign follows this argument in the command's syntax statement because it accepts a multiword value
                    which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates.
                    Provide only one date (and optionally, time) definition.</para>
                  </note>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-portoffset</emphasis></term>

                <listitem>
                  <para>Specifies one or more port offset numbers, each corresponding to a Tape Coordinator to use in the operation.
                  If there is more than one value, the Backup System uses the first one when restoring the full dump of each volume,
                  the second one when restoring the level 1 incremental dump of each volume, and so on. It uses the final value in
                  the list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower
                  levels.</para>

                  <para>Provide this argument unless the default value of 0 (zero) is appropriate for all dumps. If 0 is just one of
                  the values in the list, provide it explicitly in the appropriate order.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-n</emphasis></term>

                <listitem>
                  <para>Displays the list of tapes that contain the dumps required by the restore operation, without actually
                  performing the operation.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>If you did not include the <emphasis role="bold">-noautoquery</emphasis> flag when you issued the <emphasis
          role="bold">butc</emphasis> command, or the device's <emphasis role="bold">CFG_</emphasis>device_name configuration file
          includes the instruction <emphasis role="bold">AUTOQUERY YES</emphasis>, then the Tape Coordinator prompts you to place
          the tape in the device's drive. You have already done so, but you must now press &lt;<emphasis
          role="bold">Return</emphasis>&gt; to indicate that the tape is ready for labeling.</para>

          <para>If more than one tape is required, you must either include the <emphasis role="bold">MOUNT</emphasis> instruction in
          the <emphasis role="bold">CFG_</emphasis>device_name file and stock the corresponding stacker or jukebox with tapes, or
          remain at the console to respond to the Tape Coordinator's prompts for subsequent tapes.</para>
        </listitem>

        <listitem>
          <para>After the restore operation completes, review the Backup System's log files to check for errors. Use the <emphasis
          role="bold">bos getlog</emphasis> command as instructed in <link linkend="HDRWQ173">Displaying Server Process Log
          Files</link> to read the <emphasis role="bold">/usr/afs/logs/BackupLog</emphasis> file, and a text editor on the Tape
          Coordinator machine to read the <emphasis role="bold">TE_</emphasis>device_name and <emphasis
          role="bold">TL_</emphasis>device_name files in the local <emphasis role="bold">/usr/afs/backup</emphasis>
          directory.</para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="HDRWQ310">
      <title>Using the backup diskrestore Command</title>

      <indexterm>
        <primary>partition</primary>

        <secondary>restoring using Backup System</secondary>

        <tertiary>to the same location</tertiary>
      </indexterm>

      <indexterm>
        <primary>partition</primary>

        <secondary>restoring using Backup System</secondary>

        <tertiary>to a new location</tertiary>
      </indexterm>

      <para>The <emphasis role="bold">backup diskrestore</emphasis> command is most appropriate when you need to restore all of the
      volumes on an AFS server partition, perhaps because a hardware failure has corrupted or destroyed all of the data. The command
      performs a full restore of all of the read/write volumes for which the VLDB lists the specified partition as the current site,
      using the dumps of either the read/write or backup version of each volume depending on which type was dumped more recently.
      (You can restore any backup or read-only volumes that resided on the partition by using the <emphasis role="bold">vos
      backup</emphasis> and <emphasis role="bold">vos release</emphasis> commands after the <emphasis role="bold">backup
      diskrestore</emphasis> operation is complete.)</para>

      <para>By default, the Backup System restores the volumes to the site they previously occupied. To move the partition contents
      to a different site, use the <emphasis role="bold">-newserver</emphasis> and <emphasis role="bold">-newpartition</emphasis>
      arguments, singly or in combination.</para>

      <para>By default, the Backup System overwrites the contents of existing volumes with the restored data. To create a new volume
      to house the restored data instead, use the <emphasis role="bold">-extension</emphasis> argument. The Backup System creates
      the new volume at the site designated by the <emphasis role="bold">-newserver</emphasis> and <emphasis
      role="bold">-newpartition</emphasis> arguments if they are used or the <emphasis role="bold">-server</emphasis> and <emphasis
      role="bold">-partition</emphasis> arguments otherwise. It derives the volume name by adding the extension to the read/write
      base name listed in the VLDB, and creates a new VLDB entry. The command does not affect the existing volume in any way.
      However, if a volume with the specified extension also already exists, the command overwrites it.</para>

      <para>If a partition seems damaged, be sure not to run the <emphasis role="bold">vos syncserv</emphasis> command before the
      <emphasis role="bold">backup diskrestore</emphasis> command. As noted, the Backup System restores volumes according to VLDB
      site definitions. The <emphasis role="bold">vos syncserv</emphasis> command sometimes removes a volume's VLDB entry when the
      corruption on the partition is so severe that the Volume Server cannot confirm the volume's presence.</para>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>diskrestore</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup diskrestore</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ311">
      <title>To restore a partition with the backup diskrestore command</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a
          connection to the appropriate Tape Coordinator machine and issue the <emphasis role="bold">butc</emphasis> command, for
          which complete instructions appear in <link linkend="HDRWQ292">To start a Tape Coordinator process</link>.
          <programlisting>
   % <emphasis role="bold">butc</emphasis> [&lt;<emphasis>port offset</emphasis>&gt;] [<emphasis role="bold">-noautoquery</emphasis>]
</programlisting></para>

          <para>Repeat the command for each Tape Coordinator if you are using more than one tape device.</para>
        </listitem>

        <listitem>
          <para>If using a tape device, insert the tape.</para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup</emphasis> command to enter interactive mode. <programlisting>
   % <emphasis role="bold">backup</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup diskrestore</emphasis> command with the desired arguments. <programlisting>
   backup&gt; <emphasis role="bold">diskrestore</emphasis> &lt;<emphasis>machine to restore</emphasis>&gt; &lt;<emphasis>partition to restore</emphasis>&gt;  \
                       [<emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;+]  \
                       [<emphasis role="bold">-newserver</emphasis> &lt;<emphasis>destination machine</emphasis>&gt;]  \
                       [<emphasis role="bold">-newpartition</emphasis> &lt;<emphasis>destination partition</emphasis>&gt;]  \
                       [<emphasis role="bold">-extension</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;] [<emphasis
                role="bold">-n</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">di</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">diskrestore</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine to restore</emphasis></term>

                <listitem>
                  <para>Names the file server machine that the VLDB lists as the site of the volumes that need to be
                  restored.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">partition to restore</emphasis></term>

                <listitem>
                  <para>Names the partition that the VLDB lists as the site of the volumes that need to be restored.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-portoffset</emphasis></term>

                <listitem>
                  <para>Specifies one or more port offset numbers, each corresponding to a Tape Coordinator to use in the operation.
                  If there is more than one value, the Backup System uses the first one when restoring the full dump of each volume,
                  the second one when restoring the level 1 incremental dump of each volume, and so on. It uses the final value in
                  the list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower
                  levels.</para>

                  <para>Provide this argument unless the default value of 0 (zero) is appropriate for all dumps. If 0 is just one of
                  the values in the list, provide it explicitly in the appropriate order.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-newserver</emphasis></term>

                <listitem>
                  <para>Names an alternate file server machine to which to restore the volumes. If you omit this argument, the
                  volumes are restored to the file server machine named by the <emphasis role="bold">-server</emphasis>
                  argument.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-newpartition</emphasis></term>

                <listitem>
                  <para>Names an alternate partition to which to restore the data. If you omit this argument, the volumes are
                  restored to the partition named by the <emphasis role="bold">-partition</emphasis> argument.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-extension</emphasis></term>

                <listitem>
                  <para>Creates a new volume for each volume being restored, to house the restored data, appending the specified
                  string to the volume's read/write base name as listed in the VLDB. Any string other than <emphasis
                  role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> is acceptable, but the combination of
                  the base name and extension cannot exceed 22 characters in length. To use a period to separate the extension from
                  the name, specify it as the first character of the string (as in <emphasis role="bold">.rst</emphasis>, for
                  example).</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-n</emphasis></term>

                <listitem>
                  <para>Displays a list of the tapes necessary to perform the requested restore, without actually performing the
                  operation.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>If you did not include the <emphasis role="bold">-noautoquery</emphasis> flag when you issued the <emphasis
          role="bold">butc</emphasis> command, or the device's <emphasis role="bold">CFG_</emphasis>device_name configuration file
          includes the instruction <emphasis role="bold">AUTOQUERY YES</emphasis>, then the Tape Coordinator prompts you to place
          the tape in the device's drive. You have already done so, but you must now press &lt;<emphasis
          role="bold">Return</emphasis>&gt; to indicate that the tape is ready for labeling.</para>

          <para>If more than one tape is required, you must either include the <emphasis role="bold">MOUNT</emphasis> instruction in
          the <emphasis role="bold">CFG_</emphasis>device_name file and stock the corresponding stacker or jukebox with tapes, or
          remain at the console to respond to the Tape Coordinator's prompts for subsequent tapes.</para>
        </listitem>

        <listitem>
          <para>After the restore operation completes, review the Backup System's log files to check for errors. Use the <emphasis
          role="bold">bos getlog</emphasis> command as instructed in <link linkend="HDRWQ173">Displaying Server Process Log
          Files</link> to read the <emphasis role="bold">/usr/afs/logs/BackupLog</emphasis> file, and a text editor on the Tape
          Coordinator machine to read the <emphasis role="bold">TE_</emphasis>device_name and <emphasis
          role="bold">TL_</emphasis>device_name files in the local <emphasis role="bold">/usr/afs/backup</emphasis>
          directory.</para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="HDRWQ312">
      <title>Using the backup volsetrestore Command</title>

      <para>The <emphasis role="bold">backup volsetrestore</emphasis> command is most appropriate when you need to perform a full
      restore of several read/write volumes, placing each at a specified site. You specify the volumes to restore either by naming a
      volume set with the <emphasis role="bold">-name</emphasis> argument or by listing each volume's name and restoration site in a
      file named by the <emphasis role="bold">-file</emphasis> argument, as described in the following sections.</para>

      <para>Because the <emphasis role="bold">backup volsetrestore</emphasis> command enables you to restore a large number of
      volumes with a single command, the restore operation can potentially take hours to complete. One way to reduce the time is to
      run multiple instances of the command simultaneously. Either use the <emphasis role="bold">-name</emphasis> argument to
      specify disjoint volume sets for each command, or the <emphasis role="bold">-file</emphasis> argument to name files that list
      different volumes. You must have several Tape Coordinators available to read the required tapes. Depending on how the volumes
      to be restored were dumped to tape, specifying disjoint volume sets can also reduce the number of tape changes
      required.</para>

      <sect3 id="HDRWQ313">
        <title>Restoring a Volume Set with the -name Argument</title>

        <para>Use the <emphasis role="bold">-name</emphasis> argument to restore a group of volumes defined in a volume set. The
        Backup System creates a list of the volumes in the VLDB that match the server, partition, and volume name criteria defined
        in the volume set's volume entries, and for which dumps are available. The volumes do not have to exist on the server
        partition as long as the VLDB still lists them (this can happen when, for instance, a hardware problem destroys the contents
        of an entire disk).</para>

        <para>By default, the Backup System restores, as a read/write volume, each volume that matches the volume set criteria to
        the site listed in the VLDB. If a volume of the matching name exists at that site, its current contents are overwritten. You
        can instead create a new volume to house the restored data by including the <emphasis role="bold">-extension</emphasis>
        argument. The Backup System creates the new volume at the existing volume's site, derives its name by adding the extension
        to the existing volume's read/write base name, and creates a new VLDB entry for it. The command does not affect the existing
        volume in any way. However, if a volume with the specified extension also already exists, the command overwrites it. To make
        the contents of the new volume accessible, use the <emphasis role="bold">fs mkmount</emphasis> command to mount it. You can
        then compare its contents to those of the existing volume, to see which to retain permanently.</para>

        <para>It is not required that the volume set was previously used to back up volumes (was used as the <emphasis
        role="bold">-volumeset</emphasis> option to the <emphasis role="bold">backup dump</emphasis> command). It can be defined
        especially to match the volumes that need to be restored with this command, and that is usually the better choice. Indeed, a
        <emphasis>temporary</emphasis> volume set, created by including the <emphasis role="bold">-temporary</emphasis> flag to the
        <emphasis role="bold">backup addvolset</emphasis> command, can be especially useful in this context (instructions appear in
        <link linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</link>). A temporary volume set is not added
        to the Backup Database and exists only during the current interactive backup session, which is suitable if the volume set is
        needed only to complete the single restore operation initialized by this command.</para>

        <para>The reason that a specially defined volume set is probably better is that volume sets previously defined for use in
        dump operations usually match the backup version of volumes, whereas for a restore operation it is best to define volume
        entries that match the base (read/write) name. In this case, the Backup System searches the Backup Database for the newest
        dump set that includes a dump of either the read/write or the backup version of the volume. If, in contrast, a volume entry
        explicitly matches the volume's backup or read-only version, the Backup System uses dumps of that volume version only,
        restoring them to a read/write volume by stripping off the <emphasis role="bold">.backup</emphasis> or <emphasis
        role="bold">.readonly</emphasis> extension.</para>

        <para>If there are VLDB entries that match the volume set criteria, but for which there are no dumps recorded in the Backup
        Database, the Backup System cannot restore them. It generates an error message on the standard error stream for each
        one.</para>
      </sect3>

      <sect3 id="HDRWQ314">
        <title>Restoring Volumes Listed in a File with the -file Argument</title>

        <para>Use the <emphasis role="bold">-file</emphasis> argument to specify the name and site of each read/write volume to
        restore. Each volume's entry must appear on its own (unbroken) line in the file, and comply with the following
        format:</para>

        <programlisting>
   machine    partition   volume    [comments...]
</programlisting>

        <para>where <variablelist>
            <varlistentry>
              <term><emphasis role="bold">machine</emphasis></term>

              <listitem>
                <para>Names the file server machine to which to restore the volume. You can move the volume as you restore it by
                naming a machine other than the current site.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">partition</emphasis></term>

              <listitem>
                <para>Names the partition to which to restore the volume. You can move the volume as you restore it by naming a
                partition other than the current site.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">volume</emphasis></term>

              <listitem>
                <para>Names the volume to restore. Specify the base (read/write) name to have the Backup System search the Backup
                Database for the newest dump set that includes a dump of either the read/write or the backup version of the volume.
                It restores the dumps of that version of the volume, starting with the most recent full dump. If, in contrast, you
                include the <computeroutput>.backup</computeroutput> or <computeroutput>.readonly</computeroutput> extension, the
                Backup System restores dumps of that volume version only, but into a read/write volume without the extension. The
                base name must match the name used in Backup Database dump records rather than in the VLDB, if they differ, because
                the Backup System does not consult the VLDB when you use the <emphasis role="bold">-file</emphasis> argument.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">comments...</emphasis></term>

              <listitem>
                <para>Is any other text. The Backup System ignores any text on each line that appears after the volume name, so you
                can use this field for helpful notes.</para>
              </listitem>
            </varlistentry>
          </variablelist></para>

        <para>Do not use wildcards (for example, <emphasis role="bold">.*</emphasis>) in the machine, partition, or volume fields.
        It is acceptable for multiple lines in the file to name the same volume, but the Backup System processes only the first of
        them.</para>

        <para>By default, the Backup System replaces the existing version of each volume with the restored data, placing the volume
        at the site specified in the machine and partition fields. You can instead create a new volume to house the restored
        contents by including the <emphasis role="bold">-extension</emphasis> argument. The Backup System creates a new volume at
        the site named in the machine and partition fields, derives its name by adding the specified extension to the read/write
        version of the name in the volume field, and creates a new VLDB entry for it. The command does not affect the existing
        volume in any way. However, if a volume with the specified extension also already exists, the command overwrites it. To make
        the contents of the new volume accessible, use the <emphasis role="bold">fs mkmount</emphasis> command to mount it. You can
        then compare its contents to those of the existing volume, to see which to retain permanently.</para>

        <para>If the file includes entries for volumes that have no dumps recorded in the Backup Database, the Backup System cannot
        restore them. It generates an error message on the standard error stream for each one.</para>

        <para>One way to generate a file to use as input to the <emphasis role="bold">-file</emphasis> argument is to issue the
        command with the <emphasis role="bold">-name</emphasis> and <emphasis role="bold">-n</emphasis> options and direct the
        output to a file. The output includes a line like the following for each volume (shown here on two lines only for legibility
        reasons); the value comes from the source indicated in the following list:</para>

        <programlisting>
   machine   partition   volume_dumped  # as   volume_restored;    \
         tape_name   (tape_ID);   pos   position_number;   date
</programlisting>

        <para>where <variablelist>
            <varlistentry>
              <term><emphasis role="bold">machine</emphasis></term>

              <listitem>
                <para>Names the file server machine that currently houses the volume, as listed in the VLDB.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">partition</emphasis></term>

              <listitem>
                <para>Names the partition that currently houses the volume, as listed in the VLDB.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">volume_dumped</emphasis></term>

              <listitem>
                <para>Specifies the version (read/write or backup) of the volume that was dumped, as listed in the Backup
                Database.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">volume_restored</emphasis></term>

              <listitem>
                <para>Specifies the name under which the Backup System restores the volume when the <emphasis
                role="bold">-n</emphasis> flag is not included. If you include the <emphasis role="bold">-extension</emphasis>
                argument with the <emphasis role="bold">-name</emphasis> and <emphasis role="bold">-n</emphasis> options, then the
                extension appears on the name in this field (as in <computeroutput>user.pat.rst</computeroutput>, for
                example).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">tape_name</emphasis></term>

              <listitem>
                <para>Names the tape containing the dump of the volume, from the Backup Database. If the tape has a permanent name,
                it appears here; otherwise, it is the AFS tape name.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">tape_ID</emphasis></term>

              <listitem>
                <para>The tape ID of the tape containing the dump of the volume, from the Backup Database.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">position_number</emphasis></term>

              <listitem>
                <para>Specifies the dump's position on the tape (for example, <computeroutput>31</computeroutput> indicates that 30
                volume dumps precede the current one on the tape). If the dump was written to a backup data file, this number is the
                ordinal of the 16 KB-offset at which the volume's data begins.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><emphasis role="bold">date</emphasis></term>

              <listitem>
                <para>The date and time when the volume was dumped.</para>
              </listitem>
            </varlistentry>
          </variablelist></para>

        <para>To make the entries suitable for use with the <emphasis role="bold">-file</emphasis> argument, edit them as indicated:
        <itemizedlist>
            <listitem>
              <para>The Backup System uses only the first three fields on each line of the input file, and so ignores all the fields
              after the number sign (<computeroutput>#</computeroutput>). You can remove them if it makes it easier for you to read
              the file, but that is not necessary.</para>
            </listitem>

            <listitem>
              <para>The volume_dumped (third) field of each line in the output file becomes the volume field in the input file. The
              Backup System restores data to read/write volumes only, so remove the <computeroutput>.backup</computeroutput> or
              <computeroutput>.readonly</computeroutput> extension if it appears on the name in the volume_dumped field.</para>
            </listitem>

            <listitem>
              <para>The output file includes a line for every dump operation in which a specific volume was included (the full dump
              and any incremental dumps), but the Backup System only processes the first line in the input file that mentions a
              specific volume. You can remove the repeated lines if it makes the file easier for you to read.</para>
            </listitem>

            <listitem>
              <para>The <emphasis>machine</emphasis> and <emphasis>partition</emphasis> fields on an output line designate the
              volume's current site. To move the volume to another location as you restore it, change the values.</para>
            </listitem>
          </itemizedlist></para>

        <indexterm>
          <primary>backup commands</primary>

          <secondary>volsetrestore</secondary>
        </indexterm>

        <indexterm>
          <primary>commands</primary>

          <secondary>backup volsetrestore</secondary>
        </indexterm>
      </sect3>
    </sect2>

    <sect2 id="HDRWQ315">
      <title>To restore a group of volumes with the backup volsetrestore command</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>If the Tape Coordinator for the tape device that is to perform the operation is not already running, open a
          connection to the appropriate Tape Coordinator machine and issue the <emphasis role="bold">butc</emphasis> command, for
          which complete instructions appear in <link linkend="HDRWQ292">To start a Tape Coordinator process</link>.
          <programlisting>
   % <emphasis role="bold">butc</emphasis> [&lt;<emphasis>port offset</emphasis>&gt;] [<emphasis role="bold">-noautoquery</emphasis>]
</programlisting></para>

          <para>Repeat the command for each Tape Coordinator if you are using more than one tape device.</para>
        </listitem>

        <listitem>
          <para>If using a tape device, insert the tape.</para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup</emphasis> command to enter interactive mode. <programlisting>
   % <emphasis role="bold">backup</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> If appropriate, issue the <emphasis role="bold">(backup)
          addvolset</emphasis> command to create a new volume set expressly for this restore operation. Include the <emphasis
          role="bold">-temporary</emphasis> flag if you do not need to add the volume set to the Backup Database. Then issue one or
          more <emphasis role="bold">(backup) addvolentry</emphasis> commands to create volume entries that include only the volumes
          to be restored. Complete instructions appear in <link linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume
          Entries</link>. <programlisting>
   backup&gt; <emphasis role="bold">addvolset</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;  [<emphasis role="bold">-temporary</emphasis>]
   backup&gt; <emphasis role="bold">addvolentry  -name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;  \
                        <emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt;  \
                        <emphasis role="bold">-partition</emphasis> &lt;<emphasis>partition name</emphasis>&gt;  \
                        <emphasis role="bold">-volumes</emphasis> &lt;<emphasis>volume name (regular expression)</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup volsetrestore</emphasis> command with the desired arguments. <programlisting>
   backup&gt; <emphasis role="bold">volsetrestore</emphasis> [<emphasis role="bold">-name</emphasis> &lt;<emphasis>volume set name</emphasis>&gt;]  \
                 [<emphasis role="bold">-file</emphasis> &lt;<emphasis>file name</emphasis>&gt;]  \
                 [<emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;+]  \
                 [<emphasis role="bold">-extension</emphasis> &lt;<emphasis>new volume name extension</emphasis>&gt;] [<emphasis
                role="bold">-n</emphasis>] 
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">-name</emphasis></term>

                <listitem>
                  <para>Names a volume set to restore. The Backup System restores all of the volumes listed in the VLDB that match
                  the volume set's volume entries, as described in <link linkend="HDRWQ313">Restoring a Volume Set with the -name
                  Argument</link>. Provide this argument or the <emphasis role="bold">-file</emphasis> argument, but not
                  both.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-file</emphasis></term>

                <listitem>
                  <para>Specifies the full pathname of a file that lists one or more volumes and the site (file server machine and
                  partition) to which to restore each. The input file has the format described in <link linkend="HDRWQ314">Restoring
                  Volumes Listed in a File with the -file Argument</link>. Use either this argument or the <emphasis
                  role="bold">-name</emphasis> argument, but not both.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-portoffset</emphasis></term>

                <listitem>
                  <para>Specifies one or more port offset numbers, each corresponding to a Tape Coordinator to use in the operation.
                  If there is more than one value, the Backup System uses the first one when restoring the full dump of each volume,
                  the second one when restoring the level 1 incremental dump of each volume, and so on. It uses the final value in
                  the list when restoring dumps at the corresponding depth in the dump hierarchy and all dumps at lower
                  levels.</para>

                  <para>Provide this argument unless the default value of 0 (zero) is appropriate for all dumps. If 0 is just one of
                  the values in the list, provide it explicitly in the appropriate order.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-extension</emphasis></term>

                <listitem>
                  <para>Creates a new volume for each volume being restored, to house the restored data, appending the specified
                  string to the volume's read/write base name as listed in the VLDB. Any string other than <emphasis
                  role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> is acceptable, but the combination of
                  the base name and extension cannot exceed 22 characters in length. To use a period to separate the extension from
                  the name, specify it as the first character of the string (as in <emphasis role="bold">.rst</emphasis>, for
                  example).</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-n</emphasis></term>

                <listitem>
                  <para>Displays a list of the volumes to be restored when the flag is not included, without actually restoring
                  them. The <emphasis role="bold">Output</emphasis> section of this reference page details the format of the output.
                  When combined with the <emphasis role="bold">-name</emphasis> argument, its output is easily edited for use as
                  input to the <emphasis role="bold">-file</emphasis> argument on a subsequent <emphasis role="bold">backup
                  volsetrestore</emphasis> command.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>If you did not include the <emphasis role="bold">-noautoquery</emphasis> flag when you issued the <emphasis
          role="bold">butc</emphasis> command, or the device's <emphasis role="bold">CFG_</emphasis>device_name configuration file
          includes the instruction <emphasis role="bold">AUTOQUERY YES</emphasis>, then the Tape Coordinator prompts you to place
          the tape in the device's drive. You have already done so, but you must now press &lt;<emphasis
          role="bold">Return</emphasis>&gt; to indicate that the tape is ready for labeling.</para>

          <para>If more than one tape is required, you must either include the <emphasis role="bold">MOUNT</emphasis> instruction in
          the <emphasis role="bold">CFG_</emphasis>device_name file and stock the corresponding stacker or jukebox with tapes, or
          remain at the console to respond to the Tape Coordinator's prompts for subsequent tapes.</para>
        </listitem>

        <listitem>
          <para>After the restore operation completes, review the Backup System's log files to check for errors. Use the <emphasis
          role="bold">bos getlog</emphasis> command as instructed in <link linkend="HDRWQ173">Displaying Server Process Log
          Files</link> to read the <emphasis role="bold">/usr/afs/logs/BackupLog</emphasis> file, and a text editor on the Tape
          Coordinator machine to read the <emphasis role="bold">TE_</emphasis>device_name and <emphasis
          role="bold">TL_</emphasis>device_name files in the local <emphasis role="bold">/usr/afs/backup</emphasis>
          directory.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>Backup Database</primary>

        <secondary>administering</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ316">
    <title>Maintaining the Backup Database</title>

    <para>The Backup Database stores all of the configuration and tracking information that the Backup System uses when dumping and
    restoring data. If a hardware failure or other problem on a database server machine corrupts or damages the database, it is
    relatively easy to recreate the configuration information (the dump hierarchy and lists of volume sets and Tape Coordinator port
    offset numbers). However, restoring the dump tracking information (dump records) is more complicated and time-consuming. To
    protect yourself against loss of data, back up the Backup Database itself to tape on a regular schedule.</para>

    <para>Another potential concern is that the Backup Database can grow large rather quickly, because the Backup System keeps very
    detailed and cross-referenced records of dump operations. Backup operations become less efficient if the Backup Server has to
    navigate through a large number of obsolete records to find the data it needs. To keep the database to a manageable size, use
    the <emphasis role="bold">backup deletedump</emphasis> command to delete obsolete records, as described in <link
    linkend="HDRWQ321">Removing Obsolete Records from the Backup Database</link>. If you later find that you have removed records
    that you still need, you can use the <emphasis role="bold">backup scantape</emphasis> command to read the information from the
    dump and tape labels on the corresponding tapes back into the database, as instructed in <link linkend="HDRWQ305">To scan the
    contents of a tape</link>.</para>

    <indexterm>
      <primary>Backup Database</primary>

      <secondary>restoring</secondary>
    </indexterm>

    <indexterm>
      <primary>Backup Database</primary>

      <secondary>backing up</secondary>
    </indexterm>

    <indexterm>
      <primary>dumping</primary>

      <secondary>Backup Database to tape</secondary>
    </indexterm>

    <indexterm>
      <primary>backing up</primary>

      <secondary>Backup Database to tape</secondary>
    </indexterm>

    <indexterm>
      <primary>restoring</primary>

      <secondary>Backup Database from tape</secondary>
    </indexterm>

    <sect2 id="HDRWQ317">
      <title>Backing Up and Restoring the Backup Database</title>

      <para>Because of the importance of the information in the Backup Database, it is best to back it up to tape or other permanent
      media on a regular basis. As for the other AFS, administrative databases, the recommended method is to use a utility designed
      to back up a machine's local disk, such as the UNIX <emphasis role="bold">tar</emphasis> command. For instructions, see <link
      linkend="HDRWQ107">Backing Up and Restoring the Administrative Databases</link>.</para>

      <para>In the rare event that the Backup Database seems damaged or corrupted, you can use the <emphasis role="bold">backup
      dbverify</emphasis> command to check its status. If it is corrupted, use the <emphasis role="bold">backup savedb</emphasis>
      command to repair some types of damage. Then use the <emphasis role="bold">backup restoredb</emphasis> to return the corrected
      database to the local disks of the database server machines. For instructions, see <link linkend="HDRWQ318">Checking for and
      Repairing Corruption in the Backup Database</link>.</para>
    </sect2>

    <sect2 id="HDRWQ318">
      <title>Checking for and Repairing Corruption in the Backup Database</title>

      <para>In rare cases, the Backup Database can become damaged or corrupted, perhaps because of disk or other hardware errors.
      Use the <emphasis role="bold">backup dbverify</emphasis> command to check the integrity of the database. If it is corrupted,
      the most efficient way to repair it is to use the <emphasis role="bold">backup savedb</emphasis> command to copy the database
      to tape. The command automatically repairs several types of corruption, and you can then use the <emphasis role="bold">backup
      restoredb</emphasis> command to transfer the repaired copy of the database back to the local disks of the database server
      machines.</para>

      <para>The <emphasis role="bold">backup savedb</emphasis> command also removes <emphasis>orphan blocks</emphasis>, which are
      ranges of memory that the Backup Server preallocated in the database but cannot use. Orphan blocks do not interfere with
      database access, but do waste disk space. The <emphasis role="bold">backup dbverify</emphasis> command reports the existence
      of orphan blocks if you include the <emphasis role="bold">-detail</emphasis> flag.</para>

      <indexterm>
        <primary>Backup Database</primary>

        <secondary>verifying integrity</secondary>
      </indexterm>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>dbverify</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup dbverify</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ319">
      <title>To verify the integrity of the Backup Database</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup dbverify</emphasis> command to check the integrity of the Backup Database.
          <programlisting>
   % <emphasis role="bold">backup dbverify</emphasis> [<emphasis role="bold">-detail</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">db</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">dbverify</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-detail</emphasis></term>

                <listitem>
                  <para>Reports the existence of orphan blocks and other information about the database, as described on the
                  <emphasis role="bold">backup dbverify</emphasis> reference page in the <emphasis>OpenAFS Administration
                  Reference</emphasis>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>

          <para>The output reports one of the following messages: <itemizedlist>
              <listitem>
                <para><computeroutput>Database OK</computeroutput> indicates that the Backup Database is undamaged.</para>
              </listitem>

              <listitem>
                <para><computeroutput>Database not OK</computeroutput> indicates that the Backup Database is damaged. To recover
                from the problem, use the instructions in <link linkend="HDRWQ320">To repair corruption in the Backup
                Database</link>.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup savedb</secondary>
      </indexterm>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>savedb</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ320">
      <title>To repair corruption in the Backup Database</title>

      <orderedlist>
        <listitem>
          <para>Log in as the local superuser <emphasis role="bold">root</emphasis> on each database server machine in the
          cell.</para>
        </listitem>

        <listitem id="LISAVEDB-STARTTC">
          <para>If the Tape Coordinator for the tape device that is to perform the operation is not
          already running, open a connection to the appropriate Tape Coordinator machine and issue the <emphasis
          role="bold">butc</emphasis> command, for which complete instructions appear in <link linkend="HDRWQ292">To start a Tape
          Coordinator process</link>. <programlisting>
   % <emphasis role="bold">butc</emphasis> [&lt;<emphasis>port offset</emphasis>&gt;] [<emphasis role="bold">-noautoquery</emphasis>]
</programlisting></para>
        </listitem>

        <listitem>
          <para>If writing to tape, place a tape in the appropriate device.</para>
        </listitem>

        <listitem>
          <para>Working on one of the machines, issue the <emphasis role="bold">backup</emphasis> command to enter interactive mode.
          <programlisting>
   # <emphasis role="bold">backup -localauth</emphasis>
</programlisting></para>

          <para>where <emphasis role="bold">-localauth</emphasis> constructs a server ticket from the local <emphasis
          role="bold">/usr/afs/etc/KeyFile</emphasis> file. This flag enables you to issue a privileged command while logged in as
          the local superuser <emphasis role="bold">root</emphasis> but without AFS administrative tokens.</para>
        </listitem>

        <listitem>
          <para>Verify that no backup operations are actively running. If necessary, issue the <emphasis role="bold">(backup)
          status</emphasis> command as described in <link linkend="HDRWQ295">To check the status of a Tape Coordinator
          process</link>. Repeat for each Tape Coordinator port offset in turn. <programlisting>
   backup&gt; <emphasis role="bold">status -portoffset</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem id="LISAVEDB-CMD">
          <para>Issue the <emphasis role="bold">(backup) savedb</emphasis> command to repair corruption
          in the database as it is written to tape or a file. <programlisting>
   backup&gt; <emphasis role="bold">savedb</emphasis> [<emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">sa</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">savedb</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-portoffset</emphasis></term>

                <listitem>
                  <para>Specifies the port offset number of the Tape Coordinator handling the tape or backup data file for this
                  operation. You must provide this argument unless the default value of 0 (zero) is appropriate.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>Exit interactive mode. <programlisting>
   backup&gt;  <emphasis role="bold">quit</emphasis>  
</programlisting></para>
        </listitem>

        <listitem>
          <para>On each machine in turn, issue the <emphasis role="bold">bos shutdown</emphasis> command to shut down the Backup
          Server process. Include the <emphasis role="bold">-localauth</emphasis> flag because you are logged in as the local
          superuser root, but do not necessarily have administrative tokens. For complete command syntax, see <link
          linkend="HDRWQ168">To stop processes temporarily</link>. <programlisting>
   # <emphasis role="bold">/usr/afs/bin/bos shutdown</emphasis> &lt;<emphasis>machine name</emphasis>&gt; <emphasis role="bold">buserver  -localauth  -wait</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>On each machine in turn, issue the following commands to remove the Backup Database. <programlisting>
   # <emphasis role="bold">cd /usr/afs/db</emphasis>
   # <emphasis role="bold">rm bdb.DB0</emphasis>
   # <emphasis role="bold">rm bdb.DBSYS1</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>On each machine in turn, starting with the machine with the lowest IP address, issue the <emphasis role="bold">bos
          start</emphasis> command to restart the Backup Server process, which creates a zero-length copy of the Backup Database as
          it starts. For complete command syntax, see <link linkend="HDRWQ166">To start processes by changing their status flags to
          Run</link>. <programlisting>
   # <emphasis role="bold">/usr/afs/bin/bos start</emphasis> &lt;<emphasis>machine name</emphasis>&gt; <emphasis role="bold">buserver  -localauth</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Working on one of the machines, issue the <emphasis role="bold">backup</emphasis> command to enter interactive mode.
          <programlisting>
   # <emphasis role="bold">backup -localauth</emphasis>
</programlisting></para>

          <para>where <emphasis role="bold">-localauth</emphasis> constructs a server ticket from the local <emphasis
          role="bold">/usr/afs/etc/KeyFile</emphasis> file.</para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">(backup) addhost</emphasis> command to create an entry in the new, empty database
          for the Tape Coordinator process handling the tape or file from which you are reading the repaired copy of the database
          (presumably the process you started in Step <link linkend="LISAVEDB-STARTTC">2</link> and which performed the <emphasis
          role="bold">backup savedb</emphasis> operation in Step <link linkend="LISAVEDB-CMD">6</link>). For complete syntax, see
          Step <link linkend="LICONFTC-ADDHOST">8</link> in <link linkend="HDRWQ262">To configure a Tape Coordinator machine</link>.
          <programlisting>
   backup&gt;  <emphasis role="bold">addhost</emphasis> &lt;<emphasis>tape machine name</emphasis>&gt; [&lt;<emphasis>TC port offset</emphasis>&gt;]
</programlisting></para>

          <indexterm>
            <primary>commands</primary>

            <secondary>backup restoredb</secondary>
          </indexterm>

          <indexterm>
            <primary>backup commands</primary>

            <secondary>restoredb</secondary>
          </indexterm>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">(backup) restoredb</emphasis> command to copy the repaired database to the database
          server machines. <programlisting>
   backup&gt; <emphasis role="bold">restoredb</emphasis>  [<emphasis role="bold">-portoffset</emphasis> &lt;<emphasis>TC port offset</emphasis>&gt;]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">res</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restoredb</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-portoffset</emphasis></term>

                <listitem>
                  <para>Specifies the port offset number of the Tape Coordinator handling the tape or backup data file for this
                  operation. You must provide this argument unless the default value of <emphasis role="bold">0</emphasis> (zero) is
                  appropriate.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Exit interactive mode if you do not plan to issue any additional
          <emphasis role="bold">backup</emphasis> commands. <programlisting>
   backup&gt; <emphasis role="bold">quit</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> If desired, enter <emphasis role="bold">Ctrl-d</emphasis> or another
          interrupt signal to exit the <emphasis role="bold">root</emphasis> shell on each database server machine. You can also
          issue the <emphasis role="bold">Ctrl-c</emphasis> signal on the Tape Coordinator machine to stop the process.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>dump set (Backup System)</primary>

        <secondary>deleting from Backup Database</secondary>
      </indexterm>

      <indexterm>
        <primary>Backup System</primary>

        <secondary>dump records</secondary>

        <tertiary>deleting</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ321">
      <title>Removing Obsolete Records from the Backup Database</title>

      <para>Whenever you recycle or relabel a tape using the <emphasis role="bold">backup dump</emphasis> or <emphasis
      role="bold">backup labeltape</emphasis> command, the Backup System automatically removes all of the dump records for the dumps
      contained on the tape and all other tapes in the dump set. However, obsolete records can still accumulate in the Backup
      Database over time. For example, when you discard a backup tape after using it the maximum number of times recommended by the
      manufacturer, the records for dumps on it remain in the database. Similarly, the Backup System does not automatically remove a
      dump's record when the dump reaches its expiration date, but only if you then recycle or relabel the tape that contains the
      dump. Finally, if a backup operation halts in the middle, the records for any volumes successfully written to tape before the
      halt remain in the database.</para>

      <para>A very large Backup Database can make backup operations less efficient because the Backup Server has to navigate through
      a large number of records to find the ones it needs. To remove obsolete records, use the <emphasis role="bold">backup
      deletedump</emphasis> command. Either identify individual dumps by dump ID number, or specify the removal of all dumps created
      during a certain time period. Keep in mind that you cannot remove the record of an appended dump except by removing the record
      of its initial dump, which removes the records of all associated appended dumps. Removing records of a dump makes it
      impossible to restore data from the corresponding tapes or from any dump that refers to the deleted dump as its parent,
      directly or indirectly. That is, restore operations must begin with the full dump and continue with each incremental dump in
      order. If you have removed the records for a specific dump, you cannot restore any data from later incremental dumps.</para>

      <para>Another way to truncate the Backup Database is to include the <emphasis role="bold">-archive</emphasis> argument to the
      <emphasis role="bold">backup savedb</emphasis> command. After a copy of the database is written to tape or to a backup data
      file, the Backup Server deletes the dump records for all dump operations with timestamps prior to the date and time you
      specify. However, issuing the <emphasis role="bold">backup deletedump</emphasis> command with only the <emphasis
      role="bold">-to</emphasis> argument is equivalent in effect and is simpler because it does not require starting a Tape
      Coordinator process as the <emphasis role="bold">backup savedb</emphasis> command does. For further information on the
      <emphasis role="bold">-archive</emphasis> argument to the <emphasis role="bold">backup savedb</emphasis> command, see the
      command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>

      <para>If you later need to access deleted dump records, and the corresponding tapes still exist, you can use the <emphasis
      role="bold">-dbadd</emphasis> argument to the <emphasis role="bold">backup scantape</emphasis> command to scan their contents
      into the database, as instructed in <link linkend="HDRWQ305">To scan the contents of a tape</link>.</para>

      <indexterm>
        <primary>backup commands</primary>

        <secondary>deletedump</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>backup deletedump</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ322">
      <title>To delete dump records from the Backup Database</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
          file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
          linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<emphasis>machine name</emphasis>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">backup</emphasis> command to enter
          interactive mode, if you want to delete multiple records or issue additional commands. The interactive prompt appears in
          the following step. <programlisting>
   % <emphasis role="bold">backup</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">backup dumpinfo</emphasis> command to
          list information from the Backup Database that can help you decide which records to delete. For detailed instructions, see
          <link linkend="HDRWQ303">To display dump records</link>. <programlisting>
   backup&gt; <emphasis role="bold">dumpinfo</emphasis> [&lt;<emphasis>no. of dumps</emphasis>&gt;]  [<emphasis role="bold">-id</emphasis> &lt;<emphasis>dump id</emphasis>&gt;]  [<emphasis
                role="bold">-verbose</emphasis>]
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">backup deletedump</emphasis> command to delete one or more dump sets.
          <programlisting>
   backup&gt; <emphasis role="bold">deletedump</emphasis> [<emphasis role="bold">-dumpid</emphasis> &lt;<emphasis>dumpid</emphasis>&gt;+] [<emphasis
                role="bold">-from</emphasis> &lt;<emphasis>date time</emphasis>&gt;]  \
                      [<emphasis role="bold">-to</emphasis> &lt;<emphasis>date time</emphasis>&gt;] 
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">dele</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">deletedump</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-dumpid</emphasis></term>

                <listitem>
                  <para>Specifies the dump ID of each initial dump to delete from the Backup Database. The records for all
                  associated appended dumps are also deleted. Provide either this argument or the <emphasis
                  role="bold">-to</emphasis> (and optionally, <emphasis role="bold">-from</emphasis>) argument.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-from</emphasis></term>

                <listitem>
                  <para>Specifies the beginning of a range of dates; the record for any dump created during the indicated period of
                  time is deleted.</para>

                  <para>To omit all records before the time indicated with the <emphasis role="bold">-to</emphasis> argument, omit
                  this argument. Otherwise provide a value in the following format</para>

                  <para>mm/dd/yyyy [hh:MM]</para>

                  <para>where the month (mm), day (dd), and year (yyyy) are required. You can omit the hour and minutes (hh:MM) to
                  indicate the default of midnight (00:00 hours). If you provide them, use 24-hour format (for example, the value
                  <emphasis role="bold">14:36</emphasis> represents 2:36 p.m.).</para>

                  <para>You must provide the <emphasis role="bold">-to</emphasis> argument along with this one.</para>

                  <note>
                    <para>A plus sign follows this argument in the command's syntax statement because it accepts a multiword value
                    which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates.
                    Provide only one date (and optionally, time) definition.</para>
                  </note>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-to</emphasis></term>

                <listitem>
                  <para>Specifies the end of a range of dates; the record of any dump created during the range is deleted from the
                  Backup Database.</para>

                  <para>To delete all records created after the date you specify with the <emphasis role="bold">-from</emphasis>
                  argument, specify the value <emphasis role="bold">NOW</emphasis>. To delete every dump record in the Backup
                  Database, provide the value <emphasis role="bold">NOW</emphasis> and omit the <emphasis
                  role="bold">-from</emphasis> argument. Otherwise, provide a date value in the same format as described for the
                  <emphasis role="bold">-from</emphasis> argument. Valid values for the year (yyyy) range from <emphasis
                  role="bold">1970</emphasis> to <emphasis role="bold">2037</emphasis>; higher values are not valid because the
                  latest possible date in the standard UNIX representation is in early 2038. The command interpreter automatically
                  reduces any later date to the maximum value in 2038.</para>

                  <para>If you omit the time portion (hh:MM), it defaults to 59 seconds after midnight (00:00:59 hours). Similarly,
                  the <emphasis role="bold">backup</emphasis> command interpreter automatically adds 59 seconds to any time value
                  you provide. In both cases, adding 59 seconds compensates for how the Backup Database and <emphasis
                  role="bold">backup dumpinfo</emphasis> command represent dump creation times in hours and minutes only. For
                  example, the Database records a creation timestamp of <computeroutput>20:55</computeroutput> for any dump
                  operation that begins between 20:55:00 and 20:55:59. Automatically adding 59 seconds to a time thus includes the
                  records for all dumps created during that minute.</para>

                  <para>Provide either this argument, or the <emphasis role="bold">-dumpid</emphasis> argument. This argument is
                  required if the <emphasis role="bold">-from</emphasis> argument is provided.</para>

                  <note>
                    <para>A plus sign follows this argument in the command's syntax statement because it accepts a multiword value
                    which does not need to be enclosed in double quotes or other delimiters, not because it accepts multiple dates.
                    Provide only one date (and optionally, time) definition.</para>
                  </note>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>
</chapter>
