1.\" Copyright (c) 1980, 1991, 1993 2.\" Regents of the University of California. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. Neither the name of the University nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd December 28, 2020 30.Dt DUMP 8 31.Os 32.Sh NAME 33.Nm dump , 34.Nm rdump 35.Nd file system backup 36.Sh SYNOPSIS 37.Nm 38.Op Fl 0123456789acLnrRSu 39.Op Fl B Ar records 40.Op Fl b Ar blocksize 41.Op Fl C Ar cachesize 42.Op Fl D Ar dumpdates 43.Op Fl d Ar density 44.Op Fl f Ar file | Fl P Ar pipecommand 45.Op Fl h Ar level 46.Op Fl s Ar feet 47.Op Fl T Ar date 48.Ar filesystem 49.Nm 50.Fl W | Fl w 51.Sh DESCRIPTION 52The 53.Nm 54utility examines files 55on a file system 56and determines which files 57need to be backed up. 58These files 59are copied to the given disk, tape or other 60storage medium for safe keeping (see the 61.Fl f 62option below for doing remote backups). 63A dump that is larger than the output medium is broken into 64multiple volumes. 65On most media the size is determined by writing until an 66end-of-media indication is returned. 67This can be enforced 68by using the 69.Fl a 70option. 71.Pp 72On media that cannot reliably return an end-of-media indication 73(such as some cartridge tape drives) 74each volume is of a fixed size; 75the actual size is determined by the tape size and density and/or 76.Fl B 77options. 78By default, the same output file name is used for each volume 79after prompting the operator to change media. 80.Pp 81The file system to be dumped is specified by the argument 82.Ar filesystem 83as either its device-special file or its mount point 84(if that is in a standard entry in 85.Pa /etc/fstab ) . 86.Pp 87.Nm 88may also be invoked as 89.Nm rdump . 90The 91.Bx 4.3 92option syntax is implemented for backward compatibility, but 93is not documented here. 94.Pp 95The following options are supported by 96.Nm : 97.Bl -tag -width Ds 98.It Fl 0-9 99Dump levels. 100A level 0, full backup, 101guarantees the entire file system is copied 102(but see also the 103.Fl h 104option below). 105A level number above 0, 106incremental backup, 107tells dump to 108copy all files new or modified since the 109last dump of any lower level. 110The default level is 0. 111.It Fl a 112.Dq auto-size . 113Bypass all tape length considerations, and enforce writing 114until an end-of-media indication is returned. 115This fits best for most modern tape drives. 116Use of this option is particularly 117recommended when appending to an existing tape, or using a tape 118drive with hardware compression (where you can never be sure about 119the compression ratio). 120.It Fl B Ar records 121The number of kilobytes per output volume, except that if it is 122not an integer multiple of the output block size, 123the command uses the next smaller such multiple. 124This option overrides the calculation of tape size 125based on length and density. 126.It Fl b Ar blocksize 127The number of kilobytes per output block. 128The default block size is 10. 129.It Fl C Ar cachesize 130Specify the cache size in megabytes. 131This will greatly improve performance 132at the cost of 133.Nm 134possibly not noticing changes in the file system between passes 135unless a snapshot is being used. 136The potential for performance improvement indicates that 137use of this option together with snapshots is the recommended 138course of action. 139Beware that 140.Nm 141forks, and the actual memory use may be larger than the specified cache 142size. 143The recommended cache size is between 8 and 32 (megabytes). 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 dumpdates 148Specify an alternate path to the 149.Pa dumpdates 150file. 151The default is 152.Pa /etc/dumpdates . 153.It Fl d Ar density 154Set tape density to 155.Ar density . 156The default is 1600BPI. 157.It Fl f Ar file 158Write the backup to 159.Ar file ; 160.Ar file 161may be a special device file 162like 163.Pa /dev/sa0 164(a tape drive), 165.Pa /dev/fd1 166(a floppy disk drive), 167an ordinary file, 168or 169.Sq Fl 170(the standard output). 171Multiple file names may be given as a single argument separated by commas. 172Each file will be used for one dump volume in the order listed; 173if the dump requires more volumes than the number of names given, 174the last file name will used for all remaining volumes after prompting 175for media changes. 176If the name of the file is of the form 177.Dq host:file , 178or 179.Dq user@host:file , 180.Nm 181writes to the named file on the remote host using 182.Xr rmt 8 . 183The default path name of the remote 184.Xr rmt 8 185program is 186.\" rmt path, is the path on the remote host 187.Pa /etc/rmt ; 188this can be overridden by the environment variable 189.Ev RMT . 190.It Fl P Ar pipecommand 191Use 192.Xr popen 3 193to execute the 194.Xr sh 1 195script string defined by 196.Ar pipecommand 197for the output device of each volume. 198This child pipeline's 199.Dv stdin 200.Pq Pa /dev/fd/0 201is redirected from the 202.Nm 203output stream, and the environment variable 204.Ev DUMP_VOLUME 205is set to the current volume number being written. 206After every volume, the writer side of the pipe is closed and 207.Ar pipecommand 208is executed again. 209Subject to the media size specified by 210.Fl B , 211each volume is written in this manner as if the output were a tape drive. 212.It Fl h Ar level 213Honor the user 214.Dq nodump 215flag 216.Pq Dv UF_NODUMP 217only for dumps at or above the given 218.Ar level . 219The default honor level is 1, 220so that incremental backups omit such files 221but full backups retain them. 222.It Fl L 223This option is to notify 224.Nm 225that it is dumping a live file system. 226To obtain a consistent dump image, 227.Nm 228takes a snapshot of the file system in the 229.Pa .snap 230directory in the root of the file system being dumped and 231then does a dump of the snapshot. 232The snapshot is unlinked as soon as the dump starts, and 233is thus removed when the dump is complete. 234This option is ignored for unmounted or read-only file systems. 235If the 236.Pa .snap 237directory does not exist in the root of the file system being dumped, 238a warning will be issued and the 239.Nm 240will revert to the standard behavior. 241This problem can be corrected by creating a 242.Pa .snap 243directory in the root of the file system to be dumped; 244its owner should be 245.Dq Li root , 246its group should be 247.Dq Li operator , 248and its mode should be 249.Dq Li 0770 . 250.It Fl n 251Whenever 252.Nm 253requires operator attention, 254notify all operators in the group 255.Dq operator 256by means similar to a 257.Xr wall 1 . 258.It Fl r 259Be rsync-friendly. 260Normally dump stores the date of the current 261and prior dump in numerous places throughout the dump. 262These scattered changes significantly slow down rsync or 263another incremental file transfer program when they are 264used to update a remote copy of a level 0 dump, 265since the date changes for each dump. 266This option sets both dates to the epoch, permitting 267rsync to be much more efficient when transferring a dump file. 268The 269.Fl r 270option can be used only to create level 0 dumps. 271A dump using the 272.Fl r 273option cannot be used as the basis for a later incremental dump. 274.It Fl R 275Be even more rsync-friendly. 276This option disables the storage of the actual inode access time 277(storing it instead as the inode's modified time). 278This option permits rsync to be even more efficient 279when transferring dumps generated from filesystems with numerous files 280which are not changing other than their access times. 281The 282.Fl R 283option also sets 284.Fl r . 285The 286.Fl R 287option can be used only to create level 0 dumps. 288A dump using the 289.Fl R 290option cannot be used as the basis for a later incremental dump. 291.It Fl S 292Display an estimate of the backup size and the number of 293tapes required, and exit without actually performing the dump. 294.It Fl s Ar feet 295Attempt to calculate the amount of tape needed 296at a particular density. 297If this amount is exceeded, 298.Nm 299prompts for a new tape. 300It is recommended to be a bit conservative on this option. 301The default tape length is 2300 feet. 302.It Fl T Ar date 303Use the specified date as the starting time for the dump 304instead of the time determined from looking in 305the 306.Pa dumpdates 307file. 308The format of date is the same as that of 309.Xr ctime 3 . 310This option is useful for automated dump scripts that wish to 311dump over a specific period of time. 312The 313.Fl T 314option is mutually exclusive from the 315.Fl u 316option. 317.It Fl u 318Update the 319.Pa dumpdates 320file 321after a successful dump. 322The format of 323the 324.Pa dumpdates 325file 326is readable by people, consisting of one 327free format record per line: 328file system name, 329increment level 330and 331.Xr ctime 3 332format dump date. 333There may be only one entry per file system at each level. 334The 335.Pa dumpdates 336file 337may be edited to change any of the fields, 338if necessary. 339The default path for the 340.Pa dumpdates 341file is 342.Pa /etc/dumpdates , 343but the 344.Fl D 345option may be used to change it. 346.It Fl W 347Tell the operator what file systems need to be dumped. 348This information is gleaned from the files 349.Pa dumpdates 350and 351.Pa /etc/fstab . 352The 353.Fl W 354option causes 355.Nm 356to print out, for each file system in 357the 358.Pa dumpdates 359file 360the most recent dump date and level, 361and highlights those file systems that should be dumped. 362If the 363.Fl W 364option is set, all other options are ignored, and 365.Nm 366exits immediately. 367.It Fl w 368Is like 369.Fl W , 370but prints only those file systems which need to be dumped. 371.El 372.Pp 373Directories and regular files which have their 374.Dq nodump 375flag 376.Pq Dv UF_NODUMP 377set will be omitted along with everything under such directories, 378subject to the 379.Fl h 380option. 381.Pp 382The 383.Nm 384utility requires operator intervention on these conditions: 385end of tape, 386end of dump, 387tape write error, 388tape open error or 389disk read error (if there are more than a threshold of 32). 390In addition to alerting all operators implied by the 391.Fl n 392key, 393.Nm 394interacts with the operator on 395.Em dump's 396control terminal at times when 397.Nm 398can no longer proceed, 399or if something is grossly wrong. 400All questions 401.Nm 402poses 403.Em must 404be answered by typing 405.Dq yes 406or 407.Dq no , 408appropriately. 409.Pp 410Since making a dump involves a lot of time and effort for full dumps, 411.Nm 412checkpoints itself at the start of each tape volume. 413If writing that volume fails for some reason, 414.Nm 415will, 416with operator permission, 417restart itself from the checkpoint 418after the old tape has been rewound and removed, 419and a new tape has been mounted. 420.Pp 421The 422.Nm 423utility tells the operator what is going on at periodic intervals 424(every 5 minutes, or promptly after receiving 425.Dv SIGINFO ) , 426including usually low estimates of the number of blocks to write, 427the number of tapes it will take, the time to completion, and 428the time to the tape change. 429The output is verbose, 430so that others know that the terminal 431controlling 432.Nm 433is busy, 434and will be for some time. 435.Pp 436In the event of a catastrophic disk event, the time required 437to restore all the necessary backup tapes or files to disk 438can be kept to a minimum by staggering the incremental dumps. 439An efficient method of staggering incremental dumps 440to minimize the number of tapes follows: 441.Bl -bullet -offset indent 442.It 443Always start with a level 0 backup, for example: 444.Bd -literal -offset indent 445/sbin/dump -0u -f /dev/nsa0 /usr/src 446.Ed 447.Pp 448This should be done at set intervals, say once a month or once every two months, 449and on a set of fresh tapes that is saved forever. 450.It 451After a level 0, dumps of active file systems (file systems with files 452that change, depending on your partition layout some file systems may 453contain only data that does not change) are taken on a daily basis, 454using a modified Tower of Hanoi algorithm, 455with this sequence of dump levels: 456.Bd -literal -offset indent 4573 2 5 4 7 6 9 8 9 9 ... 458.Ed 459.Pp 460For the daily dumps, it should be possible to use a fixed number of tapes 461for each day, used on a weekly basis. 462Each week, a level 1 dump is taken, and 463the daily Hanoi sequence repeats beginning with 3. 464For weekly dumps, another fixed set of tapes per dumped file system is 465used, also on a cyclical basis. 466.El 467.Pp 468After several months or so, the daily and weekly tapes should get 469rotated out of the dump cycle and fresh tapes brought in. 470.Sh ENVIRONMENT 471.Bl -tag -width ".Ev TAPE" 472.It Ev TAPE 473The 474.Ar file 475or device to dump to if the 476.Fl f 477option is not used. 478.It Ev RMT 479Pathname of the remote 480.Xr rmt 8 481program. 482.It Ev RSH 483Pathname of a remote shell program, if not 484.Xr rsh 1 . 485.El 486.Sh FILES 487.Bl -tag -width /etc/dumpdates -compact 488.It Pa /dev/sa0 489default tape unit to dump to 490.It Pa /etc/dumpdates 491dump date records 492(this can be changed; 493see the 494.Fl D 495option) 496.It Pa /etc/fstab 497dump table: file systems and frequency 498.It Pa /etc/group 499to find group 500.Em operator 501.El 502.Sh EXIT STATUS 503Dump exits with zero status on success. 504Startup errors are indicated with an exit code of 1; 505abnormal termination is indicated with an exit code of 3. 506.Sh EXAMPLES 507Dumps the 508.Pa /u 509file system to DVDs using 510.Nm growisofs . 511Uses a 16MB cache, creates a snapshot of the dump, and records the 512.Pa dumpdates 513file. 514.Bd -literal 515/sbin/dump -0u -L -C16 -B4589840 -P 'growisofs -Z /dev/cd0=/dev/fd/0' /u 516.Ed 517.Sh DIAGNOSTICS 518Many, and verbose. 519.Sh SEE ALSO 520.Xr chflags 1 , 521.Xr fstab 5 , 522.Xr restore 8 , 523.Xr rmt 8 524.Sh HISTORY 525A 526.Nm 527utility appeared in 528.At v4 . 529.Sh BUGS 530Fewer than 32 read errors on the file system are ignored, though all 531errors will generate a warning message. 532This is a bit of a compromise. 533In practice, it is possible to generate read errors when doing dumps 534on mounted partitions if the file system is being modified while the 535.Nm 536is running. 537Since dumps are often done in an unattended fashion using 538.Xr cron 8 539jobs asking for Operator intervention would result in the 540.Nm 541dying. 542However, there is nothing wrong with a dump tape written when this sort 543of read error occurs, and there is no reason to terminate the 544.Nm . 545.Pp 546Each reel requires a new process, so parent processes for 547reels already written just hang around until the entire tape 548is written. 549.Pp 550The 551.Nm 552utility with the 553.Fl W 554or 555.Fl w 556options does not report file systems that have never been recorded 557in the 558.Pa dumpdates 559file, 560even if listed in 561.Pa /etc/fstab . 562.Pp 563It would be nice if 564.Nm 565knew about the dump sequence, 566kept track of the tapes scribbled on, 567told the operator which tape to mount when, 568and provided more assistance 569for the operator running 570.Xr restore 8 . 571.Pp 572The 573.Nm 574utility cannot do remote backups without being run as root, due to its 575security history. 576This will be fixed in a later version of 577.Fx . 578Presently, it works if you set it setuid (like it used to be), but this 579might constitute a security risk. 580