501 lines
13 KiB
Groff
501 lines
13 KiB
Groff
.\" 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.
|
|
.\" 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
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd March 1, 2002
|
|
.Dt DUMP 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm dump ,
|
|
.Nm rdump
|
|
.Nd file system backup
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl 0123456789acLnSu
|
|
.Op Fl B Ar records
|
|
.Op Fl b Ar blocksize
|
|
.Op Fl C Ar cachesize
|
|
.Op Fl D Ar dumpdates
|
|
.Op Fl d Ar density
|
|
.Op Fl f Ar file
|
|
.Op Fl h Ar level
|
|
.Op Fl s Ar feet
|
|
.Op Fl T Ar date
|
|
.Ar filesystem
|
|
.Nm
|
|
.Fl W | Fl w
|
|
.Pp
|
|
.Nm rdump
|
|
is an alternate name for
|
|
.Nm .
|
|
.Pp
|
|
.in \" XXX
|
|
(The
|
|
.Bx 4.3
|
|
option syntax is implemented for backward compatibility, but
|
|
is not documented here.)
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility 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.
|
|
This can be enforced
|
|
by using the
|
|
.Fl a
|
|
option.
|
|
.Pp
|
|
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
|
|
.Fl B
|
|
options.
|
|
By default, the same output file name is used for each volume
|
|
after prompting the operator to change media.
|
|
.Pp
|
|
The file system to be dumped is specified by the argument
|
|
.Ar filesystem
|
|
as either its device-special file or its mount point
|
|
(if that is in a standard entry in
|
|
.Pa /etc/fstab ) .
|
|
.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 any lower level.
|
|
The default level is 0.
|
|
.It Fl a
|
|
.Dq auto-size .
|
|
Bypass all tape length considerations, and enforce writing
|
|
until an end-of-media indication is returned.
|
|
This fits best for most modern tape drives.
|
|
Use of this option is particularly
|
|
recommended when appending to an existing tape, or using a tape
|
|
drive with hardware compression (where you can never be sure about
|
|
the compression ratio).
|
|
.It Fl B Ar records
|
|
The number of kilobytes per output volume, except that if it is
|
|
not an integer multiple of the output block size,
|
|
the command uses the next smaller such multiple.
|
|
This option overrides the calculation of tape size
|
|
based on length and density.
|
|
.It Fl b Ar blocksize
|
|
The number of kilobytes per output block.
|
|
The default block size is 10.
|
|
.It Fl C Ar cachesize
|
|
Specify the cache size in megabytes.
|
|
This will greatly improve performance
|
|
at the cost of
|
|
.Nm
|
|
possibly not noticing changes in the file system between passes.
|
|
It is
|
|
recommended that you always use this option when dumping a snapshot.
|
|
Beware that
|
|
.Nm
|
|
forks, and the actual memory use may be larger than the specified cache
|
|
size.
|
|
The recommended cache size is between 8 and 32 (megabytes).
|
|
.It Fl c
|
|
Change the defaults for use with a cartridge tape drive, with a density
|
|
of 8000 bpi, and a length of 1700 feet.
|
|
.It Fl D Ar dumpdates
|
|
Specify an alternate path to the
|
|
.Pa dumpdates
|
|
file.
|
|
The default is
|
|
.Pa /etc/dumpdates .
|
|
.It Fl d Ar density
|
|
Set tape density to
|
|
.Ar density .
|
|
The default is 1600BPI.
|
|
.It Fl f Ar file
|
|
Write the backup to
|
|
.Ar file ;
|
|
.Ar file
|
|
may be a special device file
|
|
like
|
|
.Pa /dev/sa0
|
|
(a tape drive),
|
|
.Pa /dev/fd1
|
|
(a floppy disk drive),
|
|
an ordinary file,
|
|
or
|
|
.Sq 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
|
|
.Dq host:file ,
|
|
or
|
|
.Dq user@host:file ,
|
|
.Nm
|
|
writes to the named file on the remote host using
|
|
.Xr rmt 8 .
|
|
The default path name of the remote
|
|
.Xr rmt 8
|
|
program is
|
|
.\" rmt path, is the path on the remote host
|
|
.Pa /etc/rmt ;
|
|
this can be overridden by the environment variable
|
|
.Ev RMT .
|
|
.It Fl h Ar level
|
|
Honor the user
|
|
.Dq nodump
|
|
flag
|
|
.Pq 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 L
|
|
This option is to notify
|
|
.Nm
|
|
that it is dumping a live file system.
|
|
To obtain a consistent dump image,
|
|
.Nm
|
|
takes a snapshot of the file system in the
|
|
.Pa .snap
|
|
directory in the root of the filesystem being dumped and
|
|
then does a dump of the snapshot.
|
|
The snapshot is removed when the dump is complete.
|
|
If the
|
|
.Pa .snap
|
|
directory does not exist in the root of the filesystem being dumped,
|
|
the dump will fail.
|
|
This problem can be corrected by creating a
|
|
.Pa .snap
|
|
directory in the root of the filesystem to be dumped;
|
|
its owner should be root, its group should be operator,
|
|
and its mode should be 0770.
|
|
.It Fl n
|
|
Whenever
|
|
.Nm
|
|
requires operator attention,
|
|
notify all operators in the group
|
|
.Dq operator
|
|
by means similar to a
|
|
.Xr wall 1 .
|
|
.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 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 T Ar date
|
|
Use the specified date as the starting time for the dump
|
|
instead of the time determined from looking in
|
|
the
|
|
.Pa dumpdates
|
|
file.
|
|
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
|
|
.Pa dumpdates
|
|
file
|
|
after a successful dump.
|
|
The format of
|
|
the
|
|
.Pa dumpdates
|
|
file
|
|
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
|
|
.Pa dumpdates
|
|
file
|
|
may be edited to change any of the fields,
|
|
if necessary.
|
|
The default path for the
|
|
.Pa dumpdates
|
|
file is
|
|
.Pa /etc/dumpdates ,
|
|
but the
|
|
.Fl D
|
|
option may be used to change it.
|
|
.It Fl W
|
|
Tell the operator what file systems need to be dumped.
|
|
This information is gleaned from the files
|
|
.Pa dumpdates
|
|
and
|
|
.Pa /etc/fstab .
|
|
The
|
|
.Fl W
|
|
option causes
|
|
.Nm
|
|
to print out, for each file system in
|
|
the
|
|
.Pa dumpdates
|
|
file
|
|
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
|
|
.Fl W ,
|
|
but prints only those file systems which need to be dumped.
|
|
.El
|
|
.Pp
|
|
Directories and regular files which have their
|
|
.Dq nodump
|
|
flag
|
|
.Pq Dv UF_NODUMP
|
|
set will be omitted along with everything under such directories,
|
|
subject to the
|
|
.Fl h
|
|
option.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility 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
|
|
key,
|
|
.Nm
|
|
interacts with the operator on
|
|
.Em dump'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
|
|
.Dq yes
|
|
or
|
|
.Dq 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
|
|
The
|
|
.Nm
|
|
utility tells the operator what is going on at periodic intervals
|
|
(every 5 minutes, or promptly after receiving
|
|
.Dv SIGINFO ) ,
|
|
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/nsa0 /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 (file systems with files
|
|
that change, depending on your partition layout some file systems may
|
|
contain only data that does not change) 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 ENVIRONMENT
|
|
.Bl -tag -width ".Ev TAPE"
|
|
.It Ev TAPE
|
|
Device from which to read backup.
|
|
.It Ev RMT
|
|
Pathname of the remote
|
|
.Xr rmt 8
|
|
program.
|
|
.It Ev RSH
|
|
Pathname of remote shell program, if not
|
|
.Xr rsh 1 .
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/dumpdates -compact
|
|
.It Pa /dev/sa0
|
|
default tape unit to dump to
|
|
.It Pa /etc/dumpdates
|
|
dump date records
|
|
(this can be changed;
|
|
see the
|
|
.Fl D
|
|
option)
|
|
.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 fstab 5 ,
|
|
.Xr restore 8 ,
|
|
.Xr rmt 8
|
|
.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
|
|
Fewer than 32 read errors on the file system are ignored, though all
|
|
errors will generate a warning message.
|
|
This is a bit of a compromise.
|
|
In practice it is possible to generate read errors when doing dumps
|
|
on mounted partitions if the file system is being modified while the
|
|
dump is running.
|
|
Since dumps are often done in an unattended fashion using
|
|
.Xr cron 8
|
|
jobs asking for Operator intervention would result in the dump dying.
|
|
However there is nothing wrong with a dump tape written when this sort
|
|
of read error occurs and there is no reason to terminate the dump.
|
|
.Pp
|
|
Each reel requires a new process, so parent processes for
|
|
reels already written just hang around until the entire tape
|
|
is written.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility with the
|
|
.Fl W
|
|
or
|
|
.Fl w
|
|
options does not report file systems that have never been recorded
|
|
in the
|
|
.Pa dumpdates
|
|
file,
|
|
even if listed in
|
|
.Pa /etc/fstab .
|
|
.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 .
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility cannot do remote backups without being run as root, due to its
|
|
security history.
|
|
This will be fixed in a later version of
|
|
.Fx .
|
|
Presently, it works if you set it setuid (like it used to be), but this
|
|
might constitute a security risk.
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
utility appeared in
|
|
.At v6 .
|