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 file system backup 43.Sh SYNOPSIS 44.Nm 45.Op Fl 0123456789ackLnSu 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 file system 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 file system 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 file system 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.Sq 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 L 198This option is to notify 199.Nm 200that it is dumping a live file system. 201To obtain a consistent dump image, 202.Nm 203takes a snapshot of the file system and 204then does a dump of the snapshot. 205The snapshot is removed when the dump is complete. 206.It Fl n 207Whenever 208.Nm 209requires operator attention, 210notify all operators in the group 211.Dq operator 212by means similar to a 213.Xr wall 1 . 214.It Fl s Ar feet 215Attempt to calculate the amount of tape needed 216at a particular density. 217If this amount is exceeded, 218.Nm 219prompts for a new tape. 220It is recommended to be a bit conservative on this option. 221The default tape length is 2300 feet. 222.It Fl S 223Display an estimate of the backup size and the number of 224tapes required, and exit without actually performing the dump. 225.It Fl T Ar date 226Use the specified date as the starting time for the dump 227instead of the time determined from looking in 228the 229.Pa dumpdates 230file. 231The format of date is the same as that of 232.Xr ctime 3 . 233This option is useful for automated dump scripts that wish to 234dump over a specific period of time. 235The 236.Fl T 237option is mutually exclusive from the 238.Fl u 239option. 240.It Fl u 241Update the 242.Pa dumpdates 243file 244after a successful dump. 245The format of 246the 247.Pa dumpdates 248file 249is readable by people, consisting of one 250free format record per line: 251file system name, 252increment level 253and 254.Xr ctime 3 255format dump date. 256There may be only one entry per file system at each level. 257The 258.Pa dumpdates 259file 260may be edited to change any of the fields, 261if necessary. 262The default path for the 263.Pa dumpdates 264file is 265.Pa /etc/dumpdates , 266but the 267.Fl D 268option may be used to change it. 269.It Fl W 270Tell the operator what file systems need to be dumped. 271This information is gleaned from the files 272.Pa dumpdates 273and 274.Pa /etc/fstab . 275The 276.Fl W 277option causes 278.Nm 279to print out, for each file system in 280the 281.Pa dumpdates 282file 283the most recent dump date and level, 284and highlights those file systems that should be dumped. 285If the 286.Fl W 287option is set, all other options are ignored, and 288.Nm 289exits immediately. 290.It Fl w 291Is like W, but prints only those file systems which need to be dumped. 292.El 293.Pp 294Directories and regular files which have their 295.Dq nodump 296flag 297.Pq Dv UF_NODUMP 298set will be omitted along with everything under such directories, 299subject to the 300.Fl h 301option. 302.Pp 303The 304.Nm 305utility requires operator intervention on these conditions: 306end of tape, 307end of dump, 308tape write error, 309tape open error or 310disk read error (if there are more than a threshold of 32). 311In addition to alerting all operators implied by the 312.Fl n 313key, 314.Nm 315interacts with the operator on 316.Em dump's 317control terminal at times when 318.Nm 319can no longer proceed, 320or if something is grossly wrong. 321All questions 322.Nm 323poses 324.Em must 325be answered by typing 326.Dq yes 327or 328.Dq no , 329appropriately. 330.Pp 331Since making a dump involves a lot of time and effort for full dumps, 332.Nm 333checkpoints itself at the start of each tape volume. 334If writing that volume fails for some reason, 335.Nm 336will, 337with operator permission, 338restart itself from the checkpoint 339after the old tape has been rewound and removed, 340and a new tape has been mounted. 341.Pp 342The 343.Nm 344utility tells the operator what is going on at periodic intervals 345(every 5 minutes, or promptly after receiving 346.Dv SIGINFO ) , 347including usually low estimates of the number of blocks to write, 348the number of tapes it will take, the time to completion, and 349the time to the tape change. 350The output is verbose, 351so that others know that the terminal 352controlling 353.Nm 354is busy, 355and will be for some time. 356.Pp 357In the event of a catastrophic disk event, the time required 358to restore all the necessary backup tapes or files to disk 359can be kept to a minimum by staggering the incremental dumps. 360An efficient method of staggering incremental dumps 361to minimize the number of tapes follows: 362.Bl -bullet -offset indent 363.It 364Always start with a level 0 backup, for example: 365.Bd -literal -offset indent 366/sbin/dump -0u -f /dev/nsa0 /usr/src 367.Ed 368.Pp 369This should be done at set intervals, say once a month or once every two months, 370and on a set of fresh tapes that is saved forever. 371.It 372After a level 0, dumps of active file systems are taken on a daily basis, 373using a modified Tower of Hanoi algorithm, 374with this sequence of dump levels: 375.Bd -literal -offset indent 3763 2 5 4 7 6 9 8 9 9 ... 377.Ed 378.Pp 379For the daily dumps, it should be possible to use a fixed number of tapes 380for each day, used on a weekly basis. 381Each week, a level 1 dump is taken, and 382the daily Hanoi sequence repeats beginning with 3. 383For weekly dumps, another fixed set of tapes per dumped file system is 384used, also on a cyclical basis. 385.El 386.Pp 387After several months or so, the daily and weekly tapes should get 388rotated out of the dump cycle and fresh tapes brought in. 389.Sh ENVIRONMENT 390The environment variable 391.Ev RMT 392will be used to determine the pathname of the remote 393.Xr rmt 8 394program. 395.Sh FILES 396.Bl -tag -width /etc/dumpdates -compact 397.It Pa /dev/sa0 398default tape unit to dump to 399.It Pa /etc/dumpdates 400dump date records 401(this can be changed; 402see the 403.Fl D 404option) 405.It Pa /etc/fstab 406dump table: file systems and frequency 407.It Pa /etc/group 408to find group 409.Em operator 410.El 411.Sh SEE ALSO 412.Xr chflags 1 , 413.Xr fstab 5 , 414.Xr restore 8 , 415.Xr rmt 8 416.Sh DIAGNOSTICS 417Many, and verbose. 418.Pp 419Dump exits with zero status on success. 420Startup errors are indicated with an exit code of 1; 421abnormal termination is indicated with an exit code of 3. 422.Sh BUGS 423Fewer than 32 read errors on the file system are ignored. 424.Pp 425Each reel requires a new process, so parent processes for 426reels already written just hang around until the entire tape 427is written. 428.Pp 429Currently, 430.Xr physio 9 431slices all requests into chunks of 64 KB. Therefore, it is 432impossible to use a larger output block size, so 433.Nm 434will prevent this from happening. 435.Pp 436The 437.Nm 438utility with the 439.Fl W 440or 441.Fl w 442options does not report file systems that have never been recorded 443in the 444.Pa dumpdates 445file, 446even if listed in 447.Pa /etc/fstab . 448.Pp 449It would be nice if 450.Nm 451knew about the dump sequence, 452kept track of the tapes scribbled on, 453told the operator which tape to mount when, 454and provided more assistance 455for the operator running 456.Xr restore . 457.Pp 458The 459.Nm 460utility cannot do remote backups without being run as root, due to its 461security history. This will be fixed in a later version of 462.Fx . 463Presently, it works if you set it setuid (like it used to be), but this 464might constitute a security risk. 465.Sh HISTORY 466A 467.Nm 468utility appeared in 469.At v6 . 470