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