484 lines
13 KiB
Groff
484 lines
13 KiB
Groff
.\" $NetBSD: dump.8,v 1.37 2001/06/05 11:22:43 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1980, 1991, 1993
|
|
.\" 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 8.3 (Berkeley) 5/1/95
|
|
.\"
|
|
.Dd May 28, 2001
|
|
.Dt DUMP 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm dump ,
|
|
.Nm rdump
|
|
.Nd file-system backup
|
|
.Sh SYNOPSIS
|
|
.Nm ""
|
|
.Op Fl 0123456789cenSu
|
|
.Op Fl B Ar records
|
|
.Op Fl b Ar blocksize
|
|
.Op Fl d Ar density
|
|
.Op Fl f Ar file
|
|
.Op Fl h Ar level
|
|
.Op Fl k Ar read blocksize
|
|
.Op Fl L Ar label
|
|
.Op Fl r Ar cachesize
|
|
.Op Fl s Ar feet
|
|
.Op Fl T Ar date
|
|
.Ar files-to-dump
|
|
.Nm ""
|
|
.Op Fl W Li \&| Fl w
|
|
.Pp
|
|
.in -\\n(iSu
|
|
(The
|
|
.Bx 4.3
|
|
option syntax is implemented for backward compatibility, but
|
|
is not documented here).
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
examines files on a file-system 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 the
|
|
.Fl f
|
|
option below for doing remote backups).
|
|
A dump that is larger than the output medium is broken into
|
|
multiple volumes.
|
|
On most media the size is determined by writing until an
|
|
end-of-media indication is returned.
|
|
On media that cannot reliably return an end-of-media indication
|
|
(such as some cartridge tape drives)
|
|
each volume is 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
|
|
.Ar files-to-dump
|
|
is either a single file-system,
|
|
or a list of files and directories on a single file-system to be backed
|
|
up as a subset of the file-system.
|
|
In the former case,
|
|
.Ar files-to-dump
|
|
may be the device of a file-system,
|
|
the path to a currently mounted file-system, or
|
|
the path to an unmounted file-system listed in
|
|
.Pa /etc/fstab .
|
|
In the latter case, certain restrictions are placed on the backup:
|
|
.Fl u
|
|
is ignored, the only dump level that is supported is
|
|
.Fl 0 ,
|
|
and all of the files must reside on the same file-system.
|
|
.Pp
|
|
The following options are supported by
|
|
.Nm "" :
|
|
.Bl -tag -width Ds
|
|
.It Fl 0\-9
|
|
Dump levels.
|
|
A level 0, full backup,
|
|
guarantees the entire file system is copied
|
|
(but see also the
|
|
.Fl h
|
|
option below).
|
|
A level number above 0,
|
|
incremental backup,
|
|
tells dump to
|
|
copy all files new or modified since the
|
|
last dump of a lower level.
|
|
The default level is 9.
|
|
.It Fl B Ar records
|
|
The number of kilobytes per volume, rounded
|
|
down to a multiple of the blocksize.
|
|
This option overrides the calculation of tape size
|
|
based on length and density.
|
|
.It Fl b Ar blocksize
|
|
The number of kilobytes per dump record.
|
|
.It Fl c
|
|
Modify the calculation of the default density and tape size to be more
|
|
appropriate for cartridge tapes.
|
|
.It Fl d Ar density
|
|
Set tape density to
|
|
.Ar density .
|
|
The default is 1600 Bits Per Inch (BPI).
|
|
.It Fl e
|
|
Eject tape automatically if a tape change is required.
|
|
.It Fl f Ar file
|
|
Write the backup to
|
|
.Ar file ;
|
|
.Ar file
|
|
may be a special device file
|
|
like
|
|
.Pa /dev/rst0
|
|
(a tape drive),
|
|
.Pa /dev/rsd1c
|
|
(a disk 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.
|
|
If the name of the file is of the form
|
|
.Qq host:file ,
|
|
or
|
|
.Qq user@host:file ,
|
|
.Nm
|
|
writes to the named file on the remote host using
|
|
.Xr rmt 8 .
|
|
Note that methods more secure than
|
|
.Xr rsh 1
|
|
.Pq such as Xr ssh 1
|
|
can be used to invoke
|
|
.Xr rmt 8
|
|
on the remote host, via the environment variable
|
|
.Ev RCMD_CMD .
|
|
See
|
|
.Xr rcmd 3
|
|
for more details.
|
|
|
|
.It Fl h Ar level
|
|
Honor the user
|
|
.Qq nodump
|
|
flag
|
|
.Dp Dv UF_NODUMP
|
|
only for dumps at or above the given
|
|
.Ar level .
|
|
The default honor level is 1,
|
|
so that incremental backups omit such files
|
|
but full backups retain them.
|
|
.It Fl k Ar read blocksize
|
|
The size in kilobyte of the read buffers, rounded up to a multiple of the
|
|
file-system block size. Default is 32k.
|
|
.It Fl L Ar label
|
|
The user-supplied text string
|
|
.Ar label
|
|
is placed into the dump header, where tools like
|
|
.Xr restore 8
|
|
and
|
|
.Xr file 1
|
|
can access it.
|
|
Note that this label is limited
|
|
to be at most LBLSIZE (currently 16) characters, which must include
|
|
the terminating
|
|
.Ql \e0 .
|
|
.It Fl n
|
|
Whenever
|
|
.Nm
|
|
requires operator attention,
|
|
notify all operators in the group
|
|
.Qq operator
|
|
by means similar to a
|
|
.Xr wall 1 .
|
|
.It Fl r Ar cachesize
|
|
Use that many buffers for read cache operations.
|
|
A value of zero disables the read cache altogether, higher values
|
|
improve read performance by reading larger data blocks from the
|
|
disk and maintaining them in an LRU cache. See the
|
|
.Fl k
|
|
option for the size of the buffers. Maximum is 512, the size of the cache is
|
|
limited to 15% of the avail RAM by default.
|
|
.It Fl s Ar feet
|
|
Attempt to calculate the amount of tape needed
|
|
at a particular density.
|
|
If this amount is exceeded,
|
|
.Nm
|
|
prompts for a new tape.
|
|
It is recommended to be a bit conservative on this option.
|
|
The default tape length is 2300 feet.
|
|
.It Fl S
|
|
Display an estimate of the backup size and the number of tapes
|
|
required, and exit without actually performing the dump.
|
|
.It Fl T Ar date
|
|
Use the specified date as the starting time for the dump
|
|
instead of the time determined from looking in
|
|
.Pa /etc/dumpdates .
|
|
The format of date is the same as that of
|
|
.Xr ctime 3 .
|
|
This option is useful for automated dump scripts that wish to
|
|
dump over a specific period of time.
|
|
The
|
|
.Fl T
|
|
option is mutually exclusive from the
|
|
.Fl u
|
|
option.
|
|
.It Fl 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:
|
|
file-system name,
|
|
increment level
|
|
and
|
|
.Xr ctime 3
|
|
format dump date.
|
|
There may be only one entry per file-system at each level.
|
|
The file
|
|
.Pa /etc/dumpdates
|
|
may be edited to change any of the fields,
|
|
if necessary.
|
|
If a list of files or subdirectories is being dumped
|
|
(as opposed to and entire file-system), then
|
|
.Fl u
|
|
is ignored.
|
|
.It Fl W
|
|
.Nm
|
|
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
|
|
.Fl W
|
|
option causes
|
|
.Nm
|
|
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
|
|
.Fl W
|
|
option is set, all other options are ignored, and
|
|
.Nm
|
|
exits immediately.
|
|
.It Fl w
|
|
Is like W, but prints only those file-systems which need to be dumped.
|
|
.El
|
|
.Pp
|
|
If
|
|
.Nm
|
|
honors the
|
|
.Qq nodump
|
|
flag,
|
|
.Dp Dv UF_NODUMP
|
|
files with the
|
|
.Qq nodump
|
|
flag will not be backed up. If a directory has the
|
|
.Qq nodump
|
|
flag, this directory and any file or directory under it will not be backed up.
|
|
.Pp
|
|
.Nm
|
|
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
|
|
.Fl n
|
|
option,
|
|
.Nm
|
|
interacts with the operator on
|
|
.Nm "" Ns 's
|
|
control terminal at times when
|
|
.Nm
|
|
can no longer proceed,
|
|
or if something is grossly wrong.
|
|
All questions
|
|
.Nm
|
|
poses
|
|
.Em must
|
|
be answered by typing
|
|
.Qq yes
|
|
or
|
|
.Qq no ,
|
|
appropriately.
|
|
.Pp
|
|
Since making a dump involves a lot of time and effort for full dumps,
|
|
.Nm
|
|
checkpoints itself at the start of each tape volume.
|
|
If writing that volume fails for some reason,
|
|
.Nm
|
|
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
|
|
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
|
|
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
|
|
/sbin/dump -0u -f /dev/nrst1 /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.
|
|
.Pp
|
|
If
|
|
.Nm
|
|
receives a
|
|
.Dv SIGINFO
|
|
signal
|
|
(see the
|
|
.Qq status
|
|
argument of
|
|
.Xr stty 1 )
|
|
whilst a backup is in progress, statistics on the amount completed,
|
|
current transfer rate, and estimated finished time, will be written
|
|
to the standard error output.
|
|
.Sh ENVIRONMENT
|
|
If the following environment variables exist, they are utilized by
|
|
.Nm "" .
|
|
.Bl -tag -width Fl
|
|
.It Ev TAPE
|
|
If no -f option was specified,
|
|
.Nm
|
|
will use the device specified via
|
|
.Ev TAPE
|
|
as the dump device.
|
|
.Ev TAPE
|
|
may be of the form
|
|
.Qq tapename ,
|
|
.Qq host:tapename ,
|
|
or
|
|
.Qq user@host:tapename .
|
|
.It Ev RCMD_CMD
|
|
.Nm
|
|
will use
|
|
.Ev RCMD_CMD
|
|
rather than
|
|
.Xr rsh 1
|
|
to invoke
|
|
.Xr rmt 8
|
|
on the remote machine.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/dumpdates -compact
|
|
.It Pa /dev/nrst0
|
|
default tape unit to use. Taken from
|
|
.Dv _PATH_DEFTAPE
|
|
in
|
|
.Pa /usr/include/paths.h .
|
|
.It Pa /dev/rst*
|
|
raw SCSI tape interface
|
|
.It Pa /etc/dumpdates
|
|
dump date records
|
|
.It Pa /etc/fstab
|
|
dump table: file systems and frequency
|
|
.It Pa /etc/group
|
|
to find group
|
|
.Em operator
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr chflags 1 ,
|
|
.Xr stty 1 ,
|
|
.Xr fts 3 ,
|
|
.Xr fstab 5 ,
|
|
.Xr restore 8 ,
|
|
.Xr rmt 8 ,
|
|
.Xr st 4
|
|
.Sh DIAGNOSTICS
|
|
Many, and verbose.
|
|
.Pp
|
|
.Nm
|
|
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
|
|
Fewer than 32 read errors on the file-system are ignored.
|
|
.Pp
|
|
Each reel requires a new process, so parent processes for
|
|
reels already written just hang around until the entire tape
|
|
is written.
|
|
.Pp
|
|
.Nm
|
|
with the
|
|
.Fl W
|
|
or
|
|
.Fl w
|
|
options does not report file-systems that have never been recorded
|
|
in
|
|
.Pa /etc/dumpdates ,
|
|
even if listed in
|
|
.Pa /etc/fstab .
|
|
.Pp
|
|
When dumping a list of files or subdirectories, access privileges are
|
|
required to scan the directory (as this is done via the
|
|
.Xr fts 3
|
|
routines rather than directly accessing the file-system).
|
|
.Pp
|
|
It would be nice if
|
|
.Nm
|
|
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 8 .
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
command appeared in
|
|
.At v6 .
|