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