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