1.\" $OpenBSD: dump.8,v 1.49 2015/05/03 01:44:34 guenther Exp $ 2.\" $NetBSD: dump.8,v 1.17 1997/06/05 11:15:06 lukem Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" Regents of the University of California. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)dump.8 8.1 (Berkeley) 6/16/93 33.\" 34.Dd $Mdocdate: May 3 2015 $ 35.Dt DUMP 8 36.Os 37.Sh NAME 38.Nm dump 39.Nd filesystem backup 40.Sh SYNOPSIS 41.Nm dump 42.Bk -words 43.Op Fl 0123456789acnSuWw 44.Op Fl B Ar records 45.Op Fl b Ar blocksize 46.Op Fl d Ar density 47.Op Fl f Ar file 48.Op Fl h Ar level 49.Op Fl s Ar feet 50.Op Fl T Ar date 51.Ar files-to-dump 52.Ek 53.Sh DESCRIPTION 54.Nm 55examines files 56on a filesystem 57and determines which files 58need to be backed up. 59These files are copied to the given disk, tape or other 60storage medium for safe keeping. 61A dump that is larger than the output medium is broken into 62multiple volumes. 63On most media the size is determined by writing until an 64end-of-media indication is returned. 65This can be enforced by using the 66.Fl a 67option. 68.Pp 69.Nm 70works across networks, 71replacing the functionality of the old 72.Nm rdump 73program 74(though 75.Nm 76may still be invoked as 77.Nm rdump ) . 78See the 79.Fl f 80option for more on writing backups to remote hosts. 81.Pp 82Files can be marked with the 83.Dq nodump 84flag using 85.Xr chflags 1 , 86settable only by the file's owner or the superuser. 87Files with this flag set will only be dumped during full backups. 88When set on a directory, 89.Dq nodump 90effectively deselects the whole subtree from being dumped, 91though it will still be scanned. 92See also the 93.Fl h 94option, below. 95.Pp 96On media that cannot reliably return an end-of-media indication 97(such as some cartridge tape drives), 98each volume is of a fixed size; 99the actual size is determined by the tape size, density and/or 100block count options below. 101By default, the same output file name is used for each volume 102after prompting the operator to change media. 103.Pp 104Rewinding or ejecting tape features after a close operation on 105a tape device depend on the name of the tape unit device used. 106See the 107.Fl f 108option and 109.Xr st 4 110for more information. 111.Pp 112The options are as follows: 113.Bl -tag -width Ds 114.It Fl 0\-9 115Dump levels. 116A level 0, full backup, 117guarantees the entire file system is copied 118(but see also the 119.Fl h 120option below). 121A level number above 0, 122incremental backup, 123tells 124.Nm 125to 126copy all files new or modified since the 127last dump of a lower level. 128The default level is 0. 129.It Fl a 130.Dq auto-size . 131Bypass all tape length considerations, and enforce writing until 132an end-of-media indication is returned. 133This option is recommended for most modern tape drives. 134Use of this option is particularly 135recommended when appending to an existing tape, or using a tape 136drive with hardware compression (where you can never be sure about 137the compression ratio). 138.It Fl B Ar records 139The number of kilobytes per volume, rounded 140down to a multiple of the blocksize. 141This option overrides the calculation of tape size 142based on length and density. 143.It Fl b Ar blocksize 144The number of kilobytes per dump record. 145Since the I/O system slices all requests into chunks of MAXBSIZE 146(typically 64KB), it is not possible to use a larger blocksize 147without having problems later with 148.Xr restore 8 . 149Therefore 150.Nm 151will constrain writes to MAXBSIZE. 152.It Fl c 153Change the defaults for use with a cartridge tape drive, with a density 154of 8000 bpi, and a length of 1700 feet. 155.It Fl d Ar density 156Set tape density to 157.Ar density . 158The default is 1600BPI. 159.It Fl f Ar file 160Write the backup to 161.Ar file ; 162.Ar file 163may be a special device file 164like 165.Pa /dev/rst0 166(a tape drive), 167.Pa /dev/rsd1c 168(a disk drive), 169an ordinary file, 170or 171.Sq - 172(the standard output). 173See also the 174.Ev TAPE 175environment variable, below. 176.Pp 177Multiple file names may be given as a single argument separated by commas. 178Each file will be used for one dump volume in the order listed; 179if the dump requires more volumes than the number of names given, 180the last file name will be used for all remaining volumes after prompting 181for media changes. 182If the name of the file is of the form 183.Dq host:file 184or 185.Dq user@host:file , 186.Nm 187writes to the named file on the remote host using 188.Xr rmt 8 . 189.It Fl h Ar level 190Honor the user 191.Dq nodump 192flag (see above), 193only for dumps at or above the given 194.Ar level . 195The default honor level is 1, 196so that incremental backups omit such files 197but full backups retain them. 198.It Fl n 199Whenever 200.Nm 201requires operator attention, 202notify all operators in the group 203.Dq operator 204by means similar to a 205.Xr wall 1 . 206.It Fl S 207Display an estimate of the backup size and the number of tapes 208required, and exit without actually performing the dump. 209.It Fl s Ar feet 210Attempt to calculate the amount of tape needed 211at a particular density. 212If this amount is exceeded, 213.Nm 214prompts for a new tape. 215It is recommended to be a bit conservative on this option. 216The default tape length is 2300 feet. 217.It Fl T Ar date 218Use the specified date as the starting time for the dump 219instead of the time determined from looking in 220.Pa /etc/dumpdates . 221The format of 222.Ar date 223is the same as that of 224.Xr ctime 3 . 225This option is useful for automated dump scripts that wish to 226dump over a specific period of time. 227The 228.Fl T 229flag is mutually exclusive from the 230.Fl u 231flag. 232.It Fl u 233Update the file 234.Pa /etc/dumpdates 235after a successful dump. 236The format of 237.Pa /etc/dumpdates 238is human readable, consisting of one 239free format record per line: 240filesystem name (defaults to 241.Xr disklabel 8 242UID when possible), 243increment level 244and 245.Xr ctime 3 246format dump date. 247There may be only one entry per filesystem at each level. 248The file 249.Pa /etc/dumpdates 250may be edited to change any of the fields, 251if necessary. 252If a list of files or subdirectories is being dumped 253(as opposed to an entire filesystem), then 254.Fl u 255is ignored. 256.It Fl W 257.Nm 258tells the operator what file systems need to be dumped. 259This information is gleaned from the files 260.Pa /etc/dumpdates 261and 262.Pa /etc/fstab . 263The 264.Fl W 265flag causes 266.Nm 267to print out, for each file system in 268.Pa /etc/dumpdates , 269the most recent dump date and level, 270and highlights those file systems that should be dumped. 271If the 272.Fl W 273flag is set, all other options are ignored, and 274.Nm 275exits immediately. 276.It Fl w 277Same as 278.Fl W , 279but prints only those filesystems which need to be dumped. 280.El 281.Pp 282.Ar files-to-dump 283is either a mountpoint of a filesystem 284or a list of files and directories on a single filesystem to be backed 285up as a subset of the filesystem. 286In the former case, either the path to a mounted filesystem, 287the device of an unmounted filesystem or the 288.Xr disklabel 8 289UID can be used. 290In the latter case, certain restrictions are placed on the backup: 291.Fl u 292is ignored, the only dump level that is supported is 293.Fl 0 , 294and all of the files must reside on the same filesystem. 295.Pp 296.Nm 297requires operator intervention on these conditions: 298end of tape, 299end of dump, 300tape write error, 301tape open error or 302disk read error (if there is more than a threshold of 32). 303In addition to alerting all operators implied by the 304.Fl n 305flag, 306.Nm 307interacts with the operator on 308.Nm dump Ns 's 309control terminal at times when 310.Nm 311can no longer proceed, 312or if something is grossly wrong. 313All questions 314.Nm 315poses 316.Em must 317be answered by typing 318.Dq yes 319or 320.Dq no , 321appropriately. 322.Pp 323Since making a dump involves a lot of time and effort for full dumps, 324.Nm 325checkpoints itself at the start of each tape volume. 326If writing that volume fails for some reason, 327.Nm 328will, 329with operator permission, 330restart itself from the checkpoint 331after the old tape has been rewound and removed, 332and a new tape has been mounted. 333.Pp 334.Nm 335tells the operator what is going on at periodic intervals, 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 346If 347.Nm 348receives a 349.Dv SIGINFO 350signal 351(see the 352.Dq status 353argument of 354.Xr stty 1 ) 355whilst a backup is in progress, statistics on the amount completed, 356current transfer rate, and estimated finished time, will be written 357to the standard error output. 358.Pp 359In the event of a catastrophic disk event, the time required 360to restore all the necessary backup tapes or files to disk 361is dependent on the levels of the dumps taken. 362A few methods of staggering incremental dumps to either minimize 363backup effort or restore effort follow: 364.Bl -bullet -offset indent 365.It 366Always start with a level 0 backup, for example: 367.Bd -literal -offset indent 368# /sbin/dump -0u -f /dev/nrst1 /usr/src 369.Ed 370.Pp 371This should be done at set intervals, say once a month or once every two months, 372and on a set of fresh tapes that is saved forever. 373.It 374After the level 0 dump, 375backups of active file systems are taken on each day in a cycle of a week. 376Once a week, a level 1 dump is taken. 377The other days of the week a higher level dump is done. 378.Pp 379The following cycle needs at most three tapes to restore to a given point 380in time, 381but the dumps at the end of the weekly cycle will require more 382time and space: 383.Bd -literal -offset indent 3841 2 2 2 2 2 2 385.Ed 386.Pp 387This sequence requires at most eight tapes to restore, 388but the size of the individual dumps will be smaller: 389.Bd -literal -offset indent 3901 2 3 4 5 6 7 391.Ed 392.Pp 393This sequence seeks a compromise between backup and restore effort: 394.Bd -literal -offset indent 3951 2 2 3 3 4 4 396.Ed 397.Pp 398The weekly level 1 dumps should be done on a set of tapes that 399is used cyclically. 400For the daily dumps a tape per day of the week can be used. 401.It 402After several months or so, the daily and weekly tapes should get 403rotated out of the dump cycle and fresh tapes brought in. 404.El 405.Sh ENVIRONMENT 406.Bl -tag -width /etc/dumpdates 407.It Ev TAPE 408The default file to use instead of 409.Pa /dev/rst0 . 410See also 411.Fl f , 412above. 413.El 414.Sh FILES 415.Bl -tag -width /etc/dumpdates -compact 416.It Pa /dev/rst0 417default tape unit to dump to 418.It Pa /dev/rst* 419raw SCSI tape interface 420.It Pa /etc/dumpdates 421dump date records 422.It Pa /etc/fstab 423dump table: file systems and frequency 424.It Pa /etc/group 425to find group 426.Em operator 427.El 428.Sh DIAGNOSTICS 429Many, and verbose. 430.Pp 431.Nm 432exits with zero status on success. 433Startup errors are indicated with an exit code of 1; 434abnormal termination is indicated with an exit code of 3. 435.Sh SEE ALSO 436.Xr chflags 1 , 437.Xr stty 1 , 438.Xr fts 3 , 439.Xr rcmd 3 , 440.Xr st 4 , 441.Xr fstab 5 , 442.Xr restore 8 , 443.Xr rmt 8 444.Sh HISTORY 445A 446.Nm 447command appeared in 448.At v5 . 449.Pp 450The 451.Bx 4.3 452option syntax is implemented for backward compatibility but 453is not documented here. 454.Sh BUGS 455Fewer than 32 read errors on the filesystem are ignored. 456.Pp 457Each reel requires a new process, so parent processes for 458reels already written just hang around until the entire tape 459is written. 460.Pp 461.Nm 462with the 463.Fl W 464or 465.Fl w 466flag does not report filesystems that have never been recorded 467in 468.Pa /etc/dumpdates , 469even if listed in 470.Pa /etc/fstab . 471.Pp 472When dumping a list of files or subdirectories, access privileges are 473required to scan the directory (as this is done via the 474.Xr fts 3 475routines rather than directly accessing the filesystem). 476.Pp 477It would be nice if 478.Nm 479knew about the dump sequence, 480kept track of the tapes scribbled on, 481told the operator which tape to mount when, 482and provided more assistance 483for the operator running 484.Xr restore 8 . 485