mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-05 09:14:03 +00:00
a692c58a90
belong). With this change, mandoc now formats these manpages properly.
569 lines
15 KiB
Groff
569 lines
15 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 February 24, 2006
|
|
.Dt DUMP 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm dump ,
|
|
.Nm rdump
|
|
.Nd file system backup
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl 0123456789acLnrRSu
|
|
.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 | Fl P Ar pipecommand
|
|
.Op Fl h Ar level
|
|
.Op Fl s Ar feet
|
|
.Op Fl T Ar date
|
|
.Ar filesystem
|
|
.Nm
|
|
.Fl W | Fl w
|
|
.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
|
|
.Nm
|
|
may also be invoked as
|
|
.Nm rdump .
|
|
The
|
|
.Bx 4.3
|
|
option syntax is implemented for backward compatibility, but
|
|
is not documented here.
|
|
.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 P Ar pipecommand
|
|
Use
|
|
.Xr popen 3
|
|
to execute the
|
|
.Xr sh 1
|
|
script string defined by
|
|
.Ar pipecommand
|
|
for the output device of each volume.
|
|
This child pipeline's
|
|
.Dv stdin
|
|
.Pq Pa /dev/fd/0
|
|
is redirected from the
|
|
.Nm
|
|
output stream, and the environment variable
|
|
.Ev DUMP_VOLUME
|
|
is set to the current volume number being written.
|
|
After every volume, the writer side of the pipe is closed and
|
|
.Ar pipecommand
|
|
is executed again.
|
|
Subject to the media size specified by
|
|
.Fl B ,
|
|
each volume is written in this manner as if the output were a tape drive.
|
|
.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 file system being dumped and
|
|
then does a dump of the snapshot.
|
|
The snapshot is unlinked as soon as the dump starts, and
|
|
is thus removed when the dump is complete.
|
|
This option is ignored for unmounted or read-only file systems.
|
|
If the
|
|
.Pa .snap
|
|
directory does not exist in the root of the file system being dumped,
|
|
a warning will be issued and the
|
|
.Nm
|
|
will revert to the standard behavior.
|
|
This problem can be corrected by creating a
|
|
.Pa .snap
|
|
directory in the root of the file system to be dumped;
|
|
its owner should be
|
|
.Dq Li root ,
|
|
its group should be
|
|
.Dq Li operator ,
|
|
and its mode should be
|
|
.Dq Li 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 r
|
|
Be rsync-friendly.
|
|
Normally dump stores the date of the current
|
|
and prior dump in numerous places throughout the dump.
|
|
These scattered changes significantly slow down rsync or
|
|
another incremental file transfer program when they are
|
|
used to update a remote copy of a level 0 dump,
|
|
since the date changes for each dump.
|
|
This option sets both dates to the epoch, permitting
|
|
rsync to be much more efficient when transferring a dump file.
|
|
.It Fl R
|
|
Be even more rsync-friendly.
|
|
This option disables the storage of the actual inode access time
|
|
(storing it instead as the inode's modified time).
|
|
This option permits rsync to be even more efficient
|
|
when transferring dumps generated from filesystems with numerous files
|
|
which are not changing other than their access times.
|
|
The
|
|
.Fl R
|
|
option also sets
|
|
.Fl r .
|
|
.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
|
|
The
|
|
.Ar file
|
|
or device to dump to if the
|
|
.Fl f
|
|
option is not used.
|
|
.It Ev RMT
|
|
Pathname of the remote
|
|
.Xr rmt 8
|
|
program.
|
|
.It Ev RSH
|
|
Pathname of a 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 EXIT STATUS
|
|
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 EXAMPLES
|
|
Dumps the
|
|
.Pa /u
|
|
file system to DVDs using
|
|
.Nm growisofs .
|
|
Uses a 16MB cache, creates a snapshot of the dump, and records the
|
|
.Pa dumpdates
|
|
file.
|
|
.Bd -literal
|
|
/sbin/dump -0u -L -C16 -B4589840 -P 'growisofs -Z /dev/cd0=/dev/fd/0' /u
|
|
.Ed
|
|
.Sh DIAGNOSTICS
|
|
Many, and verbose.
|
|
.Sh SEE ALSO
|
|
.Xr chflags 1 ,
|
|
.Xr fstab 5 ,
|
|
.Xr restore 8 ,
|
|
.Xr rmt 8
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
utility appeared in
|
|
.At v6 .
|
|
.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
|
|
.Nm
|
|
is running.
|
|
Since dumps are often done in an unattended fashion using
|
|
.Xr cron 8
|
|
jobs asking for Operator intervention would result in the
|
|
.Nm
|
|
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
|
|
.Nm .
|
|
.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.
|