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 acknowledgment: 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.3 (Berkeley) 5/1/95 34.\" $FreeBSD$ 35.\" 36.Dd March 1, 2002 37.Dt DUMP 8 38.Os 39.Sh NAME 40.Nm dump , 41.Nm rdump 42.Nd filesystem backup 43.Sh SYNOPSIS 44.Nm 45.Op Fl 0123456789acknSu 46.Op Fl B Ar records 47.Op Fl b Ar blocksize 48.Op Fl D Ar dumpdates 49.Op Fl d Ar density 50.Op Fl f Ar file 51.Op Fl h Ar level 52.Op Fl s Ar feet 53.Op Fl T Ar date 54.Ar filesystem 55.Nm 56.Op Fl W Li \&| Fl w 57.Pp 58.in \" XXX 59(The 60.Bx 4.3 61option syntax is implemented for backward compatibility, but 62is not documented here.) 63.Sh DESCRIPTION 64.Nm Dump 65examines files 66on a filesystem 67and determines which files 68need to be backed up. 69These files 70are copied to the given disk, tape or other 71storage medium for safe keeping (see the 72.Fl f 73option below for doing remote backups). 74A dump that is larger than the output medium is broken into 75multiple volumes. 76On most media the size is determined by writing until an 77end-of-media indication is returned. This can be enforced 78by using the 79.Fl a 80option. 81.Pp 82On media that cannot reliably return an end-of-media indication 83(such as some cartridge tape drives) 84each volume is of a fixed size; 85the actual size is determined by the tape size and density and/or 86block count options below. 87By default, the same output file name is used for each volume 88after prompting the operator to change media. 89.Pp 90The following options are supported by 91.Nm : 92.Bl -tag -width Ds 93.It Fl 0\-9 94Dump levels. 95A level 0, full backup, 96guarantees the entire file system is copied 97(but see also the 98.Fl h 99option below). 100A level number above 0, 101incremental backup, 102tells dump to 103copy all files new or modified since the 104last dump of any lower level. 105The default level is 0. 106.It Fl a 107.Dq auto-size . 108Bypass all tape length considerations, and enforce writing 109until an end-of-media indication is returned. This fits best 110for most modern tape drives. Use of this option is particularly 111recommended when appending to an existing tape, or using a tape 112drive with hardware compression (where you can never be sure about 113the compression ratio). 114.It Fl B Ar records 115The number of 1 KB blocks per volume. 116This option overrides the calculation of tape size 117based on length and density. 118.It Fl b Ar blocksize 119The number of kilobytes per dump record. 120.It Fl c 121Change the defaults for use with a cartridge tape drive, with a density 122of 8000 bpi, and a length of 1700 feet. 123.It Fl D Ar dumpdates 124Specify an alternate path to the 125.Pa dumpdates 126file. 127The default is 128.Pa /etc/dumpdates . 129.It Fl d Ar density 130Set tape density to 131.Ar density . 132The default is 1600BPI. 133.It Fl f Ar file 134Write the backup to 135.Ar file ; 136.Ar file 137may be a special device file 138like 139.Pa /dev/sa0 140(a tape drive), 141.Pa /dev/fd1 142(a floppy disk drive), 143an ordinary file, 144or 145.Ql Fl 146(the standard output). 147Multiple file names may be given as a single argument separated by commas. 148Each file will be used for one dump volume in the order listed; 149if the dump requires more volumes than the number of names given, 150the last file name will used for all remaining volumes after prompting 151for media changes. 152If the name of the file is of the form 153.Dq host:file , 154or 155.Dq user@host:file , 156.Nm 157writes to the named file on the remote host using 158.Xr rmt 8 . 159The default path name of the remote 160.Xr rmt 8 161program is 162.\" rmt path, is the path on the remote host 163.Pa /etc/rmt ; 164this can be overridden by the environment variable 165.Ev RMT . 166.It Fl h Ar level 167Honor the user 168.Dq nodump 169flag 170.Pq Dv UF_NODUMP 171only for dumps at or above the given 172.Ar level . 173The default honor level is 1, 174so that incremental backups omit such files 175but full backups retain them. 176.It Fl k 177Use Kerberos authentication to talk to remote tape servers. (Only 178available if this option was enabled when 179.Nm 180was compiled.) 181.It Fl n 182Whenever 183.Nm 184requires operator attention, 185notify all operators in the group 186.Dq operator 187by means similar to a 188.Xr wall 1 . 189.It Fl s Ar feet 190Attempt to calculate the amount of tape needed 191at a particular density. 192If this amount is exceeded, 193.Nm 194prompts for a new tape. 195It is recommended to be a bit conservative on this option. 196The default tape length is 2300 feet. 197.It Fl S 198Display an estimate of the backup size and the number of 199tapes required, and exit without actually performing the dump. 200.It Fl T Ar date 201Use the specified date as the starting time for the dump 202instead of the time determined from looking in 203the 204.Pa dumpdates 205file. 206The format of date is the same as that of 207.Xr ctime 3 . 208This option is useful for automated dump scripts that wish to 209dump over a specific period of time. 210The 211.Fl T 212option is mutually exclusive from the 213.Fl u 214option. 215.It Fl u 216Update the 217.Pa dumpdates 218file 219after a successful dump. 220The format of 221the 222.Pa dumpdates 223file 224is readable by people, consisting of one 225free format record per line: 226filesystem name, 227increment level 228and 229.Xr ctime 3 230format dump date. 231There may be only one entry per filesystem at each level. 232The 233.Pa dumpdates 234file 235may be edited to change any of the fields, 236if necessary. 237The default path for the 238.Pa dumpdates 239file is 240.Pa /etc/dumpdates , 241but the 242.Fl D 243option may be used to change it. 244.It Fl W 245.Nm Dump 246tells the operator what file systems need to be dumped. 247This information is gleaned from the files 248.Pa dumpdates 249and 250.Pa /etc/fstab . 251The 252.Fl W 253option causes 254.Nm 255to print out, for each file system in 256the 257.Pa dumpdates 258file 259the most recent dump date and level, 260and highlights those file systems that should be dumped. 261If the 262.Fl W 263option is set, all other options are ignored, and 264.Nm 265exits immediately. 266.It Fl w 267Is like W, but prints only those filesystems which need to be dumped. 268.El 269.Pp 270Directories and regular files which have their 271.Dq nodump 272flag 273.Pq Dv UF_NODUMP 274set will be omitted along with everything under such directories, 275subject to the 276.Fl h 277option. 278.Pp 279.Nm Dump 280requires operator intervention on these conditions: 281end of tape, 282end of dump, 283tape write error, 284tape open error or 285disk read error (if there are more than a threshold of 32). 286In addition to alerting all operators implied by the 287.Fl n 288key, 289.Nm 290interacts with the operator on 291.Em dump's 292control terminal at times when 293.Nm 294can no longer proceed, 295or if something is grossly wrong. 296All questions 297.Nm 298poses 299.Em must 300be answered by typing 301.Dq yes 302or 303.Dq no , 304appropriately. 305.Pp 306Since making a dump involves a lot of time and effort for full dumps, 307.Nm 308checkpoints itself at the start of each tape volume. 309If writing that volume fails for some reason, 310.Nm 311will, 312with operator permission, 313restart itself from the checkpoint 314after the old tape has been rewound and removed, 315and a new tape has been mounted. 316.Pp 317.Nm Dump 318tells the operator what is going on at periodic intervals 319(every 5 minutes, or promptly after receiving 320.Dv SIGINFO ) , 321including usually low estimates of the number of blocks to write, 322the number of tapes it will take, the time to completion, and 323the time to the tape change. 324The output is verbose, 325so that others know that the terminal 326controlling 327.Nm 328is busy, 329and will be for some time. 330.Pp 331In the event of a catastrophic disk event, the time required 332to restore all the necessary backup tapes or files to disk 333can be kept to a minimum by staggering the incremental dumps. 334An efficient method of staggering incremental dumps 335to minimize the number of tapes follows: 336.Bl -bullet -offset indent 337.It 338Always start with a level 0 backup, for example: 339.Bd -literal -offset indent 340/sbin/dump -0u -f /dev/nsa0 /usr/src 341.Ed 342.Pp 343This should be done at set intervals, say once a month or once every two months, 344and on a set of fresh tapes that is saved forever. 345.It 346After a level 0, dumps of active file 347systems are taken on a daily basis, 348using a modified Tower of Hanoi algorithm, 349with this sequence of dump levels: 350.Bd -literal -offset indent 3513 2 5 4 7 6 9 8 9 9 ... 352.Ed 353.Pp 354For the daily dumps, it should be possible to use a fixed number of tapes 355for each day, used on a weekly basis. 356Each week, a level 1 dump is taken, and 357the daily Hanoi sequence repeats beginning with 3. 358For weekly dumps, another fixed set of tapes per dumped file system is 359used, also on a cyclical basis. 360.El 361.Pp 362After several months or so, the daily and weekly tapes should get 363rotated out of the dump cycle and fresh tapes brought in. 364.Sh ENVIRONMENT 365The environment variable 366.Ev RMT 367will be used to determine the pathname of the remote 368.Xr rmt 8 369program. 370.Sh FILES 371.Bl -tag -width /etc/dumpdates -compact 372.It Pa /dev/sa0 373default tape unit to dump to 374.It Pa /etc/dumpdates 375dump date records 376(this can be changed; 377see the 378.Fl D 379option) 380.It Pa /etc/fstab 381dump table: file systems and frequency 382.It Pa /etc/group 383to find group 384.Em operator 385.El 386.Sh SEE ALSO 387.Xr chflags 1 , 388.Xr fstab 5 , 389.Xr restore 8 , 390.Xr rmt 8 391.Sh DIAGNOSTICS 392Many, and verbose. 393.Pp 394Dump exits with zero status on success. 395Startup errors are indicated with an exit code of 1; 396abnormal termination is indicated with an exit code of 3. 397.Sh BUGS 398Fewer than 32 read errors on the filesystem are ignored. 399.Pp 400Each reel requires a new process, so parent processes for 401reels already written just hang around until the entire tape 402is written. 403.Pp 404Currently, 405.Xr physio 9 406slices all requests into chunks of 64 KB. Therefore, it is 407impossible to use a larger tape blocksize, so 408.Nm 409will prevent this from happening. 410.Pp 411.Nm Dump 412with the 413.Fl W 414or 415.Fl w 416options does not report filesystems that have never been recorded 417in the 418.Pa dumpdates 419file, 420even if listed in 421.Pa /etc/fstab . 422.Pp 423It would be nice if 424.Nm 425knew about the dump sequence, 426kept track of the tapes scribbled on, 427told the operator which tape to mount when, 428and provided more assistance 429for the operator running 430.Xr restore . 431.Pp 432.Nm Dump 433cannot do remote backups without being run as root, due to its 434security history. This will be fixed in a later version of 435.Fx . 436Presently, it works if you set it setuid (like it used to be), but this 437might constitute a security risk. 438.Sh HISTORY 439A 440.Nm 441command appeared in 442.At v6 . 443