3 backup scantape - Extracts dump information from a tape
7 B<backup scantape> [B<-dbadd>] [-portoffset <I<TC port offset>>]
8 [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
10 B<backup sc> [B<-d>] [B<-p> <I<TC port offset>>] [B<-l>] [B<-c> <I<cell name>>] [-help]
14 The backup scantape command extracts information from the dump
15 labels and volume headers on the tape in the device controlled by the Tape
16 Coordinator indicated by the B<-portoffset> argument. The Tape
17 Coordinator displays the information for each volume in its window as soon as
18 it extracts it (rather than waiting until it has scanned the entire
21 (If the FILE YES instruction appears in the
22 B</usr/afs/backup/CFG_>I<device_name> file associated with the
23 specified port offset, then the B<backup scantape> command extracts
24 dump information from the backup data file named in that port offset's
25 entry in the B</usr/afs/backup/tapeconfig> file on the Tape
26 Coordinator machine, rather than from a tape. For the sake of clarity,
27 the following text refers to tapes only, but the Backup System handles backup
28 data files in much the same way.)
30 If the B<-dbadd> flag is provided, the backup scantape
31 command creates new dump and volume records in the Backup Database for the
32 scanned information. However, if it finds that a record already exists
33 in the database for the same dump, it terminates the scanning
36 The scanning operation works only on tapes containing volume data.
37 The command fails with an error message if the tape contains a copy of the
38 Backup Database (was created with the B<backup savedb> command, or has
39 the AFS tape name B<Ubik_db_dump.1>).
41 The Tape Coordinator's default response to this command is to access
42 the tape by invoking the B<MOUNT> instruction in the
43 B<CFG_>I<device_name> file, or by prompting the backup operator
44 to insert the tape if there is no B<MOUNT> instruction.
45 However, if the B<AUTOQUERY NO> instruction appears in the
46 B<CFG_>I<device_name> file, or if the issuer of the
47 B<butc> command included the B<-noautoquery> flag, the Tape
48 Coordinator instead expects the tape to be in the device already. If it
49 is not, the Tape Coordinator invokes the B<MOUNT> instruction or
52 To terminate a tape scanning operation in interactive mode, issue the
53 B<(backup) kill> command. In noninteractive mode, the only
54 choice is to use a termination signal such as <B<Ctrl-c>> to halt
55 the Tape Coordinator completely.
59 A scanning operation does not have to begin with the first tape in a dump
60 set, but the Backup System can process tapes only in sequential order after
61 the initial tape provided. The Tape Coordinator automatically requests
62 any subsequent tapes by invoking the B<MOUNT> instruction in the local
63 B</usr/afs/backup/CFG_>I<device_name> file, or by prompting the
64 operator if there is no B<MOUNT> instruction.
66 The Tape Coordinator's success in scanning a tape that is corrupted or
67 damaged depends on the extent of the damage and what type of data is
68 corrupted. It can almost always scan the tape successfully up to the
69 point of damage. If the damage is minor, the Tape Coordinator can
70 usually skip over it and scan the rest of the tape, but more major damage can
71 prevent further scanning. Because a scanning operation can start on any
72 tape in a dump set, damage on one tape does not prevent scanning of the others
73 in the dump set. However, it is possible to scan either the tapes that
74 precede the damaged one or the ones that follow it, but not both.
76 If a tape is relabeled with the backup labeltape command, it is
77 not possible to recover data from it for the purposes of rebuilding the Backup
80 If the -dbadd flag is included on the command, it is best not to
81 terminate the tape scanning operation before it completes (for example, by
82 issuing the B<(backup) kill> command in interactive mode). The
83 Backup System writes a new record in the Backup Database for each dump as soon
84 as it scans the relevant information on the tape, and so it possibly has
85 already written new records. If the operator wants to rerun the
86 scanning operation, he or she must locate and remove the records created
87 during the terminated operation: the second operation exits
88 automatically if it finds that a record that it needs to create already
91 If the -dbadd flag is included and the first tape provided is
92 not the first tape in the dump set, the following restrictions apply:
98 If the first data on the tape is a continuation of a volume that begins on
99 the previous (unscanned) tape in the dump set, the Backup System does not add
100 a record for that volume to the Backup Database.
105 The Backup System must read the marker that indicates the start of an
106 appended dump to add database records for the volumes in it. If the
107 first volume on the tape belongs to an appended dump, but is not immediately
108 preceded by the appended-dump marker, the Backup System does not create a
109 Backup Database record for it or any subsequent volumes that belong to that
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 ID
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 B</usr/afs/etc/KeyFile> file. The B<backup> command
134 interpreter presents it to the Backup Server, Volume Server and VL Server
135 during mutual authentication. Do not combine this flag with the
136 B<-cell> argument. For more details, see the introductory
137 B<backup> reference page.
141 Names the cell in which to run the command. Do not combine this
142 argument with the B<-localauth> flag. For more details, see the
143 introductory B<backup> reference page.
147 Prints the online help for this command. All other valid options
154 For every dump on a tape, the backup scantape command displays
155 in the Tape Coordinator window the dump label and the volume header of each
156 volume in the dump. If a dump spans more than one tape, the dump label
157 does not repeat at the beginning of subsequent tapes.
159 A dump label contains the following fields, which are the same as in the
160 output from the B<backup readlabel> command:
167 The permanent name assigned by using the -pname argument of the
168 B<backup labeltape> command. This name remains on the tape
169 until that argument is used again, no matter how many times the tape is
170 recycled or otherwise relabeled. If the tape does not have a permanent
171 name, the value C<<NULL>> appears in this field.
173 =item C<AFS tape name
176 A tape name in one of the following prescribed formats. The Backup
177 System automatically writes the appropriate AFS tape name to the label as part
178 of a B<backup dump> operation, or the operator can assign it with the
179 B<-name> argument to the B<backup labeltape> command.
185 I<volume_set_name>.I<dump_level_name>.I<tape
186 _index>, if the tape contains volume data. The
187 I<volume_set_name> is the name of the volume set that was dumped to
188 create the initial dump in the dump set of which this tape is a part;
189 I<dump_level_name> is the last pathname element of the dump level at
190 which the initial dump was backed up; and I<tape_index> is the
191 numerical position of the tape in the dump set.
196 C<<NULL>> if the tape has no AFS tape name. This is
197 normally the case if the B<-name> argument was not included the last
198 time the B<backup labeltape> command was used on this tape, and no
199 data has been written to it since.
207 The date and time at which the Backup System started performing the dump
208 operation that created the initial dump.
213 The cell in which the dump set was created. This is the cell whose
214 Backup Database contains a record of the dump set.
219 The tape's capacity (in kilobytes) as recorded on the label, rather
220 than the amount of data on the tape. The value is assigned by the
221 B<-size> argument to the B<backup labeltape> command or
222 derived from the B</usr/afs/backup/tapeconfig> file on the Tape
223 Coordinator machine, not from a measurement of the tape.
228 The dump level of the initial dump in the dump set.
233 The dump ID number of the initial dump in the dump set, as recorded in the
239 The number of times a dump has been written to the tape, or it has been
244 The volume header contains the following fields:
248 =item C<volume C<name>
251 The volume name, complete with a C<.backup> or
252 C<.readonly> extension, if appropriate.
257 The volume's volume ID.
262 The dump to which the volume belongs. The dump name is of the form
263 I<volume_set_name>B<.>I<dump_level_name> and
264 matches the name displayed in the dump label.
269 The dump ID of the dump named in the C<dumpSetName> field.
274 The depth in the dump hierarchy of the dump level used in creating the
275 dump. A value of C<0> indicates a full dump. A value of
276 C<1> or greater indicates an incremental dump made at the indicated
277 depth in the hierarchy. The value reported is for the entire dump, not
278 necessarily for the volume itself; for example, it is possible for a dump
279 performed at an incremental level to include a full dump of an individual
280 volume if the volume was omitted from previous dumps.
285 The dump ID number of C<dumpSetName>'s parent dump. It
286 is C<0> if the value in the C<level> field is
292 Is always C<0>; it is reserved for internal use.
297 The date and time at which the volume was created. For a backup or
298 read-only volume, this represents the time at which it was cloned from its
299 read/write source. For a read/write volume, it indicates the time at
300 which the Backup System locked the volume for purposes of including it in the
301 dump named in the C<dumpSetName> field.
305 The message C<Scantape: Finished> indicates the completion of
308 In normal circumstances, the Backup System writes a marker to indicate that
309 a volume is the last one on a tape, or that the volume continues on the next
310 tape. However, if a backup operation terminated abnormally (for
311 example, because the operator terminated the Tape Coordinator by issuing the
312 <B<Ctrl-c>> command during the operation), then there is no such
313 marker. Some very early versions of the Backup System also did not
314 write these markers. If a tape does not conclude with one of the
315 expected markers, the Tape Coordinator cannot determine if there is a
316 subsequent tape in the dump set and so generates the following message in its
319 Are there more tapes? (y/n)
323 The following example shows the output for the first two volumes on a tape
324 in the device with port offset 0:
329 tape name = monthly_guest
330 AFS tape name = guests.monthly.3
331 creationTime = Mon Feb 1 04:06:40 1999
333 size = 2150000 Kbytes
337 -- End of dump label --
339 volume name: user.guest10.backup
341 dumpSetName: guests.monthly
346 clonedate Mon Feb 1 03:03:23 1999
348 volume name: user.guest11.backup
350 dumpSetName: guests.monthly
355 clonedate Mon Feb 1 03:05:15 1999
357 =head1 PRIVILEGE REQUIRED
359 The issuer must be listed in the /usr/afs/etc/UserList file on
360 every machine where the Backup Server is running, or must be logged onto a
361 server machine as the local superuser B<root> if the
362 B<-localauth> flag is included.
368 L<backup_dumpinfo(1)>,
373 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
375 This documentation is covered by the IBM Public License Version 1.0. It was
376 converted from HTML to POD by software written by Chas Williams and Russ
377 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.