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