xref: /freebsd/sbin/dump/dump.8 (revision 6990ffd8a95caaba6858ad44ff1b3157d1efba8f)
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
14.\"    must display the following acknowledgment:
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
34.\" $FreeBSD$
35.\"
36.Dd July 9, 2001
37.Dt DUMP 8
38.Os
39.Sh NAME
40.Nm dump ,
41.Nm rdump
42.Nd filesystem backup
43.Sh SYNOPSIS
44.Nm
45.Op Fl 0123456789acknu
46.Op Fl B Ar records
47.Op Fl b Ar blocksize
48.Op Fl D Ar dumpdates
49.Op Fl d Ar density
50.Op Fl f Ar file
51.Op Fl h Ar level
52.Op Fl s Ar feet
53.Op Fl T Ar date
54.Ar filesystem
55.Nm
56.Op Fl W Li \&| Fl w
57.Pp
58.in \" XXX
59(The
60.Bx 4.3
61option syntax is implemented for backward compatibility, but
62is not documented here.)
63.Sh DESCRIPTION
64.Nm Dump
65examines files
66on a filesystem
67and determines which files
68need to be backed up.
69These files
70are copied to the given disk, tape or other
71storage medium for safe keeping (see the
72.Fl f
73option below for doing remote backups).
74A dump that is larger than the output medium is broken into
75multiple volumes.
76On most media the size is determined by writing until an
77end-of-media indication is returned.  This can be enforced
78by using the
79.Fl a
80option.
81.Pp
82On media that cannot reliably return an end-of-media indication
83(such as some cartridge tape drives)
84each volume is of a fixed size;
85the actual size is determined by the tape size and density and/or
86block count options below.
87By default, the same output file name is used for each volume
88after prompting the operator to change media.
89.Pp
90The following options are supported by
91.Nm :
92.Bl -tag -width Ds
93.It Fl 0\-9
94Dump levels.
95A level 0, full backup,
96guarantees the entire file system is copied
97(but see also the
98.Fl h
99option below).
100A level number above 0,
101incremental backup,
102tells dump to
103copy all files new or modified since the
104last dump of any lower level.
105The default level is 0.
106.It Fl a
107.Dq auto-size .
108Bypass all tape length considerations, and enforce writing
109until an end-of-media indication is returned.  This fits best
110for most modern tape drives.  Use of this option is particularly
111recommended when appending to an existing tape, or using a tape
112drive with hardware compression (where you can never be sure about
113the compression ratio).
114.It Fl B Ar records
115The number of 1 KB blocks per volume.
116This option overrides the calculation of tape size
117based on length and density.
118.It Fl b Ar blocksize
119The number of kilobytes per dump record.
120.It Fl c
121Change the defaults for use with a cartridge tape drive, with a density
122of 8000 bpi, and a length of 1700 feet.
123.It Fl D Ar dumpdates
124Specify an alternate path to the
125.Pa dumpdates
126file.
127The default is
128.Pa /etc/dumpdates .
129.It Fl d Ar density
130Set tape density to
131.Ar density .
132The default is 1600BPI.
133.It Fl f Ar file
134Write the backup to
135.Ar file ;
136.Ar file
137may be a special device file
138like
139.Pa /dev/sa0
140(a tape drive),
141.Pa /dev/fd1
142(a floppy disk drive),
143an ordinary file,
144or
145.Ql Fl
146(the standard output).
147Multiple file names may be given as a single argument separated by commas.
148Each file will be used for one dump volume in the order listed;
149if the dump requires more volumes than the number of names given,
150the last file name will used for all remaining volumes after prompting
151for media changes.
152If the name of the file is of the form
153.Dq host:file ,
154or
155.Dq user@host:file ,
156.Nm
157writes to the named file on the remote host using
158.Xr rmt 8 .
159The default path name of the remote
160.Xr rmt 8
161program is
162.\" rmt path, is the path on the remote host
163.Pa /etc/rmt ;
164this can be overridden by the environment variable
165.Ev RMT .
166.It Fl h Ar level
167Honor the user
168.Dq nodump
169flag
170.Pq Dv UF_NODUMP
171only for dumps at or above the given
172.Ar level .
173The default honor level is 1,
174so that incremental backups omit such files
175but full backups retain them.
176.It Fl k
177Use Kerberos authentication to talk to remote tape servers.  (Only
178available if this option was enabled when
179.Nm
180was compiled.)
181.It Fl n
182Whenever
183.Nm
184requires operator attention,
185notify all operators in the group
186.Dq operator
187by means similar to a
188.Xr wall 1 .
189.It Fl s Ar feet
190Attempt to calculate the amount of tape needed
191at a particular density.
192If this amount is exceeded,
193.Nm
194prompts for a new tape.
195It is recommended to be a bit conservative on this option.
196The default tape length is 2300 feet.
197.It Fl T Ar date
198Use the specified date as the starting time for the dump
199instead of the time determined from looking in
200the
201.Pa dumpdates
202file.
203The format of date is the same as that of
204.Xr ctime 3 .
205This option is useful for automated dump scripts that wish to
206dump over a specific period of time.
207The
208.Fl T
209option is mutually exclusive from the
210.Fl u
211option.
212.It Fl u
213Update the
214.Pa dumpdates
215file
216after a successful dump.
217The format of
218the
219.Pa dumpdates
220file
221is readable by people, consisting of one
222free format record per line:
223filesystem name,
224increment level
225and
226.Xr ctime 3
227format dump date.
228There may be only one entry per filesystem at each level.
229The
230.Pa dumpdates
231file
232may be edited to change any of the fields,
233if necessary.
234The default path for the
235.Pa dumpdates
236file is
237.Pa /etc/dumpdates ,
238but the
239.Fl D
240option may be used to change it.
241.It Fl W
242.Nm Dump
243tells the operator what file systems need to be dumped.
244This information is gleaned from the files
245.Pa dumpdates
246and
247.Pa /etc/fstab .
248The
249.Fl W
250option causes
251.Nm
252to print out, for each file system in
253the
254.Pa dumpdates
255file
256the most recent dump date and level,
257and highlights those file systems that should be dumped.
258If the
259.Fl W
260option is set, all other options are ignored, and
261.Nm
262exits immediately.
263.It Fl w
264Is like W, but prints only those filesystems which need to be dumped.
265.El
266.Pp
267.Nm Dump
268honors the user
269.Dq nodump
270flag
271.Pq Dv UF_NODUMP
272on regular files and directories.
273If a directory is marked
274.Dq nodump ,
275the latter and all files and directories under it will not be backed
276up.
277That is,
278.Nm
279propagates the
280.Dq nodump
281flag on directories.
282.Pp
283.Nm Dump
284requires operator intervention on these conditions:
285end of tape,
286end of dump,
287tape write error,
288tape open error or
289disk read error (if there are more than a threshold of 32).
290In addition to alerting all operators implied by the
291.Fl n
292key,
293.Nm
294interacts with the operator on
295.Em dump's
296control terminal at times when
297.Nm
298can no longer proceed,
299or if something is grossly wrong.
300All questions
301.Nm
302poses
303.Em must
304be answered by typing
305.Dq yes
306or
307.Dq no ,
308appropriately.
309.Pp
310Since making a dump involves a lot of time and effort for full dumps,
311.Nm
312checkpoints itself at the start of each tape volume.
313If writing that volume fails for some reason,
314.Nm
315will,
316with operator permission,
317restart itself from the checkpoint
318after the old tape has been rewound and removed,
319and a new tape has been mounted.
320.Pp
321.Nm Dump
322tells the operator what is going on at periodic intervals,
323including usually low estimates of the number of blocks to write,
324the number of tapes it will take, the time to completion, and
325the time to the tape change.
326The output is verbose,
327so that others know that the terminal
328controlling
329.Nm
330is busy,
331and will be for some time.
332.Pp
333In the event of a catastrophic disk event, the time required
334to restore all the necessary backup tapes or files to disk
335can be kept to a minimum by staggering the incremental dumps.
336An efficient method of staggering incremental dumps
337to minimize the number of tapes follows:
338.Bl -bullet -offset indent
339.It
340Always start with a level 0 backup, for example:
341.Bd -literal -offset indent
342/sbin/dump -0u -f /dev/nsa0 /usr/src
343.Ed
344.Pp
345This should be done at set intervals, say once a month or once every two months,
346and on a set of fresh tapes that is saved forever.
347.It
348After a level 0, dumps of active file
349systems are taken on a daily basis,
350using a modified Tower of Hanoi algorithm,
351with this sequence of dump levels:
352.Bd -literal -offset indent
3533 2 5 4 7 6 9 8 9 9 ...
354.Ed
355.Pp
356For the daily dumps, it should be possible to use a fixed number of tapes
357for each day, used on a weekly basis.
358Each week, a level 1 dump is taken, and
359the daily Hanoi sequence repeats beginning with 3.
360For weekly dumps, another fixed set of tapes per dumped file system is
361used, also on a cyclical basis.
362.El
363.Pp
364After several months or so, the daily and weekly tapes should get
365rotated out of the dump cycle and fresh tapes brought in.
366.Sh ENVIRONMENT
367The environment variable
368.Ev RMT
369will be used to determine the pathname of the remote
370.Xr rmt 8
371program.
372.Sh FILES
373.Bl -tag -width /etc/dumpdates -compact
374.It Pa /dev/sa0
375default tape unit to dump to
376.It Pa /etc/dumpdates
377dump date records
378(this can be changed;
379see the
380.Fl D
381option)
382.It Pa /etc/fstab
383dump table: file systems and frequency
384.It Pa /etc/group
385to find group
386.Em operator
387.El
388.Sh SEE ALSO
389.Xr fstab 5 ,
390.Xr restore 8 ,
391.Xr rmt 8
392.Sh DIAGNOSTICS
393Many, and verbose.
394.Pp
395Dump exits with zero status on success.
396Startup errors are indicated with an exit code of 1;
397abnormal termination is indicated with an exit code of 3.
398.Sh BUGS
399Fewer than 32 read errors on the filesystem are ignored.
400.Pp
401Each reel requires a new process, so parent processes for
402reels already written just hang around until the entire tape
403is written.
404.Pp
405Currently,
406.Xr physio 9
407slices all requests into chunks of 64 KB.  Therefore, it is
408impossible to use a larger tape blocksize, so
409.Nm
410will prevent this from happening.
411.Pp
412.Nm Dump
413with the
414.Fl W
415or
416.Fl w
417options does not report filesystems that have never been recorded
418in the
419.Pa dumpdates
420file,
421even if listed in
422.Pa /etc/fstab .
423.Pp
424It would be nice if
425.Nm
426knew about the dump sequence,
427kept track of the tapes scribbled on,
428told the operator which tape to mount when,
429and provided more assistance
430for the operator running
431.Xr restore .
432.Pp
433.Nm Dump
434cannot do remote backups without being run as root, due to its
435security history.  This will be fixed in a later version of
436.Fx .
437Presently, it works if you set it setuid (like it used to be), but this
438might constitute a security risk.
439.Sh HISTORY
440A
441.Nm
442command appeared in
443.At v6 .
444