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