pod-updates-20060227
[openafs.git] / doc / man-pages / pod8 / backup_scantape.pod
1 =head1 NAME
2
3 backup scantape - Extracts dump information from a tape
4
5 =head1 SYNOPSIS
6
7 B<backup scantape> [B<-dbadd>] [B<-portoffset> <I<TC port offset>>]
8     [B<-localauth>] [B<-cell> <I<cell name>>] [B<-help>]
9
10 B<backup sc> [B<-d>] [B<-p> <I<TC port offset>>] [B<-l>]
11     [B<-c> <I<cell name>>] [B<-h>]
12
13 =head1 DESCRIPTION
14
15 The B<backup scantape> command extracts information from the dump labels
16 and volume headers on the tape in the device controlled by the Tape
17 Coordinator indicated by the B<-portoffset> argument. The Tape Coordinator
18 displays the information for each volume in its window as soon as it
19 extracts it (rather than waiting until it has scanned the entire tape).
20
21 (If the C<FILE YES> instruction appears in the
22 F</usr/afs/backup/CFG_I<device_name>> file associated with the specified
23 port offset, then the B<backup scantape> command extracts dump information
24 from the backup data file named in that port offset's entry in the
25 F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, rather
26 than from a tape. For the sake of clarity, the following text refers to
27 tapes only, but the Backup System handles backup data files in much the
28 same way.)
29
30 If the B<-dbadd> flag is provided, the backup scantape command creates new
31 dump and volume records in the Backup Database for the scanned
32 information. However, if it finds that a record already exists in the
33 database for the same dump, it terminates the scanning operation.
34
35 The scanning operation works only on tapes containing volume data.  The
36 command fails with an error message if the tape contains a copy of the
37 Backup Database (was created with the B<backup savedb> command, or has the
38 AFS tape name C<Ubik_db_dump.1>).
39
40 The Tape Coordinator's default response to this command is to access the
41 tape by invoking the C<MOUNT> instruction in the F<CFG_I<device_name>>
42 file, or by prompting the backup operator to insert the tape if there is
43 no C<MOUNT> instruction.  However, if the C<AUTOQUERY NO> instruction
44 appears in the F<CFG_I<device_name>> file, or if the issuer of the B<butc>
45 command included the B<-noautoquery> flag, the Tape Coordinator instead
46 expects the tape to be in the device already. If it is not, the Tape
47 Coordinator invokes the C<MOUNT> instruction or prompts the operator.
48
49 To terminate a tape scanning operation in interactive mode, issue the
50 B<backup kill> command. In noninteractive mode, the only choice is to use
51 a termination signal such as Ctrl-C to halt the Tape Coordinator
52 completely.
53
54 =head1 CAUTIONS
55
56 A scanning operation does not have to begin with the first tape in a dump
57 set, but the Backup System can process tapes only in sequential order
58 after the initial tape provided. The Tape Coordinator automatically
59 requests any subsequent tapes by invoking the C<MOUNT> instruction in the
60 local F</usr/afs/backup/CFG_I<device_name>> file, or by prompting the
61 operator if there is no C<MOUNT> instruction.
62
63 The Tape Coordinator's success in scanning a tape that is corrupted or
64 damaged depends on the extent of the damage and what type of data is
65 corrupted. It can almost always scan the tape successfully up to the point
66 of damage. If the damage is minor, the Tape Coordinator can usually skip
67 over it and scan the rest of the tape, but more major damage can prevent
68 further scanning. Because a scanning operation can start on any tape in a
69 dump set, damage on one tape does not prevent scanning of the others in
70 the dump set. However, it is possible to scan either the tapes that
71 precede the damaged one or the ones that follow it, but not both.
72
73 If a tape is relabeled with the backup labeltape command, it is not
74 possible to recover data from it for the purposes of rebuilding the Backup
75 Database.
76
77 If the B<-dbadd> flag is included on the command, it is best not to
78 terminate the tape scanning operation before it completes (for example, by
79 issuing the B<backup kill> command in interactive mode). The Backup System
80 writes a new record in the Backup Database for each dump as soon as it
81 scans the relevant information on the tape, and so it possibly has already
82 written new records. If the operator wants to rerun the scanning
83 operation, he or she must locate and remove the records created during the
84 terminated operation: the second operation exits automatically if it finds
85 that a record that it needs to create already exists.
86
87 If the B<-dbadd> flag is included and the first tape provided is not the
88 first tape in the dump set, the following restrictions apply:
89
90 =over 4
91
92 =item *
93
94 If the first data on the tape is a continuation of a volume that begins on
95 the previous (unscanned) tape in the dump set, the Backup System does not
96 add a record for that volume to the Backup Database.
97
98 =item *
99
100 The Backup System must read the marker that indicates the start of an
101 appended dump to add database records for the volumes in it. If the first
102 volume on the tape belongs to an appended dump, but is not immediately
103 preceded by the appended-dump marker, the Backup System does not create a
104 Backup Database record for it or any subsequent volumes that belong to
105 that appended dump.
106
107 =back
108
109 =head1 OPTIONS
110
111 =over 4
112
113 =item B<-dbadd>
114
115 Adds the information extracted from the tape to the Backup Database (but
116 only if the database does not already contain an entry with the same dump
117 ID number).
118
119 =item B<-portoffset> <I<TC port offset>>
120
121 Specifies the port offset number of the Tape Coordinator handling the
122 tapes for this operation.
123
124 =item B<-localauth>
125
126 Constructs a server ticket using a key from the local
127 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
128 it to the Backup Server, Volume Server and VL Server during mutual
129 authentication. Do not combine this flag with the B<-cell> argument. For
130 more details, see L<backup(8)>.
131
132 =item B<-cell> <I<cell name>>
133
134 Names the cell in which to run the command. Do not combine this argument
135 with the B<-localauth> flag. For more details, see L<backup(8)>.
136
137 =item B<-help>
138
139 Prints the online help for this command. All other valid options are
140 ignored.
141
142 =back
143
144 =head1 OUTPUT
145
146 For every dump on a tape, the backup scantape command displays in the Tape
147 Coordinator window the dump label and the volume header of each volume in
148 the dump. If a dump spans more than one tape, the dump label does not
149 repeat at the beginning of subsequent tapes.
150
151 A dump label contains the following fields, which are the same as in the
152 output from the B<backup readlabel> command:
153
154 =over 4
155
156 =item tape name
157
158 The permanent name assigned by using the B<-pname> argument of the
159 B<backup labeltape> command. This name remains on the tape until that
160 argument is used again, no matter how many times the tape is recycled or
161 otherwise relabeled. If the tape does not have a permanent name, the value
162 C<< <NULL> >> appears in this field.
163
164 =item AFS tape name
165
166 A tape name in one of the following prescribed formats. The Backup System
167 automatically writes the appropriate AFS tape name to the label as part of
168 a B<backup dump> operation, or the operator can assign it with the
169 B<-name> argument to the B<backup labeltape> command.
170
171 =over 4
172
173 =item *
174
175 I<volume_set_name>.I<dump_level_name>.I<tape_index>, if the tape contains
176 volume data. The I<volume_set_name> is the name of the volume set that was
177 dumped to create the initial dump in the dump set of which this tape is a
178 part; I<dump_level_name> is the last pathname element of the dump level at
179 which the initial dump was backed up; and I<tape_index> is the numerical
180 position of the tape in the dump set.
181
182 =item *
183
184 C<< <NULL> >> if the tape has no AFS tape name. This is normally the case
185 if the B<-name> argument was not included the last time the B<backup
186 labeltape> command was used on this tape, and no data has been written to
187 it since.
188
189 =back
190
191 =item creationTime
192
193 The date and time at which the Backup System started performing the dump
194 operation that created the initial dump.
195
196 =item cell
197
198 The cell in which the dump set was created. This is the cell whose Backup
199 Database contains a record of the dump set.
200
201 =item size
202
203 The tape's capacity (in kilobytes) as recorded on the label, rather than
204 the amount of data on the tape. The value is assigned by the B<-size>
205 argument to the B<backup labeltape> command or derived from the
206 F</usr/afs/backup/tapeconfig> file on the Tape Coordinator machine, not
207 from a measurement of the tape.
208
209 =item dump path
210
211 The dump level of the initial dump in the dump set.
212
213 =item dump id
214
215 The dump ID number of the initial dump in the dump set, as recorded in the
216 Backup Database.
217
218 =item useCount
219
220 The number of times a dump has been written to the tape, or it has been
221 relabeled.
222
223 =back
224
225 The volume header contains the following fields:
226
227 =over 4
228
229 =item volume name
230
231 The volume name, complete with a C<.backup> or C<.readonly> extension, if
232 appropriate.
233
234 =item volume ID
235
236 The volume's volume ID.
237
238 =item dumpSetName
239
240 The dump to which the volume belongs. The dump name is of the form
241 I<volume_set_name>.I<dump_level_name> and matches the name displayed in
242 the dump label.
243
244 =item dumpID
245
246 The dump ID of the dump named in the C<dumpSetName> field.
247
248 =item level
249
250 The depth in the dump hierarchy of the dump level used in creating the
251 dump. A value of C<0> indicates a full dump. A value of C<1> or greater
252 indicates an incremental dump made at the indicated depth in the
253 hierarchy. The value reported is for the entire dump, not necessarily for
254 the volume itself; for example, it is possible for a dump performed at an
255 incremental level to include a full dump of an individual volume if the
256 volume was omitted from previous dumps.
257
258 =item parentID
259
260 The dump ID number of C<dumpSetName>'s parent dump. It is C<0> if the
261 value in the C<level> field is C<0>.
262
263 =item endTime
264
265 Is always C<0>; it is reserved for internal use.
266
267 =item cloneDate
268
269 The date and time at which the volume was created. For a backup or
270 read-only volume, this represents the time at which it was cloned from its
271 read/write source. For a read/write volume, it indicates the time at which
272 the Backup System locked the volume for purposes of including it in the
273 dump named in the C<dumpSetName> field.
274
275 =back
276
277 The message C<Scantape: Finished> indicates the completion of the output.
278
279 In normal circumstances, the Backup System writes a marker to indicate
280 that a volume is the last one on a tape, or that the volume continues on
281 the next tape. However, if a backup operation terminated abnormally (for
282 example, because the operator terminated the Tape Coordinator by issuing
283 the Ctrl-C command during the operation), then there is no such
284 marker. Some very early versions of the Backup System also did not write
285 these markers. If a tape does not conclude with one of the expected
286 markers, the Tape Coordinator cannot determine if there is a subsequent
287 tape in the dump set and so generates the following message in its window:
288
289    Are there more tapes? (y/n)
290
291 =head1 EXAMPLES
292
293 The following example shows the output for the first two volumes on a tape
294 in the device with port offset 0:
295
296    % backup scantape
297    Dump label
298    ----------
299    tape name = monthly_guest
300    AFS tape name = guests.monthly.3
301    creationTime =  Mon Feb  1 04:06:40 1999
302    cell = abc.com
303    size = 2150000 Kbytes
304    dump path = /monthly
305    dump id = 917860000
306    useCount = 44
307    -- End of dump label --
308    -- volume --
309    volume name: user.guest10.backup
310    volume ID 1937573829
311    dumpSetName: guests.monthly
312    dumpID 917860000
313    level 0
314    parentID 0
315    endTime 0
316    clonedate Mon Feb  1 03:03:23 1999
317    -- volume --
318    volume name: user.guest11.backup
319    volume ID 1938519386
320    dumpSetName: guests.monthly
321    dumpID 917860000
322    level 0
323    parentID 0
324    endTime 0
325    clonedate Mon Feb  1 03:05:15 1999
326
327 =head1 PRIVILEGE REQUIRED
328
329 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
330 machine where the Backup Server is running, or must be logged onto a
331 server machine as the local superuser C<root> if the B<-localauth> flag is
332 included.
333
334 =head1 SEE ALSO
335
336 L<butc(5)>,
337 L<backup(8)>,
338 L<backup_dump(8)>,
339 L<backup_dumpinfo(8)>,
340 L<butc(8)>
341
342 =head1 COPYRIGHT
343
344 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
345
346 This documentation is covered by the IBM Public License Version 1.0.  It was
347 converted from HTML to POD by software written by Chas Williams and Russ
348 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.