1.\" $NetBSD: dump.8,v 1.58 2009/01/30 11:55:04 enami Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" Regents of the University of California. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)dump.8 8.3 (Berkeley) 5/1/95 32.\" 33.Dd August 12, 2008 34.Dt DUMP 8 35.Os 36.Sh NAME 37.Nm dump , 38.Nm rdump 39.Nd file system backup 40.Sh SYNOPSIS 41.Nm 42.Op Fl 0123456789aceFnStuX 43.Bk -words 44.Op Fl B Ar records 45.Ek 46.Bk -words 47.Op Fl b Ar blocksize 48.Ek 49.Bk -words 50.Op Fl d Ar density 51.Ek 52.Bk -words 53.Op Fl f Ar file 54.Ek 55.Bk -words 56.Op Fl h Ar level 57.Ek 58.Bk -words 59.Op Fl k Ar read-blocksize 60.Ek 61.Bk -words 62.Op Fl L Ar label 63.Ek 64.Bk -words 65.Op Fl l Ar timeout 66.Ek 67.Bk -words 68.Op Fl r Ar cachesize 69.Ek 70.Bk -words 71.Op Fl s Ar feet 72.Ek 73.Bk -words 74.Op Fl T Ar date 75.Ek 76.Bk -words 77.Op Fl x Ar snap-backup 78.Ek 79.Ar files-to-dump 80.Nm 81.Op Fl W Li \&| Fl w 82.Pp 83.in -\n[indent-synopsis]u 84(The 85.Bx 4.3 86option syntax is implemented for backward compatibility, but 87is not documented here). 88.Sh DESCRIPTION 89.Nm 90examines files on a file system and determines which files need to 91be backed up. 92These files are copied to the given disk, tape or other storage 93medium for safe keeping (see the 94.Fl f 95option below for doing remote backups). 96A dump that is larger than the output medium is broken into 97multiple volumes. 98On most media the size is determined by writing until an 99end-of-media indication is returned. 100This can be enforced by using the 101.Fl a 102option. 103.Pp 104On media that cannot reliably return an end-of-media indication 105(such as some cartridge tape drives) each volume is of a fixed size; 106the actual size is determined by the tape size and density and/or 107block count options below. 108By default, the same output file name is used for each volume 109after prompting the operator to change media. 110.Pp 111.Ar files-to-dump 112is either a single file system, 113or a list of files and directories on a single file system to be backed 114up as a subset of the file system. 115In the former case, 116.Ar files-to-dump 117may be the device of a file system, 118the path to a currently mounted file system, 119the path to an unmounted file system listed in 120.Pa /etc/fstab , 121or, if 122.Fl F 123is given, a file system image. 124In the latter case, certain restrictions are placed on the backup: 125.Fl u 126is ignored, the only dump level that is supported is 127.Fl 0 , 128and all of the files must reside on the same file system. 129.Pp 130Any files with the superuser 131.Qq log 132flag 133.Pq Dv SF_LOG 134set will be skipped. 135These files are assumed to be 136.Xr wapbl 4 137journal files and will not be backed up. 138.Pp 139The following options are supported by 140.Nm : 141.Bl -tag -width Ds 142.It Fl 0\-9 143Dump levels. 144A level 0, full backup, guarantees the entire file system is copied 145(but see also the 146.Fl h 147option below). 148A level number above 0, incremental backup, 149tells dump to copy all files new or modified since the 150last dump of a lower level. 151The default level is 9. 152.It Fl a 153.Dq auto-size . 154Bypass all tape length considerations, and enforce writing 155until an end-of-media indication is returned. 156This fits best for most modern tape drives. 157Use of this option is particularly recommended when appending to an 158existing tape, or using a tape drive with hardware compression (where 159you can never be sure about the compression ratio). 160.It Fl B Ar records 161The number of kilobytes per volume, rounded 162down to a multiple of the blocksize. 163This option overrides the calculation of tape size 164based on length and density. 165.It Fl b Ar blocksize 166The number of kilobytes per dump record. 167.It Fl c 168Modify the calculation of the default density and tape size to be more 169appropriate for cartridge tapes. 170.It Fl d Ar density 171Set tape density to 172.Ar density . 173The default is 1600 Bits Per Inch (BPI). 174.It Fl e 175Eject tape automatically if a tape change is required. 176.It Fl F 177Indicates that 178.Ar files-to-dump 179is a file system image. 180.It Fl f Ar file 181Write the backup to 182.Ar file ; 183.Ar file 184may be a special device file like 185.Pa /dev/rst0 186(a tape drive), 187.Pa /dev/rsd1c 188(a disk drive), 189an ordinary file, or 190.Ql Fl 191(the standard output). 192Multiple file names may be given as a single argument separated by commas. 193Each file will be used for one dump volume in the order listed; 194if the dump requires more volumes than the number of names given, 195the last file name will used for all remaining volumes after prompting 196for media changes. 197If the name of the file is of the form 198.Qq host:file , 199or 200.Qq user@host:file , 201.Nm 202writes to the named file on the remote host using 203.Xr rmt 8 . 204Note that methods more secure than 205.Xr rsh 1 206.Pq such as Xr ssh 1 207can be used to invoke 208.Xr rmt 8 209on the remote host, via the environment variable 210.Ev RCMD_CMD . 211See 212.Xr rcmd 3 213for more details. 214.It Fl h Ar level 215Honor the user 216.Qq nodump 217flag 218.Pq Dv UF_NODUMP 219only for dumps at or above the given 220.Ar level . 221The default honor level is 1, 222so that incremental backups omit such files 223but full backups retain them. 224.It Fl k Ar read-blocksize 225The size in kilobyte of the read buffers, rounded up to a multiple of the 226file system block size. 227Default is 32k. 228.It Fl l Ar timeout 229If a tape change is required, eject the tape and wait for the drive to 230be ready again. 231This is to be used with tape changers which automatically load 232the next tape when the tape is ejected. 233If after the timeout (in seconds) the drive is not ready 234.Nm 235falls back to the default behavior, 236and prompts the operator for the next tape. 237.It Fl L Ar label 238The user-supplied text string 239.Ar label 240is placed into the dump header, where tools like 241.Xr restore 8 242and 243.Xr file 1 244can access it. 245Note that this label is limited to be at most LBLSIZE 246(currently 16) characters, which must include the terminating 247.Ql \e0 . 248.It Fl n 249Whenever 250.Nm 251requires operator attention, 252notify all operators in the group 253.Qq operator 254using 255.Xr wall 1 . 256.It Fl r Ar cachesize 257Use that many buffers for read cache operations. 258A value of zero disables the read cache altogether, higher values 259improve read performance by reading larger data blocks from the 260disk and maintaining them in an LRU cache. 261See the 262.Fl k 263option for the size of the buffers. 264Maximum is 512, the size of the cache is 265limited to 15% of the avail RAM by default. 266.It Fl s Ar feet 267Attempt to calculate the amount of tape needed 268at a particular density. 269If this amount is exceeded, 270.Nm 271prompts for a new tape. 272It is recommended to be a bit conservative on this option. 273The default tape length is 2300 feet. 274.It Fl S 275Display an estimate of the backup size and the number of tapes 276required, and exit without actually performing the dump. 277.It Fl t 278All informational log messages printed by 279.Nm 280will have the time prepended to them. 281Also, the completion time interval estimations 282will have the estimated time at which the dump 283will complete printed at the end of the line. 284.It Fl T Ar date 285Use the specified date as the starting time for the dump 286instead of the time determined from looking in 287.Pa /etc/dumpdates . 288The format of date is the same as that of 289.Xr ctime 3 . 290This option is useful for automated dump scripts that wish to 291dump over a specific period of time. 292The 293.Fl T 294option is mutually exclusive from the 295.Fl u 296option. 297.It Fl u 298Update the file 299.Pa /etc/dumpdates 300after a successful dump. 301The format of 302.Pa /etc/dumpdates 303is readable by people, consisting of one 304free format record per line: 305file system name, 306increment level 307and 308.Xr ctime 3 309format dump date. 310There may be only one entry per file system at each level. 311The file 312.Pa /etc/dumpdates 313may be edited to change any of the fields, 314if necessary. 315If a list of files or subdirectories is being dumped 316(as opposed to an entire file system), then 317.Fl u 318is ignored. 319.It Fl x Ar snap-backup 320Use a snapshot with 321.Ar snap-backup 322as backup for this dump. 323See 324.Xr fss 4 325for more details. 326Snapshot support is 327.Em experimental . 328Be sure you have a backup before you use it. 329.It Fl X 330Similar to 331.Fl x 332but uses a file system internal snapshot on the file system to be dumped. 333.It Fl W 334.Nm 335tells the operator what file systems need to be dumped. 336This information is gleaned from the files 337.Pa /etc/dumpdates 338and 339.Pa /etc/fstab . 340The 341.Fl W 342option causes 343.Nm 344to print out, for each file system in 345.Pa /etc/dumpdates 346the most recent dump date and level, 347and highlights those file systems that should be dumped. 348If the 349.Fl W 350option is set, all other options are ignored, and 351.Nm 352exits immediately. 353.It Fl w 354Is like W, but prints only those file systems which need to be dumped. 355.El 356.Pp 357If 358.Nm 359honors the 360.Qq nodump 361flag 362.Pq Dv UF_NODUMP , 363files with the 364.Qq nodump 365flag will not be backed up. 366If a directory has the 367.Qq nodump 368flag, this directory and any file or directory under it will not be backed up. 369.Pp 370.Nm 371requires operator intervention on these conditions: 372end of tape, 373end of dump, 374tape write error, 375tape open error or 376disk read error (if there are more than a threshold of 32). 377In addition to alerting all operators implied by the 378.Fl n 379option, 380.Nm 381interacts with the operator on 382.Nm Ns 's 383control terminal at times when 384.Nm 385can no longer proceed, 386or if something is grossly wrong. 387All questions 388.Nm 389poses 390.Em must 391be answered by typing 392.Qq yes 393or 394.Qq no , 395appropriately. 396.Pp 397Since making a dump involves a lot of time and effort for full dumps, 398.Nm 399checkpoints itself at the start of each tape volume. 400If writing that volume fails for some reason, 401.Nm 402will, 403with operator permission, 404restart itself from the checkpoint 405after the old tape has been rewound and removed, 406and a new tape has been mounted. 407.Pp 408.Nm 409tells the operator what is going on at periodic intervals, 410including usually low estimates of the number of blocks to write, 411the number of tapes it will take, the time to completion, and 412the time to the tape change. 413The output is verbose, 414so that others know that the terminal 415controlling 416.Nm 417is busy, 418and will be for some time. 419.Pp 420In the event of a catastrophic disk event, the time required 421to restore all the necessary backup tapes or files to disk 422can be kept to a minimum by staggering the incremental dumps. 423An efficient method of staggering incremental dumps 424to minimize the number of tapes follows: 425.Bl -bullet -offset indent 426.It 427Always start with a level 0 backup, for example: 428.Bd -literal -offset indent 429/sbin/dump -0u -f /dev/nrst1 /usr/src 430.Ed 431.Pp 432This should be done at set intervals, say once a month or once every two months, 433and on a set of fresh tapes that is saved forever. 434.It 435After a level 0, dumps of active file 436systems are taken on a daily basis, 437using a modified Tower of Hanoi algorithm, 438with this sequence of dump levels: 439.Bd -literal -offset indent 4403 2 5 4 7 6 9 8 9 9 ... 441.Ed 442.Pp 443For the daily dumps, it should be possible to use a fixed number of tapes 444for each day, used on a weekly basis. 445Each week, a level 1 dump is taken, and 446the daily Hanoi sequence repeats beginning with 3. 447For weekly dumps, another fixed set of tapes per dumped file system is 448used, also on a cyclical basis. 449.El 450.Pp 451After several months or so, the daily and weekly tapes should get 452rotated out of the dump cycle and fresh tapes brought in. 453.Pp 454If 455.Nm 456receives a 457.Dv SIGINFO 458signal 459(see the 460.Qq status 461argument of 462.Xr stty 1 ) 463whilst a backup is in progress, statistics on the amount completed, 464current transfer rate, and estimated finished time, will be written 465to the standard error output. 466.Sh ENVIRONMENT 467If the following environment variables exist, they are used by 468.Nm . 469.Bl -tag -width Fl 470.It Ev TAPE 471If no -f option was specified, 472.Nm 473will use the device specified via 474.Ev TAPE 475as the dump device. 476.Ev TAPE 477may be of the form 478.Qq tapename , 479.Qq host:tapename , 480or 481.Qq user@host:tapename . 482.It Ev RCMD_CMD 483.Nm 484will use 485.Ev RCMD_CMD 486rather than 487.Xr rsh 1 488to invoke 489.Xr rmt 8 490on the remote machine. 491.It Ev TIMEFORMAT 492can be used to control the format of the timestamps produced by the 493.Fl t 494option. 495.Ev TIMEFORMAT 496is a string containing embedded formatting commands for 497.Xr strftime 3 . 498The total formatted string is limited to about 80 characters, if this 499limit is exceeded then 500.Qo 501ERROR: TIMEFORMAT too long, reverting to default 502.Qc 503will be printed and the time format will revert to the default one. 504If 505.Ev TIMEFORMAT 506is not set then the format string defaults to 507.Qo 508%T %Z 509.Qc 510.El 511.Sh FILES 512.Bl -tag -width /etc/dumpdates -compact 513.It Pa /dev/nrst0 514default tape unit to use. 515Taken from 516.Dv _PATH_DEFTAPE 517in 518.Pa /usr/include/paths.h . 519.It Pa /dev/rst* 520raw SCSI tape interface 521.It Pa /etc/dumpdates 522dump date records 523.It Pa /etc/fstab 524dump table: file systems and frequency 525.It Pa /etc/group 526to find group 527.Em operator 528.El 529.Sh DIAGNOSTICS 530Many, and verbose. 531.Pp 532.Nm 533exits with zero status on success. 534Startup errors are indicated with an exit code of 1; 535abnormal termination is indicated with an exit code of 3. 536.Sh SEE ALSO 537.Xr chflags 1 , 538.Xr rcmd 1 , 539.Xr stty 1 , 540.Xr wall 1 , 541.Xr fts 3 , 542.Xr rcmd 3 , 543.Xr fss 4 , 544.Xr st 4 , 545.Xr fstab 5 , 546.Xr environ 7 , 547.Xr restore 8 , 548.Xr rmt 8 549.Sh HISTORY 550A 551.Nm 552command appeared in 553.At v6 . 554.Sh BUGS 555Fewer than 32 read errors on the file system are ignored. 556.Pp 557Each reel requires a new process, so parent processes for 558reels already written just hang around until the entire tape 559is written. 560.Pp 561.Nm 562with the 563.Fl W 564or 565.Fl w 566options does not report file systems that have never been recorded 567in 568.Pa /etc/dumpdates , 569even if listed in 570.Pa /etc/fstab . 571.Pp 572When dumping a list of files or subdirectories, access privileges are 573required to scan the directory (as this is done via the 574.Xr fts 3 575routines rather than directly accessing the file system). 576.Pp 577It would be nice if 578.Nm 579knew about the dump sequence, 580kept track of the tapes scribbled on, 581told the operator which tape to mount when, 582and provided more assistance 583for the operator running 584.Xr restore 8 . 585.Pp 586Snapshot support is 587.Em experimental . 588Be sure you have a backup before you use it. 589