docs: Added All NetBSD Manuals

1 files changed, 608 insertions, 0 deletions

diff --git a/static/netbsd/man8/dump.8 b/static/netbsd/man8/dump.8
new file mode 100644
index 00000000..40b24857
--- /dev/null
+++ b/static/netbsd/man8/dump.8
@@ -0,0 +1,608 @@
+.\"	$NetBSD: dump.8,v 1.72 2019/08/19 18:12:50 perseant 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. 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 March 25, 2019
+.Dt DUMP 8
+.Os
+.Sh NAME
+.Nm dump ,
+.Nm rdump
+.Nd file system backup
+.Sh SYNOPSIS
+.Nm
+.Op Fl 0123456789aceFinStuX
+.Op Fl B Ar records
+.Op Fl b Ar blocksize
+.Op Fl D Ar dumpdates-file
+.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 l Ar timeout
+.Op Fl r Ar cachesize
+.Op Fl s Ar feet
+.Op Fl T Ar date
+.Op Fl U Ar dumpdev
+.Op Fl x Ar snap-backup
+.Ar files-to-dump
+.Nm
+.Op Fl W Li \&| Fl w
+.Pp
+.in -\n[indent-synopsis]u
+.Pf ( Bx 4.3
+option syntax is implemented for backward compatibility, but
+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.
+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
+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,
+the path to an unmounted file system listed in
+.Pa /etc/fstab ,
+or, if
+.Fl F
+is given, a file system image.
+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
+Any files with the superuser
+.Qq log
+flag
+.Pq Dv SF_LOG
+set will be skipped.
+These files are assumed to be
+.Xr wapbl 4
+journal files and will not be backed up.
+.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 (but see also the
+.Fl i
+option below).
+The default level is 9.
+.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 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 dumpdates-file
+Use the given file as a record of dump dates instead of
+.Pa /etc/dumpdates .
+.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
+Indicates that
+.Ar files-to-dump
+is a file system image.
+.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 be 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
+.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 i
+The dump is treated as level 9 but takes into account a previous
+level 9, if one exists.
+This makes it possible to perform a
+.Dq true incremental
+dump.
+.It Fl k Ar read-blocksize
+The size in kilobytes of the read buffers, rounded up to a multiple of the
+file system block size.
+Default is the value of the
+.Xr sysctl 7
+kern.maxphys.
+.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 l Ar timeout
+If a tape change is required, eject the tape and wait for the drive to
+be ready again.
+This is to be used with tape changers which automatically load
+the next tape when the tape is ejected.
+If after the timeout (in seconds) the drive is not ready
+.Nm
+falls back to the default behavior,
+and prompts the operator for the next tape.
+.It Fl n
+Whenever
+.Nm
+requires operator attention,
+notify all operators in the group
+.Qq operator
+using
+.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
+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
+.Pa /etc/dumpdates .
+The format of
+.Ar 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 and the
+.Fl u
+option are mutually exclusive.
+.It Fl t
+All informational log messages printed by
+.Nm
+will have the time prepended to them.
+Also, the completion time interval estimations
+will have the estimated time at which the dump
+will complete printed at the end of the line.
+.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 the
+.Fl T
+option is used or if a list of files or subdirectories is being dumped
+(as opposed to an entire file system), then
+.Fl u
+is ignored.
+.It Fl U Ar dumpdev
+Same as
+.Fl u
+but specifies the device in
+.Pa /etc/dumpdates
+as
+.Ar dumpdev .
+This option can be used with subdir dumps and with the
+.Fl T
+option.
+.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
+Like
+.Fl W ,
+but prints only those file systems which need to be dumped.
+.It Fl X
+Similar to
+.Fl x
+but uses a file system internal snapshot on the file system to be dumped.
+.It Fl x Ar snap-backup
+Use a snapshot with
+.Ar snap-backup
+as backup for this dump.
+See
+.Xr fss 4
+for more details.
+.El
+.Pp
+If
+.Nm
+honors the
+.Qq nodump
+flag
+.Pq 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.
+.Pp
+The historic alternate name
+.Nm rdump
+was once required when dumping to a remote host.
+This functionality is now built into
+.Nm
+itself.
+.Sh ENVIRONMENT
+If the following environment variables exist, they are used 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.
+.It Ev TIMEFORMAT
+can be used to control the format of the timestamps produced by the
+.Fl t
+option.
+.Ev TIMEFORMAT
+is a string containing embedded formatting commands for
+.Xr strftime 3 .
+The total formatted string is limited to about 80 characters, if this
+limit is exceeded then
+.Qo
+ERROR: TIMEFORMAT too long, reverting to default
+.Qc
+will be printed and the time format will revert to the default one.
+If
+.Ev TIMEFORMAT
+is not set then the format string defaults to
+.Qo
+%T %Z
+.Qc
+.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 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 SEE ALSO
+.Xr chflags 1 ,
+.Xr rcmd 1 ,
+.Xr stty 1 ,
+.Xr wall 1 ,
+.Xr fts 3 ,
+.Xr rcmd 3 ,
+.Xr fss 4 ,
+.Xr st 4 ,
+.Xr fstab 5 ,
+.Xr environ 7 ,
+.Xr restore 8 ,
+.Xr rmt 8
+.Sh HISTORY
+A
+.Nm
+command appeared in
+.At v4 .
+.Pp
+The
+.Fl i
+flag was inspired by the
+.Fl x
+flag from Sun's Solstice Backup utility.
+.Sh BUGS
+At least the following caveats can be mentioned.
+.Bl -bullet
+.It
+Fewer than 32 read errors on the file system are ignored.
+.It
+Each reel requires a new process, so parent processes for
+reels already written just hang around until the entire tape
+is written.
+.It
+.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 .
+.It
+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).
+.It
+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 .
+.It
+Snapshot support is
+.Em experimental .
+Be sure you have a backup before you use it.
+.El