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 dump 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 dump 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. These files 68are copied to the given disk, tape or other 69storage medium for safe keeping (see the 70.Fl f 71option below for doing remote backups). 72A dump that is larger than the output medium is broken into 73multiple volumes. 74On most media the size is determined by writing until an 75end-of-media indication is returned. This can be enforced 76by using the 77.Fl a 78option. 79.Pp 80On media that cannot reliably return an end-of-media indication 81(such as some cartridge tape drives) 82each volume is of a fixed size; 83the actual size is determined by the tape size and density and/or 84block count options below. 85By default, the same output file name is used for each volume 86after prompting the operator to change media. 87.Pp 88The following options are supported by 89.Nm Ns : 90.Bl -tag -width Ds 91.It Fl 0\-9 92Dump levels. 93A level 0, full backup, 94guarantees the entire file system is copied 95(but see also the 96.Fl h 97option below). 98A level number above 0, 99incremental backup, 100tells dump to 101copy all files new or modified since the 102last dump of any lower level. 103The default level is 0. 104.It Fl B Ar records 105The number of 1 KB blocks per volume. 106This option overrides the calculation of tape size 107based on length and density. 108.It Fl a 109.Dq auto-size . 110Bypass all tape length considerations, and enforce writing 111until an end-of-media indication is returned. This fits best 112for most modern tape drives. Use of this option is particularly 113recommended when appending to an existing tape, or using a tape 114drive with hardware compression (where you can never be sure about 115the compression ratio). 116.It Fl b Ar blocksize 117The number of kilobytes per dump record. 118.It Fl c 119Change the defaults for use with a cartridge tape drive, with a density 120of 8000 bpi, and a length of 1700 feet. 121.It Fl h Ar level 122Honor the user 123.Dq nodump 124flag 125.Dp Dv UF_NODUMP 126only for dumps at or above the given 127.Ar level . 128The default honor level is 1, 129so that incremental backups omit such files 130but full backups retain them. 131.It Fl d Ar density 132Set tape density to 133.Ar density . 134The default is 1600BPI. 135.It Fl f Ar file 136Write the backup to 137.Ar file ; 138.Ar file 139may be a special device file 140like 141.Pa /dev/rsa0 142(a tape drive), 143.Pa /dev/rfd1 144(a floppy disk drive), 145an ordinary file, 146or 147.Ql Fl 148(the standard output). 149Multiple file names may be given as a single argument separated by commas. 150Each file will be used for one dump volume in the order listed; 151if the dump requires more volumes than the number of names given, 152the last file name will used for all remaining volumes after prompting 153for media changes. 154If the name of the file is of the form 155.Dq host:file , 156or 157.Dq user@host:file , 158.Nm 159writes to the named file on the remote host using 160.Xr rmt 8 . 161The default path name of the remote 162.Xr rmt 8 163program is 164.\" rmt path, is the path on the remote host 165.Pa /etc/rmt ; 166this can be overridden by the environment variable 167.Ev RMT . 168.It Fl k 169Use Kerberos authentication to talk to remote tape servers. (Only 170available if this option was enabled when 171.Nm 172was compiled.) 173.It Fl n 174Whenever 175.Nm 176requires operator attention, 177notify all operators in the group 178.Dq operator 179by means similar to a 180.Xr wall 1 . 181.It Fl s Ar feet 182Attempt to calculate the amount of tape needed 183at a particular density. 184If this amount is exceeded, 185.Nm 186prompts for a new tape. 187It is recommended to be a bit conservative on this option. 188The default tape length is 2300 feet. 189.ne 1i 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 ft 8 , 349.Xr restore 8 , 350.Xr rmt 8 351.Sh DIAGNOSTICS 352Many, and verbose. 353.Pp 354Dump exits with zero status on success. 355Startup errors are indicated with an exit code of 1; 356abnormal termination is indicated with an exit code of 3. 357.Sh BUGS 358Fewer than 32 read errors on the filesystem are ignored. 359.Pp 360Each reel requires a new process, so parent processes for 361reels already written just hang around until the entire tape 362is written. 363.Pp 364Currently, 365.Xr physio 9 366slices all requests into chunks of 64 KB. Therefore, it is 367impossible to use a larger tape blocksize, so 368.Nm 369will prevent this from happening. 370.Pp 371.Nm Dump 372with the 373.Fl W 374or 375.Fl w 376options does not report filesystems that have never been recorded 377in 378.Pa /etc/dumpdates , 379even if listed in 380.Pa /etc/fstab . 381.Pp 382It would be nice if 383.Nm 384knew about the dump sequence, 385kept track of the tapes scribbled on, 386told the operator which tape to mount when, 387and provided more assistance 388for the operator running 389.Xr restore . 390.Pp 391.Nm Dump 392cannot do remote backups without being run as root, due to its 393security history. This will be fixed in a later version of 394.Fx . 395Presently, it works if you set it setuid (like it used to be), but this 396might constitute a security risk. 397.Sh HISTORY 398A 399.Nm 400command appeared in 401.At v6 . 402