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