1.\" Copyright (c) 1980, 1991, 1993 2.\" Regents of the University of California. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. All advertising materials mentioning features or use of this software 14.\" must display the following acknowledgement: 15.\" This product includes software developed by the University of 16.\" California, Berkeley and its contributors. 17.\" 4. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)dump.8 8.1 (Berkeley) 6/16/93 34.\" $FreeBSD$ 35.\" 36.Dd June 16, 1993 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 0123456789BbhfusTdWn Op Ar argument ... 45.Op Ar filesystem 46.Sh DESCRIPTION 47.Nm Dump 48examines files 49on a filesystem 50and determines which files 51need to be backed up. These files 52are copied to the given disk, tape or other 53storage medium for safe keeping (see the 54.Cm f 55option below for doing remote backups). 56A dump that is larger than the output medium is broken into 57multiple volumes. 58On most media the size is determined by writing until an 59end-of-media indication is returned. 60On media that cannot reliably return an end-of-media indication 61(such as some cartridge tape drives) 62each volume is of a fixed size; 63the actual size is determined by the tape size and density and/or 64block count options below. 65By default, the same output file name is used for each volume 66after prompting the operator to change media. 67.Pp 68The following options are supported by 69.Nm dump: 70.Bl -tag -width 4n 71.It Cm 0\-9 72Dump levels. 73A level 0, full backup, 74guarantees the entire file system is copied 75(but see also the 76.Cm h 77option below). 78A level number above 0, 79incremental backup, 80tells dump to 81copy all files new or modified since the 82last dump of the same or lower level. The default 83level is 9. 84.It Cm B Ar records 85The number of dump records per volume. 86This option overrides the calculation of tape size 87based on length and density. 88.It Cm b Ar blocksize 89The number of kilobytes per dump record. 90.It Cm h Ar level 91Honor the user 92.Dq nodump 93flag 94.Dp Dv UF_NODUMP 95only for dumps at or above the given 96.Ar level . 97The default honor level is 1, 98so that incremental backups omit such files 99but full backups retain them. 100.It Cm f Ar file 101Write the backup to 102.Ar file ; 103.Ar file 104may be a special device file 105like 106.Pa /dev/rst0 107(a tape drive), 108.Pa /dev/rfd1 109(a floppy disk drive), 110an ordinary file, 111or 112.Ql Fl 113(the standard output). 114Multiple file names may be given as a single argument separated by commas. 115Each file will be used for one dump volume in the order listed; 116if the dump requires more volumes than the number of names given, 117the last file name will used for all remaining volumes after prompting 118for media changes. 119If the name of the file is of the form 120.Dq host:file , 121or 122.Dq user@host:file , 123.Nm dump 124writes to the named file on the remote host using 125.Xr rmt 8 . 126The default path name of the remote 127.Xr rmt 8 128program is 129.\" rmt path, is the path on the remote host 130.Pa /etc/rmt ; 131this can be overridden by the environment variable 132.Ev RMT . 133.It Cm d Ar density 134Set tape density to 135.Ar density . 136The default is 1600BPI. 137.It Cm n 138Whenever 139.Nm dump 140requires operator attention, 141notify all operators in the group 142.Dq operator 143by means similar to a 144.Xr wall 1 . 145.It Cm s Ar feet 146Attempt to calculate the amount of tape needed 147at a particular density. 148If this amount is exceeded, 149.Nm dump 150prompts for a new tape. 151It is recommended to be a bit conservative on this option. 152The default tape length is 2300 feet. 153.It Cm u 154Update the file 155.Pa /etc/dumpdates 156after a successful dump. 157The format of 158.Pa /etc/dumpdates 159is readable by people, consisting of one 160free format record per line: 161filesystem name, 162increment level 163and 164.Xr ctime 3 165format dump date. 166There may be only one entry per filesystem at each level. 167The file 168.Pa /etc/dumpdates 169may be edited to change any of the fields, 170if necessary. 171.It Cm T Ar date 172Use the specified date as the starting time for the dump 173instead of the time determined from looking in 174.Pa /etc/dumpdates . 175The format of date is the same as that of 176.Xr ctime 3 . 177This option is useful for automated dump scripts that wish to 178dump over a specific period of time. 179The 180.Cm T 181option is mutually exclusive from the 182.Cm u 183option. 184.It Cm W 185.Nm Dump 186tells the operator what file systems need to be dumped. 187This information is gleaned from the files 188.Pa /etc/dumpdates 189and 190.Pa /etc/fstab . 191The 192.Cm W 193option causes 194.Nm dump 195to print out, for each file system in 196.Pa /etc/dumpdates 197the most recent dump date and level, 198and highlights those file systems that should be dumped. 199If the 200.Cm W 201option is set, all other options are ignored, and 202.Nm dump 203exits immediately. 204.It Cm w 205Is like W, but prints only those filesystems which need to be dumped. 206.El 207.Pp 208.Nm Dump 209requires operator intervention on these conditions: 210end of tape, 211end of dump, 212tape write error, 213tape open error or 214disk read error (if there are more than a threshold of 32). 215In addition to alerting all operators implied by the 216.Cm n 217key, 218.Nm dump 219interacts with the operator on 220.Em dump's 221control terminal at times when 222.Nm dump 223can no longer proceed, 224or if something is grossly wrong. 225All questions 226.Nm dump 227poses 228.Em must 229be answered by typing 230.Dq yes 231or 232.Dq no , 233appropriately. 234.Pp 235Since making a dump involves a lot of time and effort for full dumps, 236.Nm dump 237checkpoints itself at the start of each tape volume. 238If writing that volume fails for some reason, 239.Nm dump 240will, 241with operator permission, 242restart itself from the checkpoint 243after the old tape has been rewound and removed, 244and a new tape has been mounted. 245.Pp 246.Nm Dump 247tells the operator what is going on at periodic intervals, 248including usually low estimates of the number of blocks to write, 249the number of tapes it will take, the time to completion, and 250the time to the tape change. 251The output is verbose, 252so that others know that the terminal 253controlling 254.Nm dump 255is busy, 256and will be for some time. 257.Pp 258In the event of a catastrophic disk event, the time required 259to restore all the necessary backup tapes or files to disk 260can be kept to a minimum by staggering the incremental dumps. 261An efficient method of staggering incremental dumps 262to minimize the number of tapes follows: 263.Bl -bullet -offset indent 264.It 265Always start with a level 0 backup, for example: 266.Bd -literal -offset indent 267/sbin/dump 0uf /dev/nrst0 /usr/src 268.Ed 269.Pp 270This should be done at set intervals, say once a month or once every two months, 271and on a set of fresh tapes that is saved forever. 272.It 273After a level 0, dumps of active file 274systems are taken on a daily basis, 275using a modified Tower of Hanoi algorithm, 276with this sequence of dump levels: 277.Bd -literal -offset indent 2783 2 5 4 7 6 9 8 9 9 ... 279.Ed 280.Pp 281For the daily dumps, it should be possible to use a fixed number of tapes 282for each day, used on a weekly basis. 283Each week, a level 1 dump is taken, and 284the daily Hanoi sequence repeats beginning with 3. 285For weekly dumps, another fixed set of tapes per dumped file system is 286used, also on a cyclical basis. 287.El 288.Pp 289After several months or so, the daily and weekly tapes should get 290rotated out of the dump cycle and fresh tapes brought in. 291.Sh ENVIRONMENT 292The environment variable 293.Ev RMT 294will be used to determine the pathname of the remote 295.Xr rmt 8 296program. 297.Sh FILES 298.Bl -tag -width /etc/dumpdates -compact 299.It Pa /dev/rst0 300default tape unit to dump to 301.It Pa /etc/dumpdates 302dump date records 303.It Pa /etc/fstab 304dump table: file systems and frequency 305.It Pa /etc/group 306to find group 307.Em operator 308.El 309.Sh SEE ALSO 310.Xr dump 5 , 311.Xr fstab 5 , 312.Xr ft 8 , 313.Xr restore 8 , 314.Xr rmt 8 315.Sh DIAGNOSTICS 316Many, and verbose. 317.Pp 318Dump exits with zero status on success. 319Startup errors are indicated with an exit code of 1; 320abnormal termination is indicated with an exit code of 3. 321.Sh BUGS 322.Pp 323Fewer than 32 read errors on the filesystem are ignored. 324Each reel requires a new process, so parent processes for 325reels already written just hang around until the entire tape 326is written. 327.Pp 328restore(8) is currently unable to restore dumps that were created 329with a blocksize larger than 32 on some tape drives. This is likely 330a bug in the tape driver. Workaround for safety reasons: 331dump aborts with an error message when choosing a blocksize > 32. 332.Pp 333.Nm Dump 334with the 335.Cm W 336or 337.Cm w 338options does not report filesystems that have never been recorded 339in 340.Pa /etc/dumpdates , 341even if listed in 342.Pa /etc/fstab . 343.Pp 344It would be nice if 345.Nm dump 346knew about the dump sequence, 347kept track of the tapes scribbled on, 348told the operator which tape to mount when, 349and provided more assistance 350for the operator running 351.Xr restore . 352.Sh HISTORY 353A 354.Nm dump 355command appeared in 356.At v6 . 357