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