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