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