doc/html/AdminGuide/auagd012.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Guide</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
   8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
   9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Guide</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd011.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auagd013.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <HR><H1><A NAME="HDRWQ283" HREF="auagd002.htm#ToC_320">Backing Up and Restoring AFS Data</A></H1>
  18 <P>The instructions in this chapter explain how to back up and
  19 restore AFS data and to administer the Backup Database. They assume
  20 that you have already configured all of the Backup System components by
  21 following the instructions in <A HREF="auagd011.htm#HDRWQ248">Configuring the AFS Backup System</A>.
  22 <HR><H2><A NAME="HDRWQ284" HREF="auagd002.htm#ToC_321">Summary of Instructions</A></H2>
  23 <P>This chapter explains how to perform the following tasks by
  24 using the indicated commands:
  25 <BR>
  26 <TABLE WIDTH="100%">
  27 <TR>
  28 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Enter interactive mode
  29 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup (interactive)</B>
  30 </TD></TR><TR>
  31 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Leave interactive mode
  32 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>(backup) quit</B>
  33 </TD></TR><TR>
  34 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">List operations in interactive mode
  35 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>(backup) jobs</B>
  36 </TD></TR><TR>
  37 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Cancel operation in interactive mode
  38 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>(backup) kill</B>
  39 </TD></TR><TR>
  40 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Start Tape Coordinator
  41 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>butc</B>
  42 </TD></TR><TR>
  43 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Stop Tape Coordinator
  44 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%">&lt;<B>Ctrl-c</B>>
  45 </TD></TR><TR>
  46 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Check status of Tape Coordinator
  47 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup status</B>
  48 </TD></TR><TR>
  49 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Back up data
  50 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup dump</B>
  51 </TD></TR><TR>
  52 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display dump records
  53 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup dumpinfo</B>
  54 </TD></TR><TR>
  55 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display volume's dump history
  56 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup volinfo</B>
  57 </TD></TR><TR>
  58 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Scan contents of tape
  59 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup scantape</B>
  60 </TD></TR><TR>
  61 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Restore volume
  62 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup volrestore</B>
  63 </TD></TR><TR>
  64 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Restore partition
  65 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup diskrestore</B>
  66 </TD></TR><TR>
  67 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Restore group of volumes
  68 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup volsetrestore</B>
  69 </TD></TR><TR>
  70 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Verify integrity of Backup Database
  71 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup dbverify</B>
  72 </TD></TR><TR>
  73 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Repair corruption in Backup Database
  74 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup savedb</B> and <B>backup restoredb</B>
  75 </TD></TR><TR>
  76 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Delete dump set from Backup Database
  77 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>backup deletedump</B>
  78 </TD></TR></TABLE>
  79 <HR><H2><A NAME="HDRWQ286" HREF="auagd002.htm#ToC_322">Using the Backup System's Interfaces</A></H2>
  80 <A NAME="IDX6974"></A>
  81 <P>When performing backup operations, you interact with three Backup System
  82 components:
  83 <UL>
  84 <P><LI>You initiate backup operations by issuing commands from the
  85 <B>backup</B> suite. You can issue the commands in a command shell
  86 (or invoke them in a shell script) on any AFS client or server machine from
  87 which you can access the <B>backup</B> binary. In the conventional
  88 configuration, the binary resides in the <B>/usr/afs/bin</B> directory on
  89 a server machine and the <B>/usr/afsws/etc</B> directory on a client
  90 machine.
  91 <P>The suite provides an interactive mode, in which you can issue multiple
  92 commands over a persistent connection to the Backup Server and the Volume
  93 Location (VL) Server. Interactive mode has several convenient
  94 features. For a discussion and instructions, see <A HREF="#HDRWQ288">Using Interactive and Regular Command Mode</A>.
  95 <P>Note that some operating systems include a <B>backup</B> command of
  96 their own. You must configure machines that run such an operating
  97 system to ensure that you are accessing the desired <B>backup</B>
  98 binary.
  99 <P><LI>Before you perform a backup operation that involves reading or writing to
 100 a tape device or backup data file, you must open a dedicated connection to the
 101 appropriate Tape Coordinator machine and start the Tape Coordinator
 102 (<B>butc</B>) process that handles the device or file. The
 103 <B>butc</B> process must continue to run over the dedicated connection as
 104 long as it is executing an operation or is to be available to execute
 105 one. For further discussion and instructions, see <A HREF="#HDRWQ291">Starting and Stopping the Tape Coordinator Process</A>.
 106 <P><LI>The Backup Server (<B>buserver</B>) process must be running on
 107 database server machines, because most backup operations require accessing or
 108 changing information in the Backup Database. The <I>IBM AFS Quick
 109 Beginnings</I> explains how to configure the Backup Server.
 110 </UL>
 111 <P>For consistent Backup System performance, the AFS build level of all three
 112 binaries (<B>backup</B>, <B>butc</B>, and <B>buserver</B>) must
 113 match. For instructions on displaying the build level, see <A HREF="auagd008.htm#HDRWQ117">Displaying A Binary File's Build Level</A>.
 114 <P><H3><A NAME="HDRWQ287" HREF="auagd002.htm#ToC_323">Performing Backup Operations as the Local Superuser Root or in a Foreign Cell</A></H3>
 115 <A NAME="IDX6975"></A>
 116 <A NAME="IDX6976"></A>
 117 <A NAME="IDX6977"></A>
 118 <P>By default, the volumes and Backup Database involved in a backup operation
 119 must reside on server machines that belong to the cell named in the
 120 <B>/usr/vice/etc/ThisCell</B> files on both the Tape Coordinator machine
 121 and the machine where you issue the <B>backup</B> command. Also, to
 122 issue most <B>backup</B> commands you must have AFS tokens for an identity
 123 listed in the local cell's <B>/usr/afs/etc/UserList</B> file (which
 124 by convention is the same on every server machine in a cell). You can,
 125 however, perform backup operations on volumes or the Backup Database from a
 126 foreign cell, or perform backup operations while logged in as the local
 127 superuser <B>root</B> rather than as a privileged AFS identity.
 128 <P>To perform backup operations on volumes that reside in a foreign cell using
 129 machines from the local cell, you must designate the foreign cell as the cell
 130 of execution for both the Tape Coordinator and the <B>backup</B> command
 131 interpreter. Use one of the two following methods. For either
 132 method, you must also have tokens as an administrator listed in the foreign
 133 cell's <B>/usr/afs/etc/UserList</B> file.
 134 <UL>
 135 <P><LI>Before issuing <B>backup</B> commands and the <B>butc</B> command,
 136 set the AFSCELL environment variable to the foreign cell name in both command
 137 shells.
 138 <P><LI>Include the <B>-cell</B> argument to the <B>butc</B> and all
 139 <B>backup</B> commands. If you include the argument on the
 140 <B>backup (interactive)</B> command, it applies to all commands issued
 141 during the interactive session.
 142 </UL>
 143 <P>To perform backup operations without having administrative AFS tokens, you
 144 must log on as the local superuser <B>root</B> on both the Tape
 145 Coordinator machine and the machine where you issue <B>backup</B>
 146 commands. Both machines must be server machines, or at least have a
 147 <B>/usr/afs/etc/KeyFile</B> file that matches the file on other server
 148 machines. Then include the <B>-localauth</B> argument on both the
 149 <B>butc</B> command and all <B>backup</B> commands (or the <B>backup
 150 (interactive)</B> command). The Tape Coordinator and
 151 <B>backup</B> command interpreter construct a server ticket using the
 152 server encryption key with the highest key version number in the local
 153 <B>/usr/afs/etc/KeyFile</B> file, and present it to the Backup Server,
 154 Volume Server, and VL Server that belong to the cell named in the local
 155 <B>/usr/afs/etc/ThisCell</B> file. The ticket never expires.
 156 <P>You cannot combine the <B>-cell</B> and <B>-localauth</B> options
 157 on the same command. Also, each one overrides the local cell setting
 158 defined by the AFSCELL environment variable or the
 159 <B>/usr/vice/etc/ThisCell</B> file.
 160 <P><H3><A NAME="HDRWQ288" HREF="auagd002.htm#ToC_324">Using Interactive and Regular Command Mode</A></H3>
 161 <A NAME="IDX6978"></A>
 162 <A NAME="IDX6979"></A>
 163 <P>The <B>backup</B> command suite provides an <I>interactive
 164 mode</I>, in which you can issue multiple commands over a persistent
 165 connection to the Backup Server and the VL Server. Interactive mode
 166 provides the following features:
 167 <UL>
 168 <P><LI>The <TT>backup></TT> prompt replaces the usual command shell
 169 prompt.
 170 <P><LI>You omit the initial <B>backup</B> string from command names.
 171 Type only the operation code and option names.
 172 <P><LI>You cannot issue commands that do not belong to the <B>backup</B>
 173 suite.
 174 <P><LI>If you assume an administrative AFS identity or specify a foreign cell as
 175 you enter interactive mode, it applies to all commands issued during the
 176 interactive session. See <A HREF="#HDRWQ287">Performing Backup Operations as the Local Superuser Root or in a Foreign Cell</A>.
 177 <P><LI>You do not need to enclose shell metacharacters in double quotes.
 178 </UL>
 179 <A NAME="IDX6980"></A>
 180 <A NAME="IDX6981"></A>
 181 <P>When you initiate a backup operation in interactive mode, the Backup System
 182 assigns it a <I>job ID number</I>. You can display the list of
 183 current and pending operations with the <B>(backup) jobs</B> command, for
 184 which instructions appear in <A HREF="#HDRWQ289">To display pending or running jobs in interactive mode</A>. (In both regular and interactive modes, the Tape
 185 Coordinator also assigns a <I>task ID number</I> to each operation you
 186 initiate with a <B>backup</B> command. You can track task ID
 187 numbers with the <B>backup status</B> command. See <A HREF="#HDRWQ291">Starting and Stopping the Tape Coordinator Process</A>.)
 188 <P>You can cancel an operation in interactive mode with the <B>(backup)
 189 kill</B> command, for which instructions appear in <A HREF="#HDRWQ290">To cancel operations in interactive mode</A>. However, it is best not to interrupt a dump
 190 operation because the resulting dump is incomplete, and interrupting a restore
 191 operation can leave volumes in an inconsistent state, or even completely
 192 remove them from the server machine. For further discussion, see <A HREF="#HDRWQ296">Backing Up Data</A> and <A HREF="#HDRWQ306">Restoring and Recovering Data</A>.
 193 <P>The <B>(backup) jobs</B> and <B>(backup) kill</B> commands are
 194 available only in interactive mode and there is no equivalent functionality in
 195 regular command mode.
 196 <A NAME="IDX6982"></A>
 197 <A NAME="IDX6983"></A>
 198 <A NAME="IDX6984"></A>
 199 <A NAME="IDX6985"></A>
 200 <P><H3><A NAME="Header_325" HREF="auagd002.htm#ToC_325">To enter interactive mode</A></H3>
 201 <OL TYPE=1>
 202 <P><LI>Verify that you are authenticated as a user listed in the
 203 <B>/usr/afs/etc/UserList</B> file. Entering interactive mode does
 204 not itself require privilege, but most other <B>backup</B> commands do,
 205 and the AFS identity you assume when entering the mode applies to all commands
 206 you issue within it. If necessary, issue the <B>bos listusers</B>
 207 command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
 208 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 209 </PRE>
 210 <P><LI>Issue the <B>backup (interactive)</B> command at the system
 211 prompt. The <TT>backup></TT> prompt appears. You can include
 212 either, but not both, of the <B>-localauth</B> and <B>-cell</B>
 213 options, as discussed in <A HREF="#HDRWQ287">Performing Backup Operations as the Local Superuser Root or in a Foreign Cell</A>.
 214 <PRE>   % <B>backup</B>
 215    backup>
 216 </PRE>
 217 </OL>
 218 <A NAME="IDX6986"></A>
 219 <A NAME="IDX6987"></A>
 220 <A NAME="IDX6988"></A>
 221 <A NAME="IDX6989"></A>
 222 <P><H3><A NAME="Header_326" HREF="auagd002.htm#ToC_326">To exit interactive mode</A></H3>
 223 <P><B></B>
 224 <OL TYPE=1>
 225 <P><LI>Issue the <B>quit</B> command at the <TT>backup></TT> prompt.
 226 The command shell prompt reappears when the command succeeds, which it does
 227 only if there are no jobs pending or currently running. To display and
 228 cancel pending or running jobs, follow the instructions in <A HREF="#HDRWQ289">To display pending or running jobs in interactive mode</A> and <A HREF="#HDRWQ290">To cancel operations in interactive mode</A>.
 229 <PRE>   backup> <B>quit</B>
 230    %
 231 </PRE>
 232 </OL>
 233 <A NAME="IDX6990"></A>
 234 <A NAME="IDX6991"></A>
 235 <A NAME="IDX6992"></A>
 236 <A NAME="IDX6993"></A>
 237 <A NAME="IDX6994"></A>
 238 <A NAME="IDX6995"></A>
 239 <P><H3><A NAME="HDRWQ289" HREF="auagd002.htm#ToC_327">To display pending or running jobs in interactive mode</A></H3>
 240 <OL TYPE=1>
 241 <P><LI>Issue the <B>jobs</B> command at the <TT>backup></TT> prompt.
 242 <P>
 243 <PRE>   backup> <B>jobs</B>
 244 </PRE>
 245 <P>where
 246 <DL>
 247 <P><DT><B>j
 248 </B><DD>Is the shortest acceptable abbreviation of <B>jobs</B>.
 249 </DL>
 250 </OL>
 251 <P>The output always includes the expiration date and time of the tokens that
 252 the <B>backup</B> command interpreter is using during the current
 253 interactive session, in the following format:
 254 <PRE>   <VAR>date</VAR>   <VAR>time</VAR>: TOKEN EXPIRATION
 255 </PRE>
 256 <P>If the execution date and time specified for a scheduled dump operation is
 257 later than <I>date time</I>, then its individual line (as described in the
 258 following paragraphs) appears below this line to indicate that the current
 259 tokens will not be available to it.
 260 <P>If the issuer of the <B>backup</B> command included the
 261 <B>-localauth</B> flag when entering interactive mode, the line instead
 262 reads as follows:
 263 <PRE>   :  TOKEN NEVER EXPIRES
 264 </PRE>
 265 <P>The entry for a scheduled dump operation has the following format:
 266 <PRE>   Job <VAR>job_ID</VAR>:  <VAR>timestamp</VAR>:  dump  <VAR>volume_set</VAR>  <VAR>dump_level</VAR>
 267 </PRE>
 268 <P>where
 269 <DL>
 270 <P><DT><B><VAR>job_ID</VAR>
 271 </B><DD>Is a job identification number assigned by the Backup System.
 272 <P><DT><B><VAR>timestamp</VAR>
 273 </B><DD>Indicates the date and time the dump operation is to begin, in the format
 274 <I>month</I>/<I>date</I>/<I>year</I>
 275 <I>hours</I>:<I>minutes</I> (in 24-hour format)
 276 <P><DT><B><VAR>volume_set</VAR>
 277 </B><DD>Indicates the volume set to dump.
 278 <P><DT><B><VAR>dump_level</VAR>
 279 </B><DD>Indicates the dump level at which to perform the dump operation.
 280 </DL>
 281 <P>The line for a pending or running operation of any other type has the
 282 following format:
 283 <PRE>   Job <VAR>job_ID</VAR>:  <VAR>operation</VAR>  <VAR>status</VAR>
 284 </PRE>
 285 <P>where
 286 <DL>
 287 <P><DT><B><VAR>job_ID</VAR>
 288 </B><DD>Is a job identification number assigned by the Backup System.
 289 <P><DT><B><VAR>operation</VAR>
 290 </B><DD>Identifies the operation the Tape Coordinator is performing, which is
 291 initiated by the indicated command:
 292 <DL>
 293 <P><DT><B><TT>Dump</TT> <TT>(</TT><VAR>dump name</VAR><TT>)</TT>
 294 </B><DD>Initiated by the <B>backup dump</B> command. The <VAR>dump
 295 name</VAR> has the following format:
 296 <P><VAR>volume_set_name</VAR><B>.</B><VAR>dump_level_name</VAR>
 297 <P><DT><B><TT>Restore</TT>
 298 </B><DD>Initiated by the <B>backup diskrestore</B>, <B>backup
 299 volrestore</B>, or <B>backup volsetrestore</B> command.
 300 <P><DT><B><TT>Labeltape</TT> <TT>(</TT><VAR>tape_label</VAR><TT>)</TT>
 301 </B><DD>Initiated by the <B>backup labeltape</B> command. The
 302 <VAR>tape_label</VAR> is the name specified by the <B>backup labeltape</B>
 303 command's <B>-name</B> or <B>-pname</B> argument.
 304 <P><DT><B><TT>Scantape</TT>
 305 </B><DD>Initiated by the <B>backup scantape</B> command.
 306 <P><DT><B><TT>SaveDb</TT>
 307 </B><DD>Initiated by the <B>backup savedb</B> command.
 308 <P><DT><B><TT>RestoreDb</TT>
 309 </B><DD>Initiated by the <B>backup restoredb</B> command.
 310 </DL>
 311 <P><DT><B><VAR>status</VAR>
 312 </B><DD>Indicates the job's current status in one of the following
 313 messages. If no message appears, the job is either still pending or has
 314 finished.
 315 <DL>
 316 <P><DT><B><VAR>number</VAR> <TT>Kbytes, volume</TT> <VAR>volume_name</VAR>
 317 </B><DD>For a running dump operation, indicates the number of kilobytes copied to
 318 tape or a backup data file so far, and the volume currently being
 319 dumped.
 320 <P><DT><B><VAR>number</VAR> <TT>Kbytes, restore.volume</TT>
 321 </B><DD>For a running restore operation, indicates the number of kilobytes copied
 322 into AFS from a tape or a backup data file so far.
 323 <P><DT><B><TT>[abort requested]</TT>
 324 </B><DD>The <B>(backup) kill</B> command was issued, but the termination
 325 signal has yet to reach the Tape Coordinator.
 326 <P><DT><B><TT>[abort sent]</TT>
 327 </B><DD>The operation is canceled by the <B>(backup) kill</B> command.
 328 Once the Backup System removes an operation from the queue or stops it from
 329 running, it no longer appears at all in the output from the command.
 330 <P><DT><B><TT>[butc contact lost]</TT>
 331 </B><DD>The <B>backup</B> command interpreter cannot reach the Tape
 332 Coordinator. The message can mean either that the Tape Coordinator
 333 handling the operation was terminated or failed while the operation was
 334 running, or that the connection to the Tape Coordinator timed out.
 335 <P><DT><B><TT>[done]</TT>
 336 </B><DD>The Tape Coordinator has finished the operation.
 337 <P><DT><B><TT>[drive wait]</TT>
 338 </B><DD>The operation is waiting for the specified tape drive to become
 339 free.
 340 <P><DT><B><TT>[operator wait]</TT>
 341 </B><DD>The Tape Coordinator is waiting for the backup operator to insert a tape
 342 in the drive.
 343 </DL>
 344 </DL>
 345 <A NAME="IDX6996"></A>
 346 <A NAME="IDX6997"></A>
 347 <A NAME="IDX6998"></A>
 348 <A NAME="IDX6999"></A>
 349 <A NAME="IDX7000"></A>
 350 <P><H3><A NAME="HDRWQ290" HREF="auagd002.htm#ToC_328">To cancel operations in interactive mode</A></H3>
 351 <OL TYPE=1>
 352 <P><LI>Issue the <B>jobs</B> command at the <TT>backup></TT> prompt, to
 353 learn the job ID number of the operation you want to cancel. For
 354 details, see <A HREF="#HDRWQ289">To display pending or running jobs in interactive mode</A>.
 355 <PRE>   backup> <B>jobs</B>
 356 </PRE>
 357 <P><LI>Issue the <B>(backup) kill</B> command to cancel the operation.
 358 <P>
 359 <PRE>   backup> <B>kill</B> &lt;<VAR>job&nbsp;ID&nbsp;or&nbsp;dump&nbsp;set&nbsp;name</VAR>>
 360 </PRE>
 361 <P>where
 362 <DL>
 363 <P><DT><B>k
 364 </B><DD>Is the shortest acceptable abbreviation of <B>kill</B>.
 365 <P><DT><B><VAR>job ID or dump set name</VAR>
 366 </B><DD>Specifies either the job ID number of the operation to cancel, as reported
 367 by the <B>jobs</B> command, or for a dump operation only, the dump name in
 368 the format <VAR>volume_set_name</VAR>.<VAR>dump_level_name</VAR>.
 369 </DL>
 370 </OL>
 371 <P><H3><A NAME="HDRWQ291" HREF="auagd002.htm#ToC_329">Starting and Stopping the Tape Coordinator Process</A></H3>
 372 <A NAME="IDX7001"></A>
 373 <P>Before performing a backup operation that reads from or writes to a tape
 374 device or backup data file, you must start the Tape Coordinator
 375 (<B>butc</B>) process that handles the drive or file. This section
 376 explains how to start, stop, and check the status of a Tape Coordinator
 377 process. To use these instructions, you must have already configured
 378 the Tape Coordinator machine and created a Tape Coordinator entry in the
 379 Backup Database, as instructed in <A HREF="auagd011.htm#HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</A>.
 380 <P>
 381 <A NAME="IDX7002"></A>
 382 <A NAME="IDX7003"></A>
 383 The Tape Coordinator assigns a <I>task ID number</I> to each operation it
 384 performs. The number is distinct from the job ID number assigned by the
 385 <B>backup</B> command interpreter in interactive mode (which is discussed
 386 in <A HREF="#HDRWQ288">Using Interactive and Regular Command Mode</A>). The Tape Coordinator reports the task ID number in
 387 its onscreen trace and in the messages that it writes to its log and error
 388 files. To view the task ID numbers of a Tape Coordinator's running
 389 or pending operations, issue the <B>backup status</B> command.
 390 <A NAME="IDX7004"></A>
 391 <A NAME="IDX7005"></A>
 392 <A NAME="IDX7006"></A>
 393 <P><H3><A NAME="HDRWQ292" HREF="auagd002.htm#ToC_330">To start a Tape Coordinator process</A></H3>
 394 <OL TYPE=1>
 395 <P><LI>Verify that you are authenticated as a user listed in the
 396 <B>/usr/afs/etc/UserList</B> file of the cell in which the Tape
 397 Coordinator is to access volume data and the Backup Database. If
 398 necessary, issue the <B>bos listusers</B> command, which is fully
 399 described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
 400 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 401 </PRE>
 402 <P>Alternately, you can log into a file server machine as the local superuser
 403 <B>root</B> in Step <A HREF="#LIWQ293">3</A>.
 404 <P><LI>Verify that you can write to the Tape Coordinator's log and error
 405 files in the local <B>/usr/afs/backup</B> directory (the
 406 <B>TE_</B><VAR>device_name</VAR> and <B>TL_</B><VAR>device_name</VAR>
 407 files). If the log and error files do not already exist, you must be
 408 able to insert and write to files in the <B>/usr/afs/backup</B>
 409 directory.
 410 <P><LI><A NAME="LIWQ293"></A>Open a connection (using a command such as <B>telnet</B> or
 411 <B>rlogin</B>) to the Tape Coordinator machine that drives the tape
 412 device, or whose local disk houses the backup data file. The Tape
 413 Coordinator uses a devoted connection or window that must remain open for the
 414 Tape Coordinator to accept requests and while it is executing them.
 415 <P>If you plan to include the <B>-localauth</B> flag to the
 416 <B>butc</B> command in the next step, log in as the local superuser
 417 <B>root</B>.
 418 <P><LI><A NAME="LIWQ294"></A>Issue the <B>butc</B> command to start the Tape
 419 Coordinator. You can include either, but not both, of the
 420 <B>-localauth</B> and <B>-cell</B> options, as discussed in <A HREF="#HDRWQ287">Performing Backup Operations as the Local Superuser Root or in a Foreign Cell</A>.
 421 <PRE>   % <B>butc</B> [&lt;<VAR>port&nbsp;offset</VAR>>]  [<B>-debuglevel</B> &lt;<VAR>trace&nbsp;level</VAR>>]  \
 422           [<B>-cell</B> &lt;<VAR>cellname</VAR>>] [<B>-noautoquery</B>] [<B>-localauth</B>]
 423 </PRE>
 424 <P>where
 425 <DL>
 426 <P><DT><B>butc
 427 </B><DD>Must be typed in full.
 428 <P><DT><B><VAR>port offset</VAR>
 429 </B><DD>Specifies the Tape Coordinator's port offset number. You must
 430 provide this argument unless the default value of <B>0</B> (zero) is
 431 appropriate.
 432 <P><DT><B>-debuglevel
 433 </B><DD>Specifies the type of trace messages that the Tape Coordinator writes to
 434 the standard output stream (stdout). Provide one of the following three
 435 values, or omit this argument to display the default type of messages
 436 (equivalent to setting a value of <B>0</B> [zero]):
 437 <UL>
 438 <P><LI><B>0</B>: The Tape Coordinator generates only the minimum number
 439 of messages necessary to communicate with the backup operator, including
 440 prompts for insertion of additional tapes and messages that indicate errors or
 441 the beginning or completion of operations.
 442 <P><LI><B>1</B>: In addition to the messages displayed at level
 443 <B>0</B>, the Tape Coordinator displays the name of each volume being
 444 dumped or restored.
 445 <P><LI><B>2</B>: In addition to the messages displayed at levels
 446 <B>0</B> and <B>1</B>, the Tape Coordinator displays all of the
 447 messages it is also writing to its log file
 448 (<B>/usr/afs/backup/TL_</B><VAR>device_name</VAR>).
 449 </UL>
 450 <P><DT><B><VAR>cellname</VAR>
 451 </B><DD>Names the cell in which to perform the backup operations (the cell where
 452 the relevant volumes reside and the Backup Server process is running).
 453 If you omit this argument, the Tape Coordinator uses its home cell, as defined
 454 in the local <B>/usr/vice/etc/ThisCell</B> file. Do not combine
 455 this argument with the <B>-localauth</B> flag.
 456 <P><DT><B>-noautoquery
 457 </B><DD>Disables the Tape Coordinator's prompt for the first tape it needs
 458 for each operation. For a description of the advantages and
 459 consequences of including this flag, see <A HREF="auagd011.htm#HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</A>.
 460 <P><DT><B>-localauth
 461 </B><DD>Constructs a server ticket using a key from the local
 462 <B>/usr/afs/etc/KeyFile</B> file. The <B>butc</B> process
 463 presents it to the Backup Server, Volume Server, and VL Server during mutual
 464 authentication. You must be logged into a file server machine as the
 465 local superuser <B>root</B> to include this flag, and cannot combine it
 466 with the <B>-cell</B> argument.
 467 </DL>
 468 </OL>
 469 <A NAME="IDX7007"></A>
 470 <P><H3><A NAME="Header_331" HREF="auagd002.htm#ToC_331">To stop a Tape Coordinator process</A></H3>
 471 <OL TYPE=1>
 472 <P><LI>Enter an interrupt signal such as &lt;<B>Ctrl-c</B>> over the
 473 dedicated connection to the Tape Coordinator.
 474 </OL>
 475 <A NAME="IDX7008"></A>
 476 <A NAME="IDX7009"></A>
 477 <A NAME="IDX7010"></A>
 478 <P><H3><A NAME="HDRWQ295" HREF="auagd002.htm#ToC_332">To check the status of a Tape Coordinator process</A></H3>
 479 <OL TYPE=1>
 480 <P><LI>Verify that you are authenticated as a user listed in the
 481 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
 482 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
 483 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 484 </PRE>
 485 <P><LI>Issue the <B>backup status</B> command.
 486 <PRE>   % <B>backup status</B> [&lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
 487 </PRE>
 488 <P>where
 489 <DL>
 490 <P><DT><B>st
 491 </B><DD>Is the shortest acceptable abbreviation of <B>status</B>.
 492 <P><DT><B><VAR>TC port offset</VAR>
 493 </B><DD>Specifies the Tape Coordinator's port offset number. You must
 494 provide this argument unless the default value of <B>0</B> (zero) is
 495 appropriate.
 496 </DL>
 497 </OL>
 498 <P>The following message indicates that the Tape Coordinator is not currently
 499 performing an operation:
 500 <PRE>   Tape coordinator is idle
 501 </PRE>
 502 <P>Otherwise, the output includes a message of the following format for each
 503 running or pending operation:
 504 <PRE>   Task <VAR>task_ID</VAR>:  <VAR>operation</VAR>:   <VAR>status</VAR>
 505 </PRE>
 506 <P>where
 507 <DL>
 508 <P><DT><B><VAR>task_ID</VAR>
 509 </B><DD>Is a task identification number assigned by the Tape Coordinator.
 510 It begins with the Tape Coordinator's port offset number.
 511 <P><DT><B><VAR>operation</VAR>
 512 </B><DD>Identifies the operation the Tape Coordinator is performing, which is
 513 initiated by the indicated command:
 514 <UL>
 515 <P><LI><TT>Dump</TT> (the <B>backup dump</B> command)
 516 <P><LI><TT>Restore</TT> (the <B>backup diskrestore</B>, <B>backup
 517 volrestore</B>, or <B>backup volsetrestore</B> commands)
 518 <P><LI><TT>Labeltape</TT> (the <B>backup labeltape</B> command)
 519 <P><LI><TT>Scantape</TT> (the <B>backup scantape</B> command)
 520 <P><LI><TT>SaveDb</TT> (the <B>backup savedb</B> command)
 521 <P><LI><TT>RestoreDb</TT> (the <B>backup restoredb</B> command)
 522 </UL>
 523 <P><DT><B><VAR>status</VAR>
 524 </B><DD>Indicates the job's current status in one of the following
 525 messages.
 526 <DL>
 527 <P><DT><B><VAR>number</VAR> <TT>Kbytes transferred, volume</TT> <VAR>volume_name</VAR>
 528 </B><DD>For a running dump operation, indicates the number of kilobytes copied to
 529 tape or a backup data file so far, and the volume currently being
 530 dumped.
 531 <P><DT><B><VAR>number</VAR> <TT>Kbytes, restore.volume</TT>
 532 </B><DD>For a running restore operation, indicates the number of kilobytes copied
 533 into AFS from a tape or a backup data file so far.
 534 <P><DT><B><TT>[abort requested]</TT>
 535 </B><DD>The <B>(backup) kill</B> command was issued, but the termination
 536 signal has yet to reach the Tape Coordinator.
 537 <P><DT><B><TT>[abort sent]</TT>
 538 </B><DD>The operation is canceled by the <B>(backup) kill</B> command.
 539 Once the Backup System removes an operation from the queue or stops it from
 540 running, it no longer appears at all in the output from the command.
 541 <P><DT><B><TT>[butc contact lost]</TT>
 542 </B><DD>The <B>backup</B> command interpreter cannot reach the Tape
 543 Coordinator. The message can mean either that the Tape Coordinator
 544 handling the operation was terminated or failed while the operation was
 545 running, or that the connection to the Tape Coordinator timed out.
 546 <P><DT><B><TT>[done]</TT>
 547 </B><DD>The Tape Coordinator has finished the operation.
 548 <P><DT><B><TT>[drive wait]</TT>
 549 </B><DD>The operation is waiting for the specified tape drive to become
 550 free.
 551 <P><DT><B><TT>[operator wait]</TT>
 552 </B><DD>The Tape Coordinator is waiting for the backup operator to insert a tape
 553 in the drive.
 554 </DL>
 555 </DL>
 556 <P>If the Tape Coordinator is communicating with an XBSA server (a third-party
 557 backup utility that implements the Open Group's Backup Service API
 558 [XBSA]), the following message appears last in the output:
 559 <PRE>   <VAR>XBSA_program</VAR> Tape coordinator
 560 </PRE>
 561 <P>where <VAR>XBSA_program</VAR> is the name of the XBSA-compliant
 562 program.
 563 <HR><H2><A NAME="HDRWQ296" HREF="auagd002.htm#ToC_333">Backing Up Data</A></H2>
 564 <A NAME="IDX7011"></A>
 565 <A NAME="IDX7012"></A>
 566 <A NAME="IDX7013"></A>
 567 <A NAME="IDX7014"></A>
 568 <A NAME="IDX7015"></A>
 569 <A NAME="IDX7016"></A>
 570 <A NAME="IDX7017"></A>
 571 <A NAME="IDX7018"></A>
 572 <A NAME="IDX7019"></A>
 573 <A NAME="IDX7020"></A>
 574 <A NAME="IDX7021"></A>
 575 <A NAME="IDX7022"></A>
 576 <P>This section explains how to use the <B>backup dump</B> command to back
 577 up AFS data to tape or to a backup data file. The instructions assume
 578 that you understand Backup System concepts and have already configured the
 579 Backup System according to the instructions in <A HREF="auagd011.htm#HDRWQ248">Configuring the AFS Backup System</A>. Specifically, you must already have:
 580 <UL>
 581 <P><LI>Decided whether to dump data to tape or to a backup data file, and
 582 configured the Tape Coordinator machine and Tape Coordinator process
 583 appropriately. See <A HREF="auagd011.htm#HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</A> and <A HREF="auagd011.htm#HDRWQ282">Dumping Data to a Backup Data File</A>.
 584 <P><LI>Defined a volume set that includes the volumes you want to dump
 585 together. See <A HREF="auagd011.htm#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>.
 586 <P><LI>Defined the dump level in the dump hierarchy at which you want to dump the
 587 volume set. If it is an incremental dump level, you must have
 588 previously created a dump at its parent level. See <A HREF="auagd011.htm#HDRWQ267">Defining and Displaying the Dump Hierarchy</A>.
 589 <P><LI>Created a device configuration file. Such a file is required for
 590 each tape stacker, jukebox device, or backup data file. You can also
 591 use it to configure the Backup System's automation features. See <A HREF="auagd011.htm#HDRWQ275">Automating and Increasing the Efficiency of the Backup Process</A>.
 592 </UL>
 593 <P>The most basic way to perform a dump operation is to create an initial dump
 594 of a single volume set as soon as the appropriate Tape Coordinator is
 595 available, by providing only the required arguments to the <B>backup
 596 dump</B> command. Instructions appear in <A HREF="#HDRWQ301">To create a dump</A>. The command has several optional arguments that
 597 you can use to increase the efficiency and flexibility of your backup
 598 procedures:
 599 <UL>
 600 <P><LI>To append a dump to the end of a set of tapes that already contains other
 601 dumps, include the <B>-append</B> argument. Otherwise, the Backup
 602 System creates an initial dump. Appending dumps enables you to use a
 603 tape's full capacity and has other potentially useful features.
 604 For a discussion, see <A HREF="#HDRWQ299">Appending Dumps to an Existing Dump Set</A>.
 605 <P><LI>To schedule one or more dump operations to run at a future time, include
 606 the <B>-at</B> argument. For a discussion and instructions, see <A HREF="#HDRWQ300">Scheduling Dumps</A>.
 607 <P><LI>To initiate a number of dump operations with a single <B>backup
 608 dump</B> command, include the <B>-file</B> argument to name a file in
 609 which you have listed the commands. For a discussion and instructions,
 610 see <A HREF="#HDRWQ299">Appending Dumps to an Existing Dump Set</A> and <A HREF="#HDRWQ300">Scheduling Dumps</A>.
 611 <P><LI>To generate a list of the volumes to be included in a dump, without
 612 actually dumping them, combine the <B>-n</B> flag with the other arguments
 613 to be used on the actual command.
 614 </UL>
 615 <P><H3><A NAME="HDRWQ297" HREF="auagd002.htm#ToC_334">Making Backup Operations More Efficient</A></H3>
 616 <A NAME="IDX7023"></A>
 617 <P>There are several ways to make dump operations more efficient, less prone
 618 to error, and less disruptive to your users. Several of them also
 619 simplify the process of restoring data if that becomes necessary.
 620 <UL>
 621 <P><LI>It is best not to dump the read/write or read-only version of a volume,
 622 because no other users or processes can access a volume while it is being
 623 dumped. Instead, shortly before the dump operation begins, create a
 624 backup version of each volume to be dumped, and dump the backup
 625 version. Creating a Backup version usually makes the source volume
 626 unavailable for just a few moments (during which access attempts by other
 627 processes are blocked but do not fail). To automate the creation of
 628 backup volumes, you can create a <B>cron</B> process in the
 629 <B>/usr/afs/local/BosConfig</B> file on one or more server machines,
 630 setting its start time at a sufficient interval before the dump operation is
 631 to begin. Include the <B>-localauth</B> argument to the <B>vos
 632 backup</B> or <B>vos backupsys</B> command to enable it to run without
 633 administrative tokens. For instructions, see <A HREF="auagd009.htm#HDRWQ162">To create and start a new process</A>.
 634 <P><LI>The volume set, dump level, and Tape Coordinator port offset you specify
 635 on the <B>backup dump</B> command line must be properly defined in the
 636 Backup Database. The Backup System checks the database before beginning
 637 a dump operation and halts the command immediately if any of the required
 638 entities are missing. If necessary, use the indicated commands:
 639 <UL>
 640 <P><LI>To display volume sets, use the <B>backup listvolsets</B> command as
 641 described in <A HREF="auagd011.htm#HDRWQ266">To display volume sets and volume entries</A>.
 642 <P><LI>To display dump levels, use the <B>backup listdumps</B> command as
 643 described in <A HREF="auagd011.htm#HDRWQ271">To display the dump hierarchy</A>.
 644 <P><LI>To display port offsets, use the <B>backup listhosts</B> command as
 645 described in <A HREF="auagd011.htm#HDRWQ264">To display the list of configured Tape Coordinators</A>.
 646 </UL>
 647 <P><LI>Ensure that a valid token corresponding to a privileged administrative
 648 identity is available to the Backup System processes both when the <B>backup
 649 dump</B> command is issued and when the dump operation actually runs (for a
 650 complete description or the necessary privileges, see <A HREF="auagd011.htm#HDRWQ260">Granting Administrative Privilege to Backup Operators</A>). This is a special concern for scheduled
 651 dumps. One alternative is to run <B>backup</B> commands (or the
 652 script that invokes them) and the <B>butc</B> command on server machines,
 653 and to include the <B>-localauth</B> argument on the command. In
 654 this case, the processes use the key with the highest key version number in
 655 the local <B>/usr/afs/etc/KeyFile</B> file to construct a token that never
 656 expires. Otherwise, you must use a method to renew tokens before they
 657 expire, or grant tokens with long lifetimes. In either case, you must
 658 protect against improper access to the tokens by securing the machines both
 659 physically and against unauthorized network access. The protection
 660 possibly needs to be even stronger than when a human operator is present
 661 during the operations.
 662 <P><LI>Record tape capacity and filemark size values that are as accurate as
 663 possible in the Tape Coordinator's <B>/usr/afs/backup/tapeconfig</B>
 664 file and on the tape's label. For suggested values and a
 665 description of what can happen when they are inaccurate, see <A HREF="auagd011.htm#HDRWQ258">Configuring the tapeconfig File</A>.
 666 <P><LI>If an unattended dump requires multiple tapes, arrange to provide them by
 667 properly configuring a tape stacker or jukebox and writing a tape-mounting
 668 script to be invoked in the device's <B>CFG_</B><VAR>device_name</VAR>
 669 file. For instructions, see <A HREF="auagd011.htm#HDRWQ277">Invoking a Device's Tape Mounting and Unmounting Routines</A>.
 670 <P><LI>You can configure any tape device or backup data file's
 671 <B>CFG_</B><VAR>device_name</VAR> file to take advantage of the Backup
 672 System's automation features. See <A HREF="auagd011.htm#HDRWQ275">Automating and Increasing the Efficiency of the Backup Process</A>.
 673 <P><LI>When you issue a <B>backup</B> command in regular (noninteractive)
 674 mode, the command shell prompt does not return until the operation
 675 completes. To avoid having to open additional connections, issue the
 676 <B>backup dump</B> command in interactive mode, especially when including
 677 the <B>-at</B> argument to schedule dump operations.
 678 <P><LI>An incremental dump proceeds most smoothly if there is a dump created at
 679 the dump level immediately above the level you are using. If the Backup
 680 System does not find a Backup Database record for a dump created at the
 681 immediate parent level, it looks for a dump created at one level higher in the
 682 hierarchy, continuing up to the full dump level if necessary. It
 683 creates an incremental dump at the level one below the lowest valid parent
 684 dump that it finds, or even creates a full dump if that is necessary.
 685 This algorithm guarantees that the dump captures all data that has changed
 686 since the last dump, but has a couple of disadvantages. First, the
 687 Backup System's search through the database for a valid parent dump takes
 688 extra time. Second, the subsequent pattern of dumps can be confusing to
 689 a human operator who needs to restore data from them, because they were not
 690 performed at the expected dump levels.
 691 <P>The easiest way to guarantee that a dump exists at the immediate parent
 692 level is always to perform dump operations on the predetermined
 693 schedule. To check that the parent dump exists, you can issue the
 694 <B>backup dumpinfo</B> command (as described in <A HREF="#HDRWQ303">To display dump records</A>) and search for it in the output. Alternatively,
 695 issue the <B>backup volinfo</B> command (as described in <A HREF="#HDRWQ304">To display a volume's dump history</A>) for a volume that you believe is in the parent dump.
 696 <P><LI>Always use dump levels from the same hierarchy (levels that are
 697 descendants of the same full level) when dumping a given volume set.
 698 The result of alternating between levels from different hierarchies can be
 699 confusing when you need to restore data or read dump records. It also
 700 increases the chance that changed data is not captured in any dump, or is
 701 backed up redundantly into more than one dump.
 702 <P><LI>Use permanent tape names rather than AFS tape names. You can make
 703 permanent names more descriptive than is allowed by an AFS tape name's
 704 strict format, and also bypass the name-checking step that the Backup System
 705 performs by default when a tape has an AFS tape name only. You can also
 706 configure the Tape Coordinator always to skip the check, however; for
 707 instructions and a description of the acceptable format for AFS tape names,
 708 see <A HREF="auagd011.htm#HDRWQ280">Eliminating the AFS Tape Name Check</A>.
 709 <P><LI>If you write dumps to tape, restore operations are simplest if all of your
 710 tape devices are compatible (can read the same type of tape, at the same
 711 compression ratios, and so on). If you must use incompatible devices,
 712 then at least use compatible devices for all dumps performed at dump levels
 713 that are at the same depth in their respective hierarchies (compatible devices
 714 for all dumps performed at a full dump level, compatible devices for all dumps
 715 performed at a level 1 incremental dump level, and so on). The
 716 <B>-portoffset</B> argument to the <B>backup diskrestore</B> and
 717 <B>backup volsetrestore</B> commands accepts multiple port offset numbers,
 718 but uses the first listed port offset when restoring all full dumps, the
 719 second port offset when restoring all level 1 dumps, and so on. If you
 720 did not use compatible tape devices when creating dumps at the same depth in a
 721 hierarchy, you must restore one volume at a time with the <B>backup
 722 volrestore</B> command.
 723 <P><LI>In some cases, it makes sense to use a <I>temporary</I> volume set,
 724 which exists only within the context of the interactive session in which it is
 725 created and for which no record is created in the Backup Database. One
 726 suitable situation is when dumping a volume to tape in preparation for
 727 removing it permanently (perhaps because its owner is leaving the
 728 cell). In this case, you can define a volume entry that includes only
 729 the volume of interest without cluttering up the Backup Database with a volume
 730 set record that you are using only once.
 731 <P><LI>Do not perform a dump operation when you know that there are network,
 732 machine, or server process problems that can prevent the Backup System from
 733 accessing volumes or the Volume Location Database (VLDB). Although the
 734 Backup System automatically makes a number of repeated attempts to get to an
 735 inaccessible volume, the dump operation takes extra time and in some cases
 736 stops completely to prompt you for instructions on how to continue.
 737 Furthermore, if the Backup System's last access attempt fails and the
 738 volume is omitted from the dump, you must take extra steps to have it backed
 739 up (namely, the steps described just following for a halted dump
 740 operation). For a more complete description of how the Backup System
 741 makes repeated access attempts, see <A HREF="#HDRWQ298">How Your Configuration Choices Influence the Dump Process</A>.
 742 <P><LI>Review the logs created by the Backup System as soon as possible after a
 743 dump operation completes, particularly if it ran unattended. They name
 744 any volumes that were not successfully backed up, among other problems.
 745 The Backup Server writes to the <B>/usr/afs/logs/BackupLog</B> file on the
 746 local disk of the database server machine, and you can use the <B>bos
 747 getlog</B> command to read it remotely if you wish; for instructions,
 748 see <A HREF="auagd009.htm#HDRWQ173">Displaying Server Process Log Files</A>. The Tape Coordinator writes to two files in the
 749 local <B>/usr/afs/backup</B> directory on the machine where it is
 750 running: the <B>TE_</B><VAR>device_name</VAR> file records errors, and
 751 the <B>TL_</B><VAR>device_name</VAR> file records both trace and error
 752 messages.
 753 <P><LI>Avoid halting a dump operation (for instance, by issuing the <B>(backup)
 754 kill</B> command in interactive mode), both because it introduces the
 755 potential for confusion and because recovering from the interruption requires
 756 extra effort. When a dump operation is interrupted, the volumes that
 757 were backed up before the halt signal is received are complete on the tape or
 758 in the backup data file, and are usable in restore operations. The
 759 records in the Backup Database about the volumes' dump history accurately
 760 show when and at which dump level they were backed up; to display the
 761 records, use the <B>backup volinfo</B> command as described in <A HREF="#HDRWQ304">To display a volume's dump history</A>.
 762 <P>However, there is no indication in the dump's Backup Database record
 763 that volumes were omitted; to display the record, use the <B>backup
 764 dumpinfo</B> command as described in <A HREF="#HDRWQ303">To display dump records</A>. You must choose one of the following methods for
 765 dealing with the volumes that were not backed up before the dump operation
 766 halted. (Actually, you must make the same decision if the dump
 767 operation halts for reasons outside your control.)
 768 <UL>
 769 <P><LI>You can take no action, waiting until the next regularly scheduled dump
 770 operation to back them up. At that time, the Backup System
 771 automatically dumps them at the appropriate level to guarantee that the dump
 772 captures all of the data that changed since the volume was last dumped.
 773 However, you are gambling that restoring the volume is not necessary before
 774 the next dump operation. If restoration is necessary, you can restore
 775 the volume only to its state at the time it was last included in a
 776 dump--you have lost all changes made to the volume since that
 777 time.
 778 <P><LI>You can discard the entire dump and run the dump operation again.
 779 To discard the dump, use the <B>backup labeltape</B> command to relabel
 780 the tapes or backup data file, which automatically removes all associated
 781 records from the Backup Database. For instructions, see <A HREF="auagd011.htm#HDRWQ272">Writing and Reading Tape Labels</A>. If a long time has passed since the backup version
 782 of the volumes was created, some of the source volumes have possibly
 783 changed. If that seems likely, reissue the <B>vos backup</B> or
 784 <B>vos backupsys</B> command on them before redoing the dump
 785 operation.
 786 <P><LI>You can create a new volume set that includes the missed volumes and dump
 787 it at a full dump level (even if you specify an incremental dump level, the
 788 Backup System uses the full dump level at the top of your specified
 789 level's hierarchy, because it has never before backed up these volumes as
 790 part of the new volume set). The next time you dump the original volume
 791 set, the Backup System automatically dumps the missed volumes at the level one
 792 below the level it used the last time it dumped the volumes as part of the
 793 original volume set.
 794 </UL>
 795 </UL>
 796 <P><H3><A NAME="HDRWQ298" HREF="auagd002.htm#ToC_335">How Your Configuration Choices Influence the Dump Process</A></H3>
 797 <A NAME="IDX7024"></A>
 798 <P>This section provides an overview of the backup process, describing what
 799 happens at each stage both by default and as a result of your configuration
 800 choices, including the configuration instructions you include in the
 801 device-specific <B>CFG_</B><VAR>device_name</VAR> file. For the sake
 802 of clarity, it tracks the progress of a single <B>backup dump</B> command
 803 that creates an initial dump. For a discussion of the slight
 804 differences in the procedure when you append or schedule dumps, see <A HREF="#HDRWQ299">Appending Dumps to an Existing Dump Set</A> or <A HREF="#HDRWQ300">Scheduling Dumps</A>.
 805 <P>As a concrete example, the following description traces a dump of the
 806 volume set <B>user</B> at the <B>/weekly/mon/tues/wed</B> dump
 807 level. The <B>user</B> volume set has one volume entry that matches
 808 the backup version of all user volumes:
 809 <PRE>   <B>.*    .*    user.*\.backup</B>
 810 </PRE>
 811 <P>The dump level belongs to the following dump hierarchy.
 812 <PRE>   /weekly
 813           /mon
 814               /tues
 815                    /wed
 816                        /thurs
 817                              /fri
 818 </PRE>
 819 <OL TYPE=1>
 820 <P><LI><A NAME="LIBKOV-BUTC"></A>You issue the <B>butc</B> command to start a Tape
 821 Coordinator to handle the dump operation. The Tape Coordinator does not
 822 have to be running when you issue the <B>backup dump</B> command, but must
 823 be active in time to accept the list of volumes to be included in the dump,
 824 when Step <A HREF="#LIBKOV-VOLMATCHES">3</A> is completed. To avoid coordination problems, it is
 825 best to start the Tape Coordinator before issuing the <B>backup dump</B>
 826 command.
 827 <P>As the Tape Coordinator initializes, it reads the entry in its local
 828 <B>/usr/afs/backup/tapeconfig</B> file for the port offset you specify on
 829 the <B>butc</B> command line. The entry specifies the name of the
 830 device to use, and the Tape Coordinator verifies that it can access it.
 831 It also reads the device's configuration file,
 832 <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR>, if it exists. See
 833 Step <A HREF="#LIBKOV-READCFG">6</A> for a description of how the instructions in the file
 834 influence the dump operation.
 835 <P><LI>You issue the <B>backup dump</B> command, specifying a volume set,
 836 dump level, and the same port offset number you specified on the
 837 <B>butc</B> command in Step <A HREF="#LIBKOV-BUTC">1</A>. The Backup System verifies that they have
 838 correct Backup Database records and halts the operation with an error message
 839 if they do not.
 840 <P>If you issue the command in interactive mode, the Backup System assigns the
 841 operation a job ID number, which you can use to check the operation's
 842 status or halt it by using the <B>(backup) jobs</B> or <B>(backup)
 843 kill</B> command, respectively. For instructions, see <A HREF="#HDRWQ289">To display pending or running jobs in interactive mode</A> and <A HREF="#HDRWQ290">To cancel operations in interactive mode</A>.
 844 <P><LI><A NAME="LIBKOV-VOLMATCHES"></A>The Backup System works with the VL Server to
 845 generate a list of the volumes in the VLDB that match the name and location
 846 criteria defined in the volume set's volume entries. If a volume
 847 matches more than one volume entry, the Backup System ignores the duplicates
 848 so that the dump includes only one copy of data from the volume.
 849 <P>To reduce the number of times you need to switch tapes during a restore
 850 operation, the Backup System sorts the volumes by server machine and
 851 partition, and during the dump operation writes the data from all volumes
 852 stored on a specific partition before moving to the next partition.
 853 <P>As previously mentioned, it is best to back up backup volumes rather than
 854 read/write volumes, to avoid blocking users' access to data during the
 855 dump. To achieve this, you must explicitly include the
 856 <B>.backup</B> suffix on the volume names in volume entry
 857 definitions. For instructions, and to learn how to define volume
 858 entries that match multiple volumes, see <A HREF="auagd011.htm#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>.
 859 <P>In the example, suppose that 50 volumes match the <B>user</B> volume
 860 set criteria, including three called <B>user.pat.backup</B>,
 861 <B>user.terry.backup</B>, and
 862 <B>user.smith.backup</B>.
 863 <P><LI><A NAME="LIBKOV-CLONEDATE"></A>The Backup System next scans the dump hierarchy for
 864 the dump level you have specified on the <B>backup dump</B> command
 865 line. If it is a full level, then in the current operation the Backup
 866 System backs up all of the data in all of the volumes in the list obtained in
 867 Step <A HREF="#LIBKOV-VOLMATCHES">3</A>.
 868 <P>If the dump level is incremental, the Backup System reads each
 869 volume's dump history in the Backup Database to learn which of the parent
 870 levels in its pathname was used when the volume was most recently backed up as
 871 part of this volume set. In the usual case, it is the current dump
 872 level's immediate parent level.
 873 <P>An incremental dump of a volume includes only the data that changed since
 874 the volume was included in the parent dump. To determine which data are
 875 eligible, the Backup System uses the concept of a volume's <I>clone
 876 date</I>. A read/write volume's clone date is when the Backup
 877 System locks the volume before copying its contents into a dump. A
 878 backup volume's clone date is the completion time of the operation that
 879 created it by cloning its read/write source volume (the operation initiated by
 880 a <B>vos backup</B> or <B>vos backupsys</B> command). A
 881 read-only volume's clone date is the time of the release operation
 882 (initiated by the <B>vos release</B> command) that completed most recently
 883 before the dump operation.
 884 <P>More precisely then, an incremental dump includes only data that have a
 885 modification timestamp between the clone date of the volume included in the
 886 parent dump (the <I>parent clone date</I>) and the clone date of the
 887 volume to be included in the current dump (the <I>current clone
 888 date</I>).
 889 <P>There are some common exceptions to the general rule that a volume's
 890 parent dump is the dump created at the immediate parent level:
 891 <UL>
 892 <P><LI>The volume did not exist at all at the time of the last dump. In
 893 this case, the Backup System automatically does a full dump of it.
 894 <P><LI>The volume did not match the volume set's name and location criteria
 895 at the time of the last dump. In this case, the Backup System
 896 automatically does a full dump of it, even if it was backed up recently (fully
 897 or incrementally) as part of another volume set. This redundancy is an
 898 argument for defining volume entries in terms of names rather than locations,
 899 particularly if you move volumes frequently.
 900 <P><LI>The volume was not included in the dump at the immediate parent level for
 901 some reason (perhaps a process, machine, or network access prevented the
 902 Backup System from accessing it). In this case, the Backup System sets
 903 the clone date to the time of the last dump operation that included the
 904 volume. If the volume was not included in a dump performed at any of
 905 the levels in the current level's pathname, the Backup System does a full
 906 dump of it.
 907 </UL>
 908 <P>In the example, the current dump level is
 909 <B>/weekly/mon/tues/wed</B>. The
 910 <B>user.pat.backup</B> and
 911 <B>user.terry.backup</B> volumes were included in the dump
 912 performed yesterday, Tuesday, at the <B>/weekly/mon/tues</B> level.
 913 The Backup System uses as their parent clone date 3:00
 914 a.m. on Tuesday, which is when backup versions of them were
 915 created just before Tuesday's dump operation. However,
 916 Tuesday's dump did not include the
 917 <B>user.smith.backup</B> volume for some reason. The
 918 last time it was included in a dump was Monday, at the <B>/weekly/mon</B>
 919 level. The Backup System uses a parent clone date of Monday at
 920 2:47 a.m., which is when a backup version of the volume
 921 was created just before the dump operation on Monday.
 922 <P><LI>If performing an incremental dump, the Backup System works with the Volume
 923 Server to prepare a list of all of the files in each volume that have changed
 924 (have modification timestamps) between the parent clone date and the current
 925 clone date. The dump includes the complete contents of every such
 926 file. If a file has not changed, the dump includes only a placeholder
 927 stub for it. The dump also includes a copy of the complete directory
 928 structure in the volume, whether or not it has changed since the previous
 929 dump.
 930 <P>If none of the data in the volume has changed since the last dump, the
 931 Backup System omits the volume completely. It generates the following
 932 message in the Tape Coordinator window and log files:
 933 <PRE>   Volume <VAR>volume_name</VAR> (<VAR>volume_ID</VAR>) not dumped - has not been modified
 934       since last dump.
 935 </PRE>
 936 <P><LI><A NAME="LIBKOV-READCFG"></A>The Tape Coordinator prepares to back up the
 937 data. If there is a <B>CFG_</B><VAR>device_name</VAR> file, the Tape
 938 Coordinator already read it in Step <A HREF="#LIBKOV-BUTC">1</A>. The following list describes how the instructions in
 939 the file guide the Tape Coordinator's behavior at this point:
 940 <DL>
 941 <P><DT><B>FILE
 942 </B><DD>If this instruction is set to <B>YES</B>, the Tape Coordinator writes
 943 data to a backup data file. The <VAR>device_name</VAR> field in the
 944 <B>tapeconfig</B> file must also specify a filename for the dump to work
 945 properly. For further discussion and instructions on configuring a
 946 backup data file, see <A HREF="auagd011.htm#HDRWQ282">Dumping Data to a Backup Data File</A>.
 947 <P>If it is set to <B>NO</B> or does not appear in the file, the Tape
 948 Coordinator writes to a tape device.
 949 <P><DT><B>MOUNT and UNMOUNT
 950 </B><DD>If there is a <B>MOUNT</B> instruction in the file, each time the Tape
 951 Coordinator needs a new tape, it invokes the indicated script or program to
 952 mount a tape in the device's tape drive. There must be a
 953 <B>MOUNT</B> instruction if you want to utilize a tape stacker or
 954 jukebox's ability to switch between tapes automatically. If there
 955 is no <B>MOUNT</B> instruction, the Tape Coordinator prompts the human
 956 operator whenever it needs a tape.
 957 <P>The <B>AUTOQUERY</B> instruction, which is described just following,
 958 modifies the Tape Coordinator's tape acquisition procedure for the first
 959 tape it needs in a dump operation.
 960 <P>If there is an <B>UNMOUNT</B> instruction, then the Tape Coordinator
 961 invokes the indicated script or program whenever it closes the tape
 962 device. Not all tape devices have a separate tape unmounting routine,
 963 in which case the <B>UNMOUNT</B> instruction is not necessary. For
 964 more details on both instructions, see <A HREF="auagd011.htm#HDRWQ277">Invoking a Device's Tape Mounting and Unmounting Routines</A>.
 965 <P><DT><B>AUTOQUERY
 966 </B><DD>If this instruction is set to <B>NO</B>, the Tape Coordinator assumes
 967 that the first tape needed for the dump operation is already in the tape
 968 drive. It does not use its usual tape acquisition procedure as
 969 described in the preceding discussion of the <B>MOUNT</B>
 970 instruction. You can achieve the same effect by including the
 971 <B>-noautoquery</B> flag to the <B>butc</B> command.
 972 <P>If this instruction is absent or set to <B>YES</B>, the Tape
 973 Coordinator uses its usual tape acquisition procedure even for the first
 974 tape. For more details, see <A HREF="auagd011.htm#HDRWQ278">Eliminating the Search or Prompt for the Initial Tape</A>.
 975 <P><DT><B>BUFFERSIZE
 976 </B><DD>If this instruction appears in the file, the Tape Coordinator sets its
 977 buffer size to the specified value rather than using the default buffer size
 978 of 16 KB. For further discussion, see <A HREF="auagd011.htm#HDRWQ281">Setting the Memory Buffer Size to Promote Tape Streaming</A>.
 979 </DL>
 980 <P>If there is no <B>CFG_</B><VAR>device_name</VAR> file, the Tape
 981 Coordinator writes data to a tape device and prompts the human operator each
 982 time it needs a tape (the only exception being the first tape if you include
 983 the <B>-noautoquery</B> flag to the <B>butc</B> command).
 984 <P><LI><A NAME="LIBKOV-NAMECHECK"></A>The Tape Coordinator opens either a tape drive or
 985 backup data file at this point, as directed by the instructions in the
 986 <B>CFG_</B><VAR>device_name</VAR> file (described in Step <A HREF="#LIBKOV-READCFG">6</A>). The instructions also determine whether it
 987 invokes a mount script or prompts the operator. In Step <A HREF="#LIBKOV-BUTC">1</A> the Tape Coordinator read in the device's capacity and
 988 filemark size from the <B>tapeconfig</B> file. It now reads the
 989 same values from the tape or backup data file's magnetic label, and
 990 overwrites the <B>tapeconfig</B> values if there is a difference.
 991 <P>If creating an initial dump (as in the current example) and there is no
 992 permanent name on the label, the Tape Coordinator next checks that the AFS
 993 tape name has one of the three acceptable formats. If not, it rejects
 994 the tape and you must use the <B>backup labeltape</B> command to write an
 995 acceptable name. You can bypass this name-checking step by including
 996 the <B>NAME_CHECK NO</B> instruction in the
 997 <B>CFG_</B><VAR>device_name</VAR> file. For discussion and a list of
 998 the acceptable AFS tape name values, see <A HREF="auagd011.htm#HDRWQ280">Eliminating the AFS Tape Name Check</A>.
 999 <P><LI><A NAME="LIBKOV-EXPDATE"></A>For an initial dump, the Tape Coordinator starts writing
1000 at the beginning of the tape or backup dump file, overwriting any existing
1001 data. To prevent inappropriate overwriting, the Backup System first
1002 checks the Backup Database for any dump records associated with the name
1003 (permanent or AFS tape name) on the tape or backup dump file's
1004 label. It refuses to write to a backup data file that has unexpired
1005 dumps in it, or to a tape that belongs to a dump set with any unexpired
1006 dumps. To recycle a file or tape before all dumps have expired, you
1007 must use the <B>backup labeltape</B> command to relabel it. Doing
1008 so removes the Backup Database records of all dumps in the file or on all
1009 tapes in the dump set, which makes it impossible to restore data from any of
1010 the tapes. For more information on expiration dates, see <A HREF="auagd011.htm#HDRWQ270">Defining Expiration Dates</A>.
1011 <P>The Tape Coordinator also checks for two other types of inappropriate tape
1012 reuse. The tape cannot already have data on it that belongs to the dump
1013 currently being performed, because that implies that the previous tape is
1014 still in the drive, or you have mistakenly reinserted it. The Tape
1015 Coordinator generates the following message and attempts to obtain another
1016 tape:
1017 <PRE>   Can't overwrite tape containing the dump in progress
1018 </PRE>
1019 <P>The tape cannot contain data from a parent dump of the current
1020 (incremental) dump, because overwriting a parent dump makes it impossible to
1021 restore data from the current dump. The Tape Coordinator generates the
1022 following message and attempts to obtain another tape:
1023 <PRE>   Can't overwrite the parent dump <VAR>parent_name</VAR> (<VAR>parent_dump_ID</VAR>)
1024 </PRE>
1025 <P><LI><A NAME="LIBKOV-WRITE"></A>The Tape Coordinator now writes data to the tape or backup
1026 data file. It uses the capacity and filemark size it obtained in Step <A HREF="#LIBKOV-NAMECHECK">7</A> as it tracks how much more space is available, automatically
1027 using its tape acquisition procedure if the dump is not finished when it
1028 reaches the end of the tape. For a more detailed description, and a
1029 discussion of what happens if the Tape Coordinator reaches the physical
1030 end-of-tape unexpectedly, see <A HREF="auagd011.htm#HDRWQ258">Configuring the tapeconfig File</A>. Similarly, for instructions on configuring a backup
1031 data file to optimize recovery from unexpectedly running out of space, see
1032 Step <A HREF="auagd011.htm#LITAPECONFIG-FILE">6</A> in the instructions in <A HREF="auagd011.htm#HDRWQ282">Dumping Data to a Backup Data File</A>.
1033 <P>If the Tape Coordinator cannot access a volume during the dump (perhaps
1034 because of a server process, machine, or network outage), it skips the volume
1035 and continues dumping all volumes that it can access. It generates an
1036 error message in the Tape Coordinator window and log file about the omitted
1037 volume. It generates a similar message if it discovers that a backup
1038 volume has not been recloned since the previous dump operation (that is, that
1039 the volume's current clone date is the same as its parent clone
1040 date):
1041 <PRE>   Volume <VAR>volume_name</VAR> (<VAR>volume_ID</VAR>) not dumped - has not been re-cloned
1042        since last dump.
1043 </PRE>
1044 <P>After completing a first pass through all of the volumes, it attempts to
1045 dump each omitted volume again. It first checks to see if the reason
1046 that the volume was inaccessible during the first pass is that it has been
1047 moved since the VL Server generated the list of volumes to dump in Step <A HREF="#LIBKOV-VOLMATCHES">3</A>. If so, it dumps the volume from its new site.
1048 If the second attempt to access a volume also fails, the Tape Coordinator it
1049 generates the following message, prompting you for instruction on how to
1050 proceed:
1051 <PRE>   Dump of volume <VAR>volume_name</VAR> (<VAR>volume_ID</VAR>) failed
1052    Please select action to be taken for this volume.
1053       r - retry, try dumping this volume again
1054       o - omit, this volume from this dump
1055       a - abort, the entire dump
1056 </PRE>
1057 <P>To increase the automation of the dump process, you can include the
1058 <B>ASK NO</B> instruction in the <B>CFG_</B><VAR>device_name</VAR> file
1059 to suppress this prompt and have the Tape Coordinator automatically omit the
1060 volume from the dump.
1061 <P>If you are tracking the dump as it happens, the prompt enables you to take
1062 corrective action. If the volume has not been recloned, you can issue
1063 the <B>vos backup</B> command. If the volume is inaccessible, you
1064 can investigate and attempt to resolve the cause.
1065 <A NAME="IDX7025"></A>
1066 <A NAME="IDX7026"></A>
1067 <A NAME="IDX7027"></A>
1068 <A NAME="IDX7028"></A>
1069 <A NAME="IDX7029"></A>
1070 <P><LI>If the tape or backup data file does not already have an AFS tape name,
1071 the Backup System constructs the appropriate one and records it on the label
1072 and in the Backup Database. It also assigns a dump name and ID number
1073 to the dump and records them in dump record that it creates in the Backup
1074 Database. For details on tape and dump names, see <A HREF="auagd011.htm#HDRWQ253">Dump Names and Tape Names</A>. For instructions on displaying dump records or a
1075 volume's dump history, or scanning the contents of a tape, see <A HREF="#HDRWQ302">Displaying Backup Dump Records</A>.
1076 </OL>
1077 <P><H3><A NAME="HDRWQ299" HREF="auagd002.htm#ToC_336">Appending Dumps to an Existing Dump Set</A></H3>
1078 <A NAME="IDX7030"></A>
1079 <P>The AFS Backup System enables you to append dumps to the end of the final
1080 tape in a dump set by including the <B>-append</B> flag to the <B>backup
1081 dump</B> command. Appending dumps improves Backup System automation
1082 and efficiency in several ways:
1083 <UL>
1084 <P><LI>It maximizes use of a tape's capacity. An initial dump must
1085 always start on a new tape, but does not necessarily extend to the end of the
1086 final tape in the dump set. You can fill up the unused tape by
1087 appending one or more dumps.
1088 <P><LI>It can reduce the number of tapes and tape changes needed to complete a
1089 dump operation. Rather than performing a series of initial dumps first,
1090 instead begin with an initial dump and follow it immediately with several
1091 appended dumps. In this way you can write all dumps in the series to
1092 the same tape (assuming the tape is large enough to accommodate them
1093 all). If, in contrast, you perform all of the initial dumps first, each
1094 must begin on a new tape and you must switch tapes again if you then want to
1095 append dumps.
1096 <P>You can either issue the appropriate series of <B>backup dump</B>
1097 commands at the interactive <TT>backup></TT> prompt, or record them in a
1098 file that you then name with the <B>-file</B> argument to the <B>backup
1099 dump</B> command. Appending dumps in this way enables you to run
1100 multiple unattended backup operations even without a tape stacker or jukebox,
1101 if all of the dumps fit on one tape.
1102 <P><LI>It can reduce the number of tape changes during a restore
1103 operation. For example, if you append all of the incremental dumps of a
1104 volume set to tapes in one dump set, then restoring a volume from the volume
1105 set requires a minimum number of tape changes. It is best not to append
1106 incremental dumps to a tape that contains the parent full dump, however:
1107 if the tape is lost or damaged, you lose all of the data from the
1108 volume.
1109 <P>Although it can be efficient to group together appended dumps that are
1110 related, the Backup System does not require any relationship between the
1111 appended dumps on a tape or in a dump set.
1112 </UL>
1113 <P>When writing an appended dump, the Backup System performs most of the steps
1114 described in <A HREF="#HDRWQ298">How Your Configuration Choices Influence the Dump Process</A>. Appended dumps do not have to be related to one
1115 another or the initial dump, so it skips Step <A HREF="#LIBKOV-NAMECHECK">7</A>: there is no need to check that the AFS tape name
1116 reflects the volume set and dump level names in this case. It also
1117 skips Step <A HREF="#LIBKOV-EXPDATE">8</A>. Because it is not overwriting any existing data on
1118 the tape, it does not need to check the expiration dates of existing dumps on
1119 the tape or in the file. Then in Step <A HREF="#LIBKOV-WRITE">9</A> the Tape Coordinator scans to the end of the last dump on
1120 the tape or in the backup data file before it begins writing data.
1121 <P>The Backup System imposes the following conditions on appended dumps:
1122 <UL>
1123 <P><LI>If writing to tape, the Tape Coordinator checks that it is the final one
1124 in a dump set for which there are complete and valid tape and dump records in
1125 the Backup Database. If not, it rejects the tape and requests an
1126 acceptable one. If you believe the tape has valid data on it, you can
1127 reconstruct the Backup Database dump records for it by using the
1128 <B>-dbadd</B> argument to the <B>backup scantape</B> command as
1129 instructed in <A HREF="#HDRWQ305">To scan the contents of a tape</A>.
1130 <P><LI>The most recent dump on the tape or in the backup data file must have
1131 completed successfully.
1132 <P><LI>The dump set to which the tape or file belongs must begin with an initial
1133 dump that is recorded in the Backup Database. If there are no dumps on
1134 the current tape, then the Backup System treats the dump operation as an
1135 initial dump and imposes the relevant requirements (for example, checks the
1136 AFS tape name if appropriate).
1137 </UL>
1138 <P>As you append dumps, keep in mind that all of a dump set's dump and
1139 tape records in the Backup Database are indexed to the initial dump. If
1140 you want to delete an appended dump's record, you must delete the initial
1141 dump record, and doing so erases the records of all dumps in the dump
1142 set. Without those records, you cannot restore any of the data in the
1143 dump set.
1144 <P>Similarly, all of the dumps in a dump set must expire before you can
1145 recycle (write a new initial dump to) any of the tapes in a dump set.
1146 Do not append a dump if its expiration date is later than the date on which
1147 you want to recycle any of the tapes in its dump set. To recycle a tape
1148 before the last expiration date, you must delete the initial dump's
1149 record from the Backup Database. Either use the <B>backup
1150 labeltape</B> command to relabel the tape as instructed in <A HREF="auagd011.htm#HDRWQ273">To label a tape</A>, or use the <B>backup deletedump</B> command
1151 to delete the record directly as instructed in <A HREF="#HDRWQ322">To delete dump records from the Backup Database</A>.
1152 <P>Although in theory you can append as many dumps as you wish, it generally
1153 makes sense to limit the number of tapes in a dump set (for example, to five),
1154 for these reasons:
1155 <UL>
1156 <P><LI>If an unreadable spot develops on one of the tapes in a dump set, it can
1157 prevent the Tape Coordinator from scanning the tape as part of a <B>backup
1158 scantape</B> operation you use to reconstruct Backup Database
1159 records. The Tape Coordinator can almost always scan the tape
1160 successfully up to the point of damage and can usually skip past minor
1161 damage. A scanning operation can start on any tape in a dump set, so
1162 damage on one tape does not prevent scanning of the others in the dump
1163 set. However, you can scan only the tapes that precede the damaged one
1164 in the dump set or the ones that follow the damaged one, but not both.
1165 (For more information on using tapes to reconstruct the information in the
1166 Backup Database, see <A HREF="#HDRWQ305">To scan the contents of a tape</A>.)
1167 <P>An unreadable bad spot can also prevent you from restoring a volume
1168 completely, because restore operations must begin with the full dump and
1169 continue with each incremental dump in order. If you cannot restore a
1170 specific dump, you cannot restore any data from later incremental
1171 dumps.
1172 <P><LI>If you decide in the future to archive one or more dumps, then you must
1173 archive the entire set of tapes that constitute the dump set, rather than just
1174 the ones that contain the data of interest. This wastes both tape and
1175 archive storage space. For more information on archiving, see <A HREF="auagd011.htm#HDRWQ269">Archiving Tapes</A>.
1176 </UL>
1177 <P><H3><A NAME="HDRWQ300" HREF="auagd002.htm#ToC_337">Scheduling Dumps</A></H3>
1178 <P>By default, the Backup System starts executing a dump
1179 operation as soon as you enter the <B>backup dump</B> command, and the
1180 Tape Coordinator begins writing data as soon as it is not busy and the list of
1181 files to write is available. You can, however, schedule a dump
1182 operation to begin at a specific later time:
1183 <UL>
1184 <P><LI>To schedule a single dump operation, include the <B>-at</B> argument
1185 to specify its start time.
1186 <P><LI>To schedule multiple dump operations, list the operations in a file named
1187 by the <B>-file</B> argument and use the <B>-at</B> argument to
1188 specify when the <B>backup</B> command interpreter reads the file.
1189 If you omit the <B>-at</B> argument, the command interpreter reads the
1190 file immediately, which does not count as scheduling, but does allow you to
1191 initiate multiple dump operations in a single command. Do not combine
1192 the <B>-file</B> argument with the <B>-volumeset</B>,
1193 <B>-dump</B>, <B>-portoffset</B>, <B>-append</B>, or <B>-n</B>
1194 options.
1195 <P>For file-formatting instructions, see the description of the
1196 <B>-file</B> argument in Step <A HREF="#LIBKDUMP-SYNTAX">7</A> of <A HREF="#HDRWQ301">To create a dump</A>.
1197 </UL>
1198 <P>The Backup System performs initial and appended dumps in the same manner
1199 whether they are scheduled or begin running as soon as you issue the
1200 <B>backup dump</B> command. The only difference is that the
1201 requirements for successful execution hold both at the time you issue the
1202 command and when the Backup System actually begins running it. All
1203 required Backup Database entries for volume sets, dump levels, and port
1204 offsets, and all dump and tape records must exist at both times.
1205 Perhaps more importantly, the required administrative tokens must be available
1206 at both times. See <A HREF="#HDRWQ297">Making Backup Operations More Efficient</A>.
1207 <P><H3><A NAME="HDRWQ301" HREF="auagd002.htm#ToC_338">To create a dump</A></H3>
1208 <OL TYPE=1>
1209 <P><LI>Verify that you are authenticated as a user listed in the
1210 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1211 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1212 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1213 </PRE>
1214 <P><LI>If the Tape Coordinator for the tape device that is to perform the
1215 operation is not already running, open a connection to the appropriate Tape
1216 Coordinator machine and issue the <B>butc</B> command, for which complete
1217 instructions appear in <A HREF="#HDRWQ292">To start a Tape Coordinator process</A>.
1218 <PRE>   % <B>butc</B> [&lt;<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
1219 </PRE>
1220 <P><LI>If using a tape device, insert the tape.
1221 <P><LI>Issue the <B>backup</B> command to enter interactive mode.
1222 <PRE>   % <B>backup</B>
1223 </PRE>
1224 <P><LI>Decide which volume set and dump level to use. If necessary, issue
1225 the <B>backup listvolsets</B> and <B>backup listdumps</B> commands to
1226 display the existing volume sets and dump levels. For complete
1227 instructions and a description of the output, see <A HREF="auagd011.htm#HDRWQ266">To display volume sets and volume entries</A> and <A HREF="auagd011.htm#HDRWQ271">To display the dump hierarchy</A>.
1228 <PRE>   backup> <B>listvolsets</B>  [&lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>]
1229    backup> <B>listdumps</B>
1230 </PRE>
1231 <P>If you want to use a temporary volume set, you must create it during the
1232 current interactive session. This can be useful if you are dumping a
1233 volume to tape in preparation for removing it permanently (perhaps because its
1234 owner is leaving the cell). In this case, you can define a volume entry
1235 that includes only the volume of interest without cluttering up the Backup
1236 Database with a volume set record that you are using only once.
1237 Complete instructions appear in <A HREF="auagd011.htm#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>.
1238 <PRE>   backup>  <B>addvolset</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>> <B>-temporary</B>
1239    backup> <B>addvolentry  -name</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>  \
1240                         <B>-server</B> &lt;<VAR>machine&nbsp;name</VAR>>  \
1241                         <B>-partition</B> &lt;<VAR>partition&nbsp;name</VAR>>  \
1242                         <B>-volumes</B> &lt;<VAR>volume&nbsp;name&nbsp;(regular&nbsp;expression)</VAR>>
1243 </PRE>
1244 <P><LI>If you are creating an initial dump and writing to a tape or backup data
1245 file that does not have a permanent name, its AFS tape name must satisfy the
1246 Backup System's format requirements as described in <A HREF="auagd011.htm#HDRWQ280">Eliminating the AFS Tape Name Check</A>. If necessary, use the <B>backup readlabel</B>
1247 command to display the label and the <B>backup labeltape</B> command to
1248 change the names, as instructed in <A HREF="auagd011.htm#HDRWQ272">Writing and Reading Tape Labels</A>. You must also relabel a tape if you want to
1249 overwrite it and it is part of a dump set that includes any unexpired dumps,
1250 though this is not recommended. For a discussion of the appropriate way
1251 to recycle tapes, see <A HREF="auagd011.htm#HDRWQ268">Creating a Tape Recycling Schedule</A>.
1252 <A NAME="IDX7031"></A>
1253 <A NAME="IDX7032"></A>
1254 <P><LI><A NAME="LIBKDUMP-SYNTAX"></A>Issue the <B>backup dump</B> command to dump the
1255 volume set.
1256 <UL>
1257 <P><LI>To create one initial dump, provide only the volume set name, dump level
1258 name, and port offset (if not zero).
1259 <P><LI>To create one appended dump, add the <B>-append</B> flag.
1260 <P><LI>To schedule a single initial or appended dump, add the <B>-at</B>
1261 argument.
1262 <P><LI>To initiate multiple dump operations, record the appropriate commands in a
1263 file and name it with the <B>-file</B> argument. Do not combine
1264 this argument with options other than the <B>-at</B> argument.
1265 </UL>
1266 <PRE>   backup> <B>dump</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>> &lt;<VAR>dump&nbsp;level&nbsp;name</VAR>> [&lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]   \
1267                 [<B>-at</B> &lt;<VAR>Date/time&nbsp;to&nbsp;start&nbsp;dump</VAR>><SUP>+</SUP>]  \
1268                 [<B>-append</B>]  [<B>-n</B>] [<B>-file</B> &lt;<VAR>load file</VAR>>]
1269 </PRE>
1270 <P>where
1271 <DL>
1272 <P><DT><B>dump
1273 </B><DD>Must be typed in full.
1274 <P><DT><B><VAR>volume set name</VAR>
1275 </B><DD>Names the volume set to dump.
1276 <P><DT><B><VAR>dump level name</VAR>
1277 </B><DD>Specifies the complete pathname of the dump level at which to dump the
1278 volume set.
1279 <P><DT><B><VAR>TC port offset</VAR>
1280 </B><DD>Specifies the port offset number of the Tape Coordinator process that is
1281 handling the operation. You must provide this argument unless the
1282 default value of 0 (zero) is appropriate.
1283 <P><DT><B>-at
1284 </B><DD>Specifies the date and time in the future at which to run the command, or
1285 to read the file named by the <B>-file</B> argument. Provide a
1286 value in the format <VAR>mm</VAR>/<VAR>dd</VAR>/<VAR>yyyy</VAR>
1287 [<VAR>hh</VAR>:<VAR>MM</VAR>], where the month (<VAR>mm</VAR>), day
1288 (<VAR>dd</VAR>), and year (<VAR>yyyy</VAR>) are required. Valid values for
1289 the year range from <B>1970</B> to <B>2037</B>; higher values are
1290 not valid because the latest possible date in the standard UNIX representation
1291 is in February 2038. The Backup System automatically reduces any later
1292 date to the maximum value in 2038.
1293 <P>The hour and minutes (<VAR>hh</VAR>:<VAR>MM</VAR>) are optional, but if
1294 provided must be in 24-hour format (for example, the value
1295 <B>14:36</B> represents 2:36 p.m.). If
1296 you omit them, the time defaults to midnight (00:00 hours).
1297 <P>As an example, the value <B>04/23/1999 20:20</B> schedules the
1298 command for 8:20 p.m. on 23 April 1999.
1299 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A plus sign follows this argument in the command's syntax statement
1300 because it accepts a multiword value which does not need to be enclosed in
1301 double quotes or other delimiters, not because it accepts multiple
1302 dates. Provide only one date (and optionally, time) definition.
1303 </TD></TR></TABLE>
1304 <P><DT><B>-append
1305 </B><DD>Creates an appended dump by scanning to the end of the data from one or
1306 more previous dump operations that it finds on the tape or in the backup data
1307 file.
1308 <P><DT><B>-n
1309 </B><DD>Displays the names of all volumes to be included in the indicated dump,
1310 without actually writing data to tape or the backup data file. Combine
1311 this flag with the arguments you plan to use on the actual command, but not
1312 with the <B>-file</B> argument.
1313 <P><DT><B>-file
1314 </B><DD>Specifies the local disk or AFS pathname of a file containing
1315 <B>backup</B> commands. The Backup System reads the file
1316 immediately, or at the time specified by the <B>-at</B> argument if it is
1317 provided. A partial pathname is interpreted relative to the current
1318 working directory.
1319 <P>Place each <B>backup dump</B> command on its own line in the indicated
1320 file, using the same syntax as for the command line, but without the word
1321 <B>backup</B> at the start of the line. Each command must include
1322 the <VAR>volume set name</VAR> and <VAR>dump level name</VAR> arguments plus the
1323 <VAR>TC port offset</VAR> argument if the default value of zero is not
1324 appropriate. Commands in the file can also include any of the
1325 <B>backup dump</B> command's optional arguments, including the
1326 <B>-at</B> argument (which must specify a date and time later than the
1327 date and time at which the Backup System reads the file).
1328 </DL>
1329 <P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
1330 the <B>butc</B> command, or if the device's
1331 <B>CFG_</B><VAR>device_name</VAR> configuration file includes the
1332 instruction <B>AUTOQUERY YES</B>, then the Tape Coordinator prompts you to
1333 place the tape in the device's drive. You have already done so,
1334 but you must now press &lt;<B>Return</B>> to indicate that the tape is
1335 ready for labeling.
1336 <P>If more than one tape is required, you must either include the
1337 <B>MOUNT</B> instruction in the <B>CFG_</B><VAR>device_name</VAR> file
1338 and stock the corresponding stacker or jukebox with tapes, or remain at the
1339 console to respond to the Tape Coordinator's prompts for subsequent
1340 tapes.
1341 <P><LI>After the dump operation completes, review the Backup System's log
1342 files to check for errors. Use the <B>bos getlog</B> command as
1343 instructed in <A HREF="auagd009.htm#HDRWQ173">Displaying Server Process Log Files</A> to read the <B>/usr/afs/logs/BackupLog</B> file, and a
1344 text editor on the Tape Coordinator machine to read the
1345 <B>TE_</B><VAR>device_name</VAR> and <B>TL_</B><VAR>device_name</VAR>
1346 files in the local <B>/usr/afs/backup</B> directory.
1347 <P>It is also a good idea to record the tape name and dump ID number on the
1348 exterior label of each tape.
1349 </OL>
1350 <HR><H2><A NAME="HDRWQ302" HREF="auagd002.htm#ToC_339">Displaying Backup Dump Records</A></H2>
1351 <P>The <B>backup</B> command suite includes three commands
1352 for displaying information about data you have backed up:
1353 <UL>
1354 <P><LI>To display information about one or more dump operations, such as the date
1355 it was performed and the number of volumes included, use the <B>backup
1356 dumpinfo</B> command as described in <A HREF="#HDRWQ303">To display dump records</A>. You can display a detailed record of a single dump
1357 or more condensed records for a certain number of dumps, starting with the
1358 most recent and going back in time. You can specify the number of dumps
1359 or accept the default of 10.
1360 <P><LI>To display a volume's dump history, use the <B>backup volinfo</B>
1361 command as described in <A HREF="#HDRWQ304">To display a volume's dump history</A>.
1362 <P><LI>To display information extracted from a tape or backup data file about the
1363 volumes it includes, use the <B>backup scantape</B> command. To
1364 create new dump and tape records in the Backup Database derived from the tape
1365 and dump labels, add the <B>-dbadd</B> flag. For instructions, see <A HREF="#HDRWQ305">To scan the contents of a tape</A>.
1366 </UL>
1367 <A NAME="IDX7033"></A>
1368 <A NAME="IDX7034"></A>
1369 <A NAME="IDX7035"></A>
1370 <A NAME="IDX7036"></A>
1371 <A NAME="IDX7037"></A>
1372 <A NAME="IDX7038"></A>
1373 <A NAME="IDX7039"></A>
1374 <P><H3><A NAME="HDRWQ303" HREF="auagd002.htm#ToC_340">To display dump records</A></H3>
1375 <OL TYPE=1>
1376 <P><LI>Verify that you are authenticated as a user listed in the
1377 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1378 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1379 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1380 </PRE>
1381 <P><LI>Issue the <B>backup dumpinfo</B> command to list information about
1382 dumps recorded in the Backup Database.
1383 <PRE>   % <B>backup dumpinfo</B> [<B>-ndumps</B> &lt;<VAR>no.&nbsp;of&nbsp;dumps</VAR>>]  [<B>-id</B> &lt;<VAR>dump&nbsp;id</VAR>>]  [<B>-verbose</B>]
1384 </PRE>
1385 <P>where
1386 <DL>
1387 <P><DT><B>dump
1388 </B><DD>Is the shortest acceptable abbreviation of <B>dumpinfo</B>.
1389 <P><DT><B>-ndumps
1390 </B><DD>Displays the Backup Database record for each of the specified number of
1391 dumps, starting with the most recent and going back in time. If the
1392 database contains fewer dumps than are requested, the output includes the
1393 records for all existing dumps. Do not combine this argument with the
1394 <B>-id</B> argument or <B>-verbose</B> flag; omit all three
1395 options to display the records for the last 10 dumps.
1396 <P><DT><B>-id
1397 </B><DD>Specifies the dump ID number of a single dump for which to display the
1398 Backup Database record. You must include the <B>-id</B>
1399 switch. Do not combine this option with the <B>-ndumps</B> or
1400 <B>-verbose</B> arguments; omit all three arguments to display the
1401 records for the last 10 dumps.
1402 <P><DT><B>-verbose
1403 </B><DD>Provides more detailed information about the dump specified with the
1404 <B>-id</B> argument, which must be provided along with it. Do not
1405 combine this flag with the <B>-ndumps</B> option.
1406 </DL>
1407 </OL>
1408 <P>If the <B>-ndumps</B> argument is provided, the output presents the
1409 following information in table form, with a separate line for each dump:
1410 <DL>
1411 <P><DT><B><TT>dumpid</TT>
1412 </B><DD>The dump ID number.
1413 <P><DT><B><TT>parentid</TT>
1414 </B><DD>The dump ID number of the dump's parent dump. A value of
1415 <TT>0</TT> (zero) identifies a full dump.
1416 <P><DT><B><TT>lv</TT>
1417 </B><DD>The depth in the dump hierarchy of the dump level used to create the
1418 dump. A value of <TT>0</TT> (zero) identifies a full dump, in which
1419 case the value in the <TT>parentid</TT> field is also <TT>0</TT>. A
1420 value of <TT>1</TT> or greater indicates an incremental dump made at the
1421 corresponding level in the dump hierarchy.
1422 <P><DT><B><TT>created</TT>
1423 </B><DD>The date and time at which the Backup System started the dump operation
1424 that created the dump.
1425 <P><DT><B><TT>nt</TT>
1426 </B><DD>The number of tapes that contain the data in the dump. A value of
1427 <TT>0</TT> (zero) indicates that the dump operation was terminated or
1428 failed. Use the <B>backup deletedump</B> command to remove such
1429 entries.
1430 <P><DT><B><TT>nvols</TT>
1431 </B><DD>The number of volumes from which the dump includes data. If a
1432 volume spans tapes, it is counted twice. A value of <TT>0</TT> (zero)
1433 indicates that the dump operation was terminated or failed; the value in
1434 the <TT>nt</TT> field is also <TT>0</TT> in this case.
1435 <P><DT><B><TT>dump name</TT>
1436 </B><DD>The dump name in the form
1437 <PRE>   <VAR>volume_set_name</VAR>.<VAR>dump_level_name</VAR> (<VAR>initial_dump_ID</VAR>)
1438
1439 </PRE>
1440 <P>
1441 <P>where <VAR>volume_set_name</VAR> is the name of the volume set, and
1442 <VAR>dump_level_name</VAR> is the last element in the dump level pathname at
1443 which the volume set was dumped.
1444 <P>The <VAR>initial_dump_ID</VAR>, if displayed, is the dump ID of the initial
1445 dump in the dump set to which this dump belongs. If there is no value
1446 in parentheses, the dump is the initial dump in a dump set that has no
1447 appended dumps.
1448 </DL>
1449 <P>If the <B>-id</B> argument is provided alone, the first line of output
1450 begins with the string <TT>Dump</TT> and reports information for the entire
1451 dump in the following fields:
1452 <DL>
1453 <P><DT><B><TT>id</TT>
1454 </B><DD>The dump ID number.
1455 <P><DT><B><TT>level</TT>
1456 </B><DD>The depth in the dump hierarchy of the dump level used to create the
1457 dump. A value of <TT>0</TT> (zero) identifies a full dump. A
1458 value of <TT>1</TT> (one) or greater indicates an incremental dump made at
1459 the specified level in the dump hierarchy.
1460 <P><DT><B><TT>volumes</TT>
1461 </B><DD>The number of volumes for which the dump includes data.
1462 <P><DT><B><TT>created</TT>
1463 </B><DD>The date and time at which the dump operation began.
1464 </DL>
1465 <P>If an XBSA server was the backup medium for the dump (rather than a tape
1466 device or backup data file), the following line appears next:
1467 <PRE>   Backup Service: <VAR>XBSA_program</VAR>: Server: <VAR>hostname</VAR>
1468 </PRE>
1469 <P>where <VAR>XBSA_program</VAR> is the name of the XBSA-compliant program and
1470 <VAR>hostname</VAR> is the name of the machine on which the program runs.
1471 <P>Next the output includes an entry for each tape that houses volume data
1472 from the dump. Following the string <TT>Tape</TT>, the first two
1473 lines of each entry report information about that tape in the following
1474 fields:
1475 <DL>
1476 <P><DT><B><TT>name</TT>
1477 </B><DD>The tape's permanent name if it has one, or its AFS tape name
1478 otherwise, and its tape ID number in parentheses.
1479 <P><DT><B><TT>nVolumes</TT>
1480 </B><DD>The number of volumes for which this tape includes dump data.
1481 <P><DT><B><TT>created</TT>
1482 </B><DD>The date and time at which the Tape Coordinator began writing data to this
1483 tape.
1484 </DL>
1485 <P>Following another blank line, the tape-specific information concludes with
1486 a table that includes a line for each volume dump on the tape. The
1487 information appears in columns with the following headings:
1488 <DL>
1489 <P><DT><B><TT>Pos</TT>
1490 </B><DD>The relative position of each volume in this tape or file. On a
1491 tape, the counter begins at position 2 (the tape label occupies position 1),
1492 and increments by one for each volume. For volumes in a backup data
1493 file, the position numbers start with 1 and do not usually increment only by
1494 one, because each is the ordinal of the 16 KB offset in the file at which the
1495 volume's data begins. The difference between the position numbers
1496 therefore indicates how many 16 KB blocks each volume's data
1497 occupies. For example, if the second volume is at position 5 and the
1498 third volume in the list is at position 9, that means that the dump of the
1499 second volume occupies 64 KB (four 16-KB blocks) of space in the file.
1500 <P><DT><B><TT>Clone time</TT>
1501 </B><DD>For a backup or read-only volume, the time at which it was cloned from its
1502 read/write source. For a Read/Write volume, it is the same as the dump
1503 creation date reported on the first line of the output.
1504 <P><DT><B><TT>Nbytes</TT>
1505 </B><DD>The number of bytes of data in the dump of the volume.
1506 <P><DT><B><TT>Volume</TT>
1507 </B><DD>The volume name, complete with <TT>.backup</TT> or
1508 <TT>.readonly</TT> extension if appropriate.
1509 </DL>
1510 <P>If both the <B>-id</B> and <B>-verbose</B> options are provided,
1511 the output is divided into several sections:
1512 <UL>
1513 <P><LI>The first section, headed by the underlined string <TT>Dump</TT>,
1514 includes information about the entire dump. The fields labeled
1515 <TT>id</TT>, <TT>level</TT>, <TT>created</TT>, and <TT>nVolumes</TT>
1516 report the same values (though in a different order) as appear on the first
1517 line of output when the <B>-id</B> argument is provided by itself.
1518 Other fields of potential interest to the backup operator are:
1519 <DL>
1520 <P><DT><B><TT>Group id</TT>
1521 </B><DD>The dump's <I>group ID number</I>, which is recorded in the
1522 dump's Backup Database record if the <B>GROUPID</B> instruction
1523 appears in the Tape Coordinator's <B>
1524 /usr/afs/backup/CFG_</B><VAR>tcid</VAR> file when the dump is created.
1525 <P><DT><B><TT>maxTapes</TT>
1526 </B><DD>The number of tapes that contain the dump set to which this dump
1527 belongs.
1528 <P><DT><B><TT>Start Tape Seq</TT>
1529 </B><DD>The ordinal of the tape on which this dump begins in the set of tapes that
1530 contain the dump set.
1531 </DL>
1532 <P><LI>For each tape that contains data from this dump, there follows a section
1533 headed by the underlined string <TT>Tape</TT>. The fields labeled
1534 <TT>name</TT>, <TT>written</TT>, and <TT>nVolumes</TT> report the same
1535 values (though in a different order) as appear on the second and third lines
1536 of output when the <B>-id</B> argument is provided by itself. Other
1537 fields of potential interest to the backup operator are:
1538 <DL>
1539 <P><DT><B><TT>expires</TT>
1540 </B><DD>The date and time when this tape can be recycled, because all dumps it
1541 contains have expired.
1542 <P><DT><B><TT>nMBytes Data</TT> and <TT>nBytes Data</TT>
1543 </B><DD>Summed together, these fields represent the total amount of dumped data
1544 actually from volumes (as opposed to labels, filemarks, and other
1545 markers).
1546 <P><DT><B><TT>KBytes Tape Used</TT>
1547 </B><DD>The number of kilobytes of tape (or disk space, for a backup data file)
1548 used to store the dump data. It is generally larger than the sum of the
1549 values in the <TT>nMBytes Data</TT> and <TT>nBytes Data</TT> fields,
1550 because it includes the space required for the label, file marks and other
1551 markers, and because the Backup System writes data at 16 KB offsets, even if
1552 the data in a given block doesn't fill the entire 16 KB.
1553 </DL>
1554 <P><LI>For each volume on a given tape, there follows a section headed by the
1555 underlined string <TT>Volume</TT>. The fields labeled
1556 <TT>name</TT>, <TT>position</TT>, <TT>clone</TT>, and <TT>nBytes</TT>
1557 report the same values (though in a different order) as appear in the table
1558 that lists the volumes in each tape when the <B>-id</B> argument is
1559 provided by itself. Other fields of potential interest to the backup
1560 operator are:
1561 <DL>
1562 <P><DT><B><TT>id</TT>
1563 </B><DD>The volume ID.
1564 <P><DT><B><TT>tape</TT>
1565 </B><DD>The name of the tape containing this volume data.
1566 </DL>
1567 </UL>
1568 <P>The following example command displays the Backup Database records for the
1569 five most recent dump operations.
1570 <PRE>   % <B>backup dump 5</B>
1571       dumpid   parentid lv created          nt nvols dump name
1572    924424000          0 0  04/18/1999 04:26  1    22 usr.sun (924424000)
1573    924685000  924424000 1  04/21/1999 04:56  1    62 usr.wed (924424000)
1574    924773000  924424000 1  04/22/1999 05:23  1    46 usr.thu (924424000)
1575    924860000  924424000 1  04/23/1999 05:33  1    58 usr.fri (924424000)
1576    925033000          0 0  04/25/1999 05:36  2    73 sys.week
1577 </PRE>
1578 <A NAME="IDX7040"></A>
1579 <A NAME="IDX7041"></A>
1580 <A NAME="IDX7042"></A>
1581 <A NAME="IDX7043"></A>
1582 <P><H3><A NAME="HDRWQ304" HREF="auagd002.htm#ToC_341">To display a volume's dump history</A></H3>
1583 <OL TYPE=1>
1584 <P><LI>Verify that you are authenticated as a user listed in the
1585 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1586 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1587 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1588 </PRE>
1589 <P><LI>Issue the <B>backup volinfo</B> command to display a volume's
1590 dump history.
1591 <PRE>   % <B>backup volinfo</B> &lt;<VAR>volume&nbsp;name</VAR>>
1592 </PRE>
1593 <P>where
1594 <DL>
1595 <P><DT><B>voli
1596 </B><DD>Is the shortest acceptable abbreviation of <B>volinfo</B>.
1597 <P><DT><B><VAR>volume name</VAR>
1598 </B><DD>Names the volume for which to display the dump history. If you
1599 dumped the backup or read-only version of the volume, include the
1600 <B>.backup</B> or <B>.readonly</B> extension.
1601 </DL>
1602 </OL>
1603 <P>The output includes a line for each Backup Database dump record that
1604 mentions the specified volume, order from most to least recent. The
1605 output for each record appears in a table with six columns:
1606 <DL>
1607 <P><DT><B><TT>dumpID</TT>
1608 </B><DD>The dump ID of the dump that includes the volume.
1609 <P><DT><B><TT>lvl</TT>
1610 </B><DD>The depth in the dump hierarchy of the dump level at which the volume was
1611 dumped. A value of <TT>0</TT> indicates a full dump. A value
1612 of <TT>1</TT> or greater indicates an incremental dump made at the specified
1613 depth in the dump hierarchy.
1614 <P><DT><B><TT>parentid</TT>
1615 </B><DD>The dump ID of the dump's parent dump. A value of <TT>0</TT>
1616 indicates a full dump, which has no parent; in this case, the value in
1617 the <TT>lvl</TT> column is also <TT>0</TT>.
1618 <P><DT><B><TT>creation date</TT>
1619 </B><DD>The date and time at which the Backup System started the dump operation
1620 that created the dump.
1621 <P><DT><B><TT>clone date</TT>
1622 </B><DD>For a backup or read-only volume, the time at which it was cloned from its
1623 read/write source. For a read/write volume, the same as the value in
1624 the <TT>creation date</TT> field.
1625 <P><DT><B><TT>tape name</TT>
1626 </B><DD>The name of the tape containing the dump: either the permanent tape
1627 name, or an AFS tape name in the format
1628 <I>volume_set_name</I>.<I>dump_level_name</I>.<I>tape_index</I>
1629 where <I>volume_set_name</I> is the name of the volume set associated with
1630 the initial dump in the dump set of which this tape is a part;
1631 <I>dump_level_name</I> is the name of the dump level at which the initial
1632 dump was backed up; <I>tape_index</I> is the ordinal of the tape in
1633 the dump set. Either type of name can be followed by a dump ID in
1634 parentheses; if it appears, it is the dump ID of the initial dump in the
1635 dump set to which this appended dump belongs.
1636 </DL>
1637 <P>The following example shows part of the dump history of the backup volume
1638 <B>user.smith.backup</B>:
1639 <PRE>   %<B> backup volinfo user.smith.backup</B>
1640    DumpID    lvl parentID  creation   date  clone date       tape name
1641    924600000 1   924427600 04/20/1999 05:20 04/20/1999 05:01 user_incr_2 (924514392)
1642    924514392 1   924427600 04/19/1999 05:33 04/19/1999 05:08 user_incr_2
1643    924427600 0           0 04/18/1999 05:26 04/18/1999 04:58 user_full_6
1644        .     .      .         .       .       .      .         .
1645        .     .      .         .       .       .      .         .
1646 </PRE>
1647 <A NAME="IDX7044"></A>
1648 <A NAME="IDX7045"></A>
1649 <A NAME="IDX7046"></A>
1650 <A NAME="IDX7047"></A>
1651 <A NAME="IDX7048"></A>
1652 <P><H3><A NAME="HDRWQ305" HREF="auagd002.htm#ToC_342">To scan the contents of a tape</A></H3>
1653 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">The ability to scan a tape that is corrupted or damaged
1654 depends on the extent of the damage and what type of data is corrupted.
1655 The Backup System can almost always scan the tape successfully up to the point
1656 of damage. If the damage is minor, the Backup System can usually skip
1657 over it and scan the rest of the tape, but more major damage can prevent
1658 further scanning. A scanning operation does not have to begin with the
1659 first tape in a dump set, but the Backup System can process tapes only in
1660 sequential order after the initial tape provided. Therefore, damage on
1661 one tape does not prevent scanning of the others in the dump set, but it is
1662 possible to scan either the tapes that precede the damaged one or the ones
1663 that follow it, not both.
1664 <P>If you use the <B>-dbadd</B> flag to scan information into the Backup
1665 Database and the first tape you provide is not the first tape in the dump set,
1666 the following restrictions apply:
1667 <UL>
1668 <P><LI>If the first data on the tape is a continuation of a volume that begins on
1669 the previous (unscanned) tape in the dump set, the Backup System does not add
1670 a record for that volume to the Backup Database.
1671 <P><LI>The Backup System must read the marker that indicates the start of an
1672 appended dump to add database records for the volumes in it. If the
1673 first volume on the tape belongs to an appended dump, but is not immediately
1674 preceded by the appended-dump marker, the Backup System does not create a
1675 Backup Database record for it or any subsequent volumes that belong to that
1676 appended dump.
1677 </UL>
1678 </TD></TR></TABLE>
1679 <OL TYPE=1>
1680 <P><LI>Verify that you are authenticated as a user listed in the
1681 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1682 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1683 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1684 </PRE>
1685 <P><LI>If the Tape Coordinator for the tape device that is to perform the
1686 operation is not already running, open a connection to the appropriate Tape
1687 Coordinator machine and issue the <B>butc</B> command, for which complete
1688 instructions appear in <A HREF="#HDRWQ292">To start a Tape Coordinator process</A>.
1689 <PRE>   % <B>butc</B> [&lt;<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
1690 </PRE>
1691 <P><LI>If scanning a tape, place it in the drive.
1692 <P><LI><B>(Optional)</B> Issue the <B>backup</B> command to enter
1693 interactive mode.
1694 <PRE>   % <B>backup</B>
1695 </PRE>
1696 <A NAME="IDX7049"></A>
1697 <A NAME="IDX7050"></A>
1698 <P><LI>Issue the <B>backup scantape</B> command to read the contents of the
1699 tape.
1700 <PRE>   backup> <B>scantape</B> [<B>-dbadd</B>] [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
1701 </PRE>
1702 <P>where
1703 <DL>
1704 <P><DT><B>sc
1705 </B><DD>Is the shortest acceptable abbreviation of <B>scantape</B>.
1706 <P><DT><B>-dbadd
1707 </B><DD>Constructs dump and tape records from the tape and dump labels in the dump
1708 and writes them into the Backup Database.
1709 <P><DT><B><VAR>TC port offset</VAR>
1710 </B><DD>Specifies the port offset number of the Tape Coordinator process that is
1711 handling the operation. You must provide this argument unless the
1712 default value of 0 (zero) is appropriate.
1713 </DL>
1714 <P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
1715 the <B>butc</B> command, or the device's
1716 <B>CFG_</B><VAR>device_name</VAR> configuration file includes the
1717 instruction <B>AUTOQUERY YES</B> instruction, then the Tape Coordinator
1718 prompts you to place the tape in the device's drive. You have
1719 already done so, but you must now press &lt;<B>Return</B>> to indicate
1720 that the tape is ready for reading.
1721 </OL>
1722 <P>To terminate a tape scanning operation, use a termination signal such as
1723 &lt;<B>Ctrl-c</B>>, or issue the <B>(backup) kill</B> command in
1724 interactive mode. It is best not to interrupt the scan if you included
1725 the <B>-dbadd</B> argument. If the Backup System has already
1726 written new records into the Backup Database, then you must remove them before
1727 rerunning the scanning operation. If during the repeated scan operation
1728 the Backup System finds that a record it needs to create already exists, it
1729 halts the operation.
1730 <P>For each dump on the tape, the output in the Tape Coordinator window
1731 displays the dump label followed by an entry for each volume. There is
1732 no output in the command window. The dump label has the same fields as
1733 the tape label displayed by the <B>backup readlabel</B> command, as
1734 described in <A HREF="auagd011.htm#HDRWQ272">Writing and Reading Tape Labels</A>. Or see the <I>IBM AFS Administration
1735 Reference</I> for a detailed description of the fields in the output.
1736 <P>The following example shows the dump label and first volume entry on the
1737 tape in the device that has port offset 2:
1738 <PRE>   % <B>backup scantape 2</B>
1739    -- Dump label --
1740    tape name = monthly_guest
1741    AFS tape name = guests.monthly.3
1742    creationTime =  Mon Feb  1 04:06:40 1999
1743    cell = abc.com
1744    size = 2150000 Kbytes
1745    dump path = /monthly
1746    dump id = 917860000
1747    useCount = 44
1748    -- End of dump label --
1749    -- volume --
1750    volume name: user.guest10.backup
1751    volume ID 1937573829
1752    dumpSetName: guests.monthly
1753    dumpID 917860000
1754    level 0
1755    parentID 0
1756    endTime 0
1757    clonedate Mon Feb  1 03:03:23 1999
1758 </PRE>
1759 <HR><H2><A NAME="HDRWQ306" HREF="auagd002.htm#ToC_343">Restoring and Recovering Data</A></H2>
1760 <A NAME="IDX7051"></A>
1761 <A NAME="IDX7052"></A>
1762 <A NAME="IDX7053"></A>
1763 <A NAME="IDX7054"></A>
1764 <A NAME="IDX7055"></A>
1765 <A NAME="IDX7056"></A>
1766 <A NAME="IDX7057"></A>
1767 <A NAME="IDX7058"></A>
1768 <A NAME="IDX7059"></A>
1769 <A NAME="IDX7060"></A>
1770 <A NAME="IDX7061"></A>
1771 <A NAME="IDX7062"></A>
1772 <P>The purpose of making backups is to enable you to recover when data becomes
1773 corrupted or is removed accidentally, returning the data to a coherent past
1774 state. The AFS Backup System provides three commands that restore
1775 varying numbers of volumes:
1776 <UL>
1777 <P><LI>To restore one or more volumes to a single site (partition on an AFS file
1778 server machine), use the <B>backup volrestore</B> command.
1779 <P><LI>To restore one or more volumes that are defined as a volume set, each to a
1780 specified site, use the <B>backup volsetrestore</B> command.
1781 <P><LI>To restore an entire partition (that is, all of the volumes that the VLDB
1782 lists as resident on it), use the <B>backup diskrestore</B>
1783 command.
1784 </UL>
1785 <P>The commands are suited to different purposes because they vary in the
1786 combinations of features they offer and in the requirements they
1787 impose. To decide which is appropriate for a specific restore
1788 operation, see the subsequent sections of this introduction: <A HREF="#HDRWQ308">Using the backup volrestore Command</A>, <A HREF="#HDRWQ310">Using the backup diskrestore Command</A>, and <A HREF="#HDRWQ312">Using the backup volsetrestore Command</A>.
1789 <P><H3><A NAME="HDRWQ307" HREF="auagd002.htm#ToC_344">Making Restore Operations More Efficient</A></H3>
1790 <P>The following comments apply to all types of restore
1791 operation:
1792 <UL>
1793 <P><LI>The Backup System begins by restoring the most recent full dump of a
1794 volume. As it restores subsequent incremental dumps, it alters the data
1795 in the full dump appropriately, essentially repeating the volume's change
1796 history. The <B>backup diskrestore</B> and <B>backup
1797 volsetrestore</B> commands always restore all incremental dumps, bringing a
1798 volume to its state at the time of the most recent incremental dump.
1799 You can use the <B>backup volrestore</B> command to return a volume to its
1800 state at a specified time in the past, by not restoring the data from
1801 incremental dumps performed after that time.
1802 <P><LI>The Backup System sets a restored volume's creation date to the date
1803 and time of the restore operation. The creation date appears in the
1804 <TT>Creation</TT> field of the output from the <B>vos examine</B> and
1805 <B>vos listvol</B> commands.
1806 <P><LI>When identifying the volumes to restore, it is best to specify the base
1807 (read/write) name. In this case, the Backup System searches the Backup
1808 Database for the most recent dump set that includes data from either the
1809 read/write or backup version of the volume, and restores dumps of that volume
1810 starting with the most recent full dump. If you include the
1811 <B>.backup</B> or <B>.readonly</B> extension on the
1812 volume name, the Backup System restores dumps of that version only. If
1813 it cannot find data dumped from that version, it does not perform the
1814 restoration even if another version was dumped.
1815 <P><LI>All three restoration commands accept the <B>-n</B> option, which
1816 generates a list of the volumes to be restored and the tapes or backup data
1817 files that contain the necessary dumps, without actually restoring data to AFS
1818 server partitions. This enables you to gather together the tapes before
1819 beginning the restore operation, even preloading them into a stacker or
1820 jukebox if you are using one.
1821 <P><LI>If you back up AFS data to tape, restoration is simplest if all of your
1822 tape devices are compatible, meaning that they can read the same type of tape,
1823 at the same compression ratios, and so on. (This suggestion also
1824 appears in <A HREF="#HDRWQ297">Making Backup Operations More Efficient</A>, because by the time you need to restore data it is too late
1825 to implement it.) You can still restore multiple volumes with a single
1826 command even if data was backed up using incompatible devices, because the
1827 <B>-portoffset</B> argument to all three restoration commands accepts
1828 multiple values. However, the Backup System uses the first port offset
1829 listed when restoring the full dump of each volume, the next port offset when
1830 restoring the level 1 incremental dump of each volume, and so on. If
1831 you did not use a compatible tape device when creating the full dump of every
1832 volume (and at each incremental level too), you cannot restore multiple
1833 volumes with a single command. You must use the <B>backup
1834 volrestore</B> command to restore one volume at a time, or use the
1835 <B>backup volsetrestore</B> command after defining volume sets that group
1836 volumes according to the tape device used to dump them.
1837 <P><LI>During a restore operation, the Backup System uses instructions in the
1838 relevant <B>CFG_</B><VAR>device_name</VAR> configuration file in much the
1839 same way as during a dump operation, as described in <A HREF="#HDRWQ298">How Your Configuration Choices Influence the Dump Process</A>. It uses the <B>MOUNT</B>, <B>UNMOUNT</B>,
1840 <B>AUTOQUERY</B>, <B>BUFFERSIZE</B>, and <B>FILE</B> instructions
1841 just as for a dump operation. A difference for the
1842 <B>BUFFERSIZE</B> instruction is that the default buffer size overridden
1843 by the instruction is 32 KB for restore operations rather than the 16 KB used
1844 for dump operations. The Backup System does not use the
1845 <B>NAME_CHECK</B> instruction at all during restore operations. The
1846 <B>ASK</B> instruction controls whether the Backup System prompts you if
1847 it cannot restore a volume for any reason. If the setting is
1848 <B>NO</B>, it skips the problematic volume and restores as many of the
1849 other volumes as possible.
1850 <P><LI>Do not perform a restore operation when you know that there are network,
1851 machine, or server process problems that can prevent the Backup System from
1852 accessing volumes or the VLDB. Although the Backup System automatically
1853 makes a number of repeated attempts to restore a volume, the restore operation
1854 takes extra time and in some cases stops completely to prompt you for
1855 instructions on how to continue.
1856 <P><LI>Avoid halting a restore operation (for instance by issuing the
1857 <B>(backup) kill</B> command in interactive mode). If a restore
1858 operation is interrupted for any reason, including causes outside your
1859 control, reissue the same restoration command as soon as is practical; if
1860 an outage or other problem caused the operation to halt, do not continue until
1861 the system returns to normal.
1862 <P>Any volume that is completely restored when the operation halts is online
1863 and usable, but very few volumes are likely to be in this state. When
1864 restoring multiple volumes at once, the Backup System restores the full dump
1865 of every volume before beginning the level 1 incremental restore for any of
1866 them, and so on, completing the restore of every volume at a specific
1867 incremental level before beginning to restore data from the next incremental
1868 level. Unless a volume was dumped at fewer incremental levels than
1869 others being restored as part of the same operation, it is unlikely to be
1870 complete.
1871 <P>It is even more dangerous to interrupt a restore operation if you are
1872 overwriting the current contents of the volume. Depending on how far
1873 the restore operation has progressed, it is possible that the volume is in
1874 such an inconsistent state that the Backup System removes it entirely.
1875 The data being restored is still available on tape or in the backup data file,
1876 but you must take extra steps to re-create the volume.
1877 </UL>
1878 <P><H3><A NAME="HDRWQ308" HREF="auagd002.htm#ToC_345">Using the backup volrestore Command</A></H3>
1879 <A NAME="IDX7063"></A>
1880 <A NAME="IDX7064"></A>
1881 <A NAME="IDX7065"></A>
1882 <A NAME="IDX7066"></A>
1883 <A NAME="IDX7067"></A>
1884 <A NAME="IDX7068"></A>
1885 <P>The <B>backup volrestore</B> command is most appropriate when you need
1886 to restore a few volumes to a single site (partition on a file server
1887 machine). By default, it restores the volumes to their state at the
1888 time of the most recent dump operation (this is termed a <I>full
1889 restore</I>). You can also use the command to perform a
1890 <I>date-specific restore</I>, which restores only the dumps (full and
1891 incremental) performed before a specified date and time, leaving the volume in
1892 the state it was in at the time of the final relevant incremental dump.
1893 The <B>backup diskrestore</B> and <B>backup volsetrestore</B> commands
1894 can only perform full restores.
1895 <P>You can restore data into a new copy of each volume rather than overwriting
1896 the current version, by including the <B>-extension</B> argument.
1897 After mounting the new volume in the filespace, you can compare the contents
1898 of the two and decide which to keep permanently.
1899 <P>The following list summarizes how to combine the <B>backup
1900 volrestore</B> command's arguments to restore a volume in different
1901 ways:
1902 <UL>
1903 <P><LI>To perform a date-specific restore as described just previously, use the
1904 <B>-date</B> argument to specify the date and optionally time. The
1905 Backup System restores the most recent full dump and each subsequent
1906 incremental dump for which the clone date of the volume included in the dump
1907 is before the indicated date and time (for a definition of the clone date, see
1908 Step <A HREF="#LIBKOV-CLONEDATE">4</A> in <A HREF="#HDRWQ298">How Your Configuration Choices Influence the Dump Process</A>). You can combine this argument with
1909 the <B>-extension</B> argument to place the date-specific restore in a new
1910 volume.
1911 <P><LI>To move a volume to a new site as you overwrite its contents with the
1912 restored data, use the <B>-server</B> and <B>-partition</B> arguments,
1913 singly or in combination, to specify the new site rather than the current
1914 site. The Backup System creates a new volume at that site, removes the
1915 existing volume, and updates the site information in the volume's VLDB
1916 entry. The volume's backup version is not removed automatically
1917 from the original site, if it exists. Use the <B>vos remove</B>
1918 command to remove it and the <B>vos backup</B> command to create a backup
1919 version at the new site.
1920 <P><LI>To create a new volume to house the restored data, rather than overwriting
1921 an existing volume, use the <B>-extension</B> argument. The Backup
1922 System creates the new volume on the server and partition named by the
1923 <B>-server</B> and <B>-partition</B> arguments, derives its name by
1924 adding the extension to the name specified with the <B>-volume</B>
1925 argument, and creates a new VLDB entry for it. The command does not
1926 affect the existing volume in any way. However, if a volume with the
1927 specified extension also already exists, the command overwrites it. To
1928 make the contents of the new volume accessible, use the <B>fs mkmount</B>
1929 command to mount it. You can then compare its contents to those of the
1930 existing volume, to see which to retain permanently.
1931 <P><LI>To restore a volume that no longer exists on an AFS server partition, but
1932 for which you have backed up data, specify the name of the new volume with the
1933 <B>-volume</B> argument and use the <B>-server</B> and
1934 <B>-partition</B> arguments to place it at the desired site. The
1935 Backup System creates a new volume and new VLDB entry.
1936 </UL>
1937 <A NAME="IDX7069"></A>
1938 <A NAME="IDX7070"></A>
1939 <P><H3><A NAME="HDRWQ309" HREF="auagd002.htm#ToC_346">To restore volumes with the backup volrestore command</A></H3>
1940 <OL TYPE=1>
1941 <P><LI>Verify that you are authenticated as a user listed in the
1942 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
1943 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
1944 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1945 </PRE>
1946 <P><LI>If the Tape Coordinator for the tape device that is to perform the
1947 operation is not already running, open a connection to the appropriate Tape
1948 Coordinator machine and issue the <B>butc</B> command, for which complete
1949 instructions appear in <A HREF="#HDRWQ292">To start a Tape Coordinator process</A>.
1950 <PRE>   % <B>butc</B> [&lt;<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
1951 </PRE>
1952 <P>Repeat the command for each Tape Coordinator if you are using more than one
1953 tape device.
1954 <P><LI>If using a tape device, insert the tape.
1955 <P><LI>Issue the <B>backup</B> command to enter interactive mode.
1956 <PRE>   % <B>backup</B>
1957 </PRE>
1958 <P><LI>Issue the <B>backup volrestore</B> command with the desired
1959 arguments.
1960 <PRE>   backup> <B>volrestore</B> &lt;<VAR>destination&nbsp;machine</VAR>> &lt;<VAR>destination&nbsp;partition</VAR>>  \
1961                       <B>-volume</B> &lt;<VAR>volume(s)&nbsp;to&nbsp;restore</VAR>><SUP>+</SUP>  \
1962                       [<B>-extension</B> &lt;<VAR>new&nbsp;volume&nbsp;name&nbsp;extension</VAR>>]  \
1963                       [<B>-date</B> &lt;<VAR>date&nbsp;from&nbsp;which&nbsp;to&nbsp;restore</VAR>>]  \
1964                       [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offsets</VAR>><SUP>+</SUP>] [<B>-n</B>]
1965 </PRE>
1966 <P>where
1967 <DL>
1968 <P><DT><B>volr
1969 </B><DD>Is the shortest acceptable abbreviation of <B>volrestore</B>.
1970 <P><DT><B><VAR>destination machine</VAR>
1971 </B><DD>Names the file server machine on which to restore each volume. It
1972 does not have to be a volume's current site.
1973 <P><DT><B><VAR>destination partition</VAR>
1974 </B><DD>Names the partition on which to restore each volume. It does not
1975 have to be a volume's current site.
1976 <P><DT><B>-volume
1977 </B><DD>Names each volume to restore. It is best to provide the base
1978 (read/write) name, for the reasons discussed in <A HREF="#HDRWQ307">Making Restore Operations More Efficient</A>.
1979 <P><DT><B>-extension
1980 </B><DD>Creates a new volume to house the restored data, with a name derived by
1981 appending the specified string to each volume named by the <B>-volume</B>
1982 extension. The Backup System preserves the contents of the existing
1983 volume if it still exists. Do not use either of the
1984 <B>.readonly</B> or <B>.backup</B> extensions, which are
1985 reserved. The combination of base volume name and extension cannot
1986 exceed 22 characters in length. If you want a period to separate the
1987 extension from the name, specify it as the first character of the string (as
1988 in <B>.rst</B>, for example).
1989 <P><DT><B>-date
1990 </B><DD>Specifies a date and optionally time; the restored volume includes
1991 data from dumps performed before the date only. Provide a value in the
1992 format <I>mm</I>/<I>dd</I>/<I>yyyy</I>
1993 [<I>hh</I>:<I>MM</I>], where the required <I>mm/dd/yyyy</I>
1994 portion indicates the month (<I>mm</I>), day (<I>dd</I>), and year
1995 (<I>yyyy</I>), and the optional <I>hh:MM</I> portion indicates
1996 the hour and minutes in 24-hour format (for example, the value
1997 <B>14:36</B> represents 2:36 p.m.). If
1998 omitted, the time defaults to 59 seconds after midnight (00:00:59
1999 hours).
2000 <P>Valid values for the year range from <B>1970</B> to
2001 <B>2037</B>; higher values are not valid because the latest possible
2002 date in the standard UNIX representation is in February 2038. The
2003 command interpreter automatically reduces any later date to the maximum
2004 value.
2005 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A plus sign follows this argument in the command's syntax statement
2006 because it accepts a multiword value which does not need to be enclosed in
2007 double quotes or other delimiters, not because it accepts multiple
2008 dates. Provide only one date (and optionally, time) definition.
2009 </TD></TR></TABLE>
2010 <P><DT><B>-portoffset
2011 </B><DD>Specifies one or more port offset numbers, each corresponding to a Tape
2012 Coordinator to use in the operation. If there is more than one value,
2013 the Backup System uses the first one when restoring the full dump of each
2014 volume, the second one when restoring the level 1 incremental dump of each
2015 volume, and so on. It uses the final value in the list when restoring
2016 dumps at the corresponding depth in the dump hierarchy and all dumps at lower
2017 levels.
2018 <P>Provide this argument unless the default value of 0 (zero) is appropriate
2019 for all dumps. If 0 is just one of the values in the list, provide it
2020 explicitly in the appropriate order.
2021 <P><DT><B>-n
2022 </B><DD>Displays the list of tapes that contain the dumps required by the restore
2023 operation, without actually performing the operation.
2024 </DL>
2025 <P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
2026 the <B>butc</B> command, or the device's
2027 <B>CFG_</B><VAR>device_name</VAR> configuration file includes the
2028 instruction <B>AUTOQUERY YES</B>, then the Tape Coordinator prompts you to
2029 place the tape in the device's drive. You have already done so,
2030 but you must now press &lt;<B>Return</B>> to indicate that the tape is
2031 ready for labeling.
2032 <P>If more than one tape is required, you must either include the
2033 <B>MOUNT</B> instruction in the <B>CFG_</B><VAR>device_name</VAR> file
2034 and stock the corresponding stacker or jukebox with tapes, or remain at the
2035 console to respond to the Tape Coordinator's prompts for subsequent
2036 tapes.
2037 <P><LI>After the restore operation completes, review the Backup System's log
2038 files to check for errors. Use the <B>bos getlog</B> command as
2039 instructed in <A HREF="auagd009.htm#HDRWQ173">Displaying Server Process Log Files</A> to read the <B>/usr/afs/logs/BackupLog</B> file, and a
2040 text editor on the Tape Coordinator machine to read the
2041 <B>TE_</B><VAR>device_name</VAR> and <B>TL_</B><VAR>device_name</VAR>
2042 files in the local <B>/usr/afs/backup</B> directory.
2043 </OL>
2044 <P><H3><A NAME="HDRWQ310" HREF="auagd002.htm#ToC_347">Using the backup diskrestore Command</A></H3>
2045 <A NAME="IDX7071"></A>
2046 <A NAME="IDX7072"></A>
2047 <P>The <B>backup diskrestore</B> command is most appropriate when you need
2048 to restore all of the volumes on an AFS server partition, perhaps because a
2049 hardware failure has corrupted or destroyed all of the data. The
2050 command performs a full restore of all of the read/write volumes for which the
2051 VLDB lists the specified partition as the current site, using the dumps of
2052 either the read/write or backup version of each volume depending on which type
2053 was dumped more recently. (You can restore any backup or read-only
2054 volumes that resided on the partition by using the <B>vos backup</B> and
2055 <B>vos release</B> commands after the <B>backup diskrestore</B>
2056 operation is complete.)
2057 <P>By default, the Backup System restores the volumes to the site they
2058 previously occupied. To move the partition contents to a different
2059 site, use the <B>-newserver</B> and <B>-newpartition</B> arguments,
2060 singly or in combination.
2061 <P>By default, the Backup System overwrites the contents of existing volumes
2062 with the restored data. To create a new volume to house the restored
2063 data instead, use the <B>-extension</B> argument. The Backup System
2064 creates the new volume at the site designated by the <B>-newserver</B> and
2065 <B>-newpartition</B> arguments if they are used or the <B>-server</B>
2066 and <B>-partition</B> arguments otherwise. It derives the volume
2067 name by adding the extension to the read/write base name listed in the VLDB,
2068 and creates a new VLDB entry. The command does not affect the existing
2069 volume in any way. However, if a volume with the specified extension
2070 also already exists, the command overwrites it.
2071 <P>If a partition seems damaged, be sure not to run the <B>vos
2072 syncserv</B> command before the <B>backup diskrestore</B>
2073 command. As noted, the Backup System restores volumes according to VLDB
2074 site definitions. The <B>vos syncserv</B> command sometimes removes
2075 a volume's VLDB entry when the corruption on the partition is so severe
2076 that the Volume Server cannot confirm the volume's presence.
2077 <A NAME="IDX7073"></A>
2078 <A NAME="IDX7074"></A>
2079 <P><H3><A NAME="HDRWQ311" HREF="auagd002.htm#ToC_348">To restore a partition with the backup diskrestore command</A></H3>
2080 <OL TYPE=1>
2081 <P><LI>Verify that you are authenticated as a user listed in the
2082 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
2083 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2084 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2085 </PRE>
2086 <P><LI>If the Tape Coordinator for the tape device that is to perform the
2087 operation is not already running, open a connection to the appropriate Tape
2088 Coordinator machine and issue the <B>butc</B> command, for which complete
2089 instructions appear in <A HREF="#HDRWQ292">To start a Tape Coordinator process</A>.
2090 <PRE>   % <B>butc</B> [&lt;<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
2091 </PRE>
2092 <P>Repeat the command for each Tape Coordinator if you are using more than one
2093 tape device.
2094 <P><LI>If using a tape device, insert the tape.
2095 <P><LI>Issue the <B>backup</B> command to enter interactive mode.
2096 <PRE>   % <B>backup</B>
2097 </PRE>
2098 <P><LI>Issue the <B>backup diskrestore</B> command with the desired
2099 arguments.
2100 <PRE>   backup> <B>diskrestore</B> &lt;<VAR>machine&nbsp;to&nbsp;restore</VAR>> &lt;<VAR>partition&nbsp;to&nbsp;restore</VAR>>  \
2101                        [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>><SUP>+</SUP>]  \
2102                        [<B>-newserver</B> &lt;<VAR>destination&nbsp;machine</VAR>>]  \
2103                        [<B>-newpartition</B> &lt;<VAR>destination&nbsp;partition</VAR>>]  \
2104                        [<B>-extension</B> &lt;<VAR>new&nbsp;volume&nbsp;name&nbsp;extension</VAR>>] [<B>-n</B>]
2105 </PRE>
2106 <P>where
2107 <DL>
2108 <P><DT><B>di
2109 </B><DD>Is the shortest acceptable abbreviation of <B>diskrestore</B>.
2110 <P><DT><B><VAR>machine to restore</VAR>
2111 </B><DD>Names the file server machine that the VLDB lists as the site of the
2112 volumes that need to be restored.
2113 <P><DT><B><VAR>partition to restore</VAR>
2114 </B><DD>Names the partition that the VLDB lists as the site of the volumes that
2115 need to be restored.
2116 <P><DT><B>-portoffset
2117 </B><DD>Specifies one or more port offset numbers, each corresponding to a Tape
2118 Coordinator to use in the operation. If there is more than one value,
2119 the Backup System uses the first one when restoring the full dump of each
2120 volume, the second one when restoring the level 1 incremental dump of each
2121 volume, and so on. It uses the final value in the list when restoring
2122 dumps at the corresponding depth in the dump hierarchy and all dumps at lower
2123 levels.
2124 <P>Provide this argument unless the default value of 0 (zero) is appropriate
2125 for all dumps. If 0 is just one of the values in the list, provide it
2126 explicitly in the appropriate order.
2127 <P><DT><B>-newserver
2128 </B><DD>Names an alternate file server machine to which to restore the
2129 volumes. If you omit this argument, the volumes are restored to the
2130 file server machine named by the <B>-server</B> argument.
2131 <P><DT><B>-newpartition
2132 </B><DD>Names an alternate partition to which to restore the data. If you
2133 omit this argument, the volumes are restored to the partition named by the
2134 <B>-partition</B> argument.
2135 <P><DT><B>-extension
2136 </B><DD>Creates a new volume for each volume being restored, to house the restored
2137 data, appending the specified string to the volume's read/write base name
2138 as listed in the VLDB. Any string other than
2139 <B>.readonly</B> or <B>.backup</B> is acceptable, but
2140 the combination of the base name and extension cannot exceed 22 characters in
2141 length. To use a period to separate the extension from the name,
2142 specify it as the first character of the string (as in <B>.rst</B>,
2143 for example).
2144 <P><DT><B>-n
2145 </B><DD>Displays a list of the tapes necessary to perform the requested restore,
2146 without actually performing the operation.
2147 </DL>
2148 <P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
2149 the <B>butc</B> command, or the device's
2150 <B>CFG_</B><VAR>device_name</VAR> configuration file includes the
2151 instruction <B>AUTOQUERY YES</B>, then the Tape Coordinator prompts you to
2152 place the tape in the device's drive. You have already done so,
2153 but you must now press &lt;<B>Return</B>> to indicate that the tape is
2154 ready for labeling.
2155 <P>If more than one tape is required, you must either include the
2156 <B>MOUNT</B> instruction in the <B>CFG_</B><VAR>device_name</VAR> file
2157 and stock the corresponding stacker or jukebox with tapes, or remain at the
2158 console to respond to the Tape Coordinator's prompts for subsequent
2159 tapes.
2160 <P><LI>After the restore operation completes, review the Backup System's log
2161 files to check for errors. Use the <B>bos getlog</B> command as
2162 instructed in <A HREF="auagd009.htm#HDRWQ173">Displaying Server Process Log Files</A> to read the <B>/usr/afs/logs/BackupLog</B> file, and a
2163 text editor on the Tape Coordinator machine to read the
2164 <B>TE_</B><VAR>device_name</VAR> and <B>TL_</B><VAR>device_name</VAR>
2165 files in the local <B>/usr/afs/backup</B> directory.
2166 </OL>
2167 <P><H3><A NAME="HDRWQ312" HREF="auagd002.htm#ToC_349">Using the backup volsetrestore Command</A></H3>
2168 <P>The <B>backup volsetrestore</B> command is most
2169 appropriate when you need to perform a full restore of several read/write
2170 volumes, placing each at a specified site. You specify the volumes to
2171 restore either by naming a volume set with the <B>-name</B> argument or by
2172 listing each volume's name and restoration site in a file named by the
2173 <B>-file</B> argument, as described in the following sections.
2174 <P>Because the <B>backup volsetrestore</B> command enables you to restore
2175 a large number of volumes with a single command, the restore operation can
2176 potentially take hours to complete. One way to reduce the time is to
2177 run multiple instances of the command simultaneously. Either use the
2178 <B>-name</B> argument to specify disjoint volume sets for each command, or
2179 the <B>-file</B> argument to name files that list different
2180 volumes. You must have several Tape Coordinators available to read the
2181 required tapes. Depending on how the volumes to be restored were dumped
2182 to tape, specifying disjoint volume sets can also reduce the number of tape
2183 changes required.
2184 <P><H4><A NAME="HDRWQ313">Restoring a Volume Set with the -name Argument</A></H4>
2185 <P>Use the <B>-name</B> argument to restore a group of
2186 volumes defined in a volume set. The Backup System creates a list of
2187 the volumes in the VLDB that match the server, partition, and volume name
2188 criteria defined in the volume set's volume entries, and for which dumps
2189 are available. The volumes do not have to exist on the server partition
2190 as long as the VLDB still lists them (this can happen when, for instance, a
2191 hardware problem destroys the contents of an entire disk).
2192 <P>By default, the Backup System restores, as a read/write volume, each volume
2193 that matches the volume set criteria to the site listed in the VLDB. If
2194 a volume of the matching name exists at that site, its current contents are
2195 overwritten. You can instead create a new volume to house the restored
2196 data by including the <B>-extension</B> argument. The Backup System
2197 creates the new volume at the existing volume's site, derives its name by
2198 adding the extension to the existing volume's read/write base name, and
2199 creates a new VLDB entry for it. The command does not affect the
2200 existing volume in any way. However, if a volume with the specified
2201 extension also already exists, the command overwrites it. To make the
2202 contents of the new volume accessible, use the <B>fs mkmount</B> command
2203 to mount it. You can then compare its contents to those of the existing
2204 volume, to see which to retain permanently.
2205 <P>It is not required that the volume set was previously used to back up
2206 volumes (was used as the <B>-volumeset</B> option to the <B>backup
2207 dump</B> command). It can be defined especially to match the volumes
2208 that need to be restored with this command, and that is usually the better
2209 choice. Indeed, a <I>temporary</I> volume set, created by including
2210 the <B>-temporary</B> flag to the <B>backup addvolset</B> command, can
2211 be especially useful in this context (instructions appear in <A HREF="auagd011.htm#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>). A temporary volume set is not added to the Backup
2212 Database and exists only during the current interactive backup session, which
2213 is suitable if the volume set is needed only to complete the single restore
2214 operation initialized by this command.
2215 <P>The reason that a specially defined volume set is probably better is that
2216 volume sets previously defined for use in dump operations usually match the
2217 backup version of volumes, whereas for a restore operation it is best to
2218 define volume entries that match the base (read/write) name. In this
2219 case, the Backup System searches the Backup Database for the newest dump set
2220 that includes a dump of either the read/write or the backup version of the
2221 volume. If, in contrast, a volume entry explicitly matches the
2222 volume's backup or read-only version, the Backup System uses dumps of
2223 that volume version only, restoring them to a read/write volume by stripping
2224 off the <B>.backup</B> or <B>.readonly</B>
2225 extension.
2226 <P>If there are VLDB entries that match the volume set criteria, but for which
2227 there are no dumps recorded in the Backup Database, the Backup System cannot
2228 restore them. It generates an error message on the standard error
2229 stream for each one.
2230 <P><H4><A NAME="HDRWQ314">Restoring Volumes Listed in a File with the -file Argument</A></H4>
2231 <P>Use the <B>-file</B> argument to specify the name and
2232 site of each read/write volume to restore. Each volume's entry
2233 must appear on its own (unbroken) line in the file, and comply with the
2234 following format:
2235 <PRE>   <VAR>machine</VAR>    <VAR>partition</VAR>   <VAR>volume</VAR>    [<VAR>comments...</VAR>]
2236 </PRE>
2237 <P>where
2238 <DL>
2239 <P><DT><B><VAR>machine</VAR>
2240 </B><DD>Names the file server machine to which to restore the volume. You
2241 can move the volume as you restore it by naming a machine other than the
2242 current site.
2243 <P><DT><B><VAR>partition</VAR>
2244 </B><DD>Names the partition to which to restore the volume. You can move
2245 the volume as you restore it by naming a partition other than the current
2246 site.
2247 <P><DT><B><VAR>volume</VAR>
2248 </B><DD>Names the volume to restore. Specify the base (read/write) name to
2249 have the Backup System search the Backup Database for the newest dump set that
2250 includes a dump of either the read/write or the backup version of the
2251 volume. It restores the dumps of that version of the volume, starting
2252 with the most recent full dump. If, in contrast, you include the
2253 <TT>.backup</TT> or <TT>.readonly</TT> extension, the Backup
2254 System restores dumps of that volume version only, but into a read/write
2255 volume without the extension. The base name must match the name used in
2256 Backup Database dump records rather than in the VLDB, if they differ, because
2257 the Backup System does not consult the VLDB when you use the <B>-file</B>
2258 argument.
2259 <P><DT><B><VAR>comments...</VAR>
2260 </B><DD>Is any other text. The Backup System ignores any text on each line
2261 that appears after the volume name, so you can use this field for helpful
2262 notes.
2263 </DL>
2264 <P>Do not use wildcards (for example, <B>.*</B>) in the
2265 <VAR>machine</VAR>, <VAR>partition</VAR>, or <VAR>volume</VAR> fields. It is
2266 acceptable for multiple lines in the file to name the same volume, but the
2267 Backup System processes only the first of them.
2268 <P>By default, the Backup System replaces the existing version of each volume
2269 with the restored data, placing the volume at the site specified in the
2270 <VAR>machine</VAR> and <VAR>partition</VAR> fields. You can instead create
2271 a new volume to house the restored contents by including the
2272 <B>-extension</B> argument. The Backup System creates a new volume
2273 at the site named in the <VAR>machine</VAR> and <VAR>partition</VAR> fields,
2274 derives its name by adding the specified extension to the read/write version
2275 of the name in the <VAR>volume</VAR> field, and creates a new VLDB entry for
2276 it. The command does not affect the existing volume in any way.
2277 However, if a volume with the specified extension also already exists, the
2278 command overwrites it. To make the contents of the new volume
2279 accessible, use the <B>fs mkmount</B> command to mount it. You can
2280 then compare its contents to those of the existing volume, to see which to
2281 retain permanently.
2282 <P>If the file includes entries for volumes that have no dumps recorded in the
2283 Backup Database, the Backup System cannot restore them. It generates an
2284 error message on the standard error stream for each one.
2285 <P>One way to generate a file to use as input to the <B>-file</B> argument
2286 is to issue the command with the <B>-name</B> and <B>-n</B> options
2287 and direct the output to a file. The output includes a line like the
2288 following for each volume (shown here on two lines only for legibility
2289 reasons); the value comes from the source indicated in the following
2290 list:
2291 <PRE>   <VAR>machine</VAR>   <VAR>partition</VAR>   <VAR>volume_dumped</VAR>  # as   <VAR>volume_restored</VAR>;    \
2292          <VAR>tape_name</VAR>   (<VAR>tape_ID</VAR>);   pos   <VAR>position_number</VAR>;   <VAR>date</VAR>
2293 </PRE>
2294 <P>where
2295 <DL>
2296 <P><DT><B><VAR>machine</VAR>
2297 </B><DD>Names the file server machine that currently houses the volume, as listed
2298 in the VLDB.
2299 <P><DT><B><VAR>partition</VAR>
2300 </B><DD>Names the partition that currently houses the volume, as listed in the
2301 VLDB.
2302 <P><DT><B><VAR>volume_dumped</VAR>
2303 </B><DD>Specifies the version (read/write or backup) of the volume that was
2304 dumped, as listed in the Backup Database.
2305 <P><DT><B><VAR>volume_restored</VAR>
2306 </B><DD>Specifies the name under which the Backup System restores the volume when
2307 the <B>-n</B> flag is not included. If you include the
2308 <B>-extension</B> argument with the <B>-name</B> and <B>-n</B>
2309 options, then the extension appears on the name in this field (as in
2310 <TT>user.pat.rst</TT>, for example).
2311 <P><DT><B><VAR>tape_name</VAR>
2312 </B><DD>Names the tape containing the dump of the volume, from the Backup
2313 Database. If the tape has a permanent name, it appears here;
2314 otherwise, it is the AFS tape name.
2315 <P><DT><B><VAR>tape_ID</VAR>
2316 </B><DD>The tape ID of the tape containing the dump of the volume, from the Backup
2317 Database.
2318 <P><DT><B><VAR>position_number</VAR>
2319 </B><DD>Specifies the dump's position on the tape (for example, <TT>31</TT>
2320 indicates that 30 volume dumps precede the current one on the tape). If
2321 the dump was written to a backup data file, this number is the ordinal of the
2322 16 KB-offset at which the volume's data begins.
2323 <P><DT><B><VAR>date</VAR>
2324 </B><DD>The date and time when the volume was dumped.
2325 </DL>
2326 <P>To make the entries suitable for use with the <B>-file</B> argument,
2327 edit them as indicated:
2328 <UL>
2329 <P><LI>The Backup System uses only the first three fields on each line of the
2330 input file, and so ignores all the fields after the number sign
2331 (<TT>#</TT>). You can remove them if it makes it easier for you to
2332 read the file, but that is not necessary.
2333 <P><LI>The <VAR>volume_dumped</VAR> (third) field of each line in the output file
2334 becomes the <VAR>volume</VAR> field in the input file. The Backup System
2335 restores data to read/write volumes only, so remove the
2336 <TT>.backup</TT> or <TT>.readonly</TT> extension if it
2337 appears on the name in the <VAR>volume_dumped</VAR> field.
2338 <P><LI>The output file includes a line for every dump operation in which a
2339 specific volume was included (the full dump and any incremental dumps), but
2340 the Backup System only processes the first line in the input file that
2341 mentions a specific volume. You can remove the repeated lines if it
2342 makes the file easier for you to read.
2343 <P><LI>The <I>machine</I> and <I>partition</I> fields on an output line
2344 designate the volume's current site. To move the volume to another
2345 location as you restore it, change the values.
2346 </UL>
2347 <A NAME="IDX7075"></A>
2348 <A NAME="IDX7076"></A>
2349 <P><H3><A NAME="HDRWQ315" HREF="auagd002.htm#ToC_352">To restore a group of volumes with the backup volsetrestore command</A></H3>
2350 <OL TYPE=1>
2351 <P><LI>Verify that you are authenticated as a user listed in the
2352 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
2353 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2354 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2355 </PRE>
2356 <P><LI>If the Tape Coordinator for the tape device that is to perform the
2357 operation is not already running, open a connection to the appropriate Tape
2358 Coordinator machine and issue the <B>butc</B> command, for which complete
2359 instructions appear in <A HREF="#HDRWQ292">To start a Tape Coordinator process</A>.
2360 <PRE>   % <B>butc</B> [&lt;<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
2361 </PRE>
2362 <P>Repeat the command for each Tape Coordinator if you are using more than one
2363 tape device.
2364 <P><LI>If using a tape device, insert the tape.
2365 <P><LI>Issue the <B>backup</B> command to enter interactive mode.
2366 <PRE>   % <B>backup</B>
2367 </PRE>
2368 <P><LI><B>(Optional)</B> If appropriate, issue the <B>(backup)
2369 addvolset</B> command to create a new volume set expressly for this restore
2370 operation. Include the <B>-temporary</B> flag if you do not need to
2371 add the volume set to the Backup Database. Then issue one or more
2372 <B>(backup) addvolentry</B> commands to create volume entries that include
2373 only the volumes to be restored. Complete instructions appear in <A HREF="auagd011.htm#HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</A>.
2374 <PRE>   backup> <B>addvolset</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>  [<B>-temporary</B>]
2375
2376    backup> <B>addvolentry  -name</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>  \
2377                         <B>-server</B> &lt;<VAR>machine&nbsp;name</VAR>>  \
2378                         <B>-partition</B> &lt;<VAR>partition&nbsp;name</VAR>>  \
2379                         <B>-volumes</B> &lt;<VAR>volume&nbsp;name&nbsp;(regular&nbsp;expression)</VAR>>
2380 </PRE>
2381 <P><LI>Issue the <B>backup volsetrestore</B> command with the desired
2382 arguments.
2383 <PRE>   backup> <B>volsetrestore</B> [<B>-name</B> &lt;<VAR>volume&nbsp;set&nbsp;name</VAR>>]  \
2384                  [<B>-file</B> &lt;<VAR>file&nbsp;name</VAR>>]  \
2385                  [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>><SUP>+</SUP>]  \
2386                  [<B>-extension</B> &lt;<VAR>new&nbsp;volume&nbsp;name&nbsp;extension</VAR>>] [<B>-n</B>]
2387 </PRE>
2388 <P>where
2389 <DL>
2390 <P><DT><B>-name
2391 </B><DD>Names a volume set to restore. The Backup System restores all of
2392 the volumes listed in the VLDB that match the volume set's volume
2393 entries, as described in <A HREF="#HDRWQ313">Restoring a Volume Set with the -name Argument</A>. Provide this argument or the <B>-file</B>
2394 argument, but not both.
2395 <P><DT><B>-file
2396 </B><DD>Specifies the full pathname of a file that lists one or more volumes and
2397 the site (file server machine and partition) to which to restore each.
2398 The input file has the format described in <A HREF="#HDRWQ314">Restoring Volumes Listed in a File with the -file Argument</A>. Use either this argument or the <B>-name</B>
2399 argument, but not both.
2400 <P><DT><B><B>-portoffset</B>
2401 </B><DD>Specifies one or more port offset numbers, each corresponding to a Tape
2402 Coordinator to use in the operation. If there is more than one value,
2403 the Backup System uses the first one when restoring the full dump of each
2404 volume, the second one when restoring the level 1 incremental dump of each
2405 volume, and so on. It uses the final value in the list when restoring
2406 dumps at the corresponding depth in the dump hierarchy and all dumps at lower
2407 levels.
2408 <P>Provide this argument unless the default value of 0 (zero) is appropriate
2409 for all dumps. If 0 is just one of the values in the list, provide it
2410 explicitly in the appropriate order.
2411 <P><DT><B>-extension
2412 </B><DD>Creates a new volume for each volume being restored, to house the restored
2413 data, appending the specified string to the volume's read/write base name
2414 as listed in the VLDB. Any string other than
2415 <B>.readonly</B> or <B>.backup</B> is acceptable, but
2416 the combination of the base name and extension cannot exceed 22 characters in
2417 length. To use a period to separate the extension from the name,
2418 specify it as the first character of the string (as in <B>.rst</B>,
2419 for example).
2420 <P><DT><B><B>-n</B>
2421 </B><DD>Displays a list of the volumes to be restored when the flag is not
2422 included, without actually restoring them. The <B>Output</B>
2423 section of this reference page details the format of the output. When
2424 combined with the <B>-name</B> argument, its output is easily edited for
2425 use as input to the <B>-file</B> argument on a subsequent <B>backup
2426 volsetrestore</B> command.
2427 </DL>
2428 <P><LI>If you did not include the <B>-noautoquery</B> flag when you issued
2429 the <B>butc</B> command, or the device's
2430 <B>CFG_</B><VAR>device_name</VAR> configuration file includes the
2431 instruction <B>AUTOQUERY YES</B>, then the Tape Coordinator prompts you to
2432 place the tape in the device's drive. You have already done so,
2433 but you must now press &lt;<B>Return</B>> to indicate that the tape is
2434 ready for labeling.
2435 <P>If more than one tape is required, you must either include the
2436 <B>MOUNT</B> instruction in the <B>CFG_</B><VAR>device_name</VAR> file
2437 and stock the corresponding stacker or jukebox with tapes, or remain at the
2438 console to respond to the Tape Coordinator's prompts for subsequent
2439 tapes.
2440 <P><LI>After the restore operation completes, review the Backup System's log
2441 files to check for errors. Use the <B>bos getlog</B> command as
2442 instructed in <A HREF="auagd009.htm#HDRWQ173">Displaying Server Process Log Files</A> to read the <B>/usr/afs/logs/BackupLog</B> file, and a
2443 text editor on the Tape Coordinator machine to read the
2444 <B>TE_</B><VAR>device_name</VAR> and <B>TL_</B><VAR>device_name</VAR>
2445 files in the local <B>/usr/afs/backup</B> directory.
2446 </OL>
2447 <A NAME="IDX7077"></A>
2448 <HR><H2><A NAME="HDRWQ316" HREF="auagd002.htm#ToC_353">Maintaining the Backup Database</A></H2>
2449 <P>The Backup Database stores all of the configuration and
2450 tracking information that the Backup System uses when dumping and restoring
2451 data. If a hardware failure or other problem on a database server
2452 machine corrupts or damages the database, it is relatively easy to recreate
2453 the configuration information (the dump hierarchy and lists of volume sets and
2454 Tape Coordinator port offset numbers). However, restoring the dump
2455 tracking information (dump records) is more complicated and
2456 time-consuming. To protect yourself against loss of data, back up the
2457 Backup Database itself to tape on a regular schedule.
2458 <P>Another potential concern is that the Backup Database can grow large rather
2459 quickly, because the Backup System keeps very detailed and cross-referenced
2460 records of dump operations. Backup operations become less efficient if
2461 the Backup Server has to navigate through a large number of obsolete records
2462 to find the data it needs. To keep the database to a manageable size,
2463 use the <B>backup deletedump</B> command to delete obsolete records, as
2464 described in <A HREF="#HDRWQ321">Removing Obsolete Records from the Backup Database</A>. If you later find that you have removed records that
2465 you still need, you can use the <B>backup scantape</B> command to read the
2466 information from the dump and tape labels on the corresponding tapes back into
2467 the database, as instructed in <A HREF="#HDRWQ305">To scan the contents of a tape</A>.
2468 <A NAME="IDX7078"></A>
2469 <A NAME="IDX7079"></A>
2470 <A NAME="IDX7080"></A>
2471 <A NAME="IDX7081"></A>
2472 <A NAME="IDX7082"></A>
2473 <P><H3><A NAME="HDRWQ317" HREF="auagd002.htm#ToC_354">Backing Up and Restoring the Backup Database</A></H3>
2474 <P>Because of the importance of the information in the Backup
2475 Database, it is best to back it up to tape or other permanent media on a
2476 regular basis. As for the other AFS, administrative databases, the
2477 recommended method is to use a utility designed to back up a machine's
2478 local disk, such as the UNIX <B>tar</B> command. For instructions,
2479 see <A HREF="auagd008.htm#HDRWQ107">Backing Up and Restoring the Administrative Databases</A>.
2480 <P>In the rare event that the Backup Database seems damaged or corrupted, you
2481 can use the <B>backup dbverify</B> command to check its status. If
2482 it is corrupted, use the <B>backup savedb</B> command to repair some types
2483 of damage. Then use the <B>backup restoredb</B> to return the
2484 corrected database to the local disks of the database server machines.
2485 For instructions, see <A HREF="#HDRWQ318">Checking for and Repairing Corruption in the Backup Database</A>.
2486 <P><H3><A NAME="HDRWQ318" HREF="auagd002.htm#ToC_355">Checking for and Repairing Corruption in the Backup Database</A></H3>
2487 <P>In rare cases, the Backup Database can become damaged or
2488 corrupted, perhaps because of disk or other hardware errors. Use the
2489 <B>backup dbverify</B> command to check the integrity of the
2490 database. If it is corrupted, the most efficient way to repair it is to
2491 use the <B>backup savedb</B> command to copy the database to tape.
2492 The command automatically repairs several types of corruption, and you can
2493 then use the <B>backup restoredb</B> command to transfer the repaired copy
2494 of the database back to the local disks of the database server
2495 machines.
2496 <P>The <B>backup savedb</B> command also removes <I>orphan blocks</I>,
2497 which are ranges of memory that the Backup Server preallocated in the database
2498 but cannot use. Orphan blocks do not interfere with database access,
2499 but do waste disk space. The <B>backup dbverify</B> command reports
2500 the existence of orphan blocks if you include the <B>-detail</B>
2501 flag.
2502 <A NAME="IDX7083"></A>
2503 <A NAME="IDX7084"></A>
2504 <A NAME="IDX7085"></A>
2505 <P><H3><A NAME="HDRWQ319" HREF="auagd002.htm#ToC_356">To verify the integrity of the Backup Database</A></H3>
2506 <OL TYPE=1>
2507 <P><LI>Verify that you are authenticated as a user listed in the
2508 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
2509 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2510 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2511 </PRE>
2512 <P><LI>Issue the <B>backup dbverify</B> command to check the integrity of the
2513 Backup Database.
2514 <PRE>   % <B>backup dbverify</B> [<B>-detail</B>]
2515 </PRE>
2516 <P>where
2517 <DL>
2518 <P><DT><B>db
2519 </B><DD>Is the shortest acceptable abbreviation of <B>dbverify</B>.
2520 <P><DT><B>-detail
2521 </B><DD>Reports the existence of orphan blocks and other information about the
2522 database, as described on the <B>backup dbverify</B> reference page in the
2523 <I>IBM AFS Administration Reference</I>.
2524 </DL>
2525 <P>The output reports one of the following messages:
2526 <UL>
2527 <P><LI><TT>Database OK</TT> indicates that the Backup Database is
2528 undamaged.
2529 <P><LI><TT>Database not OK</TT> indicates that the Backup Database is
2530 damaged. To recover from the problem, use the instructions in <A HREF="#HDRWQ320">To repair corruption in the Backup Database</A>.
2531 </UL>
2532 </OL>
2533 <A NAME="IDX7086"></A>
2534 <A NAME="IDX7087"></A>
2535 <P><H3><A NAME="HDRWQ320" HREF="auagd002.htm#ToC_357">To repair corruption in the Backup Database</A></H3>
2536 <OL TYPE=1>
2537 <P><LI>Log in as the local superuser <B>root</B> on each database server
2538 machine in the cell.
2539 <P><LI><A NAME="LISAVEDB-STARTTC"></A>If the Tape Coordinator for the tape device that is to
2540 perform the operation is not already running, open a connection to the
2541 appropriate Tape Coordinator machine and issue the <B>butc</B> command,
2542 for which complete instructions appear in <A HREF="#HDRWQ292">To start a Tape Coordinator process</A>.
2543 <PRE>   % <B>butc</B> [&lt;<VAR>port offset</VAR>>] [<B>-noautoquery</B>]
2544 </PRE>
2545 <P><LI>If writing to tape, place a tape in the appropriate device.
2546 <P><LI>Working on one of the machines, issue the <B>backup</B> command to
2547 enter interactive mode.
2548 <PRE>   # <B> backup -localauth</B>
2549 </PRE>
2550 <P>where <B>-localauth</B> constructs a server ticket from the local
2551 <B>/usr/afs/etc/KeyFile</B> file. This flag enables you to issue a
2552 privileged command while logged in as the local superuser <B>root</B> but
2553 without AFS administrative tokens.
2554 <P><LI>Verify that no backup operations are actively running. If
2555 necessary, issue the <B>(backup) status</B> command as described in <A HREF="#HDRWQ295">To check the status of a Tape Coordinator process</A>. Repeat for each Tape Coordinator port offset in
2556 turn.
2557 <PRE>   backup> <B>status -portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>
2558 </PRE>
2559 <P><LI><A NAME="LISAVEDB-CMD"></A>Issue the <B>(backup) savedb</B> command to repair
2560 corruption in the database as it is written to tape or a file.
2561 <PRE>   backup> <B>savedb</B> [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
2562 </PRE>
2563 <P>where
2564 <DL>
2565 <P><DT><B>sa
2566 </B><DD>Is the shortest acceptable abbreviation of <B>savedb</B>.
2567 <P><DT><B>-portoffset
2568 </B><DD>Specifies the port offset number of the Tape Coordinator handling the tape
2569 or backup data file for this operation. You must provide this argument
2570 unless the default value of 0 (zero) is appropriate.
2571 </DL>
2572 <P><LI>Exit interactive mode.
2573 <PRE>   backup>  <B>quit</B>
2574 </PRE>
2575 <P><LI>On each machine in turn, issue the <B>bos shutdown</B> command to shut
2576 down the Backup Server process. Include the <B>-localauth</B> flag
2577 because you are logged in as the local superuser root, but do not necessarily
2578 have administrative tokens. For complete command syntax, see <A HREF="auagd009.htm#HDRWQ168">To stop processes temporarily</A>.
2579 <PRE>   # <B>/usr/afs/bin/bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>buserver  -localauth  -wait</B>
2580 </PRE>
2581 <P><LI>On each machine in turn, issue the following commands to remove the Backup
2582 Database.
2583 <PRE>   # <B>cd /usr/afs/db</B>
2584    # <B>rm bdb.DB0</B>
2585    # <B>rm bdb.DBSYS1</B>
2586 </PRE>
2587 <P><LI>On each machine in turn, starting with the machine with the lowest IP
2588 address, issue the <B>bos start</B> command to restart the Backup Server
2589 process, which creates a zero-length copy of the Backup Database as it
2590 starts. For complete command syntax, see <A HREF="auagd009.htm#HDRWQ166">To start processes by changing their status flags to Run</A>.
2591 <PRE>   # <B>/usr/afs/bin/bos start</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>buserver  -localauth</B>
2592 </PRE>
2593 <P><LI>Working on one of the machines, issue the <B>backup</B> command to
2594 enter interactive mode.
2595 <PRE>   # <B> backup -localauth</B>
2596 </PRE>
2597 <P>where <B>-localauth</B> constructs a server ticket from the local
2598 <B>/usr/afs/etc/KeyFile</B> file.
2599 <P><LI>Issue the <B>(backup) addhost</B> command to create an entry in the
2600 new, empty database for the Tape Coordinator process handling the tape or file
2601 from which you are reading the repaired copy of the database (presumably the
2602 process you started in Step <A HREF="#LISAVEDB-STARTTC">2</A> and which performed the <B>backup savedb</B> operation
2603 in Step <A HREF="#LISAVEDB-CMD">6</A>). For complete syntax, see Step <A HREF="auagd011.htm#LICONFTC-ADDHOST">8</A> in <A HREF="auagd011.htm#HDRWQ262">To configure a Tape Coordinator machine</A>.
2604 <PRE>   backup>  <B>addhost</B> &lt;<VAR>tape&nbsp;machine&nbsp;name</VAR>> [&lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
2605 </PRE>
2606 <A NAME="IDX7088"></A>
2607 <A NAME="IDX7089"></A>
2608 <P><LI>Issue the <B>(backup) restoredb</B> command to copy the repaired
2609 database to the database server machines.
2610 <PRE>   backup> <B>restoredb</B>  [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
2611 </PRE>
2612 <P>where
2613 <DL>
2614 <P><DT><B>res
2615 </B><DD>Is the shortest acceptable abbreviation of <B>restoredb</B>.
2616 <P><DT><B>-portoffset
2617 </B><DD>Specifies the port offset number of the Tape Coordinator handling the tape
2618 or backup data file for this operation. You must provide this argument
2619 unless the default value of <B>0</B> (zero) is appropriate.
2620 </DL>
2621 <P><LI><B>(Optional)</B> Exit interactive mode if you do not plan to issue
2622 any additional <B>backup</B> commands.
2623 <PRE>   backup> <B>quit</B>
2624 </PRE>
2625 <P><LI><B>(Optional)</B> If desired, enter <B>Ctrl-d</B> or another
2626 interrupt signal to exit the <B>root</B> shell on each database server
2627 machine. You can also issue the <B>Ctrl-c</B> signal on the Tape
2628 Coordinator machine to stop the process.
2629 </OL>
2630 <A NAME="IDX7090"></A>
2631 <A NAME="IDX7091"></A>
2632 <P><H3><A NAME="HDRWQ321" HREF="auagd002.htm#ToC_358">Removing Obsolete Records from the Backup Database</A></H3>
2633 <P>Whenever you recycle or relabel a tape using the <B>backup
2634 dump</B> or <B>backup labeltape</B> command, the Backup System
2635 automatically removes all of the dump records for the dumps contained on the
2636 tape and all other tapes in the dump set. However, obsolete records can
2637 still accumulate in the Backup Database over time. For example, when
2638 you discard a backup tape after using it the maximum number of times
2639 recommended by the manufacturer, the records for dumps on it remain in the
2640 database. Similarly, the Backup System does not automatically remove a
2641 dump's record when the dump reaches its expiration date, but only if you
2642 then recycle or relabel the tape that contains the dump. Finally, if a
2643 backup operation halts in the middle, the records for any volumes successfully
2644 written to tape before the halt remain in the database.
2645 <P>A very large Backup Database can make backup operations less efficient
2646 because the Backup Server has to navigate through a large number of records to
2647 find the ones it needs. To remove obsolete records, use the <B>backup
2648 deletedump</B> command. Either identify individual dumps by dump ID
2649 number, or specify the removal of all dumps created during a certain time
2650 period. Keep in mind that you cannot remove the record of an appended
2651 dump except by removing the record of its initial dump, which removes the
2652 records of all associated appended dumps. Removing records of a dump
2653 makes it impossible to restore data from the corresponding tapes or from any
2654 dump that refers to the deleted dump as its parent, directly or
2655 indirectly. That is, restore operations must begin with the full dump
2656 and continue with each incremental dump in order. If you have removed
2657 the records for a specific dump, you cannot restore any data from later
2658 incremental dumps.
2659 <P>Another way to truncate the Backup Database is to include the
2660 <B>-archive</B> argument to the <B>backup savedb</B> command.
2661 After a copy of the database is written to tape or to a backup data file, the
2662 Backup Server deletes the dump records for all dump operations with timestamps
2663 prior to the date and time you specify. However, issuing the
2664 <B>backup deletedump</B> command with only the <B>-to</B> argument is
2665 equivalent in effect and is simpler because it does not require starting a
2666 Tape Coordinator process as the <B>backup savedb</B> command does.
2667 For further information on the <B>-archive</B> argument to the <B>backup
2668 savedb</B> command, see the command's reference page in the <I>IBM
2669 AFS Administration Reference</I>.
2670 <P>If you later need to access deleted dump records, and the corresponding
2671 tapes still exist, you can use the <B>-dbadd</B> argument to the
2672 <B>backup scantape</B> command to scan their contents into the database,
2673 as instructed in <A HREF="#HDRWQ305">To scan the contents of a tape</A>.
2674 <A NAME="IDX7092"></A>
2675 <A NAME="IDX7093"></A>
2676 <P><H3><A NAME="HDRWQ322" HREF="auagd002.htm#ToC_359">To delete dump records from the Backup Database</A></H3>
2677 <OL TYPE=1>
2678 <P><LI>Verify that you are authenticated as a user listed in the
2679 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
2680 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ593">To display the users in the UserList file</A>.
2681 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
2682 </PRE>
2683 <P><LI><B>(Optional)</B> Issue the <B>backup</B> command to enter
2684 interactive mode, if you want to delete multiple records or issue additional
2685 commands. The interactive prompt appears in the following step.
2686 <PRE>   % <B>backup</B>
2687 </PRE>
2688 <P><LI><B>(Optional)</B> Issue the <B>backup dumpinfo</B> command to list
2689 information from the Backup Database that can help you decide which records to
2690 delete. For detailed instructions, see <A HREF="#HDRWQ303">To display dump records</A>.
2691 <PRE>   backup> <B>dumpinfo</B> [&lt;<VAR>no.&nbsp;of&nbsp;dumps</VAR>>]  [<B>-id</B> &lt;<VAR>dump&nbsp;id</VAR>>]  [<B>-verbose</B>]
2692 </PRE>
2693 <P><LI>Issue the <B>backup deletedump</B> command to delete one or more dump
2694 sets.
2695 <PRE>   backup> <B>deletedump</B> [<B>-dumpid</B> &lt;<VAR>dumpid</VAR>><SUP>+</SUP>] [<B>-from</B> &lt;<VAR>date&nbsp;time</VAR>>]  \
2696                       [<B>-to</B> &lt;<VAR>date&nbsp;time</VAR>>]
2697 </PRE>
2698 <P>where
2699 <DL>
2700 <P><DT><B>dele
2701 </B><DD>Is the shortest acceptable abbreviation of <B>deletedump</B>.
2702 <P><DT><B>-dumpid
2703 </B><DD>Specifies the dump ID of each initial dump to delete from the Backup
2704 Database. The records for all associated appended dumps are also
2705 deleted. Provide either this argument or the <B>-to</B> (and
2706 optionally, <B>-from</B>) argument.
2707 <P><DT><B>-from
2708 </B><DD>Specifies the beginning of a range of dates; the record for any dump
2709 created during the indicated period of time is deleted.
2710 <P>To omit all records before the time indicated with the <B>-to</B>
2711 argument, omit this argument. Otherwise provide a value in the
2712 following format
2713 <P><VAR>mm</VAR>/<VAR>dd</VAR>/<VAR>yyyy</VAR> [<VAR>hh</VAR>:<VAR>MM</VAR>]
2714 <P>where the month (<VAR>mm</VAR>), day (<VAR>dd</VAR>), and year (<VAR>yyyy</VAR>)
2715 are required. You can omit the hour and minutes
2716 (<VAR>hh</VAR>:<VAR>MM</VAR>) to indicate the default of midnight
2717 (00:00 hours). If you provide them, use 24-hour format (for
2718 example, the value <B>14:36</B> represents 2:36
2719 p.m.).
2720 <P>You must provide the <B>-to</B> argument along with this one.
2721 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A plus sign follows this argument in the command's syntax statement
2722 because it accepts a multiword value which does not need to be enclosed in
2723 double quotes or other delimiters, not because it accepts multiple
2724 dates. Provide only one date (and optionally, time) definition.
2725 </TD></TR></TABLE>
2726 <P><DT><B>-to
2727 </B><DD>Specifies the end of a range of dates; the record of any dump created
2728 during the range is deleted from the Backup Database.
2729 <P>To delete all records created after the date you specify with the
2730 <B>-from</B> argument, specify the value <B>NOW</B>. To delete
2731 every dump record in the Backup Database, provide the value <B>NOW</B> and
2732 omit the <B>-from</B> argument. Otherwise, provide a date value in
2733 the same format as described for the <B>-from</B> argument. Valid
2734 values for the year (<VAR>yyyy</VAR>) range from <B>1970</B> to
2735 <B>2037</B>; higher values are not valid because the latest possible
2736 date in the standard UNIX representation is in early 2038. The command
2737 interpreter automatically reduces any later date to the maximum value in
2738 2038.
2739 <P>If you omit the time portion (<VAR>hh</VAR>:<VAR>MM</VAR>), it defaults
2740 to 59 seconds after midnight (00:00:59 hours). Similarly,
2741 the <B>backup</B> command interpreter automatically adds 59 seconds to any
2742 time value you provide. In both cases, adding 59 seconds compensates
2743 for how the Backup Database and <B>backup dumpinfo</B> command represent
2744 dump creation times in hours and minutes only. For example, the
2745 Database records a creation timestamp of <TT>20:55</TT> for any dump
2746 operation that begins between 20:55:00 and
2747 20:55:59. Automatically adding 59 seconds to a time thus
2748 includes the records for all dumps created during that minute.
2749 <P>Provide either this argument, or the <B>-dumpid</B> argument.
2750 This argument is required if the <B>-from</B> argument is provided.
2751 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A plus sign follows this argument in the command's syntax statement
2752 because it accepts a multiword value which does not need to be enclosed in
2753 double quotes or other delimiters, not because it accepts multiple
2754 dates. Provide only one date (and optionally, time) definition.
2755 </TD></TR></TABLE>
2756 </DL>
2757 </OL>
2758 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd011.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auagd013.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
2759 <!-- Begin Footer Records  ========================================== -->
2760 <P><HR><B>
2761 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
2762 </B>
2763 <!-- End Footer Records  ============================================ -->
2764 <A NAME="Bot_Of_Page"></A>
2765 </BODY></HTML>