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 filesystem backup 43.Sh SYNOPSIS 44.Nm 45.Op Fl 0123456789acknSu 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 68.Nm Dump 69examines files 70on a filesystem 71and determines which files 72need to be backed up. 73These files 74are copied to the given disk, tape or other 75storage medium for safe keeping (see the 76.Fl f 77option below for doing remote backups). 78A dump that is larger than the output medium is broken into 79multiple volumes. 80On most media the size is determined by writing until an 81end-of-media indication is returned. This can be enforced 82by using the 83.Fl a 84option. 85.Pp 86On media that cannot reliably return an end-of-media indication 87(such as some cartridge tape drives) 88each volume is of a fixed size; 89the actual size is determined by the tape size and density and/or 90.Fl B 91options. 92By default, the same output file name is used for each volume 93after prompting the operator to change media. 94.Pp 95The filesystem to be dumped is specified by the argument 96.Ar filesystem 97as either its device-special file or its mount point 98(if that is in a standard entry in 99.Pa /etc/fstab ) . 100.Pp 101The following options are supported by 102.Nm : 103.Bl -tag -width Ds 104.It Fl 0\-9 105Dump levels. 106A level 0, full backup, 107guarantees the entire filesystem is copied 108(but see also the 109.Fl h 110option below). 111A level number above 0, 112incremental backup, 113tells dump to 114copy all files new or modified since the 115last dump of any lower level. 116The default level is 0. 117.It Fl a 118.Dq auto-size . 119Bypass all tape length considerations, and enforce writing 120until an end-of-media indication is returned. This fits best 121for most modern tape drives. Use of this option is particularly 122recommended when appending to an existing tape, or using a tape 123drive with hardware compression (where you can never be sure about 124the compression ratio). 125.It Fl B Ar records 126The number of kilobytes per output volume, except that if it is 127not an integer multiple of the output block size, 128the command uses the next smaller such multiple. 129This option overrides the calculation of tape size 130based on length and density. 131.It Fl b Ar blocksize 132The number of kilobytes per output block, except that if it is 133larger than 64, the command uses 64. (See the BUGS section.) 134The default block size is 10. 135.It Fl c 136Change the defaults for use with a cartridge tape drive, with a density 137of 8000 bpi, and a length of 1700 feet. 138.It Fl D Ar dumpdates 139Specify an alternate path to the 140.Pa dumpdates 141file. 142The default is 143.Pa /etc/dumpdates . 144.It Fl d Ar density 145Set tape density to 146.Ar density . 147The default is 1600BPI. 148.It Fl f Ar file 149Write the backup to 150.Ar file ; 151.Ar file 152may be a special device file 153like 154.Pa /dev/sa0 155(a tape drive), 156.Pa /dev/fd1 157(a floppy disk drive), 158an ordinary file, 159or 160.Ql Fl 161(the standard output). 162Multiple file names may be given as a single argument separated by commas. 163Each file will be used for one dump volume in the order listed; 164if the dump requires more volumes than the number of names given, 165the last file name will used for all remaining volumes after prompting 166for media changes. 167If the name of the file is of the form 168.Dq host:file , 169or 170.Dq user@host:file , 171.Nm 172writes to the named file on the remote host using 173.Xr rmt 8 . 174The default path name of the remote 175.Xr rmt 8 176program is 177.\" rmt path, is the path on the remote host 178.Pa /etc/rmt ; 179this can be overridden by the environment variable 180.Ev RMT . 181.It Fl h Ar level 182Honor the user 183.Dq nodump 184flag 185.Pq Dv UF_NODUMP 186only for dumps at or above the given 187.Ar level . 188The default honor level is 1, 189so that incremental backups omit such files 190but full backups retain them. 191.It Fl k 192Use Kerberos authentication to talk to remote tape servers. (Only 193available if this option was enabled when 194.Nm 195was compiled.) 196.It Fl n 197Whenever 198.Nm 199requires operator attention, 200notify all operators in the group 201.Dq operator 202by means similar to a 203.Xr wall 1 . 204.It Fl s Ar feet 205Attempt to calculate the amount of tape needed 206at a particular density. 207If this amount is exceeded, 208.Nm 209prompts for a new tape. 210It is recommended to be a bit conservative on this option. 211The default tape length is 2300 feet. 212.It Fl S 213Display an estimate of the backup size and the number of 214tapes required, and exit without actually performing the dump. 215.It Fl T Ar date 216Use the specified date as the starting time for the dump 217instead of the time determined from looking in 218the 219.Pa dumpdates 220file. 221The format of date is the same as that of 222.Xr ctime 3 . 223This option is useful for automated dump scripts that wish to 224dump over a specific period of time. 225The 226.Fl T 227option is mutually exclusive from the 228.Fl u 229option. 230.It Fl u 231Update the 232.Pa dumpdates 233file 234after a successful dump. 235The format of 236the 237.Pa dumpdates 238file 239is readable by people, consisting of one 240free format record per line: 241filesystem name, 242increment level 243and 244.Xr ctime 3 245format dump date. 246There may be only one entry per filesystem at each level. 247The 248.Pa dumpdates 249file 250may be edited to change any of the fields, 251if necessary. 252The default path for the 253.Pa dumpdates 254file is 255.Pa /etc/dumpdates , 256but the 257.Fl D 258option may be used to change it. 259.It Fl W 260.Nm Dump 261tells the operator what filesystems need to be dumped. 262This information is gleaned from the files 263.Pa dumpdates 264and 265.Pa /etc/fstab . 266The 267.Fl W 268option causes 269.Nm 270to print out, for each filesystem in 271the 272.Pa dumpdates 273file 274the most recent dump date and level, 275and highlights those filesystems that should be dumped. 276If the 277.Fl W 278option is set, all other options are ignored, and 279.Nm 280exits immediately. 281.It Fl w 282Is like W, but prints only those filesystems which need to be dumped. 283.El 284.Pp 285Directories and regular files which have their 286.Dq nodump 287flag 288.Pq Dv UF_NODUMP 289set will be omitted along with everything under such directories, 290subject to the 291.Fl h 292option. 293.Pp 294.Nm Dump 295requires operator intervention on these conditions: 296end of tape, 297end of dump, 298tape write error, 299tape open error or 300disk read error (if there are more than a threshold of 32). 301In addition to alerting all operators implied by the 302.Fl n 303key, 304.Nm 305interacts with the operator on 306.Em dump's 307control terminal at times when 308.Nm 309can no longer proceed, 310or if something is grossly wrong. 311All questions 312.Nm 313poses 314.Em must 315be answered by typing 316.Dq yes 317or 318.Dq no , 319appropriately. 320.Pp 321Since making a dump involves a lot of time and effort for full dumps, 322.Nm 323checkpoints itself at the start of each tape volume. 324If writing that volume fails for some reason, 325.Nm 326will, 327with operator permission, 328restart itself from the checkpoint 329after the old tape has been rewound and removed, 330and a new tape has been mounted. 331.Pp 332.Nm Dump 333tells the operator what is going on at periodic intervals 334(every 5 minutes, or promptly after receiving 335.Dv SIGINFO ) , 336including usually low estimates of the number of blocks to write, 337the number of tapes it will take, the time to completion, and 338the time to the tape change. 339The output is verbose, 340so that others know that the terminal 341controlling 342.Nm 343is busy, 344and will be for some time. 345.Pp 346In the event of a catastrophic disk event, the time required 347to restore all the necessary backup tapes or files to disk 348can be kept to a minimum by staggering the incremental dumps. 349An efficient method of staggering incremental dumps 350to minimize the number of tapes follows: 351.Bl -bullet -offset indent 352.It 353Always start with a level 0 backup, for example: 354.Bd -literal -offset indent 355/sbin/dump -0u -f /dev/nsa0 /usr/src 356.Ed 357.Pp 358This should be done at set intervals, say once a month or once every two months, 359and on a set of fresh tapes that is saved forever. 360.It 361After a level 0, dumps of active filesystems are taken on a daily basis, 362using a modified Tower of Hanoi algorithm, 363with this sequence of dump levels: 364.Bd -literal -offset indent 3653 2 5 4 7 6 9 8 9 9 ... 366.Ed 367.Pp 368For the daily dumps, it should be possible to use a fixed number of tapes 369for each day, used on a weekly basis. 370Each week, a level 1 dump is taken, and 371the daily Hanoi sequence repeats beginning with 3. 372For weekly dumps, another fixed set of tapes per dumped filesystem is 373used, also on a cyclical basis. 374.El 375.Pp 376After several months or so, the daily and weekly tapes should get 377rotated out of the dump cycle and fresh tapes brought in. 378.Sh ENVIRONMENT 379The environment variable 380.Ev RMT 381will be used to determine the pathname of the remote 382.Xr rmt 8 383program. 384.Sh FILES 385.Bl -tag -width /etc/dumpdates -compact 386.It Pa /dev/sa0 387default tape unit to dump to 388.It Pa /etc/dumpdates 389dump date records 390(this can be changed; 391see the 392.Fl D 393option) 394.It Pa /etc/fstab 395dump table: filesystems and frequency 396.It Pa /etc/group 397to find group 398.Em operator 399.El 400.Sh SEE ALSO 401.Xr chflags 1 , 402.Xr fstab 5 , 403.Xr restore 8 , 404.Xr rmt 8 405.Sh DIAGNOSTICS 406Many, and verbose. 407.Pp 408Dump exits with zero status on success. 409Startup errors are indicated with an exit code of 1; 410abnormal termination is indicated with an exit code of 3. 411.Sh BUGS 412Fewer than 32 read errors on the filesystem are ignored. 413.Pp 414Each reel requires a new process, so parent processes for 415reels already written just hang around until the entire tape 416is written. 417.Pp 418Currently, 419.Xr physio 9 420slices all requests into chunks of 64 KB. Therefore, it is 421impossible to use a larger output block size, so 422.Nm 423will prevent this from happening. 424.Pp 425.Nm Dump 426with the 427.Fl W 428or 429.Fl w 430options does not report filesystems that have never been recorded 431in the 432.Pa dumpdates 433file, 434even if listed in 435.Pa /etc/fstab . 436.Pp 437It would be nice if 438.Nm 439knew about the dump sequence, 440kept track of the tapes scribbled on, 441told the operator which tape to mount when, 442and provided more assistance 443for the operator running 444.Xr restore . 445.Pp 446.Nm Dump 447cannot do remote backups without being run as root, due to its 448security history. This will be fixed in a later version of 449.Fx . 450Presently, it works if you set it setuid (like it used to be), but this 451might constitute a security risk. 452.Sh HISTORY 453A 454.Nm 455command appeared in 456.At v6 . 457