Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | backup_dumpinfo - Displays a dump record from the Backup Database | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<backup dumpinfo> S<<< [B<-ndumps> <I<number of dumps>>] >>> | |
11 | S<<< [B<-id> <I<dump id>>] >>> [B<-verbose>] [B<-localauth>] | |
12 | S<<< [B<-cell> <I<cell name>>] >>> [B<-help>] | |
13 | ||
14 | B<backup dumpi> S<<< [B<-n> <I<no. of dumps>>] >>> [-i <I<dump id>>] [B<-v>] | |
15 | [B<-l>] S<<< [B<-c> <I<cell name>>] >>> [B<-h>] | |
16 | ||
17 | =for html | |
18 | </div> | |
19 | ||
20 | =head1 DESCRIPTION | |
21 | ||
22 | The B<backup dumpinfo> command formats and displays the Backup Database | |
23 | record for the specified dumps. To specify how many of the most recent | |
24 | dumps to display, starting with the newest one and going back in time, use | |
25 | the B<-ndumps> argument. To display more detailed information about a | |
26 | single dump, use the B<-id> argument. To display the records for the 10 | |
27 | most recent dumps, omit both the B<-ndumps> and B<-id> arguments. | |
28 | ||
29 | The B<-verbose> flag produces very detailed information that is useful | |
30 | mostly for debugging purposes. It can be combined only with the B<-id> | |
31 | argument. | |
32 | ||
33 | =head1 OPTIONS | |
34 | ||
35 | =over 4 | |
36 | ||
37 | =item B<-ndumps> <I<number of dumps>> | |
38 | ||
39 | Displays the Backup Database record for each of the specified number of | |
40 | dumps that were most recently performed. If the database contains fewer | |
41 | dumps than are requested, the output includes the records for all existing | |
42 | dumps. Do not combine this argument with the B<-id> or B<-verbose> | |
43 | options; omit all options to display the records for the last 10 dumps. | |
44 | ||
45 | =item B<-id> <I<dump id>> | |
46 | ||
47 | Specifies the dump ID number of a single dump for which to display the | |
48 | Backup Database record. Precede the I<dump id> value with the B<-id> | |
49 | switch; otherwise, the command interpreter interprets it as the value of | |
50 | the B<-ndumps> argument. Combine this argument with the B<-verbose> flag, | |
51 | but not with the B<-ndumps> argument; omit all options to display the | |
52 | records for the last 10 dumps. | |
53 | ||
54 | =item B<-verbose> | |
55 | ||
56 | Provides more detailed information about the dump specified with the | |
57 | B<-id> argument, which must be provided along with it. Do not combine this | |
58 | flag with the B<-ndumps> argument. | |
59 | ||
60 | =item B<-localauth> | |
61 | ||
62 | Constructs a server ticket using a key from the local | |
63 | F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents | |
64 | it to the Backup Server, Volume Server and VL Server during mutual | |
65 | authentication. Do not combine this flag with the B<-cell> argument. For | |
66 | more details, see L<backup(8)>. | |
67 | ||
68 | =item B<-cell> <I<cell name>> | |
69 | ||
70 | Names the cell in which to run the command. Do not combine this argument | |
71 | with the B<-localauth> flag. For more details, see L<backup(8)>. | |
72 | ||
73 | =item B<-help> | |
74 | ||
75 | Prints the online help for this command. All other valid options are | |
76 | ignored. | |
77 | ||
78 | =back | |
79 | ||
80 | =head1 OUTPUT | |
81 | ||
82 | If the B<-ndumps> argument is provided, the output presents the following | |
83 | information in table form, with a separate line for each dump: | |
84 | ||
85 | =over 4 | |
86 | ||
87 | =item dumpid | |
88 | ||
89 | The dump ID number. | |
90 | ||
91 | =item parentid | |
92 | ||
93 | The dump ID number of the dump's parent dump. A value of C<0> (zero) | |
94 | identifies a full dump. | |
95 | ||
96 | =item lv | |
97 | ||
98 | The depth in the dump hierarchy of the dump level used to create the | |
99 | dump. A value of C<0> (zero) identifies a full dump, in which case the | |
100 | value in the C<parentid> field is also C<0>. A value of C<1> or greater | |
101 | indicates an incremental dump made at the corresponding level in the dump | |
102 | hierarchy. | |
103 | ||
104 | =item created | |
105 | ||
106 | The date and time at which the Backup System started the dump operation | |
107 | that created the dump. | |
108 | ||
109 | =item nt | |
110 | ||
111 | The number of tapes that contain the data in the dump. A value of C<0> | |
112 | (zero) indicates that the dump operation was terminated or failed. Use the | |
113 | B<backup deletedump> command to remove such entries. | |
114 | ||
115 | =item nvols | |
116 | ||
117 | The number of volumes from which the dump includes data. If a volume spans | |
118 | tapes, it is counted twice. A value of C<0> (zero) indicates that the dump | |
119 | operation was terminated or failed; the value in the C<nt> field is also | |
120 | C<0> in this case. | |
121 | ||
122 | =item dump name | |
123 | ||
124 | The dump name in the form | |
125 | ||
126 | <volume_set_name>.<dump_level_name> (<initial_dump_ID>) | |
127 | ||
128 | where <volume_set_name> is the name of the volume set, and | |
129 | <dump_level_name> is the last element in the dump level pathname at which | |
130 | the volume set was dumped. | |
131 | ||
132 | The <initial_dump_ID>, if displayed, is the dump ID of the initial dump in | |
133 | the dump set to which this dump belongs. If there is no value in | |
134 | parentheses, the dump is the initial dump in a dump set that has no | |
135 | appended dumps. | |
136 | ||
137 | =back | |
138 | ||
139 | If the B<-id> argument is provided alone, the first line of output begins | |
140 | with the string C<Dump> and reports information for the entire dump in the | |
141 | following fields: | |
142 | ||
143 | =over 4 | |
144 | ||
145 | =item id | |
146 | ||
147 | The dump ID number. | |
148 | ||
149 | =item level | |
150 | ||
151 | The depth in the dump hierarchy of the dump level used to create the | |
152 | dump. A value of C<0> (zero) identifies a full dump. A value of C<1> (one) | |
153 | or greater indicates an incremental dump made at the specified level in | |
154 | the dump hierarchy. | |
155 | ||
156 | =item volumes | |
157 | ||
158 | The number of volumes for which the dump includes data. | |
159 | ||
160 | =item created | |
161 | ||
162 | The date and time at which the dump operation began. | |
163 | ||
164 | =back | |
165 | ||
166 | If an XBSA server was the backup medium for the dump (rather than a tape | |
167 | device or backup data file), the following line appears next: | |
168 | ||
169 | Backup Service: <XBSA_program>: Server: <hostname> | |
170 | ||
171 | where <XBSA_program> is the name of the XBSA-compliant program and | |
172 | <hostname> is the name of the machine on which the program runs. | |
173 | ||
174 | Next the output includes an entry for each tape that houses volume data | |
175 | from the dump. Following the string C<Tape>, the first two lines of each | |
176 | entry report information about that tape in the following fields: | |
177 | ||
178 | =over 4 | |
179 | ||
180 | =item name | |
181 | ||
182 | The tape's permanent name if it has one, or its AFS tape name otherwise, | |
183 | and its tape ID number in parentheses. | |
184 | ||
185 | =item nVolumes | |
186 | ||
187 | The number of volumes for which this tape includes dump data. | |
188 | ||
189 | =item created | |
190 | ||
191 | The date and time at which the Tape Coordinator began writing data to this | |
192 | tape. | |
193 | ||
194 | =back | |
195 | ||
196 | Following another blank line, the tape-specific information concludes with | |
197 | a table that includes a line for each volume dump on the tape. The | |
198 | information appears in columns with the following headings: | |
199 | ||
200 | =over 4 | |
201 | ||
202 | =item Pos | |
203 | ||
204 | The relative position of each volume in this tape or file. On a tape, the | |
205 | counter begins at position 2 (the tape label occupies position 1), and | |
206 | increments by one for each volume. For volumes in a backup data file, the | |
207 | position numbers start with 1 and do not usually increment only by one, | |
208 | because each is the ordinal of the 16 KB offset in the file at which the | |
209 | volume's data begins. The difference between the position numbers | |
210 | therefore indicates how many 16 KB blocks each volume's data occupies. For | |
211 | example, if the second volume is at position 5 and the third volume in the | |
212 | list is at position 9, that means that the dump of the second volume | |
213 | occupies 64 KB (four 16-KB blocks) of space in the file. | |
214 | ||
215 | =item Clone time | |
216 | ||
217 | For a backup or read-only volume, the time at which it was cloned from its | |
218 | read/write source. For a Read/Write volume, it is the same as the dump | |
219 | creation date reported on the first line of the output. | |
220 | ||
221 | =item Nbytes | |
222 | ||
223 | The number of bytes of data in the dump of the volume. | |
224 | ||
225 | =item Volume | |
226 | ||
227 | The volume name, complete with C<.backup> or C<.readonly> extension if | |
228 | appropriate. | |
229 | ||
230 | =back | |
231 | ||
232 | If both the B<-id> and B<-verbose> options are provided, the output is | |
233 | divided into several sections: | |
234 | ||
235 | =over 4 | |
236 | ||
237 | =item * | |
238 | ||
239 | The first section, headed by the underlined string C<Dump>, includes | |
240 | information about the entire dump. The fields labeled C<id>, C<level>, | |
241 | C<created>, and C<nVolumes> report the same values (though in a different | |
242 | order) as appear on the first line of output when the B<-id> argument is | |
243 | provided by itself. Other fields of potential interest to the backup | |
244 | operator are: | |
245 | ||
246 | =over 4 | |
247 | ||
248 | =item Group id | |
249 | ||
250 | The dump's I<group ID number>, which is recorded in the dump's Backup | |
251 | Database record if the C<GROUPID> instruction appears in the Tape | |
252 | Coordinator's F</usr/afs/backup/CFG_I<tcid>> file when the dump is | |
253 | created. | |
254 | ||
255 | =item maxTapes | |
256 | ||
257 | The number of tapes that contain the dump set to which this dump belongs. | |
258 | ||
259 | =item Start Tape Seq | |
260 | ||
261 | The ordinal of the tape on which this dump begins in the set of tapes that | |
262 | contain the dump set. | |
263 | ||
264 | =back | |
265 | ||
266 | =item * | |
267 | ||
268 | For each tape that contains data from this dump, there follows a section | |
269 | headed by the underlined string C<Tape>. The fields labeled C<name>, | |
270 | C<written>, and C<nVolumes> report the same values (though in a different | |
271 | order) as appear on the second and third lines of output when the B<-id> | |
272 | argument is provided by itself. Other fields of potential interest to the | |
273 | backup operator are: | |
274 | ||
275 | =over 4 | |
276 | ||
277 | =item expires | |
278 | ||
279 | The date and time when this tape can be recycled, because all dumps it | |
280 | contains have expired. | |
281 | ||
282 | =item nMBytes Data and nBytes Data | |
283 | ||
284 | Summed together, these fields represent the total amount of dumped data | |
285 | actually from volumes (as opposed to labels, filemarks, and other | |
286 | markers). | |
287 | ||
288 | =item KBytes Tape Used | |
289 | ||
290 | The number of kilobytes of tape (or disk space, for a backup data file) | |
291 | used to store the dump data. It is generally larger than the sum of the | |
292 | values in the C<nMBytes Data> and C<nBytes Data> fields, because it | |
293 | includes the space required for the label, file marks and other markers, | |
294 | and because the Backup System writes data at 16 KB offsets, even if the | |
295 | data in a given block doesn't fill the entire 16 KB. | |
296 | ||
297 | =back | |
298 | ||
299 | =item * | |
300 | ||
301 | For each volume on a given tape, there follows a section headed by the | |
302 | underlined string C<Volume>. The fields labeled C<name>, C<position>, | |
303 | C<clone>, and C<nBytes> report the same values (though in a different | |
304 | order) as appear in the table that lists the volumes in each tape when the | |
305 | B<-id> argument is provided by itself. Other fields of potential interest | |
306 | to the backup operator are: | |
307 | ||
308 | =over 4 | |
309 | ||
310 | =item id | |
311 | ||
312 | The volume ID. | |
313 | ||
314 | =item tape | |
315 | ||
316 | The name of the tape containing this volume data. | |
317 | ||
318 | =back | |
319 | ||
320 | =back | |
321 | ||
322 | =head1 EXAMPLES | |
323 | ||
324 | The following example displays information about the last five dumps: | |
325 | ||
326 | % backup dumpinfo -ndumps 5 | |
327 | dumpid parentid lv created nt nvols dump name | |
328 | 924424000 0 0 04/18/1999 04:26 1 22 usr.sun (924424000) | |
329 | 924685000 924424000 1 04/21/1999 04:56 1 62 usr.wed (924424000) | |
330 | 924773000 924424000 1 04/22/1999 05:23 1 46 usr.thu (924424000) | |
331 | 924860000 924424000 1 04/23/1999 05:33 1 58 usr.fri (924424000) | |
332 | 925033000 0 0 04/25/1999 05:36 2 73 sys.week | |
333 | ||
334 | The following example displays a more detailed record for a single dump. | |
335 | ||
336 | % backup dumpinfo -id 922097346 | |
337 | Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999 | |
338 | Tape: name monday.user.backup (922097346) | |
339 | nVolumes 1, created 03/22/1999 05:09 | |
340 | Pos Clone time Nbytes Volume | |
341 | 1 03/22/1999 04:43 27787914 user.pat.backup | |
342 | ||
343 | The following example displays even more detailed information about the | |
344 | dump displayed in the previous example (dump ID 922097346). This example | |
345 | includes only one exemplar of each type of section (C<Dump>, C<Tape>, and | |
346 | C<Volume>): | |
347 | ||
348 | % backup dumpinfo -id 922097346 -verbose | |
349 | Dump | |
350 | ---- | |
351 | id = 922097346 | |
352 | Initial id = 0 | |
353 | Appended id = 922099568 | |
354 | parent = 0 | |
355 | level = 0 | |
356 | flags = 0x0 | |
357 | volumeSet = user | |
358 | dump path = /monday1 | |
359 | name = user.monday1 | |
360 | created = Mon Mar 22 05:09:06 1999 | |
361 | nVolumes = 1 | |
362 | id = 0 | |
363 | tapeServer = | |
364 | format= user.monday1.%d | |
365 | maxTapes = 1 | |
366 | Start Tape Seq = 1 | |
367 | name = pat | |
368 | instance = | |
369 | cell = | |
370 | Tape | |
371 | ---- | |
372 | tape name = monday.user.backup | |
373 | AFS tape name = user.monday1.1 | |
374 | flags = 0x20 | |
375 | written = Mon Mar 22 05:09:06 1999 | |
376 | expires = NEVER | |
377 | kBytes Tape Used = 121 | |
378 | nMBytes Data = 0 | |
379 | nBytes Data = 19092 | |
380 | nFiles = 0 | |
381 | nVolumes = 1 | |
382 | seq = 1 | |
383 | tapeid = 0 | |
384 | useCount = 1 | |
385 | dump = 922097346 | |
386 | Volume | |
387 | ------ | |
388 | name = user.pat.backup | |
389 | flags = 0x18 | |
390 | id = 536871640 | |
391 | server = | |
392 | partition = 0 | |
393 | nFrags = 1 | |
394 | position = 2 | |
395 | clone = Mon Mar 22 04:43:06 1999 | |
396 | startByte = 0 | |
397 | nBytes = 19092 | |
398 | seq = 0 | |
399 | dump = 922097346 | |
400 | tape = user.monday1.1 | |
401 | ||
402 | =head1 PRIVILEGE REQUIRED | |
403 | ||
404 | The issuer must be listed in the F</usr/afs/etc/UserList> file on every | |
405 | machine where the Backup Server is running, or must be logged onto a | |
406 | server machine as the local superuser C<root> if the B<-localauth> flag is | |
407 | included. | |
408 | ||
409 | =head1 SEE ALSO | |
410 | ||
411 | L<butc(5)>, | |
412 | L<backup(8)>, | |
413 | L<backup_deletedump(8)> | |
414 | ||
415 | =head1 COPYRIGHT | |
416 | ||
417 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
418 | ||
419 | This documentation is covered by the IBM Public License Version 1.0. It was | |
420 | converted from HTML to POD by software written by Chas Williams and Russ | |
421 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |