1.\" $OpenBSD: dump.8,v 1.56 2022/10/13 21:37:05 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: October 13 2022 $ 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 mount point 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. 296If no options are specified, the first of the 297.Ar files-to-dump 298must contain a 299.Ql / 300character to prevent it from being interpreted as a 301.Bx 4.3 302option string. 303.Pp 304.Nm 305requires operator intervention on these conditions: 306end of tape, 307end of dump, 308tape write error, 309tape open error or 310disk read error (if there is more than a threshold of 32). 311In addition to alerting all operators implied by the 312.Fl n 313flag, 314.Nm 315interacts with the operator on 316.Nm dump Ns 's 317controlling terminal at times when 318.Nm 319can no longer proceed, 320or if something is grossly wrong. 321All questions 322.Nm 323poses 324.Em must 325be answered by typing 326.Dq yes 327or 328.Dq no , 329appropriately. 330.Pp 331Since making a dump involves a lot of time and effort for full dumps, 332.Nm 333checkpoints itself at the start of each tape volume. 334If writing that volume fails for some reason, 335.Nm 336will, 337with operator permission, 338restart itself from the checkpoint 339after the old tape has been rewound and removed, 340and a new tape has been mounted. 341.Pp 342.Nm 343tells the operator what is going on at periodic intervals, 344including usually low estimates of the number of blocks to write, 345the number of tapes it will take, the time to completion, and 346the time to the tape change. 347The output is verbose, 348so that others know that the terminal 349controlling 350.Nm 351is busy, 352and will be for some time. 353.Pp 354If 355.Nm 356receives a 357.Dv SIGINFO 358signal 359(see the 360.Dq status 361argument of 362.Xr stty 1 ) 363whilst a backup is in progress, statistics on the amount completed, 364current transfer rate, and estimated finished time, will be written 365to the standard error output. 366.Pp 367In the event of a catastrophic disk event, the time required 368to restore all the necessary backup tapes or files to disk 369is dependent on the levels of the dumps taken. 370A few methods of staggering incremental dumps to either minimize 371backup effort or restore effort follow: 372.Bl -bullet -offset indent 373.It 374Always start with a level 0 backup, for example: 375.Bd -literal -offset indent 376# /sbin/dump -0u -f /dev/nrst1 /usr/src 377.Ed 378.Pp 379This should be done at set intervals, say once a month or once every two months, 380and on a set of fresh tapes that is saved forever. 381.It 382After the level 0 dump, 383backups of active file systems are taken on each day in a cycle of a week. 384Once a week, a level 1 dump is taken. 385The other days of the week a higher level dump is done. 386.Pp 387The following cycle needs at most three tapes to restore to a given point 388in time, 389but the dumps at the end of the weekly cycle will require more 390time and space: 391.Bd -literal -offset indent 3921 2 2 2 2 2 2 393.Ed 394.Pp 395This sequence requires at most eight tapes to restore, 396but the size of the individual dumps will be smaller: 397.Bd -literal -offset indent 3981 2 3 4 5 6 7 399.Ed 400.Pp 401This sequence seeks a compromise between backup and restore effort: 402.Bd -literal -offset indent 4031 2 2 3 3 4 4 404.Ed 405.Pp 406The weekly level 1 dumps should be done on a set of tapes that 407is used cyclically. 408For the daily dumps a tape per day of the week can be used. 409.It 410After several months or so, the daily and weekly tapes should get 411rotated out of the dump cycle and fresh tapes brought in. 412.El 413.Sh ENVIRONMENT 414.Bl -tag -width /etc/dumpdates 415.It Ev TAPE 416The default file to use instead of 417.Pa /dev/rst0 . 418See also 419.Fl f , 420above. 421.El 422.Sh FILES 423.Bl -tag -width /etc/dumpdates -compact 424.It Pa /dev/rst0 425default tape unit to dump to 426.It Pa /dev/rst* 427raw SCSI tape interface 428.It Pa /etc/dumpdates 429dump date records 430.It Pa /etc/fstab 431dump table: file systems and frequency 432.It Pa /etc/group 433to find group 434.Em operator 435.El 436.Sh EXIT STATUS 437.Nm 438exits with zero status on success. 439Startup errors are indicated with an exit code of 1; 440abnormal termination is indicated with an exit code of 3. 441.Sh DIAGNOSTICS 442Many, and verbose. 443.Sh SEE ALSO 444.Xr chflags 1 , 445.Xr stty 1 , 446.Xr fts_open 3 , 447.Xr rcmd 3 , 448.Xr st 4 , 449.Xr fstab 5 , 450.Xr restore 8 , 451.Xr rmt 8 452.Sh HISTORY 453A 454.Nm 455command appeared in 456.At v4 . 457.Pp 458The 459.Bx 4.3 460option syntax is implemented for backward compatibility but 461is not documented here. 462.Sh BUGS 463Fewer than 32 read errors on the filesystem are ignored. 464.Pp 465Each reel requires a new process, so parent processes for 466reels already written just hang around until the entire tape 467is written. 468.Pp 469.Nm 470with the 471.Fl W 472or 473.Fl w 474flag does not report filesystems that have never been recorded 475in 476.Pa /etc/dumpdates , 477even if listed in 478.Pa /etc/fstab . 479.Pp 480When dumping a list of files or subdirectories, access privileges are 481required to scan the directory (as this is done via the 482.Xr fts_open 3 483routines rather than directly accessing the filesystem). 484.Pp 485It would be nice if 486.Nm 487knew about the dump sequence, 488kept track of the tapes scribbled on, 489told the operator which tape to mount when, 490and provided more assistance 491for the operator running 492.Xr restore 8 . 493