3 backup scantape - Extracts dump information from a tape
10 B<backup scantape> [B<-dbadd>] S<<< [B<-portoffset> <I<TC port offset>>] >>>
11 [B<-localauth>] S<<< [B<-cell> <I<cell name>>] >>> [B<-help>]
13 B<backup sc> [B<-d>] S<<< [B<-p> <I<TC port offset>>] >>> [B<-l>]
14 S<<< [B<-c> <I<cell name>>] >>> [B<-h>]
21 The B<backup scantape> command extracts information from the dump labels
22 and volume headers on the tape in the device controlled by the Tape
23 Coordinator indicated by the B<-portoffset> argument. The Tape Coordinator
24 displays the information for each volume in its window as soon as it
25 extracts it (rather than waiting until it has scanned the entire tape).
27 (If the C<FILE YES> instruction appears in the
28 F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
29 port offset, then the B<backup scantape> command extracts dump information
30 from the backup data file named in that port offset's entry in the
31 F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, rather
32 than from a tape. For the sake of clarity, the following text refers to
33 tapes only, but the Backup System handles backup data files in much the
36 If the B<-dbadd> flag is provided, the backup scantape command creates new
37 dump and volume records in the Backup Database for the scanned
38 information. However, if it finds that a record already exists in the
39 database for the same dump, it terminates the scanning operation.
41 The scanning operation works only on tapes containing volume data. The
42 command fails with an error message if the tape contains a copy of the
43 Backup Database (was created with the B<backup savedb> command, or has the
44 AFS tape name C<Ubik_db_dump.1>).
46 The Tape Coordinator's default response to this command is to access the
47 tape by invoking the C<MOUNT> instruction in the F<CFG_I<device_name>>
48 file, or by prompting the backup operator to insert the tape if there is
49 no C<MOUNT> instruction. However, if the C<AUTOQUERY NO> instruction
50 appears in the F<CFG_I<device_name>> file, or if the issuer of the B<butc>
51 command included the B<-noautoquery> flag, the Tape Coordinator instead
52 expects the tape to be in the device already. If it is not, the Tape
53 Coordinator invokes the C<MOUNT> instruction or prompts the operator.
55 To terminate a tape scanning operation in interactive mode, issue the
56 B<backup kill> command. In noninteractive mode, the only choice is to use
57 a termination signal such as Ctrl-C to halt the Tape Coordinator
62 A scanning operation does not have to begin with the first tape in a dump
63 set, but the Backup System can process tapes only in sequential order
64 after the initial tape provided. The Tape Coordinator automatically
65 requests any subsequent tapes by invoking the C<MOUNT> instruction in the
66 local F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the
67 operator if there is no C<MOUNT> instruction.
69 The Tape Coordinator's success in scanning a tape that is corrupted or
70 damaged depends on the extent of the damage and what type of data is
71 corrupted. It can almost always scan the tape successfully up to the point
72 of damage. If the damage is minor, the Tape Coordinator can usually skip
73 over it and scan the rest of the tape, but more major damage can prevent
74 further scanning. Because a scanning operation can start on any tape in a
75 dump set, damage on one tape does not prevent scanning of the others in
76 the dump set. However, it is possible to scan either the tapes that
77 precede the damaged one or the ones that follow it, but not both.
79 If a tape is relabeled with the backup labeltape command, it is not
80 possible to recover data from it for the purposes of rebuilding the Backup
83 If the B<-dbadd> flag is included on the command, it is best not to
84 terminate the tape scanning operation before it completes (for example, by
85 issuing the B<backup kill> command in interactive mode). The Backup System
86 writes a new record in the Backup Database for each dump as soon as it
87 scans the relevant information on the tape, and so it possibly has already
88 written new records. If the operator wants to rerun the scanning
89 operation, he or she must locate and remove the records created during the
90 terminated operation: the second operation exits automatically if it finds
91 that a record that it needs to create already exists.
93 If the B<-dbadd> flag is included and the first tape provided is not the
94 first tape in the dump set, the following restrictions apply:
100 If the first data on the tape is a continuation of a volume that begins on
101 the previous (unscanned) tape in the dump set, the Backup System does not
102 add a record for that volume to the Backup Database.
106 The Backup System must read the marker that indicates the start of an
107 appended dump to add database records for the volumes in it. If the first
108 volume on the tape belongs to an appended dump, but is not immediately
109 preceded by the appended-dump marker, the Backup System does not create a
110 Backup Database record for it or any subsequent volumes that belong to
121 Adds the information extracted from the tape to the Backup Database (but
122 only if the database does not already contain an entry with the same dump
125 =item B<-portoffset> <I<TC port offset>>
127 Specifies the port offset number of the Tape Coordinator handling the
128 tapes for this operation.
132 Constructs a server ticket using a key from the local
133 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
134 it to the Backup Server, Volume Server and VL Server during mutual
135 authentication. Do not combine this flag with the B<-cell> argument. For
136 more details, see L<backup(8)>.
138 =item B<-cell> <I<cell name>>
140 Names the cell in which to run the command. Do not combine this argument
141 with the B<-localauth> flag. For more details, see L<backup(8)>.
145 Prints the online help for this command. All other valid options are
152 For every dump on a tape, the backup scantape command displays in the Tape
153 Coordinator window the dump label and the volume header of each volume in
154 the dump. If a dump spans more than one tape, the dump label does not
155 repeat at the beginning of subsequent tapes.
157 A dump label contains the following fields, which are the same as in the
158 output from the B<backup readlabel> command:
164 The permanent name assigned by using the B<-pname> argument of the
165 B<backup labeltape> command. This name remains on the tape until that
166 argument is used again, no matter how many times the tape is recycled or
167 otherwise relabeled. If the tape does not have a permanent name, the value
168 C<< <NULL> >> appears in this field.
172 A tape name in one of the following prescribed formats. The Backup System
173 automatically writes the appropriate AFS tape name to the label as part of
174 a B<backup dump> operation, or the operator can assign it with the
175 B<-name> argument to the B<backup labeltape> command.
181 I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape contains
182 volume data. The I<volume_set_name> is the name of the volume set that was
183 dumped to create the initial dump in the dump set of which this tape is a
184 part; I<dump_level_name> is the last pathname element of the dump level at
185 which the initial dump was backed up; and I<tape_index> is the numerical
186 position of the tape in the dump set.
190 C<< <NULL> >> if the tape has no AFS tape name. This is normally the case
191 if the B<-name> argument was not included the last time the B<backup
192 labeltape> command was used on this tape, and no data has been written to
199 The date and time at which the Backup System started performing the dump
200 operation that created the initial dump.
204 The cell in which the dump set was created. This is the cell whose Backup
205 Database contains a record of the dump set.
209 The tape's capacity (in kilobytes) as recorded on the label, rather than
210 the amount of data on the tape. The value is assigned by the B<-size>
211 argument to the B<backup labeltape> command or derived from the
212 F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
213 from a measurement of the tape.
217 The dump level of the initial dump in the dump set.
221 The dump ID number of the initial dump in the dump set, as recorded in the
226 The number of times a dump has been written to the tape, or it has been
231 The volume header contains the following fields:
237 The volume name, complete with a C<.backup> or C<.readonly> extension, if
242 The volume's volume ID.
246 The dump to which the volume belongs. The dump name is of the form
247 I<volume_set_name>.I<dump_level_name> and matches the name displayed in
252 The dump ID of the dump named in the C<dumpSetName> field.
256 The depth in the dump hierarchy of the dump level used in creating the
257 dump. A value of C<0> indicates a full dump. A value of C<1> or greater
258 indicates an incremental dump made at the indicated depth in the
259 hierarchy. The value reported is for the entire dump, not necessarily for
260 the volume itself; for example, it is possible for a dump performed at an
261 incremental level to include a full dump of an individual volume if the
262 volume was omitted from previous dumps.
266 The dump ID number of C<dumpSetName>'s parent dump. It is C<0> if the
267 value in the C<level> field is C<0>.
271 Is always C<0>; it is reserved for internal use.
275 The date and time at which the volume was created. For a backup or
276 read-only volume, this represents the time at which it was cloned from its
277 read/write source. For a read/write volume, it indicates the time at which
278 the Backup System locked the volume for purposes of including it in the
279 dump named in the C<dumpSetName> field.
283 The message C<Scantape: Finished> indicates the completion of the output.
285 In normal circumstances, the Backup System writes a marker to indicate
286 that a volume is the last one on a tape, or that the volume continues on
287 the next tape. However, if a backup operation terminated abnormally (for
288 example, because the operator terminated the Tape Coordinator by issuing
289 the Ctrl-C command during the operation), then there is no such
290 marker. Some very early versions of the Backup System also did not write
291 these markers. If a tape does not conclude with one of the expected
292 markers, the Tape Coordinator cannot determine if there is a subsequent
293 tape in the dump set and so generates the following message in its window:
295 Are there more tapes? (y/n)
299 The following example shows the output for the first two volumes on a tape
300 in the device with port offset 0:
305 tape name = monthly_guest
306 AFS tape name = guests.monthly.3
307 creationTime = Mon Feb 1 04:06:40 1999
309 size = 2150000 Kbytes
313 -- End of dump label --
315 volume name: user.guest10.backup
317 dumpSetName: guests.monthly
322 clonedate Mon Feb 1 03:03:23 1999
324 volume name: user.guest11.backup
326 dumpSetName: guests.monthly
331 clonedate Mon Feb 1 03:05:15 1999
333 =head1 PRIVILEGE REQUIRED
335 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
336 machine where the Backup Server is running, or must be logged onto a
337 server machine as the local superuser C<root> if the B<-localauth> flag is
345 L<backup_dumpinfo(8)>,
350 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
352 This documentation is covered by the IBM Public License Version 1.0. It was
353 converted from HTML to POD by software written by Chas Williams and Russ
354 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.