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