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 \" XXX 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.Pq 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/sa0 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 246honors the user 247.Dq nodump 248flag 249.Pq Dv UF_NODUMP 250on regular files and directories. 251If a directory is marked 252.Dq nodump , 253the latter and all files and directories under it will not be backed 254up. 255That is, 256.Nm 257propagates the 258.Dq nodump 259flag on directories. 260.Pp 261.Nm Dump 262requires operator intervention on these conditions: 263end of tape, 264end of dump, 265tape write error, 266tape open error or 267disk read error (if there are more than a threshold of 32). 268In addition to alerting all operators implied by the 269.Fl n 270key, 271.Nm 272interacts with the operator on 273.Em dump's 274control terminal at times when 275.Nm 276can no longer proceed, 277or if something is grossly wrong. 278All questions 279.Nm 280poses 281.Em must 282be answered by typing 283.Dq yes 284or 285.Dq no , 286appropriately. 287.Pp 288Since making a dump involves a lot of time and effort for full dumps, 289.Nm 290checkpoints itself at the start of each tape volume. 291If writing that volume fails for some reason, 292.Nm 293will, 294with operator permission, 295restart itself from the checkpoint 296after the old tape has been rewound and removed, 297and a new tape has been mounted. 298.Pp 299.Nm Dump 300tells the operator what is going on at periodic intervals, 301including usually low estimates of the number of blocks to write, 302the number of tapes it will take, the time to completion, and 303the time to the tape change. 304The output is verbose, 305so that others know that the terminal 306controlling 307.Nm 308is busy, 309and will be for some time. 310.Pp 311In the event of a catastrophic disk event, the time required 312to restore all the necessary backup tapes or files to disk 313can be kept to a minimum by staggering the incremental dumps. 314An efficient method of staggering incremental dumps 315to minimize the number of tapes follows: 316.Bl -bullet -offset indent 317.It 318Always start with a level 0 backup, for example: 319.Bd -literal -offset indent 320/sbin/dump -0u -f /dev/nsa0 /usr/src 321.Ed 322.Pp 323This should be done at set intervals, say once a month or once every two months, 324and on a set of fresh tapes that is saved forever. 325.It 326After a level 0, dumps of active file 327systems are taken on a daily basis, 328using a modified Tower of Hanoi algorithm, 329with this sequence of dump levels: 330.Bd -literal -offset indent 3313 2 5 4 7 6 9 8 9 9 ... 332.Ed 333.Pp 334For the daily dumps, it should be possible to use a fixed number of tapes 335for each day, used on a weekly basis. 336Each week, a level 1 dump is taken, and 337the daily Hanoi sequence repeats beginning with 3. 338For weekly dumps, another fixed set of tapes per dumped file system is 339used, also on a cyclical basis. 340.El 341.Pp 342After several months or so, the daily and weekly tapes should get 343rotated out of the dump cycle and fresh tapes brought in. 344.Sh ENVIRONMENT 345The environment variable 346.Ev RMT 347will be used to determine the pathname of the remote 348.Xr rmt 8 349program. 350.Sh FILES 351.Bl -tag -width /etc/dumpdates -compact 352.It Pa /dev/sa0 353default tape unit to dump to 354.It Pa /etc/dumpdates 355dump date records 356.It Pa /etc/fstab 357dump table: file systems and frequency 358.It Pa /etc/group 359to find group 360.Em operator 361.El 362.Sh SEE ALSO 363.Xr fstab 5 , 364.Xr restore 8 , 365.Xr rmt 8 366.Sh DIAGNOSTICS 367Many, and verbose. 368.Pp 369Dump exits with zero status on success. 370Startup errors are indicated with an exit code of 1; 371abnormal termination is indicated with an exit code of 3. 372.Sh BUGS 373Fewer than 32 read errors on the filesystem are ignored. 374.Pp 375Each reel requires a new process, so parent processes for 376reels already written just hang around until the entire tape 377is written. 378.Pp 379Currently, 380.Xr physio 9 381slices all requests into chunks of 64 KB. Therefore, it is 382impossible to use a larger tape blocksize, so 383.Nm 384will prevent this from happening. 385.Pp 386.Nm Dump 387with the 388.Fl W 389or 390.Fl w 391options does not report filesystems that have never been recorded 392in 393.Pa /etc/dumpdates , 394even if listed in 395.Pa /etc/fstab . 396.Pp 397It would be nice if 398.Nm 399knew about the dump sequence, 400kept track of the tapes scribbled on, 401told the operator which tape to mount when, 402and provided more assistance 403for the operator running 404.Xr restore . 405.Pp 406.Nm Dump 407cannot do remote backups without being run as root, due to its 408security history. This will be fixed in a later version of 409.Fx . 410Presently, it works if you set it setuid (like it used to be), but this 411might constitute a security risk. 412.Sh HISTORY 413A 414.Nm 415command appeared in 416.At v6 . 417