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.\" @(#)dump.8 8.3 (Berkeley) 5/1/95 30.\" $FreeBSD: src/sbin/dump/dump.8,v 1.27.2.18 2003/02/23 19:58:23 trhodes Exp $ 31.\" 32.Dd September 29, 2016 33.Dt DUMP 8 34.Os 35.Sh NAME 36.Nm dump , 37.Nm rdump 38.Nd UFS file system backup 39.Sh SYNOPSIS 40.Nm 41.Op Fl 0123456789acknSu 42.Op Fl B Ar records 43.Op Fl b Ar blocksize 44.Op Fl D Ar dumpdates 45.Op Fl C Ar cachesize 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 filesystem 52.Nm 53.Fl W | Fl w 54.Sh DESCRIPTION 55The 56.Nm 57utility examines files 58on a file system 59and determines which files 60need to be backed up. 61These files 62are copied to the given disk, tape or other 63storage medium for safe keeping (see the 64.Fl f 65option below for doing remote backups). 66A dump that is larger than the output medium is broken into 67multiple volumes. 68On most media the size is determined by writing until an 69end-of-media indication is returned. 70This can be enforced 71by using the 72.Fl a 73option. 74.Pp 75On media that cannot reliably return an end-of-media indication 76(such as some cartridge tape drives) 77each volume is of a fixed size; 78the actual size is determined by the tape size and density and/or 79.Fl B 80options. 81By default, the same output file name is used for each volume 82after prompting the operator to change media. 83.Pp 84The file system to be dumped is specified by the argument 85.Ar filesystem 86as either its device-special file or its mount point 87(if that is in a standard entry in 88.Pa /etc/fstab ) . 89.Pp 90.Nm 91may also be invoked as 92.Nm rdump . 93The 94.Bx 4.3 95option syntax is implemented for backward compatibility, but 96is not documented here. 97.Pp 98The following options are supported by 99.Nm : 100.Bl -tag -width Ds 101.It Fl 0-9 102Dump levels. 103A level 0, full backup, 104guarantees the entire file system is copied 105(but see also the 106.Fl h 107option below). 108A level number above 0, 109incremental backup, 110tells dump to 111copy all files new or modified since the 112last dump of any lower level. 113The default level is 0. 114.It Fl a 115.Dq auto-size . 116Bypass all tape length considerations, and enforce writing 117until an end-of-media indication is returned. 118This fits best for most modern tape drives. 119Use of this option is particularly 120recommended when appending to an existing tape, or using a tape 121drive with hardware compression (where you can never be sure about 122the compression ratio). 123.It Fl B Ar records 124The number of kilobytes per output volume, except that if it is 125not an integer multiple of the output block size, 126the command uses the next smaller such multiple. 127This option overrides the calculation of tape size 128based on length and density. 129.It Fl b Ar blocksize 130The number of kilobytes per output block, except that if it is 131larger than 64, the command uses 64. (See the BUGS section.) 132The default block size is 10. 133.It Fl c 134Change the defaults for use with a cartridge tape drive, with a density 135of 8000 bpi, and a length of 1700 feet. 136.It Fl D Ar dumpdates 137Specify an alternate path to the 138.Pa dumpdates 139file. 140The default is 141.Pa /etc/dumpdates . 142.It Fl C Ar cachesize 143Specify the cache size in megabytes. This will greatly improve performance 144at the cost of 145.Nm 146possibly not noticing changes in the filesystem between passes. 147Beware that 148.Nm 149forks, and the actual memory use may be larger than the specified cache 150size. The recommended cache size is between 8 and 32 (megabytes). 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/sa0 162(a tape drive), 163.Pa /dev/fd1 164(a floppy disk drive), 165an ordinary file, 166or 167.Sq Fl 168(the standard output). 169Multiple file names may be given as a single argument separated by commas. 170Each file will be used for one dump volume in the order listed; 171if the dump requires more volumes than the number of names given, 172the last file name will used for all remaining volumes after prompting 173for media changes. 174If the name of the file is of the form 175.Dq host:file , 176or 177.Dq user@host:file , 178.Nm 179writes to the named file on the remote host using 180.Xr rmt 8 . 181The default path name of the remote 182.Xr rmt 8 183program is 184.\" rmt path, is the path on the remote host 185.Pa /etc/rmt ; 186this can be overridden by the environment variable 187.Ev RMT . 188.It Fl h Ar level 189Honor the user 190.Dq nodump 191flag 192.Pq Dv UF_NODUMP 193only for dumps at or above the given 194.Ar level . 195The default honor level is 1, 196so that incremental backups omit such files 197but full backups retain them. 198.It Fl k 199Use Kerberos authentication to talk to remote tape servers. (Only 200available if this option was enabled when 201.Nm 202was compiled.) 203.It Fl n 204Whenever 205.Nm 206requires operator attention, 207notify all operators in the group 208.Dq operator 209by means similar to a 210.Xr wall 1 . 211.It Fl s Ar feet 212Attempt to calculate the amount of tape needed 213at a particular density. 214If this amount is exceeded, 215.Nm 216prompts for a new tape. 217It is recommended to be a bit conservative on this option. 218The default tape length is 2300 feet. 219.It Fl S 220Display an estimate of the backup size and the number of 221tapes required, and exit without actually performing the dump. 222.It Fl T Ar date 223Use the specified date as the starting time for the dump 224instead of the time determined from looking in 225the 226.Pa dumpdates 227file. 228The format of date is the same as that of 229.Xr ctime 3 . 230This option is useful for automated dump scripts that wish to 231dump over a specific period of time. 232The 233.Fl T 234option is mutually exclusive from the 235.Fl u 236option. 237.It Fl u 238Update the 239.Pa dumpdates 240file 241after a successful dump. 242The format of 243the 244.Pa dumpdates 245file 246is readable by people, consisting of one 247free format record per line: 248file system name, 249increment level 250and 251.Xr ctime 3 252format dump date. 253There may be only one entry per file system at each level. 254The 255.Pa dumpdates 256file 257may be edited to change any of the fields, 258if necessary. 259The default path for the 260.Pa dumpdates 261file is 262.Pa /etc/dumpdates , 263but the 264.Fl D 265option may be used to change it. 266.It Fl W 267Tell the operator what file systems need to be dumped. 268This information is gleaned from the files 269.Pa dumpdates 270and 271.Pa /etc/fstab . 272The 273.Fl W 274option causes 275.Nm 276to print out, for each file system in 277the 278.Pa dumpdates 279file 280the most recent dump date and level, 281and highlights those file systems that should be dumped. 282If the 283.Fl W 284option is set, all other options are ignored, and 285.Nm 286exits immediately. 287.It Fl w 288Is like 289.Fl W , 290but prints only those file systems which need to be dumped. 291.El 292.Pp 293Directories and regular files which have their 294.Dq nodump 295flag 296.Pq Dv UF_NODUMP 297set will be omitted along with everything under such directories, 298subject to the 299.Fl h 300option. 301.Pp 302The 303.Nm 304utility requires operator intervention on these conditions: 305end of tape, 306end of dump, 307tape write error, 308tape open error or 309disk read error (if there are more than a threshold of 32). 310In addition to alerting all operators implied by the 311.Fl n 312key, 313.Nm 314interacts with the operator on 315.Em dump's 316control terminal at times when 317.Nm 318can no longer proceed, 319or if something is grossly wrong. 320All questions 321.Nm 322poses 323.Em must 324be answered by typing 325.Dq yes 326or 327.Dq no , 328appropriately. 329.Pp 330Since making a dump involves a lot of time and effort for full dumps, 331.Nm 332checkpoints itself at the start of each tape volume. 333If writing that volume fails for some reason, 334.Nm 335will, 336with operator permission, 337restart itself from the checkpoint 338after the old tape has been rewound and removed, 339and a new tape has been mounted. 340.Pp 341The 342.Nm 343utility tells the operator what is going on at periodic intervals 344(every 5 minutes, or promptly after receiving 345.Dv SIGINFO ) , 346including usually low estimates of the number of blocks to write, 347the number of tapes it will take, the time to completion, and 348the time to the tape change. 349The output is verbose, 350so that others know that the terminal 351controlling 352.Nm 353is busy, 354and will be for some time. 355.Pp 356In the event of a catastrophic disk event, the time required 357to restore all the necessary backup tapes or files to disk 358can be kept to a minimum by staggering the incremental dumps. 359An efficient method of staggering incremental dumps 360to minimize the number of tapes follows: 361.Bl -bullet -offset indent 362.It 363Always start with a level 0 backup, for example: 364.Bd -literal -offset indent 365/sbin/dump -0u -f /dev/nsa0 /usr/src 366.Ed 367.Pp 368This should be done at set intervals, say once a month or once every two months, 369and on a set of fresh tapes that is saved forever. 370.It 371After a level 0, dumps of active file systems are taken on a daily basis, 372using a modified Tower of Hanoi algorithm, 373with this sequence of dump levels: 374.Bd -literal -offset indent 3753 2 5 4 7 6 9 8 9 9 ... 376.Ed 377.Pp 378For the daily dumps, it should be possible to use a fixed number of tapes 379for each day, used on a weekly basis. 380Each week, a level 1 dump is taken, and 381the daily Hanoi sequence repeats beginning with 3. 382For weekly dumps, another fixed set of tapes per dumped file system is 383used, also on a cyclical basis. 384.El 385.Pp 386After several months or so, the daily and weekly tapes should get 387rotated out of the dump cycle and fresh tapes brought in. 388.Sh ENVIRONMENT 389.Bl -tag -width ".Ev TAPE" 390.It Ev TAPE 391Device from which to read backup. 392.It Ev RMT 393Pathname of the remote 394.Xr rmt 8 395program. 396.El 397.Sh FILES 398.Bl -tag -width /etc/dumpdates -compact 399.It Pa /dev/sa0 400default tape unit to dump to 401.It Pa /etc/dumpdates 402dump date records 403(this can be changed; 404see the 405.Fl D 406option) 407.It Pa /etc/fstab 408dump table: file systems and frequency 409.It Pa /etc/group 410to find group 411.Em operator 412.El 413.Sh EXIT STATUS 414Dump exits with zero status on success. 415Startup errors are indicated with an exit code of 1; 416abnormal termination is indicated with an exit code of 3. 417.Sh DIAGNOSTICS 418Many, and verbose. 419.Sh SEE ALSO 420.Xr chflags 1 , 421.Xr fstab 5 , 422.Xr UFS 5 , 423.Xr restore 8 , 424.Xr rmt 8 425.Sh HISTORY 426A 427.Nm 428utility appeared in 429.At v4 . 430.Sh BUGS 431Fewer than 32 read errors on the file system are ignored. 432.Pp 433Each reel requires a new process, so parent processes for 434reels already written just hang around until the entire tape 435is written. 436.Pp 437Currently, 438.Xr physio 9 439slices all requests into chunks of 64 KB. 440Therefore, it is 441impossible to use a larger output block size, so 442.Nm 443will prevent this from happening. 444.Pp 445The 446.Nm 447utility with the 448.Fl W 449or 450.Fl w 451options does not report file systems that have never been recorded 452in the 453.Pa dumpdates 454file, 455even if listed in 456.Pa /etc/fstab . 457.Pp 458It would be nice if 459.Nm 460knew about the dump sequence, 461kept track of the tapes scribbled on, 462told the operator which tape to mount when, 463and provided more assistance 464for the operator running 465.Xr restore 8 . 466.Pp 467The 468.Nm 469utility cannot do remote backups without being run as root, due to its 470security history. 471This may be fixed in a later version of 472.Dx . 473Presently, it works if you set it setuid (like it used to be), but this 474might constitute a security risk. 475