X-Git-Url: https://git.wh0rd.org/?p=dump.git;a=blobdiff_plain;f=dump%2Fdump.8.in;h=ef41382582b7473296f7f8265b177f2e630dbc62;hp=9085f1a11a1be85a7742ca01dbceb862611f728e;hb=aa1b1e7f1a9c7201ba1ac4eb35921e2c9df26729;hpb=0d7af9c5f2cc7d4a97e934692ea8665e09fd5500 diff --git a/dump/dump.8.in b/dump/dump.8.in index 9085f1a..ef41382 100644 --- a/dump/dump.8.in +++ b/dump/dump.8.in @@ -30,7 +30,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dump.8.in,v 1.12 2000/03/02 11:34:51 stelian Exp $ +.\" $Id: dump.8.in,v 1.42 2002/06/10 14:05:00 stelian Exp $ .\" .Dd __DATE__ .Dt DUMP 8 @@ -40,31 +40,24 @@ .Nd ext2 filesystem backup .Sh SYNOPSIS .Nm dump -.Op Fl 0123456789ackMnSu +.Op Fl 0123456789ackMnqSuv +.Op Fl A Ar file .Op Fl B Ar records .Op Fl b Ar blocksize .Op Fl d Ar density -.Op Fl e Ar inode number +.Op Fl e Ar inode numbers +.Op Fl E Ar file .Op Fl f Ar file .Op Fl F Ar script .Op Fl h Ar level +.Op Fl I Ar nr errors +.Op Fl j Ar compression level .Op Fl L Ar label +.Op Fl Q Ar file .Op Fl s Ar feet .Op Fl T Ar date -.Ar filesystem -.Nm dump -.Op Fl 0123456789ackMnSu -.Op Fl B Ar records -.Op Fl b Ar blocksize -.Op Fl d Ar density -.Op Fl e Ar inode number -.Op Fl f Ar file -.Op Fl F Ar script -.Op Fl h Ar level -.Op Fl L Ar label -.Op Fl s Ar feet -.Op Fl T Ar date -.Ar directory +.Op Fl z Ar compression level +.Ar files-to-dump .Nm dump .Op Fl W Li \&| Fl w .Pp @@ -86,19 +79,27 @@ option below for doing remote backups). A dump that is larger than the output medium is broken into multiple volumes. On most media the size is determined by writing until an -end-of-media indication is returned. This can be enforced -by using the -.Fl a -option. +end-of-media indication is returned. .Pp On media that cannot reliably return an end-of-media indication -(such as some cartridge tape drives), -each volume is of a fixed size; -the actual size is determined by the tape size, density and/or -block count options below. +(such as some cartridge tape drives), each volume is of a fixed size; +the actual size is determined by specifying cartridge media, or via the +tape size, density and/or block count options below. By default, the same output file name is used for each volume after prompting the operator to change media. .Pp +.Ar files-to-dump +is either a mountpoint of a filesystem +or a list of files and directories to be backed up as a subset of a +filesystem. +In the former case, either the path to a mounted filesystem +or the device of an unmounted filesystem can be used. +In the latter case, certain restrictions are placed on the backup: +.Fl u +is not allowed, the only dump level that is supported is +.Fl 0 +and all the files and directories must reside on the same filesystem. +.Pp The following options are supported by .Nm Ns : .Bl -tag -width Ds @@ -117,50 +118,64 @@ to copy all files new or modified since the last dump of a lower level. The default level is 9. -.It Fl B Ar records -The number of 1 KB blocks per volume. -This option overrides the calculation of tape size -based on length and density. .It Fl a .Dq auto-size . -Bypass all tape length considerations, and enforce writing -until an end-of-media indication is returned. This fits best -for most modern tape drives. Use of this option is particularly -recommended when appending to an existing tape, or using a tape -drive with hardware compression (where you can never be sure about -the compression ratio). +Bypass all tape length calculations, and write +until an end-of-media indication is returned. This works best +for most modern tape drives, and is the default. +Use of this option is particularly recommended when appending to an +existing tape, or using a tape drive with hardware compression +(where you can never be sure about the compression ratio). +.It Fl A Ar archive_file +Archive a dump table-of-contents in the +specified +.Ar archive_file +to be used by +.Xr restore 8 +to determine whether a file is in the dump file that is being restored. .It Fl b Ar blocksize The number of kilobytes per dump record. Since the IO system slices all requests into chunks of MAXBSIZE -(typically 64KB), it is not possible to use a larger blocksize +(typically 64kB), it is not possible to use a larger blocksize without having problems later with .Xr restore 8 . Therefore .Nm dump will constrain writes to MAXBSIZE. +The default blocksize is 10. +.It Fl B Ar records +The number of 1 kB blocks per volume. Not normally required, as +.Nm +can detect end-of-media. When the specified size is reached, +.Nm +waits for you to change the volume. This option overrides +the calculation of tape size based on length and density. +If compression is on this limits the size of the compressed +output per volume. .It Fl c Change the defaults for use with a cartridge tape drive, with a density -of 8000 bpi, and a length of 1700 feet. -.It Fl e Ar inode -Exclude -.Ar inode -from the dump (you can use -.Ar stat -to find the inode number for a file or directory). -.It Fl h Ar level -Honor the user -.Dq nodump -flag -.Dp Dv UF_NODUMP -only for dumps at or above the given -.Ar level . -The default honor level is 1, -so that incremental backups omit such files -but full backups retain them. +of 8000 bpi, and a length of 1700 feet. Specifying a cartridge drive +overrides the end-of-media detection. .It Fl d Ar density Set tape density to .Ar density . -The default is 1600BPI. +The default is 1600BPI. Specifying a tape density overrides the +end-of-media detection. +.It Fl e Ar inodes +Exclude +.Ar inodes +from the dump. The +.Ar inodes +parameter is a comma separated list of inode numbers (you can use +.Ar stat +to find the inode number for a file or directory). +.It Fl E Ar file +Read list of inodes to be excluded from the dump from the text file +.Ar file . +The file +.Ar file +should be an ordinary file containing inode numbers separated by +newlines. .It Fl f Ar file Write the backup to .Ar file ; @@ -195,11 +210,49 @@ program is this can be overridden by the environment variable .Ev RMT . .It Fl F Ar script -Run script at the end of each tape. The script must return 0 -if the dump should continue without asking the user to change -the tape, 1 if the dump should continue but ask the user -to change the tape. Any other exit code will cause dump to -abort. +Run script at the end of each tape. The device name and the +current volume number are passed on the command line. +The script must return 0 if +.Nm +should continue without asking the user to change the tape, 1 if +.Nm +should continue but ask the user to change the tape. +Any other exit code will cause +.Nm +to abort. +For security reasons, +.Nm +reverts back to the real user ID and the real group ID before +running the script. +.It Fl h Ar level +Honor the user +.Dq nodump +flag +.Dp Dv UF_NODUMP +only for dumps at or above the given +.Ar level . +The default honor level is 1, +so that incremental backups omit such files +but full backups retain them. +.It Fl I Ar nr errors +By default, +.Nm +will ignore the first 32 read errors on the file +system before asking for operator intervention. You can change this +using this flag to any value. This is useful when running +.Nm +on an active filesystem where read errors simply indicate an +inconsistency between the mapping and dumping passes. +.It Fl j Ar compression level +Compress every block to be written on the tape using bzlib library. This +option will work only when dumping to a file or pipe or, when dumping +to a tape drive, if the tape drive is capable of writing variable +length blocks. You will need at least the 0.4b24 version of restore in +order to extract compressed tapes. Tapes written using compression will +not be compatible with the BSD tape format. The (optional) parameter +specifies the compression level bzlib will use. The default compression +level is 2. If the optional parameter is specified, there should be no +white space between the option letter and the parameter. .It Fl k Use Kerberos authentication to talk to remote tape servers. (Only available if this option was enabled when @@ -217,6 +270,22 @@ Note that this label is limited to be at most LBLSIZE (currently 16) characters, which must include the terminating .Ql \e0 . +.It Fl m +If this flag is specified, +.Nm +will optimise the output for inodes having been changed but not +modified since the last dump ('changed' and 'modified' have the +meaning defined in stat(2)). For those inodes, +.Nm +will save only the metadata, instead of saving the entire inode +contents. Inodes which are either directories or have been modified +since the last dump are saved in a regular way. +Uses of this flag must be consistent, meaning that either every dump +in an incremental dump set have the flag, or no one has it. +.Pp +Tapes written using such 'metadata only' inodes will not be compatible +with the BSD tape format or older versions of +.Nm restore. .It Fl M Enable the multi-volume feature. The name specified with .Fl f @@ -233,14 +302,42 @@ notify all operators in the group .Dq operator by means similar to a .Xr wall 1 . +.It Fl q +Make +.Nm +abort immediately whenever operator attention is required, +without prompting in case of write errors, tape changes etc. +.It Fl Q Ar file +Enable the Quick File Access support. Tape positions for each +inode are stored into the file +.Ar file +which is used by restore (if called with parameter Q and the filename) +to directly position the tape at the file restore is currently working +on. This saves hours when restoring single files from large backups, +saves the tapes and the drive's head. +.Pp +It is recommended to set up the st driver to return logical tape +positions rather than physical before calling dump/restore with +parameter Q. Since not all tape devices support physical tape +positions those tape devices return an error during dump/restore when +the st driver is set to the default physical setting. +Please see the st man page, option MTSETDRVBUFFER, or the mt man +page, on how to set the driver to return logical tape positions. +.Pp +Before calling restore with parameter Q, always make sure the st +driver is set to return the same type of tape position used during the +call to dump. Otherwise restore may be confused. +.Pp +This option can be used when dumping to local tapes (see above) +or to local files. .It Fl s Ar feet -Attempt to calculate the amount of tape needed -at a particular density. +Attempt to calculate the amount of tape needed at a particular density. If this amount is exceeded, .Nm prompts for a new tape. It is recommended to be a bit conservative on this option. -The default tape length is 2300 feet. +The default tape length is 2300 feet. Specifying the tape size +overrides end-of-media detection. .ne 1i .It Fl S Size estimate. Determine the amount of space @@ -282,6 +379,12 @@ The file .Pa __DUMPDATES__ may be edited to change any of the fields, if necessary. +.It Fl v +The +.Fl v +(verbose) makes +.Nm dump +to print extra information which could be helpful in debug sessions. .It Fl W .Nm Dump tells the operator what file systems need to be dumped. @@ -293,10 +396,12 @@ The .Fl W option causes .Nm -to print out, for each file system in +to print out, for all file systems in .Pa __DUMPDATES__ , +and regognized file systems in +.Pa /etc/fstab . the most recent dump date and level, -and highlights those file systems that should be dumped. +and highlights those that should be dumped. If the .Fl W option is set, all other options are ignored, and @@ -305,7 +410,19 @@ exits immediately. .It Fl w Is like .Fl W , -but prints only those filesystems which need to be dumped. +but prints only recognized filesystems in +.Pa /etc/fstab +which need to be dumped. +.It Fl z Ar compression level +Compress every block to be written on the tape using zlib library. This +option will work only when dumping to a file or pipe or, when dumping +to a tape drive, if the tape drive is capable of writing variable +length blocks. You will need at least the 0.4b22 version of restore in +order to extract compressed tapes. Tapes written using compression will +not be compatible with the BSD tape format. The (optional) parameter +specifies the compression level zlib will use. The default compression +level is 2. If the optional parameter is specified, there should be no +white space between the option letter and the parameter. .El .Pp .Nm Dump @@ -314,7 +431,7 @@ end of tape, end of dump, tape write error, tape open error or -disk read error (if there is more than a threshold of 32). +disk read error (if there is more than a threshold of nr errors). In addition to alerting all operators implied by the .Fl n key, @@ -418,6 +535,7 @@ remote shell command to use when doing remote backups (rsh, ssh etc.). If this variable is not set, .Xr rcmd 3 will be used, but only root will be able to do remote backups. +.El .Sh FILES .Bl -tag -width __DUMPDATES__ -compact .It Pa /dev/st0 @@ -445,24 +563,31 @@ abnormal termination is indicated with an exit code of 3. It might be considered a bug that this version of dump can only handle ext2 filesystems. Specifically, it does not work with FAT filesystems. .Pp -Fewer than 32 read errors on the filesystem are ignored. If noticing +Fewer than 32 read errors (change this with -I) +on the filesystem are ignored. If noticing read errors is important, the output from dump can be parsed to look for lines that contain the text 'read error'. .Pp +When a read error occurs, +.Nm +prints out the corresponding physical disk block and sector number and the +ext2 logical block number. +It doesn't print out the corresponing file name or even the inode number. +The user has to use +.Xr debugfs 8 , +commands +.Pa ncheck +and +.Pa icheck +to translate the +.Pa ext2blk +number printed out by dump into an inode number, then into a file name. +.Pp Each reel requires a new process, so parent processes for reels already written just hang around until the entire tape is written. .Pp -.Nm Dump -with the -.Fl W -or -.Fl w -option does not report filesystems that have never been recorded -in -.Pa __DUMPDATES__ , -even if listed in -.Pa /etc/fstab . +The estimated number of tapes is not correct if compression is on. .Pp It would be nice if .Nm @@ -482,17 +607,17 @@ a remote shell program instead. .Sh AUTHOR The .Nm dump/restore -backup suit was ported to Linux's Second Extended File System +backup suite was ported to Linux's Second Extended File System by Remy Card . He maintained the initial versions of dump (up and including 0.4b4, released in january 1997). .Pp Starting with 0.4b5, the new maintainer is Stelian Pop .br -. +. .Sh AVAILABILITY The .Nm dump/restore -backup suit is available from +backup suite is available from .br http://dump.sourceforge.net .Sh HISTORY