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