1.\" $NetBSD: dump_lfs.8,v 1.12 2004/07/13 17:08:50 wiz 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 July 13, 2004 34.Dt DUMP_LFS 8 35.Os 36.Sh NAME 37.Nm dump_lfs , 38.Nm rdump_lfs 39.Nd filesystem backup 40.Sh SYNOPSIS 41.Nm 42.Op Fl 0123456789cnSu 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 k Ar read blocksize 49.Op Fl l Ar timeout 50.Op Fl L Ar label 51.Op Fl r Ar cachesize 52.Op Fl s Ar feet 53.Op Fl T Ar date 54.Ar files-to-dump 55.Nm 56.Op Fl W Li \&| Fl w 57.Pp 58.in -\n(iSu 59(The 60.Bx 4.3 61option syntax is implemented for backward compatibility, but 62is not documented here). 63.Sh DESCRIPTION 64.Nm 65examines files on a filesystem and determines which files need to 66be backed up. 67These files are copied to the given disk, tape or other storage 68medium for safe keeping (see the 69.Fl f 70option below for doing remote backups). 71A dump that is larger than the output medium is broken into 72multiple volumes. 73On most media the size is determined by writing until an 74end-of-media indication is returned. 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 79block count options below. 80By default, the same output file name is used for each volume 81after prompting the operator to change media. 82.Pp 83.Ar files-to-dump 84is either a mountpoint of a filesystem, 85or a list of files and directories on a single filesystem to be backed 86up as a subset of the filesystem. 87In the former case, either the path to a mounted filesystem, 88or the device of an unmounted filesystem can be used. 89In the latter case, certain restrictions are placed on the backup: 90.Fl u 91is ignored, the only dump level that is supported is 92.Fl 0 , 93and all of the files must reside on the same filesystem. 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 a lower level. 110The default level is 9. 111.It Fl B Ar records 112The number of kilobytes per volume, rounded 113down to a multiple of the blocksize. 114This option overrides the calculation of tape size 115based on length and density. 116.It Fl b Ar blocksize 117The number of kilobytes per dump record. 118.It Fl c 119Modify the calculation of the default density and tape size to be more 120appropriate for cartridge tapes. 121.It Fl d Ar density 122Set tape density to 123.Ar density . 124The default is 1600 Bits Per Inch (BPI). 125.It Fl f Ar file 126Write the backup to 127.Ar file ; 128.Ar file 129may be a special device file 130like 131.Pa /dev/rst0 132(a tape drive), 133.Pa /dev/rsd1c 134(a disk drive), 135an ordinary file, 136or 137.Ql Fl 138(the standard output). 139Multiple file names may be given as a single argument separated by commas. 140Each file will be used for one dump volume in the order listed; 141if the dump requires more volumes than the number of names given, 142the last file name will used for all remaining volumes after prompting 143for media changes. 144If the name of the file is of the form 145.Qq host:file , 146or 147.Qq user@host:file , 148.Nm 149writes to the named file on the remote host using 150.Xr rmt 8 . 151Note that methods more secure than 152.Xr rsh 1 153.Pq such as Xr ssh 1 154can be used to invoke 155.Xr rmt 8 156on the remote host, via the environment variable 157.Ev RCMD_CMD . 158See 159.Xr rcmd 3 160for more details. 161.It Fl h Ar level 162Honor the user 163.Qq nodump 164flag 165.Pq Dv UF_NODUMP 166only for dumps at or above the given 167.Ar level . 168The default honor level is 1, 169so that incremental backups omit such files 170but full backups retain them. 171.It Fl k Ar read blocksize 172The size in kilobyte of the read buffers, rounded up to a multiple of the 173filesystem block size. 174Default is 32k. 175.It Fl L Ar label 176The user-supplied text string 177.Ar label 178is placed into the dump header, where tools like 179.Xr restore 8 180and 181.Xr file 1 182can access it. 183Note that this label is limited 184to be at most LBLSIZE (currently 16) characters, which must include 185the terminating 186.Ql \e0 . 187.It Fl l Ar timeout 188If a tape change is required, eject the tape and wait for the drive to 189be ready again. 190This is to be used with tape changers which automatically load 191the next tape when the tape is ejected. 192If after the timeout (in seconds) the drive is not ready 193.Nm 194falls back to the default behavior, 195and prompts the operator for the next tape. 196.It Fl n 197Whenever 198.Nm 199requires operator attention, 200notify all operators in the group 201.Qq operator 202by means similar to a 203.Xr wall 1 . 204.It Fl r Ar cachesize 205Use that many buffers for read cache operations. 206A value of zero disables the read cache altogether, higher values 207improve read performance by reading larger data blocks from the 208disk and maintaining them in an LRU cache. 209See the 210.Fl k 211option for the size of the buffers. 212Maximum is 512, the size of the cache is 213limited to 15% of the avail RAM by default. 214.It Fl s Ar feet 215Attempt to calculate the amount of tape needed 216at a particular density. 217If this amount is exceeded, 218.Nm 219prompts for a new tape. 220It is recommended to be a bit conservative on this option. 221The default tape length is 2300 feet. 222.It Fl S 223Display an estimate of the backup size and the number of tapes 224required, and exit without actually performing the dump. 225.It Fl T Ar date 226Use the specified date as the starting time for the dump 227instead of the time determined from looking in 228.Pa /etc/dumpdates . 229The format of date is the same as that of 230.Xr ctime 3 . 231This option is useful for automated dump scripts that wish to 232dump over a specific period of time. 233The 234.Fl T 235option is mutually exclusive from the 236.Fl u 237option. 238.It Fl u 239Update the file 240.Pa /etc/dumpdates 241after a successful dump. 242The format of 243.Pa /etc/dumpdates 244is readable by people, consisting of one 245free format record per line: 246filesystem name, 247increment level 248and 249.Xr ctime 3 250format dump date. 251There may be only one entry per filesystem at each level. 252The file 253.Pa /etc/dumpdates 254may be edited to change any of the fields, 255if necessary. 256If a list of files or subdirectories is being dumped 257(as opposed to and entire filesystem), then 258.Fl u 259is ignored. 260.It Fl W 261.Nm 262tells the operator what file systems need to be dumped. 263This information is gleaned from the files 264.Pa /etc/dumpdates 265and 266.Pa /etc/fstab . 267The 268.Fl W 269option causes 270.Nm 271to print out, for each file system in 272.Pa /etc/dumpdates 273the most recent dump date and level, 274and highlights those file systems that should be dumped. 275If the 276.Fl W 277option is set, all other options are ignored, and 278.Nm 279exits immediately. 280.It Fl w 281Is like W, but prints only those filesystems which need to be dumped. 282.El 283.Pp 284If 285.Nm 286honors the 287.Qq nodump 288flag 289.Pq Dv UF_NODUMP , 290files with the 291.Qq nodump 292flag will not be backed up. 293If a directory has the 294.Qq nodump 295flag, this directory and any file or directory under it will not be backed up. 296.Pp 297.Nm 298requires operator intervention on these conditions: 299end of tape, 300end of dump, 301tape write error, 302tape open error or 303disk read error (if there are more than a threshold of 32). 304In addition to alerting all operators implied by the 305.Fl n 306option, 307.Nm 308interacts with the operator on 309.Nm Ns 's 310control terminal at times when 311.Nm 312can no longer proceed, 313or if something is grossly wrong. 314All questions 315.Nm 316poses 317.Em must 318be answered by typing 319.Qq yes 320or 321.Qq no , 322appropriately. 323.Pp 324Since making a dump involves a lot of time and effort for full dumps, 325.Nm 326checkpoints itself at the start of each tape volume. 327If writing that volume fails for some reason, 328.Nm 329will, 330with operator permission, 331restart itself from the checkpoint 332after the old tape has been rewound and removed, 333and a new tape has been mounted. 334.Pp 335.Nm 336tells the operator what is going on at periodic intervals, 337including usually low estimates of the number of blocks to write, 338the number of tapes it will take, the time to completion, and 339the time to the tape change. 340The output is verbose, 341so that others know that the terminal 342controlling 343.Nm 344is busy, 345and will be for some time. 346.Pp 347In the event of a catastrophic disk event, the time required 348to restore all the necessary backup tapes or files to disk 349can be kept to a minimum by staggering the incremental dumps. 350An efficient method of staggering incremental dumps 351to minimize the number of tapes follows: 352.Bl -bullet -offset indent 353.It 354Always start with a level 0 backup, for example: 355.Bd -literal -offset indent 356/sbin/dump -0u -f /dev/nrst1 /usr/src 357.Ed 358.Pp 359This should be done at set intervals, say once a month or once every two months, 360and on a set of fresh tapes that is saved forever. 361.It 362After a level 0, dumps of active file 363systems are taken on a daily basis, 364using a modified Tower of Hanoi algorithm, 365with this sequence of dump levels: 366.Bd -literal -offset indent 3673 2 5 4 7 6 9 8 9 9 ... 368.Ed 369.Pp 370For the daily dumps, it should be possible to use a fixed number of tapes 371for each day, used on a weekly basis. 372Each week, a level 1 dump is taken, and 373the daily Hanoi sequence repeats beginning with 3. 374For weekly dumps, another fixed set of tapes per dumped file system is 375used, also on a cyclical basis. 376.El 377.Pp 378After several months or so, the daily and weekly tapes should get 379rotated out of the dump cycle and fresh tapes brought in. 380.Pp 381If 382.Nm 383receives a 384.Dv SIGINFO 385signal 386(see the 387.Qq status 388argument of 389.Xr stty 1 ) 390whilst a backup is in progress, statistics on the amount completed, 391current transfer rate, and estimated finished time, will be written 392to the standard error output. 393.Sh ENVIRONMENT 394If the following environment variables exist, they are used by 395.Nm . 396.Bl -tag -width Fl 397.It Ev TAPE 398If no -f option was specified, 399.Nm 400will use the device specified via 401.Ev TAPE 402as the dump device. 403.Ev TAPE 404may be of the form 405.Qq tapename , 406.Qq host:tapename , 407or 408.Qq user@host:tapename . 409.It Ev RCMD_CMD 410.Nm 411will use 412.Ev RCMD_CMD 413rather than 414.Xr rsh 1 415to invoke 416.Xr rmt 8 417on the remote machine. 418.El 419.Sh FILES 420.Bl -tag -width /etc/dumpdates -compact 421.It Pa /dev/nrst0 422default tape unit to use. 423Taken from 424.Dv _PATH_DEFTAPE 425in 426.Pa /usr/include/paths.h . 427.It Pa /dev/rst* 428raw SCSI tape interface 429.It Pa /etc/dumpdates 430dump date records 431.It Pa /etc/fstab 432dump table: file systems and frequency 433.It Pa /etc/group 434to find group 435.Em operator 436.El 437.Sh DIAGNOSTICS 438Many, and verbose. 439.Pp 440.Nm 441exits with zero status on success. 442Startup errors are indicated with an exit code of 1; 443abnormal termination is indicated with an exit code of 3. 444.Sh SEE ALSO 445.Xr chflags 1 , 446.Xr rcmd 1 , 447.Xr stty 1 , 448.Xr fts 3 , 449.Xr rcmd 3 , 450.Xr st 4 , 451.Xr fstab 5 , 452.Xr environ 7 , 453.Xr restore 8 , 454.Xr rmt 8 455.Sh HISTORY 456A 457.Nm 458command appeared in 459.Nx 1.5 . 460.Sh BUGS 461Fewer than 32 read errors on the filesystem are ignored. 462.Pp 463Each reel requires a new process, so parent processes for 464reels already written just hang around until the entire tape 465is written. 466.Pp 467.Nm 468with the 469.Fl W 470or 471.Fl w 472options does not report filesystems that have never been recorded 473in 474.Pa /etc/dumpdates , 475even if listed in 476.Pa /etc/fstab . 477.Pp 478When dumping a list of files or subdirectories, access privileges are 479required to scan the directory (as this is done via the 480.Xr fts 3 481routines rather than directly accessing the filesystem). 482.Pp 483It would be nice if 484.Nm 485knew about the dump sequence, 486kept track of the tapes scribbled on, 487told the operator which tape to mount when, 488and provided more assistance 489for the operator running 490.Xr restore 8 . 491