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