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