[unix-history] / sbin / dump / dump.8

.\" Copyright (c) 1980, 1991 Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)dump.8	6.8 (Berkeley) 6/17/91
.\"
.Dd June 17, 1991
.Dt DUMP 8
.Os BSD 4
.Sh NAME
.Nm dump
.Nd filesystem backup
.Sh SYNOPSIS
.Nm dump
.Op Cm 0123456789fusdWn Op Ar argument ...
.Op Ar filesystem
.Sh DESCRIPTION
.Nm Dump
examines files
on a filesystem
and determines which files
need to be backed up. These files
are copied to the given disk, tape or other
storage medium for safe keeping (see
.Xr rdump 8
for
remote backups) .
A dump that is larger than the output medium is broken into
multiple volumes of a fixed size;
the actual size is determined by the tape size and density and/or
block count options below.
By default, the same output file name is used for each volume
after prompting the operator to change media.
.Pp
The following options are supported by
.Nm dump:
.Bl -tag -width 4n
.It Cm 0\-9
Dump levels.
A level 0, full backup,
guarantees the entire file system is copied.
A level number above 0,
incremental backup,
tells dump to
copy all files new or modified since the
last dump of the same or lower level. The default
level is 9.
.It Cm f Op Ar file
Write the backup to
.Ar file ;
.Ar file
may be a special device file
like
.Pa /dev/rmt12
(a tape drive),
.Pa /dev/rsd1c
(an optical drive),
an ordinary file,
or
.Ql Fl
(the standard output).
Multiple file names may be given as a single argument separated by commas.
Each file will be used for one dump volume in the order listed;
if the dump requires more volumes than the number of names given,
the last file name will used for all remaining volumes after prompting
for media changes.
.It Cm d Ar density
Set tape density to
.Ar density .
The default is 1600BPI.
.It Cm n
Whenever
.Nm dump
requires operator attention,
notify all operators in the group
.Dq operator
by means similar to a
.Xr wall 1 .
.It Cm s Ar feet
Attempt to caluculate the amount of tape needed
at a particular density.
If this amount is exceeded,
.Nm dump
prompts for a new tape.
It is recommended to be a bit conservative on this option.
The default tape length is 2300 feet.
.It Cm B Ar blocks
Set the size of the dump file to the specified number of 1024-byte blocks,
superceding the tape size and density.
.It Cm u
Update the file
.Pa /etc/dumpdates
after a successful dump.
The format of
.Pa /etc/dumpdates
is readable by people, consisting of one
free format record per line:
filesystem name,
increment level
and
.Xr ctime 3
format dump date.  
There may be only one entry per filesystem at each level.
The file
.Pa /etc/dumpdates
may be edited to change any of the fields,
if necessary.
.It Cm W
.Nm Dump
tells the operator what file systems need to be dumped.
This information is gleaned from the files
.Pa /etc/dumpdates
and
.Pa /etc/fstab .
The
.Cm W
option causes
.Nm dump
to print out, for each file system in
.Pa /etc/dumpdates
the most recent dump date and level,
and highlights those file systems that should be dumped.
If the 
.Cm W
option is set, all other options are ignored, and
.Nm dump
exits immediately.
.It Cm w
Is like W, but prints only those filesystems which need to be dumped.
.El
.Pp
.Nm Dump
requires operator intervention on these conditions:
end of tape,
end of dump,
tape write error,
tape open error or
disk read error (if there are more than a threshold of 32).
In addition to alerting all operators implied by the
.Cm n
key,
.Nm dump
interacts with the operator on 
.Em dump's
control terminal at times when
.Nm dump
can no longer proceed,
or if something is grossly wrong.
All questions
.Nm dump
poses
.Em must
be answered by typing \*(lqyes\*(rq or \*(lqno\*(rq,
appropriately.
.Pp
Since making a dump involves a lot of time and effort for full dumps,
.Nm dump
checkpoints itself at the start of each tape volume.
If writing that volume fails for some reason,
.Nm dump
will,
with operator permission,
restart itself from the checkpoint
after the old tape has been rewound and removed,
and a new tape has been mounted.
.Pp
.Nm Dump
tells the operator what is going on at periodic intervals,
including usually low estimates of the number of blocks to write,
the number of tapes it will take, the time to completion, and
the time to the tape change.
The output is verbose,
so that others know that the terminal
controlling
.Nm dump
is busy,
and will be for some time.
.Pp
In the event of a catastrophic disk event, the time required
to restore all the necessary backup tapes or files to disk
can be kept to a minimum by staggering the incremental dumps.
An efficient method of staggering incremental dumps
to minimize the number of tapes follows:
.Bl -bullet -offset indent
.It
Always start with a level 0 backup, for example:
.Bd -literal -offset indent
/etc/dump 0ufds /dev/nrst1 54000 6000 /usr/src
.Ed
.Pp
This should be done at set intervals, say once a month or once every two months,
and on a set of fresh tapes that is saved forever.
.It
After a level 0, dumps of active file 
systems are taken on a daily basis,
using a modified Tower of Hanoi algorithm,
with this sequence of dump levels:
.Bd -literal -offset indent
3 2 5 4 7 6 9 8 9 9 ...
.Ed
.Pp
For the daily dumps, it should be possible to use a fixed number of tapes
for each day, used on a weekly basis.
Each week, a level 1 dump is taken, and
the daily Hanoi sequence repeats beginning with 3.
For weekly dumps, another fixed set of tapes per dumped file system is
used, also on a cyclical basis.
.El
.Pp
After several months or so, the daily and weekly tapes should get
rotated out of the dump cycle and fresh tapes brought in.
.Sh FILES
.Bl -tag -width /etc/dumpdates -compact
.It Pa /dev/rrp1g
default filesystem to dump from (system dependent).
.It Pa /dev/rmt8
default tape unit to dump to
.It Pa /etc/dumpdates
new format dump date record 
.It Pa /etc/fstab
dump table: file systems and frequency
.It Pa /etc/group
to find group
.Em operator
.El
.Sh SEE ALSO
.Xr rdump 8 ,
.Xr restore 8 ,
.Xr dump 5 ,
.Xr fstab 5
.Sh DIAGNOSTICS
Many, and verbose.
.Pp
Dump exits with zero status on success.
Startup errors are indicated with an exit code of 1;
abnormal termination is indicated with an exit code of 3.
.Sh BUGS
.Pp
Fewer than 32 read errors on the filesystem are ignored.
Each reel requires a new process, so parent processes for
reels already written just hang around until the entire tape
is written.
.Pp
.Nm Dump
with the
.Cm W
or
.Cm w
options does not report filesystems that have never been recorded
in
.Pa /etc/dumpdates ,
even if listed in
.Pa /etc/fstab .
.Pp
It would be nice if
.Nm dump
knew about the dump sequence,
kept track of the tapes scribbled on,
told the operator which tape to mount when,
and provided more assistance
for the operator running
.Xr restore .
.Sh HISTORY
A
.Nm
command appeared in Version 6 AT&T UNIX.
Commit	Line	Data
15637ed4 RG	1	.\" Copyright (c) 1980, 1991 Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)dump.8 6.8 (Berkeley) 6/17/91
	33	.\"
	34	.Dd June 17, 1991
	35	.Dt DUMP 8
	36	.Os BSD 4
	37	.Sh NAME
	38	.Nm dump
	39	.Nd filesystem backup
	40	.Sh SYNOPSIS
	41	.Nm dump
	42	.Op Cm 0123456789fusdWn Op Ar argument ...
	43	.Op Ar filesystem
	44	.Sh DESCRIPTION
	45	.Nm Dump
	46	examines files
	47	on a filesystem
	48	and determines which files
	49	need to be backed up. These files
	50	are copied to the given disk, tape or other
	51	storage medium for safe keeping (see
	52	.Xr rdump 8
	53	for
	54	remote backups) .
	55	A dump that is larger than the output medium is broken into
	56	multiple volumes of a fixed size;
	57	the actual size is determined by the tape size and density and/or
	58	block count options below.
	59	By default, the same output file name is used for each volume
	60	after prompting the operator to change media.
	61	.Pp
	62	The following options are supported by
	63	.Nm dump:
	64	.Bl -tag -width 4n
65	.It Cm 0\-9
66	Dump levels.
67	A level 0, full backup,
68	guarantees the entire file system is copied.
69	A level number above 0,
70	incremental backup,
71	tells dump to
72	copy all files new or modified since the
73	last dump of the same or lower level. The default
74	level is 9.
75	.It Cm f Op Ar file
76	Write the backup to
77	.Ar file ;
78	.Ar file
79	may be a special device file
80	like
81	.Pa /dev/rmt12
82	(a tape drive),
83	.Pa /dev/rsd1c
84	(an optical drive),
85	an ordinary file,
86	or
87	.Ql Fl
88	(the standard output).
89	Multiple file names may be given as a single argument separated by commas.
90	Each file will be used for one dump volume in the order listed;
91	if the dump requires more volumes than the number of names given,
92	the last file name will used for all remaining volumes after prompting
93	for media changes.
94	.It Cm d Ar density
95	Set tape density to
96	.Ar density .
97	The default is 1600BPI.
98	.It Cm n
99	Whenever
100	.Nm dump
101	requires operator attention,
102	notify all operators in the group
103	.Dq operator
104	by means similar to a
105	.Xr wall 1 .
106	.It Cm s Ar feet
107	Attempt to caluculate the amount of tape needed
108	at a particular density.
109	If this amount is exceeded,
110	.Nm dump
111	prompts for a new tape.
112	It is recommended to be a bit conservative on this option.
113	The default tape length is 2300 feet.
114	.It Cm B Ar blocks
115	Set the size of the dump file to the specified number of 1024-byte blocks,
116	superceding the tape size and density.
117	.It Cm u
118	Update the file
119	.Pa /etc/dumpdates
120	after a successful dump.
121	The format of
122	.Pa /etc/dumpdates
123	is readable by people, consisting of one
124	free format record per line:
125	filesystem name,
126	increment level
127	and
128	.Xr ctime 3
129	format dump date.
130	There may be only one entry per filesystem at each level.
131	The file
132	.Pa /etc/dumpdates
133	may be edited to change any of the fields,
134	if necessary.
135	.It Cm W
136	.Nm Dump
137	tells the operator what file systems need to be dumped.
138	This information is gleaned from the files
139	.Pa /etc/dumpdates
140	and
141	.Pa /etc/fstab .
142	The
143	.Cm W
144	option causes
145	.Nm dump
146	to print out, for each file system in
147	.Pa /etc/dumpdates
148	the most recent dump date and level,
149	and highlights those file systems that should be dumped.
150	If the
151	.Cm W
152	option is set, all other options are ignored, and
153	.Nm dump
154	exits immediately.
155	.It Cm w
156	Is like W, but prints only those filesystems which need to be dumped.
157	.El
158	.Pp
159	.Nm Dump
160	requires operator intervention on these conditions:
161	end of tape,
162	end of dump,
163	tape write error,
164	tape open error or
165	disk read error (if there are more than a threshold of 32).
166	In addition to alerting all operators implied by the
167	.Cm n
168	key,
169	.Nm dump
170	interacts with the operator on
171	.Em dump's
172	control terminal at times when
173	.Nm dump
174	can no longer proceed,
175	or if something is grossly wrong.
176	All questions
177	.Nm dump
178	poses
179	.Em must
180	be answered by typing \(lqyes\(rq or \(lqno\(rq,
181	appropriately.
182	.Pp
183	Since making a dump involves a lot of time and effort for full dumps,
184	.Nm dump
185	checkpoints itself at the start of each tape volume.
186	If writing that volume fails for some reason,
187	.Nm dump
188	will,
189	with operator permission,
190	restart itself from the checkpoint
191	after the old tape has been rewound and removed,
192	and a new tape has been mounted.
193	.Pp
194	.Nm Dump
195	tells the operator what is going on at periodic intervals,
196	including usually low estimates of the number of blocks to write,
197	the number of tapes it will take, the time to completion, and
198	the time to the tape change.
199	The output is verbose,
200	so that others know that the terminal
201	controlling
202	.Nm dump
203	is busy,
204	and will be for some time.
205	.Pp
206	In the event of a catastrophic disk event, the time required
207	to restore all the necessary backup tapes or files to disk
208	can be kept to a minimum by staggering the incremental dumps.
209	An efficient method of staggering incremental dumps
210	to minimize the number of tapes follows:
211	.Bl -bullet -offset indent
212	.It
213	Always start with a level 0 backup, for example:
214	.Bd -literal -offset indent
215	/etc/dump 0ufds /dev/nrst1 54000 6000 /usr/src
216	.Ed
217	.Pp
218	This should be done at set intervals, say once a month or once every two months,
219	and on a set of fresh tapes that is saved forever.
220	.It
221	After a level 0, dumps of active file
222	systems are taken on a daily basis,
223	using a modified Tower of Hanoi algorithm,
224	with this sequence of dump levels:
225	.Bd -literal -offset indent
226	3 2 5 4 7 6 9 8 9 9 ...
227	.Ed
228	.Pp
229	For the daily dumps, it should be possible to use a fixed number of tapes
230	for each day, used on a weekly basis.
231	Each week, a level 1 dump is taken, and
232	the daily Hanoi sequence repeats beginning with 3.
233	For weekly dumps, another fixed set of tapes per dumped file system is
234	used, also on a cyclical basis.
235	.El
236	.Pp
237	After several months or so, the daily and weekly tapes should get
238	rotated out of the dump cycle and fresh tapes brought in.
239	.Sh FILES
240	.Bl -tag -width /etc/dumpdates -compact
241	.It Pa /dev/rrp1g
242	default filesystem to dump from (system dependent).
243	.It Pa /dev/rmt8
244	default tape unit to dump to
245	.It Pa /etc/dumpdates
246	new format dump date record
247	.It Pa /etc/fstab
248	dump table: file systems and frequency
249	.It Pa /etc/group
250	to find group
251	.Em operator
252	.El
253	.Sh SEE ALSO
254	.Xr rdump 8 ,
255	.Xr restore 8 ,
256	.Xr dump 5 ,
257	.Xr fstab 5
258	.Sh DIAGNOSTICS
259	Many, and verbose.
260	.Pp
261	Dump exits with zero status on success.
262	Startup errors are indicated with an exit code of 1;
263	abnormal termination is indicated with an exit code of 3.
264	.Sh BUGS
265	.Pp
266	Fewer than 32 read errors on the filesystem are ignored.
267	Each reel requires a new process, so parent processes for
268	reels already written just hang around until the entire tape
269	is written.
270	.Pp
271	.Nm Dump
272	with the
273	.Cm W
274	or
275	.Cm w
276	options does not report filesystems that have never been recorded
277	in
278	.Pa /etc/dumpdates ,
279	even if listed in
280	.Pa /etc/fstab .
281	.Pp
282	It would be nice if
283	.Nm dump
284	knew about the dump sequence,
285	kept track of the tapes scribbled on,
286	told the operator which tape to mount when,
287	and provided more assistance
288	for the operator running
289	.Xr restore .
290	.Sh HISTORY
291	A
292	.Nm
293	command appeared in Version 6 AT&T UNIX.