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