]>
Commit | Line | Data |
---|---|---|
1227625a SP |
1 | .\" Copyright (c) 1980, 1991, 1993 |
2 | .\" Regents of the University of California. | |
3 | .\" All rights reserved. | |
4 | .\" | |
5 | .\" Redistribution and use in source and binary forms, with or without | |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. All advertising materials mentioning features or use of this software | |
ddd2ef55 | 14 | .\" must display the following acknowledgement: |
1227625a SP |
15 | .\" This product includes software developed by the University of |
16 | .\" California, Berkeley and its contributors. | |
17 | .\" 4. Neither the name of the University nor the names of its contributors | |
18 | .\" may be used to endorse or promote products derived from this software | |
19 | .\" without specific prior written permission. | |
20 | .\" | |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
32 | .\" | |
33 | .\" @(#)dump.8 8.3 (Berkeley) 5/1/95 | |
8d4197bb | 34 | .\" $Id: dump.8.in,v 1.1 1999/10/11 13:08:07 stelian Exp $ |
1227625a | 35 | .\" |
8d4197bb | 36 | .Dd __DATE__ |
1227625a | 37 | .Dt DUMP 8 |
8d4197bb | 38 | .Os "__VERSION__" |
1227625a SP |
39 | .Sh NAME |
40 | .Nm dump | |
ddd2ef55 | 41 | .Nd ext2 filesystem backup |
1227625a SP |
42 | .Sh SYNOPSIS |
43 | .Nm dump | |
b45f51d6 | 44 | .Op Fl 0123456789acknu |
1227625a SP |
45 | .Op Fl B Ar records |
46 | .Op Fl b Ar blocksize | |
47 | .Op Fl d Ar density | |
48 | .Op Fl f Ar file | |
49 | .Op Fl h Ar level | |
b45f51d6 | 50 | .Op Fl L Ar label |
1227625a SP |
51 | .Op Fl s Ar feet |
52 | .Op Fl T Ar date | |
53 | .Ar filesystem | |
54 | .Nm dump | |
b45f51d6 | 55 | .Op Fl 0123456789acknu |
1227625a SP |
56 | .Op Fl B Ar records |
57 | .Op Fl b Ar blocksize | |
58 | .Op Fl d Ar density | |
59 | .Op Fl f Ar file | |
60 | .Op Fl h Ar level | |
b45f51d6 | 61 | .Op Fl L Ar label |
1227625a SP |
62 | .Op Fl s Ar feet |
63 | .Op Fl T Ar date | |
64 | .Ar directory | |
65 | .Nm dump | |
66 | .Op Fl W Li \&| Fl w | |
67 | .Pp | |
8d4197bb | 68 | .in |
1227625a SP |
69 | (The |
70 | .Bx 4.3 | |
ddd2ef55 | 71 | option syntax is implemented for backward compatibility but |
1227625a SP |
72 | is not documented here.) |
73 | .Sh DESCRIPTION | |
74 | .Nm Dump | |
75 | examines files | |
ddd2ef55 | 76 | on an ext2 filesystem |
1227625a SP |
77 | and determines which files |
78 | need to be backed up. These files | |
79 | are copied to the given disk, tape or other | |
80 | storage medium for safe keeping (see the | |
81 | .Fl f | |
82 | option below for doing remote backups). | |
83 | A dump that is larger than the output medium is broken into | |
84 | multiple volumes. | |
85 | On most media the size is determined by writing until an | |
ddd2ef55 | 86 | end-of-media indication is returned. This can be enforced |
b45f51d6 SP |
87 | by using the |
88 | .Fl a | |
89 | option. | |
90 | .Pp | |
1227625a | 91 | On media that cannot reliably return an end-of-media indication |
ddd2ef55 | 92 | (such as some cartridge tape drives), |
1227625a | 93 | each volume is of a fixed size; |
ddd2ef55 | 94 | the actual size is determined by the tape size, density and/or |
1227625a SP |
95 | block count options below. |
96 | By default, the same output file name is used for each volume | |
97 | after prompting the operator to change media. | |
98 | .Pp | |
99 | The following options are supported by | |
b45f51d6 | 100 | .Nm Ns : |
1227625a SP |
101 | .Bl -tag -width Ds |
102 | .It Fl 0\-9 | |
103 | Dump levels. | |
104 | A level 0, full backup, | |
105 | guarantees the entire file system is copied | |
106 | (but see also the | |
107 | .Fl h | |
108 | option below). | |
109 | A level number above 0, | |
110 | incremental backup, | |
ddd2ef55 SP |
111 | tells |
112 | .Nm dump | |
113 | to | |
1227625a | 114 | copy all files new or modified since the |
ddd2ef55 SP |
115 | last dump of the same or lower level. |
116 | The default level is 9. | |
1227625a | 117 | .It Fl B Ar records |
b45f51d6 | 118 | The number of 1 KB blocks per volume. |
1227625a SP |
119 | This option overrides the calculation of tape size |
120 | based on length and density. | |
b45f51d6 SP |
121 | .It Fl a |
122 | .Dq auto-size . | |
123 | Bypass all tape length considerations, and enforce writing | |
124 | until an end-of-media indication is returned. This fits best | |
125 | for most modern tape drives. Use of this option is particularly | |
126 | recommended when appending to an existing tape, or using a tape | |
127 | drive with hardware compression (where you can never be sure about | |
128 | the compression ratio). | |
1227625a SP |
129 | .It Fl b Ar blocksize |
130 | The number of kilobytes per dump record. | |
ddd2ef55 SP |
131 | Since the IO system slices all requests into chunks of MAXBSIZE |
132 | (typically 64KB), it is not possible to use a larger blocksize | |
133 | without having problems later with | |
134 | .Xr restore 8 . | |
135 | Therefore | |
136 | .Nm dump | |
137 | will constrain writes to MAXBSIZE. | |
1227625a | 138 | .It Fl c |
b45f51d6 SP |
139 | Change the defaults for use with a cartridge tape drive, with a density |
140 | of 8000 bpi, and a length of 1700 feet. | |
141 | .It Fl h Ar level | |
142 | Honor the user | |
143 | .Dq nodump | |
144 | flag | |
145 | .Dp Dv UF_NODUMP | |
146 | only for dumps at or above the given | |
147 | .Ar level . | |
148 | The default honor level is 1, | |
149 | so that incremental backups omit such files | |
150 | but full backups retain them. | |
1227625a SP |
151 | .It Fl d Ar density |
152 | Set tape density to | |
153 | .Ar density . | |
154 | The default is 1600BPI. | |
155 | .It Fl f Ar file | |
156 | Write the backup to | |
157 | .Ar file ; | |
158 | .Ar file | |
159 | may be a special device file | |
160 | like | |
ddd2ef55 | 161 | .Pa /dev/st0 |
1227625a SP |
162 | (a tape drive), |
163 | .Pa /dev/rsd1c | |
b45f51d6 | 164 | (a floppy disk drive), |
1227625a SP |
165 | an ordinary file, |
166 | or | |
167 | .Ql Fl | |
168 | (the standard output). | |
169 | Multiple file names may be given as a single argument separated by commas. | |
170 | Each file will be used for one dump volume in the order listed; | |
171 | if the dump requires more volumes than the number of names given, | |
172 | the last file name will used for all remaining volumes after prompting | |
173 | for media changes. | |
174 | If the name of the file is of the form | |
ddd2ef55 | 175 | .Dq host:file |
1227625a | 176 | or |
ddd2ef55 | 177 | .Dq user@host:file |
b45f51d6 | 178 | .Nm |
1227625a SP |
179 | writes to the named file on the remote host using |
180 | .Xr rmt 8 . | |
b45f51d6 SP |
181 | The default path name of the remote |
182 | .Xr rmt 8 | |
183 | program is | |
184 | .\" rmt path, is the path on the remote host | |
185 | .Pa /etc/rmt ; | |
186 | this can be overridden by the environment variable | |
187 | .Ev RMT . | |
188 | .It Fl k | |
189 | Use Kerberos authentication to talk to remote tape servers. (Only | |
190 | available if this option was enabled when | |
191 | .Nm | |
192 | was compiled.) | |
193 | .It Fl L Ar label | |
194 | The user-supplied text string | |
195 | .Ar label | |
196 | is placed into the dump header, where tools like | |
197 | .Xr restore 8 | |
198 | and | |
199 | .Xr file 1 | |
200 | can access it. | |
201 | Note that this label is limited | |
202 | to be at most LBLSIZE (currently 16) characters, which must include | |
203 | the terminating | |
204 | .Ql \e0 . | |
1227625a SP |
205 | .It Fl n |
206 | Whenever | |
b45f51d6 | 207 | .Nm |
1227625a SP |
208 | requires operator attention, |
209 | notify all operators in the group | |
210 | .Dq operator | |
211 | by means similar to a | |
212 | .Xr wall 1 . | |
213 | .It Fl s Ar feet | |
214 | Attempt to calculate the amount of tape needed | |
215 | at a particular density. | |
216 | If this amount is exceeded, | |
b45f51d6 | 217 | .Nm |
1227625a SP |
218 | prompts for a new tape. |
219 | It is recommended to be a bit conservative on this option. | |
220 | The default tape length is 2300 feet. | |
221 | .ne 1i | |
222 | .It Fl T Ar date | |
223 | Use the specified date as the starting time for the dump | |
224 | instead of the time determined from looking in | |
8d4197bb | 225 | .Pa __DUMPDATES__ . |
ddd2ef55 SP |
226 | The format of |
227 | .Ar date | |
228 | is the same as that of | |
1227625a SP |
229 | .Xr ctime 3 . |
230 | This option is useful for automated dump scripts that wish to | |
231 | dump over a specific period of time. | |
232 | The | |
233 | .Fl T | |
234 | option is mutually exclusive from the | |
235 | .Fl u | |
236 | option. | |
237 | .It Fl u | |
238 | Update the file | |
8d4197bb | 239 | .Pa __DUMPDATES__ |
1227625a SP |
240 | after a successful dump. |
241 | The format of | |
8d4197bb | 242 | .Pa __DUMPDATES__ |
1227625a SP |
243 | is readable by people, consisting of one |
244 | free format record per line: | |
245 | filesystem name, | |
246 | increment level | |
247 | and | |
248 | .Xr ctime 3 | |
249 | format dump date. | |
250 | There may be only one entry per filesystem at each level. | |
251 | The file | |
8d4197bb | 252 | .Pa __DUMPDATES__ |
1227625a SP |
253 | may be edited to change any of the fields, |
254 | if necessary. | |
255 | .It Fl W | |
256 | .Nm Dump | |
257 | tells the operator what file systems need to be dumped. | |
258 | This information is gleaned from the files | |
8d4197bb | 259 | .Pa __DUMPDATES__ |
1227625a SP |
260 | and |
261 | .Pa /etc/fstab . | |
262 | The | |
263 | .Fl W | |
264 | option causes | |
b45f51d6 | 265 | .Nm |
1227625a | 266 | to print out, for each file system in |
8d4197bb | 267 | .Pa __DUMPDATES__ , |
1227625a SP |
268 | the most recent dump date and level, |
269 | and highlights those file systems that should be dumped. | |
270 | If the | |
271 | .Fl W | |
272 | option is set, all other options are ignored, and | |
b45f51d6 | 273 | .Nm |
1227625a SP |
274 | exits immediately. |
275 | .It Fl w | |
ddd2ef55 SP |
276 | Is like |
277 | .Fl W , | |
278 | but prints only those filesystems which need to be dumped. | |
1227625a SP |
279 | .El |
280 | .Pp | |
281 | .Nm Dump | |
282 | requires operator intervention on these conditions: | |
283 | end of tape, | |
284 | end of dump, | |
285 | tape write error, | |
286 | tape open error or | |
ddd2ef55 | 287 | disk read error (if there is more than a threshold of 32). |
1227625a SP |
288 | In addition to alerting all operators implied by the |
289 | .Fl n | |
290 | key, | |
b45f51d6 | 291 | .Nm |
1227625a SP |
292 | interacts with the operator on |
293 | .Em dump's | |
294 | control terminal at times when | |
b45f51d6 | 295 | .Nm |
1227625a SP |
296 | can no longer proceed, |
297 | or if something is grossly wrong. | |
298 | All questions | |
b45f51d6 | 299 | .Nm |
1227625a SP |
300 | poses |
301 | .Em must | |
302 | be answered by typing | |
303 | .Dq yes | |
304 | or | |
305 | .Dq no , | |
306 | appropriately. | |
307 | .Pp | |
308 | Since making a dump involves a lot of time and effort for full dumps, | |
b45f51d6 | 309 | .Nm |
1227625a SP |
310 | checkpoints itself at the start of each tape volume. |
311 | If writing that volume fails for some reason, | |
b45f51d6 | 312 | .Nm |
1227625a SP |
313 | will, |
314 | with operator permission, | |
315 | restart itself from the checkpoint | |
316 | after the old tape has been rewound and removed, | |
317 | and a new tape has been mounted. | |
318 | .Pp | |
319 | .Nm Dump | |
320 | tells the operator what is going on at periodic intervals, | |
321 | including usually low estimates of the number of blocks to write, | |
322 | the number of tapes it will take, the time to completion, and | |
323 | the time to the tape change. | |
324 | The output is verbose, | |
325 | so that others know that the terminal | |
326 | controlling | |
b45f51d6 | 327 | .Nm |
1227625a SP |
328 | is busy, |
329 | and will be for some time. | |
330 | .Pp | |
331 | In the event of a catastrophic disk event, the time required | |
332 | to restore all the necessary backup tapes or files to disk | |
333 | can be kept to a minimum by staggering the incremental dumps. | |
334 | An efficient method of staggering incremental dumps | |
335 | to minimize the number of tapes follows: | |
336 | .Bl -bullet -offset indent | |
337 | .It | |
338 | Always start with a level 0 backup, for example: | |
339 | .Bd -literal -offset indent | |
8d4197bb | 340 | /sbin/dump -0u -f /dev/st0 /usr/src |
1227625a SP |
341 | .Ed |
342 | .Pp | |
343 | This should be done at set intervals, say once a month or once every two months, | |
344 | and on a set of fresh tapes that is saved forever. | |
345 | .It | |
346 | After a level 0, dumps of active file | |
347 | systems are taken on a daily basis, | |
348 | using a modified Tower of Hanoi algorithm, | |
349 | with this sequence of dump levels: | |
350 | .Bd -literal -offset indent | |
351 | 3 2 5 4 7 6 9 8 9 9 ... | |
352 | .Ed | |
353 | .Pp | |
354 | For the daily dumps, it should be possible to use a fixed number of tapes | |
355 | for each day, used on a weekly basis. | |
356 | Each week, a level 1 dump is taken, and | |
357 | the daily Hanoi sequence repeats beginning with 3. | |
358 | For weekly dumps, another fixed set of tapes per dumped file system is | |
359 | used, also on a cyclical basis. | |
360 | .El | |
361 | .Pp | |
362 | After several months or so, the daily and weekly tapes should get | |
363 | rotated out of the dump cycle and fresh tapes brought in. | |
b45f51d6 SP |
364 | .Sh ENVIRONMENT |
365 | .Bl -tag -width Fl | |
366 | .It Ev TAPE | |
367 | If no -f option was specified, | |
368 | .Nm | |
369 | will use the device specified via | |
370 | .Ev TAPE | |
371 | as the dump device. | |
372 | .Ev TAPE | |
373 | may be of the form | |
374 | .Qq tapename , | |
375 | .Qq host:tapename , | |
376 | or | |
377 | .Qq user@host:tapename . | |
378 | .It Ev RMT | |
379 | The environment variable | |
380 | .Ev RMT | |
381 | will be used to determine the pathname of the remote | |
382 | .Xr rmt 8 | |
383 | program. | |
1227625a | 384 | .Sh FILES |
8d4197bb | 385 | .Bl -tag -width __DUMPDATES__ -compact |
ddd2ef55 | 386 | .It Pa /dev/st0 |
1227625a | 387 | default tape unit to dump to |
8d4197bb | 388 | .It Pa __DUMPDATES__ |
1227625a SP |
389 | dump date records |
390 | .It Pa /etc/fstab | |
391 | dump table: file systems and frequency | |
392 | .It Pa /etc/group | |
393 | to find group | |
394 | .Em operator | |
395 | .El | |
396 | .Sh SEE ALSO | |
b45f51d6 | 397 | .Xr fstab 5 , |
1227625a | 398 | .Xr restore 8 , |
b45f51d6 | 399 | .Xr rmt 8 |
1227625a SP |
400 | .Sh DIAGNOSTICS |
401 | Many, and verbose. | |
402 | .Pp | |
ddd2ef55 SP |
403 | .Nm Dump |
404 | exits with zero status on success. | |
1227625a SP |
405 | Startup errors are indicated with an exit code of 1; |
406 | abnormal termination is indicated with an exit code of 3. | |
407 | .Sh BUGS | |
ddd2ef55 SP |
408 | It might be considered a bug that this version of dump can only handle ext2 |
409 | filesystems. Specifically, it does not work with FAT filesystems. | |
410 | .Pp | |
411 | Fewer than 32 read errors on the filesystem are ignored. If noticing | |
412 | read errors is important, the output from dump can be parsed to look for lines | |
413 | that contain the text 'read error'. | |
1227625a SP |
414 | .Pp |
415 | Each reel requires a new process, so parent processes for | |
416 | reels already written just hang around until the entire tape | |
417 | is written. | |
418 | .Pp | |
419 | .Nm Dump | |
420 | with the | |
421 | .Fl W | |
422 | or | |
423 | .Fl w | |
ddd2ef55 | 424 | option does not report filesystems that have never been recorded |
1227625a | 425 | in |
8d4197bb | 426 | .Pa __DUMPDATES__ , |
1227625a SP |
427 | even if listed in |
428 | .Pa /etc/fstab . | |
429 | .Pp | |
430 | It would be nice if | |
b45f51d6 | 431 | .Nm |
1227625a SP |
432 | knew about the dump sequence, |
433 | kept track of the tapes scribbled on, | |
434 | told the operator which tape to mount when, | |
435 | and provided more assistance | |
436 | for the operator running | |
437 | .Xr restore . | |
b45f51d6 SP |
438 | .Pp |
439 | .Nm Dump | |
440 | cannot do remote backups without being run as root, due to its | |
441 | security history. This will be fixed in a later version of | |
442 | .Bx Free . | |
443 | Presently, it works if you set it setuid (like it used to be), but this | |
444 | might constitute a security risk. | |
8d4197bb SP |
445 | .Sh AUTHOR |
446 | The | |
447 | .Nm dump/restore | |
448 | backup suit was ported to Linux's Second Extended File System | |
449 | by Remy Card <card@Linux.EU.Org>. He maintained the initial versions | |
450 | of dump (up and including 0.4b4, released in january 1997). | |
451 | .Pp | |
452 | Starting with 0.4b5, the new maintainer is Stelian Pop | |
453 | .br | |
454 | <pop@cybercable.fr>. | |
455 | .Sh AVAILABILITY | |
456 | The | |
457 | .Nm dump/restore | |
458 | backup suit is available for anonymous ftp from tsx-11.mit.edu | |
459 | in /pub/linux/ALPHA/ext2fs (development versions) or | |
460 | /pub/linux/packages/ext2fs (stable versions). | |
461 | .Pp | |
462 | An alternate downloading location is http://perso.cybercable.fr/pop/dump. | |
1227625a SP |
463 | .Sh HISTORY |
464 | A | |
b45f51d6 SP |
465 | .Nm |
466 | command appeared in | |
467 | .At v6 . |