jimzah/openafs
1
0
Fork 0
mirror of https://git.openafs.org/openafs.git synced 2025-01-18 23:10:58 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
5d6dbcfd74
openafs/doc/xml/AdminGuide/auagd012.xml
Ken Dreyer 1cc8feb6fc doc: replace hostnames with IETF example hostnames 
There were several different real and made-up hostnames and company names used
throughout our documentation examples.

The IETF has reserved "example.com" and other "example" TLDs for use in
examples (RFC 2606). Replace almost all references to ABC Corporation, DEF
Corporation, and State University, as well as "abc.com", "bigcell.com",
"def.com", "def.gov", "ghi.com", "ghi.gov", "jkl.com", "mit.edu",
"stanford.edu", "state.edu", "stateu.edu", "uncc.edu", and "xyz.com".
Standardize on "Example Corporation", "Example Network", "Example
Organization" (example.com, example.net, and example.org).

The Scout documentation in the Admin Guide contains PNG images that contain
the old cell names, so I left those references until the images can be
replaced.

Change-Id: I4e44815b2d2ffe204810b7fd850842248f67c367
Reviewed-on: http://gerrit.openafs.org/6697
Reviewed-by: Jeffrey Altman <jaltman@secure-endpoints.com>
Tested-by: Jeffrey Altman <jaltman@secure-endpoints.com>
2012-02-17 20:51:58 -08:00

4621 lines
245 KiB
XML
Raw Blame History

<?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>
Reference in New Issue View Git Blame Copy Permalink