man8-editing-pass-20051213
[openafs.git] / doc / man-pages / pod8 / backup_dump.pod
1 =head1 NAME
2
3 backup dump - Creates a dump (dumps a volume set at a particular dump level)
4
5 =head1 SYNOPSIS
6
7 B<backup dump> [B<-volumeset> <I<volume set name>>]
8     [B<-dump> <I<dump level name>>] [B<-portoffset> <I<TC port offset>>]
9     [B<-at> <I<date/time to start dump>>+] [B<-append>] [B<-n>]
10     [B<-file> <I<load file>>] [B<-localauth>] [-B<cell> <I<cell name>>]
11     [B<-help>]
12
13 B<backup dump> [B<-v> <I<volume set name>>] [B<-d> <I<dump level name>>]
14     [B<-p> <I<TC port offset>>] [B<-at> <I<Date/time to start dump>>+]
15     [B<-ap>] [B<-n>] [B<-f> <I<load file>>] [B<-l>] [B<-c> <I<cell name>>]
16     [B<-h>]
17
18 =head1 DESCRIPTION
19
20 The B<backup dump> command either dumps the volume set specified by the
21 B<-volumeset> argument at the dump level specified by the B<-dump>
22 argument and creates a Backup Database dump record about it, or executes
23 the dump instructions listed in the file named by the B<-file>
24 argument. The Tape Coordinator indicated by the B<-portoffset> argument
25 (or on each command in the file) executes the operation.
26
27 (If the C<FILE YES> instruction appears in the
28 F</usr/afs/backup/CFG_I<device_name>> file on the Tape Coordinator machine
29 associated with the specified port offset, then the Backup System dumps
30 data to the backup data file listed for that port offset in the Tape
31 Coordinator's F</usr/afs/backup/tapeconfig> file, rather than to tape. For
32 the sake of clarity, the following text refers to tapes only, but the
33 Backup System handles backup data files in much the same way.)
34
35 The term I<dumping> refers to copying a collection of data to tape or a
36 backup data file, and the resulting collection is termed a I<dump>. The
37 set of tapes that contain one or more dumps is called a I<dump set>. The
38 first dump in a dump set is its I<initial dump>, and any dumps
39 subsequently added to the dump set (by use of the B<-append> argument) are
40 I<appended dumps>.  Creating appended dumps is optional, and appended
41 dumps can be of different volume sets, and at different dump levels, than
42 the initial dump.
43
44 A I<full dump>, created at a full dump level in the dump hierarchy,
45 contains all of the data that existed at the time of the dump in the
46 volumes belonging to the volume set. An I<incremental dump>, created at an
47 incremental dump level, contains only data that has changed since the
48 volume set was dumped at the incremental level's I<parent dump level> (the
49 dump level immediately above the incremental level in the hierarchy),
50 which can be a full or incremental level. More specifically, an
51 incremental dump includes only the files and directories that have
52 modification timestamps later than the I<clone date> of the volume
53 included at the parent dump level. For backup and read-only volumes, the
54 clone date is the time at which the volume was cloned from its read/write
55 source before being included in the parent dump; for read/write volumes,
56 it represents the time at which the volume was locked for inclusion in the
57 parent dump. The clone date appears in the I<clone date> field of the
58 output from the B<backup volinfo> command. As an example, an incremental
59 dump at the C</full/week1/thursday> level includes only files and
60 directories that have changed since the volume set was dumped at the
61 C</full/week1> level.
62
63 =head2 Initiating different types of dump operations
64
65 To initiate a dump operation that is to start as soon as the relevant Tape
66 Coordinator is available, provide only the B<-volumeset>, B<-dump>,
67 B<-portoffset>, and optionally B<-append> options. To schedule a single
68 B<backup dump> command to execute in the future, also include the B<-at>
69 argument to specify the start time.
70
71 To append a dump to an existing dump set, include the B<-append> flag. The
72 Backup System imposes the following conditions on appended dumps:
73
74 =over 4
75
76 =item *
77
78 If writing to tape, the Tape Coordinator checks that it is the final one
79 in a dump set for which there are complete and valid tape and dump records
80 in the Backup Database. If not, it rejects the tape and requests an
81 acceptable one. The operator can use the B<-dbadd> argument to the
82 B<backup scantape> command to insert the necessary records into the
83 database.
84
85 =item *
86
87 The most recent dump on the tape or in the backup data file must have
88 completed successfully.
89
90 =item *
91
92 The dump set must begin with an initial dump that is recorded in the
93 Backup Database. If there are no dumps on the tape, then the Backup System
94 treats the dump operation as an initial dump and imposes the relevant
95 requirements (for example, checks the AFS tape name if appropriate).
96
97 =back
98
99 To schedule multiple dump operations, list the operations in the file
100 named by the B<-file> argument. Optionally include the B<-at> argument to
101 specify when the B<backup> command interpreter reads the file; otherwise
102 it reads it immediately. Do not combine the B<-file> argument with the
103 command's first three arguments or the B<-append> or B<-n> flags. The
104 commands in the file can include any of the B<backup dump> command's
105 arguments, including the B<-at> argument to schedule them to run even
106 later in the future.
107
108 To generate a list of the volumes included in a dump, without actually
109 dumping them, combine the B<-n> flag with the options to be used on the
110 actual command.
111
112 =head2 How the Backup System executes a dump operation
113
114 Before beginning a dump operation, the Backup System verifies that there
115 is a Backup Database entry for the volume set, dump level, and port
116 offset. If the command is correctly formed and issued in interactive mode,
117 it is assigned a job number and added to the jobs list. List jobs in
118 interactive mode by using the B<backup jobs> command; terminate them with
119 the B<backup kill> command.
120
121 After obtaining the list of volumes to dump from the Volume Location (VL)
122 Server, the Backup System sorts the list by site (server and
123 partition). It groups volumes from the same site together in the dump to
124 minimize the number of times the operator must change tapes during restore
125 operations.
126
127 The dependence of an incremental dump on its parent means that a valid
128 parent dump must already exist for the Backup System to create its child
129 incremental dump. If the Backup System does not find a record of a dump
130 created at the immediate parent dump level, it looks in the Backup
131 Database for a dump created at one level higher in the hierarchy, and so
132 on, up to the full dump level if necessary. It creates an incremental dump
133 at the level one below the lowest valid parent dump set that it finds. If
134 it fails to find even a full dump, it dumps the volume set at the full
135 dump level.
136
137 If the Backup System is unable to access a volume during a dump operation,
138 it skips the volume and dumps the remaining volumes from the volume
139 set. Possible reasons a volume is inaccessible include server machine or
140 process outages, or that the volume was moved between the time the Volume
141 Location (VL) Server generated the list of sites for the volume in the
142 volume set and the time the Backup System actually attempts to dump the
143 data in it. After the first dumping pass, the Backup System attempts to
144 dump each volume it skipped. If it still cannot dump a volume and the
145 C<ASK NO> instruction does not appear in the F<CFG_I<device_name>> file,
146 it queries the operator as to whether it needs to attempt to dump the
147 volume again, omit the volume from the dump, or halt the dump operation
148 altogether. When prompted, the operator can attempt to solve whatever
149 problem prevented the Backup System from accessing the volumes. If the
150 C<ASK NO> instruction appears in the F<CFG_I<device_name>> file, the
151 Backup System omits the volume from the dump.
152
153 Before scheduling a dump operation, the Backup System verifies that the
154 date specified by the B<-at> argument is in the future, and checks the
155 validity of the volume set, dump level and port offset as for a regular
156 dump operation. It checks the validity of the parameters again just before
157 actually running the scheduled operation.
158
159 Before writing an initial dump to a tape that does not have a permanent
160 name on the label, the Backup System checks that the AFS tape name on the
161 label is acceptable. If desired, disable name checking by including the
162 C<NAME_CHECK NO> instruction in the F<CFG_I<device_name>> file.
163
164 If AFS tape name checking is enabled, the Backup System accepts the
165 following three types of values for the AFS tape name. If the name on the
166 label does not conform, the Backup System obtains a tape with an
167 acceptable label by invoking the C<MOUNT> instruction in the
168 F<CFG_I<device_name>> file or prompting the operator.
169
170 =over 4
171
172 =item *
173
174 A name of the form I<volume_set_name.dump_level_name.tape_index>, where
175 I<volume_set_name> matches the value of the B<-volumeset> argument,
176 I<dump_level_name> matches the last element in the pathname value of the
177 B<-dump> argument, and I<tape_index> reflects the tape's place in a
178 multitape dump set. As an example, the first tape in a dump set for which
179 the initial dump is of volume set C<user> at the dump level
180 C</sunday2/monday> has AFS tape name C<user.monday.1>. If the label
181 records this type of AFS tape name, the Backup System retains the AFS tape
182 name and writes the dump to the tape.
183
184 =item *
185
186 The string C<< <NULL> >>, which usually indicates that a backup operator
187 has used the B<backup labeltape> command to write a label on the tape, but
188 did not include the B<-name> argument to assign an AFS tape
189 name. Presumably, the operator did include the B<-pname> argument to
190 assign a permanent name. If the label records a C<< <NULL> >> value, the
191 Backup System constructs and records on the label the appropriate AFS tape
192 name, and writes the dump on the tape.
193
194 =item *
195
196 No value at all, because the tape has never been labeled or used in the
197 Backup System. As when the AFS tape name is C<< <NULL> >>, the Backup
198 System constructs and records on the label the appropriate AFS tape name,
199 and writes the dump on the tape.
200
201 =back
202
203 To determine how much data it can write to a tape, the Tape Coordinator
204 reads the capacity recorded on the tape's label (placed there by including
205 the B<-size> argument to the B<backup labeltape> command). If the label's
206 capacity field is empty, the Tape Coordinator uses the capacity recorded
207 for the specified port offset in the local F<tapeconfig> file. If the
208 capacity field in the F<tapeconfig> file is also empty, the Tape
209 Coordinator uses the maximum capacity of 2 TB.
210
211 During a dump operation, the Tape Coordinator tracks how much data it has
212 written and stops shortly before it reaches what it believes is the tape's
213 capacity. If it is in the middle of writing the data for a volume when it
214 reaches that point, it writes a special marker that indicates an
215 interrupted volume and continues writing the volume on the next tape. It
216 can split a volume this way during both an initial and an appended dump,
217 and the fact that the volume resides on multiple tapes is automatically
218 recorded in the Backup Database.
219
220 If the tape is actually larger than the expected capacity, then the Tape
221 Coordinator simply does not use the excess tape. If the tape is smaller
222 than the expected capacity, the Tape Coordinator can reach the end-of-tape
223 (EOT) unexpectedly while it is writing data. If the Tape Coordinator is in
224 the middle of the writing data from a volume, it obtains a new tape and
225 rewrites the entire contents of the interrupted volume to it. The data
226 from the volume that was written to the previous tape remains there, but
227 is never used.
228
229 The Backup System allows recycling of tapes (writing a new dump set over
230 an old dump set that is no longer needed), but imposes the following
231 conditions:
232
233 =over 4
234
235 =item *
236
237 All dumps in the old dump set must be expired. The Backup System always
238 checks expiration dates, even when name checking is disabled.
239
240 =item *
241
242 If the tape to be recycled does not have a permanent name and name
243 checking is enabled, then the AFS tape name derived from the new initial
244 dump's volume set name and dump level name must match the AFS tape name
245 already recorded on the label.
246
247 =item *
248
249 The tape cannot already have data on it that belongs to the dump currently
250 being performed, because that implies that the operator or automated tape
251 device has not removed the previous tape from the drive, or has mistakenly
252 reinserted it. The Tape Coordinator generates the following message and
253 attempts to obtain another tape:
254
255    Can't overwrite tape containing the dump in progress
256
257 =item *
258
259 The tape cannot contain data from a parent dump of the current
260 (incremental) dump, because overwriting a parent dump makes it impossible
261 to restore data from the current dump. The Tape Coordinator generates the
262 following message and attempts to obtain another tape:
263
264    Can't overwrite the parent dump I<parent_name> (I<parent_dump_ID>)
265
266 =back
267
268 To recycle a tape before all dumps on it have expired or if the AFS tape
269 name is wrong, use the B<backup labeltape> command to overwrite the tape's
270 label and remove all associated tape and dump records from the Backup
271 Database.
272
273 The Tape Coordinator's default response to this command is to access the
274 first tape by invoking the C<MOUNT> instruction in the
275 F<CFG_I<device_name>> file, or by prompting the backup operator to insert
276 the tape if there is no C<MOUNT> instruction.  However, if the C<AUTOQUERY
277 NO> instruction appears in the F<CFG_I<device_name>> file, or if the
278 issuer of the B<butc> command included the B<-noautoquery> flag, the Tape
279 Coordinator instead expects the tape to be in the device already. If it is
280 not, the Tape Coordinator invokes the C<MOUNT> instruction or prompts the
281 operator. It also invokes the C<MOUNT> instruction or prompts for any
282 additional tapes needed to complete the dump operation; the issuer must
283 arrange to provide them.
284
285 =head1 CAUTIONS
286
287 If a dump operation is interrupted or fails for any reason, data from all
288 volumes written to tape before the interrupt are valid can be used in a
289 restore operation. The Backup Database includes an entry for the failed
290 dump and for each volume that was successfully dumped. See the I<IBM AFS
291 Administration Guide> for information on dealing with interrupted dumps.
292
293 If dumping to tape rather than a backup data file, it is best to use only
294 compatible tape devices (ones that can read the same type of tape).  Using
295 compatible devices greatly simplifies restore operations. The
296 B<-portoffset> argument to the B<backup diskrestore> and B<backup
297 volsetrestore> commands accepts multiple port offset numbers, but the
298 Backup System uses the first listed port offset when restoring all full
299 dumps, the second port offset when restoring all level 1 dumps, and so
300 on. At the very least, use compatible tape devices to perform dumps at
301 each level. If compatible tape devices are not used, the B<backup
302 volrestore> command must be used to restore one volume at a time.
303
304 Valid (unexpired) administrative tokens must be available to the B<backup>
305 command interpreter both when it reads the file named by the B<-file>
306 argument and when it runs each operation listed in the file. Presumably,
307 the issuer is scheduling dumps for times when no human operator is
308 present, and so must arrange for valid tokens to be available on the local
309 machine. One option is to issue all commands (or run all scripts) on file
310 server machines and use the B<-localauth> flag on the B<backup> and B<vos>
311 commands. To protect against improper access to the machine or the tokens,
312 the machine must be physically secure (perhaps even more protected than a
313 Tape Coordinator machine monitored by a human operator during
314 operation). Also, if an unattended dump requires multiple tapes, the
315 operator must properly configure a tape stacker or jukebox and the device
316 configuration file.
317
318 When the command is issued in regular (non-interactive) mode, the command
319 shell prompt does not return until the dump operation completes. To avoid
320 having to open additional connections, issue the command in interactive
321 mode, especially when including the B<-at> argument to schedule dump
322 operations.
323
324 =head1 OPTIONS
325
326 =over 4
327
328 =item B<-volumeset> <I<volume set name>>
329
330 Names the volume set to dump. The B<-dump> argument must be provided along
331 with this one; do not combine them with the B<-file> argument. If using a
332 temporary volume set, the B<vos dump> command must be issued within the
333 interactive session in which the B<backup addvolset> command was issued
334 with the B<-temporary> flag.
335
336 =item B<-dump> <I<dump level name>>
337
338 Specifies the complete pathname of the dump level at which to dump the
339 volume set. The B<-volumeset> argument must be provided along with this
340 one; do not combine them with the B<-file> argument.
341
342 =item B<-portoffset> <I<TC port offset>>
343
344 Specifies the port offset number of the Tape Coordinator handling the
345 tapes for this operation. It must be provided unless the default value of
346 0 (zero) is appropriate; do not combine it with the B<-file> argument.
347
348 =item B<-at> <I<date/time to start dump>>
349
350 Specifies the date and time in the future at which to run the command, or
351 to read the file named by the B<-file> argument. Provide a value in the
352 format I<mm/dd/yyyy> [I<hh:MM>], where the month (I<mm>), day (I<dd>), and
353 year (I<yyyy>) are required. Valid values for the year range from C<1970>
354 to C<2037>; higher values are not valid because the latest possible date
355 in the standard UNIX representation is in February 2038. The Backup System
356 automatically reduces any later date to the maximum value.
357
358 The hour and minutes (I<hh:MM>) are optional, but if provided must be in
359 24-hour format (for example, the value C<14:36> represents 2:36 p.m.). If
360 omitted, the time defaults to midnight (00:00 hours).
361
362 As an example, the value 04/23/1999 20:20 schedules the command for 8:20
363 p.m. on 23 April 1999.
364
365 =item B<-append>
366
367 Appends the dump onto the end of a tape that already contains data from
368 another dump. However, if the tape is not in fact part of an existing dump
369 set, the Backup System creates a new dump set using the parameters of this
370 dump. If the tape is not the last tape in the dump set, the Tape
371 Coordinator prompts for insertion of the appropriate tape. Do not combine
372 this argument with the B<-file> argument.
373
374 =item B<-n>
375
376 Displays the names of volumes to be included in the indicated dump,
377 without actually performing the dump operation. Do not combine this
378 argument with the B<-file> argument.
379
380 =item B<-file> <I<load file>>
381
382 Specifies the local disk or AFS pathname of a file containing B<backup>
383 commands. The Backup System reads the file immediately, or at the time
384 specified by the B<-at> argument if it is provided. A partial pathname is
385 interpreted relative to the current working directory.
386
387 Place each B<backup dump> command on its own line in the indicated file,
388 using the same syntax as for the command line, but without the word
389 B<backup> at the start of the line. Each command must include a value for
390 the B<-volumeset> and B<-dump> arguments, and for the B<-portoffset>
391 argument unless the default value of 0 is appropriate. Commands in the
392 file can also include any of the B<backup dump> command's optional
393 options. In the following example file, the first command runs as soon as
394 the Backup System reads the file, whereas the other commands are
395 themselves scheduled; the specified date and time must be later than the
396 date and time at which the Backup System reads the file.
397
398    dump user /sunday1/wednesday -port 1 
399    dump sun4x_56 /sunday1/friday -port 2 -at 04/08/1999
400    dump sun4x_55 /sunday1/friday -port 2 -at 04/08/1999 02:00 -append
401
402 Do not combine this argument with the B<-volumeset>, B<-dump>,
403 B<-portoffset>, B<-append>, or B<-n> options.
404
405 =item B<-localauth>
406
407 Constructs a server ticket using a key from the local
408 F</usr/afs/etc/KeyFile> file. The B<backup> command interpreter presents
409 it to the Backup Server, Volume Server and VL Server during mutual
410 authentication. Do not combine this flag with the B<-cell> argument. For
411 more details, see L<backup(8)>.
412
413 =item B<-cell> <I<cell name>>
414
415 Names the cell in which to run the command. Do not combine this argument
416 with the B<-localauth> flag. For more details, see L<backup(8)>.
417
418 =item B<-help>
419
420 Prints the online help for this command. All other valid options are
421 ignored.
422
423 =back
424
425 =head1 OUTPUT
426
427 The command interpreter first generates a list of the volumes to be
428 included in the dump by matching the entries in the volume set against the
429 volumes listed in the Volume Location Database (VLDB). It prints the list
430 following the header:
431
432    Preparing to dump the following volumes:
433
434 The following message then indicates that the command interpreter has
435 passed the dump request to the appropriate Tape Coordinator for
436 processing:
437
438    Starting dump.
439
440 If the issuer includes the B<-n> flag, the output is of the following
441 form:
442
443    Starting dump of volume set '<volume set>' (dump set '<dump level>')
444    Total number of volumes : <number dumped>
445    Would have dumped the following volumes:
446    <list_of_volumes>
447
448 where I<list_of_volumes> identifies each volume by name and volume ID
449 number.
450
451 If the Tape Coordinator is unable to access a volume, it prints an error
452 message in its window and records the error in its log and error files.
453
454 =head1 EXAMPLES
455
456 The following command dumps the volumes in the volume set called C<user>
457 at the dump level C</full/sunday2/monday>. The issuer places the necessary
458 tapes in the device with port offset 5.
459
460    % backup dump -volumeset user -dump /full/sunday2/monday -portoffset 5
461    Preparing to dump the following volumes:
462    user.jones.backup   387623900
463    user.pat.backup     486219245
464    user.smith.backup   597315841
465           .                .
466           .                .
467    Starting dump.
468
469 The following command displays the list of volumes to be dumped when the
470 user dumps the C<sys_sun> volume set at the C</full> dump level.
471
472    % backup dump -volumeset sys_sun -dump /full -n
473    Starting dump of volume set 'sys_sun' (dump set '/full')
474    Total number of volumes: 24
475    Would have dumped the following volumes:
476    sun4x_56      124857238
477    sun4x_56.bin  124857241
478        .            .
479        .            .
480    sun4x_55      124857997
481        .            .
482        .            .
483
484 The following command schedules a dump of the volumes in the volume set
485 C<user> at the dump level C</sunday2/monday1> for 11:00 p.m. on 14 June
486 1999. The appropriate Tape Coordinator has port offset 0 (zero), so that
487 argument is omitted.
488
489    % backup dump -volumeset user -dump /sunday2/monday1 -at 06/14/1999 23:00
490
491 =head1 PRIVILEGE REQUIRED
492
493 The issuer must be listed in the F</usr/afs/etc/UserList> file on every
494 machine where the Backup Server or Volume Location (VL) Server is running,
495 and on every file server machine that houses an affected volume. If the
496 B<-localauth> flag is included, the issuer must instead be logged on to a
497 server machine as the local superuser C<root>.
498
499 =head1 SEE ALSO
500
501 L<backup(8)>,
502 L<backup_adddump(8)>,
503 L<backup_addvolentry(8)>,
504 L<backup_addvolset(8)>,
505 L<backup_diskrestore(8)>,
506 L<backup_labeltape(8)>,
507 L<backup_volrestore(8)>,
508 L<butc(8)>
509
510 =head1 COPYRIGHT
511
512 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
513
514 This documentation is covered by the IBM Public License Version 1.0.  It was
515 converted from HTML to POD by software written by Chas Williams and Russ
516 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.