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