RPM(8) Red Hat Linux RPM(8)

NAME rpm - RPM Package Manager

SYNOPSIS QUERYING AND VERIFYING PACKAGES: rpm {-q|--query} [select-options] [query-options]

rpm {-V|--verify} [select-options] [verify-options]

rpm --import PUBKEY ...

rpm {-K|--checksig} [--nosignature] [--nodigest] PACKAGE_FILE ...

INSTALLING, UPGRADING, AND REMOVING PACKAGES: rpm {-i|--install} [install-options] PACKAGE_FILE ...

rpm {-U|--upgrade} [install-options] PACKAGE_FILE ...

rpm {-F|--freshen} [install-options] PACKAGE_FILE ...

rpm {-e|--erase} [--allmatches] [--nodeps] [--noscripts] [--notriggers] [--repackage] [--test] PACKAGE_NAME ...

MISCELLANEOUS: rpm {--initdb|--rebuilddb}

rpm {--addsign|--resign} PACKAGE_FILE ...

rpm {--querytags|--showrc}

rpm {--setperms|--setugids} PACKAGE_NAME ...

select-options [PACKAGE_NAME] [-a,--all] [-f,--file FILE] [-g,--group GROUP] {-p,--package PACKAGE_FILE] [--fileid MD5] [--hdrid SHA1] [--pkgid MD5] [--tid TID] [--querybynumber HDRNUM] [--triggeredby PACKAGE_NAME] [--whatprovides CAPABILITY] [--whatrequires CAPABILITY]

query-options [--changelog] [-c,--configfiles] [-d,--docfiles] [--dump] [--filesbypkg] [-i,--info] [--last] [-l,--list] [--provides] [--qf,--queryformat QUERYFMT] [-R,--requires] [--scripts] [-s,--state] [--triggers,--triggerscripts]

verify-options [--nodeps] [--nofiles] [--noscripts] [--nodigest] [--nosignature] [--nolinkto] [--nomd5] [--nosize] [--nouser] [--nogroup] [--nomtime] [--nomode] [--nordev]

install-options [--aid] [--allfiles] [--badreloc] [--excludepath OLDPATH] [--excludedocs] [--force] [-h,--hash] [--ignoresize] [--ignorearch] [--ignoreos] [--includedocs] [--justdb] [--nodeps] [--nodigest] [--nosignature] [--nosuggest] [--noorder] [--noscripts] [--notriggers] [--oldpackage] [--percent] [--prefix NEWPATH] [--relocate OLDPATH=NEWPATH] [--repackage] [--replacefiles] [--replacepkgs] [--test]

DESCRIPTION rpm is a powerful Package Manager, which can be used to build, install, query, verify, update, and erase individual software packages. A pack- age consists of an archive of files and meta-data used to install and erase the archive files. The meta-data includes helper scripts, file attributes, and descriptive information about the package. Packages come in two varieties: binary packages, used to encapsulate software to be installed, and source packages, containing the source code and recipe necessary to produce binary packages.

One of the following basic modes must be selected: Query, Verify, Sig- nature Check, Install/Upgrade/Freshen, Uninstall, Initialize Database, Rebuild Database, Resign, Add Signature, Set Owners/Groups, Show Query- tags, and Show Configuration.

GENERAL OPTIONS These options can be used in all the different modes.

-?, --help Print a longer usage message then normal.

--version Print a single line containing the version number of rpm being used.

--quiet Print as little as possible - normally only error messages will be displayed.

-v Print verbose information - normally routine progress messages will be displayed.

-vv Print lots of ugly debugging information.

--rcfile FILELIST Each of the files in the colon separated FILELIST is read sequentially by rpm for configuration information. Only the first file in the list must exist, and tildes will be expanded to the value of $HOME. The default FILELIST is /usr/lib/rpm/rpmrc:/usr/lib/rpm/red- hat/rpmrc:/etc/rpmrc:~/.rpmrc.

--pipe CMD Pipes the output of rpm to the command CMD.

--dbpath DIRECTORY Use the database in DIRECTORY rather than the default path /var/lib/rpm

--root DIRECTORY Use the file system tree rooted at DIRECTORY for all operations. Note that this means the database within DIRECTORY will be used for dependency checks and any scriptlet(s) (e.g. %post if installing, or %prep if building, a package) will be run after a chroot(2) to DIRECTORY.

-D, --defineMACRO EXPR Defines MACRO with value EXPR.

-E, --evalEXPR Prints macro expansion of EXPR.

INSTALL AND UPGRADE OPTIONS The general form of an rpm install command is

rpm {-i|--install} [install-options] PACKAGE_FILE ...

This installs a new package.

The general form of an rpm upgrade command is

rpm {-U|--upgrade} [install-options] PACKAGE_FILE ...

This upgrades or installs the package currently installed to a newer version. This is the same as install, except all other version(s) of the package are removed after the new package is installed.

rpm {-F|--freshen} [install-options] PACKAGE_FILE ...

This will upgrade packages, but only if an earlier version currently exists. The PACKAGE_FILE may be specified as an ftp or http URL, in which case the package will be downloaded before being installed. See FTP/HTTP OPTIONS for information on rpms internal ftp and http client support.

--aid Add suggested packages to the transaction set when needed.

--allfiles Installs or upgrades all the missingok files in the package, regardless if they exist.

--badreloc Used with --relocate, permit relocations on all file paths, not just those OLDPATHs included in the binary package relocation hint(s).

--excludepath OLDPATH Dont install files whose name begins with OLDPATH.

--excludedocs Don t install any files which are marked as documentation (which includes man pages and texinfo documents).

--force Same as using --replacepkgs, --replacefiles, and --oldpackage.

-h, --hash Print 50 hash marks as the package archive is unpacked. Use with -v|--verbose for a nicer display.

--ignoresize Dont check mount file systems for sufficient disk space before installing this package.

--ignorearch Allow installation or upgrading even if the architectures of the binary package and host dont match.

--ignoreos Allow installation or upgrading even if the operating systems of the binary package and host dont match.

--includedocs Install documentation files. This is the default behavior.

--justdb Update only the database, not the filesystem.

--nodigest Dont verify package or header digests when reading.

--nosignature Don t verify package or header signatures when reading.

--nodeps Dont do a dependency check before installing or upgrading a package.

--nosuggest Don t suggest package(s) that provide a missing dependency.

--noorder Dont reorder the packages for an install. The list of packages would normally be reordered to satisfy dependencies.

--noscripts

--nopre

--nopost

--nopreun

--nopostun Dont execute the scriptlet of the same name. The --noscripts option is equivalent to

--nopre --nopost --nopreun --nopostun

and turns off the execution of the corresponding %pre, %post, %preun, and %postun scriptlet(s).

--notriggers

--notriggerin

--notriggerun

--notriggerpostun Dont execute any trigger scriptlet of the named type. The --notriggers option is equivalent to

--notriggerin --notriggerun --notriggerpostun

and turns off execution of the corresponding %triggerin, %trig- gerun, and %triggerpostun scriptlet(s).

--oldpackage Allow an upgrade to replace a newer package with an older one.

--percent Print percentages as files are unpacked from the package archive. This is intended to make rpm easy to run from other tools.

--prefix NEWPATH For relocatable binary packages, translate all file paths that start with the installation prefix in the package relocation hint(s) to NEWPATH.

--relocate OLDPATH=NEWPATH For relocatable binary packages, translate all file paths that start with OLDPATH in the package relocation hint(s) to NEWPATH. This option can be used repeatedly if several OLDPATHs in the package are to be relocated.

--repackage Re-package the files before erasing. The previously installed package will be named according to the macro %_repack- age_name_fmt and will be created in the directory named by the macro %_repackage_dir (default value is /var/spool/repackage).

--replacefiles Install the packages even if they replace files from other, already installed, packages.

--replacepkgs Install the packages even if some of them are already installed on this system.

--test Do not install the package, simply check for and report poten- tial conflicts.

ERASE OPTIONS The general form of an rpm erase command is

rpm {-e|--erase} [--allmatches] [--nodeps] [--noscripts] [--notriggers] [--repackage] [--test] PACKAGE_NAME ...

The following options may also be used:

--allmatches Remove all versions of the package which match PACKAGE_NAME. Normally an error is issued if PACKAGE_NAME matches multiple packages.

--nodeps Dont check dependencies before uninstalling the packages.

--noscripts

--nopreun

--nopostun Don t execute the scriptlet of the same name. The --noscripts option during package erase is equivalent to

--nopreun --nopostun

and turns off the execution of the corresponding %preun, and %postun scriptlet(s).

--notriggers

--notriggerun

--notriggerpostun Don t execute any trigger scriptlet of the named type. The --notriggers option is equivalent to

--notriggerun --notriggerpostun

and turns off execution of the corresponding %triggerun, and %triggerpostun scriptlet(s).

--repackage Re-package the files before erasing. The previously installed package will be named according to the macro %_repack- age_name_fmt and will be created in the directory named by the macro %_repackage_dir (default value is /var/spool/repackage).

--test Dont really uninstall anything, just go through the motions. Useful in conjunction with the -vv option for debugging.

QUERY OPTIONS The general form of an rpm query command is

rpm {-q|--query} [select-options] [query-options]

You may specify the format that package information should be printed in. To do this, you use the

--qf|--queryformat QUERYFMT

option, followed by the QUERYFMT format string. Query formats are mod- ified versions of the standard printf(3) formatting. The format is made up of static strings (which may include standard C character escapes for newlines, tabs, and other special characters) and printf(3) type formatters. As rpm already knows the type to print, the type specifier must be omitted however, and replaced by the name of the header tag to be printed, enclosed by {} characters. Tag names are case insensitive, and the leading RPMTAG_ portion of the tag name may be omitted as well.

Alternate output formats may be requested by following the tag with :typetag. Currently, the following types are supported:

:armor Wrap a public key in ASCII armor.

:base64 Encode binary data using base64.

:date Use strftime(3) "%c" format.

:day Use strftime(3) "%a %b %d %Y" format.

:depflags Format dependency flags.

:fflags Format file flags.

:hex Format in hexadecimal.

:octal Format in octal.

:perms Format file permissions.

:shescape Escape single quotes for use in a script.

:triggertype Display trigger suffix.

For example, to print only the names of the packages queried, you could use %{NAME} as the format string. To print the packages name and dis- tribution information in two columns, you could use %-30{NAME}%{DISTRI- BUTION}. rpm will print a list of all of the tags it knows about when it is invoked with the --querytags argument.

There are two subsets of options for querying: package selection, and information selection.

PACKAGE SELECTION OPTIONS: PACKAGE_NAME Query installed package named PACKAGE_NAME.

-a, --all Query all installed packages.

-f, --file FILE Query package owning FILE.

--fileid MD5 Query package that contains a given file identifier, i.e. the MD5 digest of the file contents.

-g, --group GROUP Query packages with the group of GROUP.

--hdrid SHA1 Query package that contains a given header identifier, i.e. the SHA1 digest of the immutable header region.

-p, --package PACKAGE_FILE Query an (uninstalled) package PACKAGE_FILE. The PACKAGE_FILE may be specified as an ftp or http style URL, in which case the package header will be downloaded and queried. See FTP/HTTP OPTIONS for information on rpms internal ftp and http client support. The PACKAGE_FILE argument(s), if not a binary package, will be interpreted as an ASCII package manifest. Comments are permitted, starting with a #, and each line of a package mani- fest file may include white space separated glob expressions, including URLs with remote glob expressions, that will be expanded to paths that are substituted in place of the package manifest as additional PACKAGE_FILE arguments to the query.

--pkgid MD5 Query package that contains a given package identifier, i.e. the MD5 digest of the combined header and payload contents.

--querybynumber HDRNUM Query the HDRNUMth database entry directly; this is useful only for debugging.

--specfile SPECFILE Parse and query SPECFILE as if it were a package. Although not all the information (e.g. file lists) is available, this type of query permits rpm to be used to extract information from spec files without having to write a specfile parser.

--tid TID Query package(s) that have a given TID transaction identifier. A unix time stamp is currently used as a transaction identifier. All package(s) installed or erased within a single transaction have a common identifier.

--triggeredby PACKAGE_NAME Query packages that are triggered by package(s) PACKAGE_NAME.

--whatprovides CAPABILITY Query all packages that provide the CAPABILITY capability.

--whatrequires CAPABILITY Query all packages that requires CAPABILITY for proper function- ing.

PACKAGE QUERY OPTIONS: --changelog Display change information for the package.

-c, --configfiles List only configuration files (implies -l).

-d, --docfiles List only documentation files (implies -l).

--dump Dump file information as follows (implies -l):

path size mtime md5sum mode owner group isconfig isdoc rdev symlink

--filesbypkg List all the files in each selected package.

-i, --info Display package information, including name, version, and description. This uses the --queryformat if one was specified.

--last Orders the package listing by install time such that the latest packages are at the top.

-l, --list List files in package.

--provides List capabilities this package provides.

-R, --requires List packages on which this package depends.

--scripts List the package specific scriptlet(s) that are used as part of the installation and uninstallation processes.

-s, --state Display the states of files in the package (implies -l). The state of each file is one of normal, not installed, or replaced.

--triggers, --triggerscripts Display the trigger scripts, if any, which are contained in the package.

VERIFY OPTIONS The general form of an rpm verify command is

rpm {-V|--verify} [select-options] [verify-options]

Verifying a package compares information about the installed files in the package with information about the files taken from the package metadata stored in the rpm database. Among other things, verifying compares the size, MD5 sum, permissions, type, owner and group of each file. Any discrepancies are displayed. Files that were not installed from the package, for example, documentation files excluded on instal- lation using the "--excludedocs" option, will be silently ignored.

The package selection options are the same as for package querying (including package manifest files as arguments). Other options unique to verify mode are:

--nodeps Dont verify dependencies of packages.

--nodigest Dont verify package or header digests when reading.

--nofiles Dont verify any attributes of package files.

--noscripts Don t execute the %verifyscript scriptlet (if any).

--nosignature Dont verify package or header signatures when reading.

--nolinkto

--nomd5

--nosize

--nouser

--nogroup

--nomtime

--nomode

--nordev Dont verify the corresponding file attribute.

The format of the output is a string of 8 characters, a possible attribute marker:

c %config configuration file. d %doc documentation file. g %ghost file (i.e. the file contents are not included in the package payload). l %license license file. r %readme readme file.

from the package header, followed by the file name. Each of the 8 characters denotes the result of a comparison of attribute(s) of the file to the value of those attribute(s) recorded in the database. A single "." (period) means the test passed, while a single "?" (question mark) indicates the test could not be performed (e.g. file permissions prevent reading). Otherwise, the (mnemonically emBoldened) character denotes failure of the corresponding --verify test:

S file Size differs M Mode differs (includes permissions and file type) 5 MD5 sum differs D Device major/minor number mismatch L readLink(2) path mismatch U User ownership differs G Group ownership differs T mTime differs

DIGITAL SIGNATURE AND DIGEST VERIFICATION The general forms of rpm digital signature commands are

rpm --import PUBKEY ...

rpm {--checksig} [--nosignature] [--nodigest] PACKAGE_FILE ...

The --checksig option checks all the digests and signatures contained in PACKAGE_FILE to ensure the integrity and origin of the package. Note that signatures are now verified whenever a package is read, and --checksig is useful to verify all of the digests and signatures asso- ciated with a package.

Digital signatures cannot be verified without a public key. An ASCII armored public key can be added to the rpm database using --import. An imported public key is carried in a header, and key ring management is performed exactly like package management. For example, all currently imported public keys can be displayed by:

rpm -qa gpg-pubkey*

Details about a specific public key, when imported, can be displayed by querying. Heres information about the Red Hat GPG/DSA key:

rpm -qi gpg-pubkey-db42a60e

Finally, public keys can be erased after importing just like packages. Heres how to remove the Red Hat GPG/DSA key

rpm -e gpg-pubkey-db42a60e

SIGNING A PACKAGE rpm --addsign|--resign PACKAGE_FILE ...

Both of the --addsign and --resign options generate and insert new sig- natures for each package PACKAGE_FILE given, replacing any existing signatures. There are two options for historical reasons, there is no difference in behavior currently.

USING GPG TO SIGN PACKAGES In order to sign packages using GPG, rpm must be configured to run GPG and be able to find a key ring with the appropriate keys. By default, rpm uses the same conventions as GPG to find key rings, namely the $GNUPGHOME environment variable. If your key rings are not located where GPG expects them to be, you will need to configure the macro %_gpg_path to be the location of the GPG key rings to use.

For compatibility with older versions of GPG, PGP, and rpm, only V3 OpenPGP signature packets should be configured. Either DSA or RSA ver- ification algorithms can be used, but DSA is preferred.

If you want to be able to sign packages you create yourself, you also need to create your own public and secret key pair (see the GPG man- ual). You will also need to configure the rpm macros

%_signature The signature type. Right now only gpg and pgp are supported.

%_gpg_name The name of the "user" whose key you wish to use to sign your packages.

For example, to be able to use GPG to sign packages as the user "John Doe <jdoe@foo.com>" from the key rings located in /etc/rpm/.gpg using the executable /usr/bin/gpg you would include

%_signature gpg %_gpg_path /etc/rpm/.gpg %_gpg_name John Doe <jdoe@foo.com> %_gpgbin /usr/bin/gpg

in a macro configuration file. Use /etc/rpm/macros for per-system con- figuration and ~/.rpmmacros for per-user configuration.

REBUILD DATABASE OPTIONS The general form of an rpm rebuild database command is

rpm {--initdb|--rebuilddb} [-v] [--dbpath DIRECTORY] [--root DIRECTORY]

Use --initdb to create a new database if one doesnt already exist (existing database is not overwritten), use --rebuilddb to rebuild the database indices from the installed package headers.

SHOWRC The command

rpm --showrc

shows the values rpm will use for all of the options are currently set in rpmrc and macros configuration file(s).

FTP/HTTP OPTIONS rpm can act as an FTP and/or HTTP client so that packages can be queried or installed from the internet. Package files for install, upgrade, and query operations may be specified as an ftp or http style URL:

ftp://USER:PASSWORD@HOST:PORT/path/to/package.rpm

If the :PASSWORD portion is omitted, the password will be prompted for (once per user/hostname pair). If both the user and password are omit- ted, anonymous ftp is used. In all cases, passive (PASV) ftp transfers are performed.

rpm allows the following options to be used with ftp URLs:

--ftpproxy HOST The host HOST will be used as a proxy server for all ftp trans- fers, which allows users to ftp through firewall machines which use proxy systems. This option may also be specified by config- uring the macro %_ftpproxy.

--ftpport PORT The TCP PORT number to use for the ftp connection on the proxy ftp server instead of the default port. This option may also be specified by configuring the macro %_ftpport.

rpm allows the following options to be used with http URLs:

--httpproxy HOST The host HOST will be used as a proxy server for all http trans- fers. This option may also be specified by configuring the macro %_httpproxy.

--httpport PORT The TCP PORT number to use for the http connection on the proxy http server instead of the default port. This option may also be specified by configuring the macro %_httpport.

LEGACY ISSUES Executing rpmbuild The build modes of rpm are now resident in the /usr/bin/rpmbuild exe- cutable. Although legacy compatibility provided by the popt aliases below has been adequate, the compatibility is not perfect; hence build mode compatibility through popt aliases is being removed from rpm. Install the package containing rpmbuild (usually rpm-build) and see rpmbuild(8) for documentation of all the rpm build modes previously documented here in rpm(8).

Add the following lines to /etc/popt if you wish to continue invoking rpmbuild from the rpm command line:

rpm exec --bp rpmb -bp rpm exec --bc rpmb -bc rpm exec --bi rpmb -bi rpm exec --bl rpmb -bl rpm exec --ba rpmb -ba rpm exec --bb rpmb -bb rpm exec --bs rpmb -bs rpm exec --tp rpmb -tp rpm exec --tc rpmb -tc rpm exec --ti rpmb -ti rpm exec --tl rpmb -tl rpm exec --ta rpmb -ta rpm exec --tb rpmb -tb rpm exec --ts rpmb -ts rpm exec --rebuild rpmb --rebuild rpm exec --recompile rpmb --recompile rpm exec --clean rpmb --clean rpm exec --rmsource rpmb --rmsource rpm exec --rmspec rpmb --rmspec rpm exec --target rpmb --target rpm exec --short-circuit rpmb --short-circuit

FILES rpmrc Configuration /usr/lib/rpm/rpmrc /usr/lib/rpm/redhat/rpmrc /etc/rpmrc ~/.rpmrc

Macro Configuration /usr/lib/rpm/macros /usr/lib/rpm/redhat/macros /etc/rpm/macros ~/.rpmmacros

Database /var/lib/rpm/Basenames /var/lib/rpm/Conflictname /var/lib/rpm/Dirnames /var/lib/rpm/Filemd5s /var/lib/rpm/Group /var/lib/rpm/Installtid /var/lib/rpm/Name /var/lib/rpm/Packages /var/lib/rpm/Providename /var/lib/rpm/Provideversion /var/lib/rpm/Pubkeys /var/lib/rpm/Removed /var/lib/rpm/Requirename /var/lib/rpm/Requireversion /var/lib/rpm/Sha1header /var/lib/rpm/Sigmd5 /var/lib/rpm/Triggername

Temporary /var/tmp/rpm*

SEE ALSO popt(3), rpm2cpio(8), rpmbuild(8),

rpm --help - as rpm supports customizing the options via popt aliases its impossible to guarantee that whats described in the manual matches whats available.

http://www.rpm.org/ <URL:http://www.rpm.org/>

AUTHORS Marc Ewing <marc@redhat.com> Jeff Johnson <jbj@redhat.com> Erik Troan <ewt@redhat.com>

Red Hat, Inc. 09 June 2002 RPM(8) DUMP(8) System management commands DUMP(8)

NAME dump - ext2/3 filesystem backup

SYNOPSIS dump [-level#] [-ackMnqSuv] [-A file] [-B records] [-b blocksize] [-d density] [-D file] [-e inode numbers] [-E file] [-f file] [-F script] [-h level] [-I nr errors] [-jcompression level] [-L label] [-Q file] [-s feet] [-T date] [-y] [-zcompression level] files-to-dump

dump [-W | -w]

DESCRIPTION Dump examines files on an ext2/3 filesystem and determines which files need to be backed up. These files are copied to the given disk, tape or other storage medium for safe keeping (see the -f 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.

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 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 oper- ator to change media.

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: -u is not allowed, the only dump level that is supported is 0 and all the files and directories must reside on the same filesystem.

OPTIONS The following options are supported by dump:

-level# The dump level (any integer). A level 0, full backup, guarantees the entire file system is copied (but see also the -h option below). A level number above 0, incremental backup, tells dump to copy all files new or modified since the last dump of a lower level. The default level is 0. Historically only levels 0 to 9 were usable in dump, this version is able to understand any integer as a dump level.

-a auto-size. 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).

-A archive_file Archive a dump table-of-contents in the specified archive_file to be used by restore(8) to determine whether a file is in the dump file that is being restored.

-b blocksize The number of kilobytes per dump record. The default blocksize is 10, unless the -d option has been used to specify a tape den- sity of 6250BPI or more, in which case the default blocksize is 32. Th maximal value is 1024. Note however that, since the IO system slices all requests into chunks of MAXBSIZE (which can be as low as 64kB), you can experience problems with dump(8) and restore(8) when using a higher value, depending on your kernel and/or libC versions.

-B records The number of 1 kB blocks per volume. Not normally required, as dump can detect end-of-media. When the specified size is reached, dump waits for you to change the volume. This option overrides the calculation of tape size based on length and den- sity. If compression is on this limits the size of the com- pressed output per volume. Multiple values may be given as a single argument separated by commas. Each value will be used for one dump volume in the order listed; if dump creates more volumes than the number of values given, the last value will be used for the remaining volumes. This is useful for filling up already partially filled media (and then continuing with full size volumes on empty media) or mixing media of different sizes.

-c Change the defaults for use with a cartridge tape drive, with a density of 8000 bpi, and a length of 1700 feet. Specifying a cartridge drive overrides the end-of-media detection.

-d density Set tape density to density. The default is 1600BPI. Specifying a tape density overrides the end-of-media detection.

-D file Set the path name of the file storing the information about the previous full and incremental dumps. The default location is /etc/dumpdates.

-e inodes Exclude inodes from the dump. The inodes parameter is a comma separated list of inode numbers (you can use stat(1) to find the inode number for a file or directory).

-E file Read list of inodes to be excluded from the dump from the text file file. The file file should be an ordinary file containing inode numbers separated by newlines.

-f file Write the backup to file; file may be a special device file like /dev/st0 (a tape drive), /dev/rsd1c (a floppy disk drive), an ordinary file, or - (the standard output). Multiple file names may be given as a single argument separated by commas. Each file will be used for one dump volume in the order listed; if the dump requires more volumes than the number of names given, the last file name will used for all remaining volumes after prompt- ing for media changes. If the name of the file is of the form host:file or user@host:file dump writes to the named file on the remote host (which should already exist, dump doesn t create a new remote file) using rmt(8). The default path name of the remote rmt(8) program is /etc/rmt; this can be overridden by the environment variable RMT.

-F script Run script at the end of each tape (except for the last one). The device name and the current volume number are passed on the command line. The script must return 0 if dump should continue without asking the user to change the tape, 1 if dump should continue but ask the user to change the tape. Any other exit code will cause dump to abort. For security reasons, dump reverts back to the real user ID and the real group ID before running the script.

-h level Honor the user nodump flag UF_NODUMP only for dumps at or above the given level. The default honor level is 1, so that incre- mental backups omit such files but full backups retain them.

-I nr errors By default, dump 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 dump on an active filesystem where read errors simply indicate an inconsistency between the mapping and dumping passes.

A value of 0 means that all read errors will be ignored.

-jcompression 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 com- pressed tapes. Tapes written using compression will not be com- patible with the BSD tape format. The (optional) parameter spec- ifies the compression level bzlib will use. The default compres- sion level is 2. If the optional parameter is specified, there should be no white space between the option letter and the parameter.

-k Use Kerberos authentication to talk to remote tape servers. (Only available if this option was enabled when dump was com- piled.)

-L label The user-supplied text string label is placed into the dump header, where tools like restore(8) and file(8) can access it. Note that this label is limited to be at most LBLSIZE (currently 16) characters, which must include the terminating .

-m If this flag is specified, dump 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, dump 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.

If you use this option, be aware that many programs that unpack files from archives (e.g. tar, rpm, unzip, dpkg) may set files mtimes to dates in the past. Files installed in this way may not be dumped correctly using "dump -m" if the modified mtime is earlier than the previous level dump.

Tapes written using such metadata only inodes will not be com- patible with the BSD tape format or older versions of restore.

-M Enable the multi-volume feature. The name specified with f is treated as a prefix and dump writes in sequence to <prefix>001, <prefix>002 etc. This can be useful when dumping to files on an ext2 partition, in order to bypass the 2GB file size limitation.

-n Whenever dump requires operator attention, notify all operators in the group operator by means similar to a wall(1).

-q Make dump abort immediately whenever operator attention is required, without prompting in case of write errors, tape changes etc.

-Q file Enable the Quick File Access support. Tape positions for each inode are stored into the file 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 drives head.

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(4) man page, option MTSETDRVBUFFER , or the mt(1) man page, on how to set the driver to return logical tape positions.

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.

This option can be used when dumping to local tapes (see above) or to local files.

-s feet Attempt to calculate the amount of tape needed at a particular density. If this amount is exceeded, dump prompts for a new tape. It is recommended to be a bit conservative on this option. The default tape length is 2300 feet. Specifying the tape size overrides end-of-media detection.

-S Size estimate. Determine the amount of space that is needed to perform the dump without actually doing it, and display the estimated number of bytes it will take. This is useful with incremental dumps to determine how many volumes of media will be needed.

-T date Use the specified date as the starting time for the dump instead of the time determined from looking in /etc/dumpdates . The format of date is the same as that of ctime(3) followed by an rfc822 timezone specification: either a plus or minus sign fol- lowed by two digits for the number of hours and two digits for the minutes. For example, -0800 for eight hours west of Green- wich or +0230 for two hours and a half east of Greenwich. This timezone offset takes into account daylight savings time (if applicable to the timezone): UTC offsets when daylight savings time is in effect will be different than offsets when daylight savings time is not in effect. For backward compatibility, if no timezone is specified, a local time is assumed. This option is useful for automated dump scripts that wish to dump over a spe- cific period of time. The -T option is mutually exclusive from the -u option.

-u Update the file /etc/dumpdates after a successful dump. The for- mat of /etc/dumpdates is readable by people, consisting of one free format record per line: filesystem name, increment level and ctime(3) format dump date followed by a rfc822 timezone specification (see the -u option for details). If no timezone offset is specified, times are interpreted as local. Whenever the file is written, all dates in the file are converted to the local time zone, without changing the UTC times. There may be only one entry per filesystem at each level. The file /etc/dump- dates may be edited to change any of the fields, if necessary.

-v The -v (verbose) makes dump to print extra information which could be helpful in debug sessions.

-W Dump tells the operator what file systems need to be dumped. This information is gleaned from the files /etc/dumpdates and /etc/fstab. The -W option causes dump to print out, for all file systems in /etc/dumpdates , and recognized file systems in /etc/mtab and /etc/fstab. the most recent dump date and level, and highlights those that should be dumped. If the -W option is set, all other options are ignored, and dump exits immediately.

-w Is like -W, but prints only recognized filesystems in /etc/mtab and /etc/fstab which need to be dumped.

-y Compress every block to be written to the tape using the lzo library. This doesnt compress as well as the zlib library but its much faster. 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.4b34 version of restore in order to extract com- pressed tapes. Tapes written using compression will not be com- patible with the BSD tape format.

-zcompression 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 com- pressed tapes. Tapes written using compression will not be com- patible with the BSD tape format. The (optional) parameter spec- ifies the compression level zlib will use. The default compres- sion level is 2. If the optional parameter is specified, there should be no white space between the option letter and the parameter.

Dump requires operator intervention on these conditions: end of tape, end of dump, tape write error, tape open error or disk read error (if there is more than a threshold of nr errors). In addition to alerting all operators implied by the -n key, dump interacts with the operator on dumps control terminal at times when dump can no longer proceed, or if something is grossly wrong. All questions dump poses must be answered by typing yes or no, appropriately.

Since making a dump involves a lot of time and effort for full dumps, dump checkpoints itself at the start of each tape volume. If writing that volume fails for some reason, dump will, with operator permission, restart itself from the checkpoint after the old tape has been rewound and removed, and a new tape has been mounted.

Dump tells the operator what is going on at periodic intervals, includ- ing usually low estimates of the number of blocks to write, the number of tapes it will take, the time to completion, and the time to the tape change. The output is verbose, so that others know that the terminal controlling dump is busy, and will be for some time.

In the event of a catastrophic disk event, the time required to restore all the necessary backup tapes or files to disk can be kept to a mini- mum by staggering the incremental dumps. An efficient method of stag- gering incremental dumps to minimize the number of tapes follows:

Always start with a level 0 backup, for example: /sbin/dump -0u -f /dev/st0 /usr/src

This should be done at set intervals, say once a month or once every two months, and on a set of fresh tapes that is saved for- ever.

After a level 0, dumps of active file systems are taken on a daily basis, using a modified Tower of Hanoi algorithm, with this sequence of dump levels: 3 2 5 4 7 6 9 8 9 9 ...

For the daily dumps, it should be possible to use a fixed number of tapes for each day, used on a weekly basis. Each week, a level 1 dump is taken, and the daily Hanoi sequence repeats beginning with 3. For weekly dumps, another fixed set of tapes per dumped file system is used, also on a cyclical basis.

After several months or so, the daily and weekly tapes should get rotated out of the dump cycle and fresh tapes brought in.

(The 4.3BSD option syntax is implemented for backward compatibility but is not documented here.)

ENVIRONMENT TAPE If no -f option was specified, dump will use the device speci- fied via TAPE as the dump device. TAPE may be of the form tape- name, host:tapename, or user@host:tapename.

RMT The environment variable RMT will be used to determine the path- name of the remote rmt(8) program.

RSH Dump uses the contents of this variable to determine the name of the remote shell command to use when doing remote backups (rsh, ssh etc.). If this variable is not set, rcmd(3) will be used, but only root will be able to do remote backups.

FILES /dev/st0 default tape unit to dump to

/etc/dumpdates dump date records

/etc/fstab dump table: file systems and frequency

/etc/mtab dump table: mounted file systems

/etc/group to find group operator

SEE ALSO fstab(5), restore(8), rmt(8)

DIAGNOSTICS Many, and verbose.

COMPATIBILITY The format of the /etc/dumpdates file has changed in release 0.4b34, however, the file will be read correctly with either pre-0.4b34 or 0.4b34 and later versions of dump provided that the machine on which dump is run did not change timezones (which should be a fairly rare occurrence).

EXIT STATUS Dump exits with zero status on success. Startup errors are indicated with an exit code of 1; abnormal termination is indicated with an exit code of 3.

BUGS It might be considered a bug that this version of dump can only handle ext2/3 filesystems. Specifically, it does not work with FAT filesys- tems.

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.

When a read error occurs, dump prints out the corresponding physical disk block and sector number and the ext2/3 logical block number. It doesnt print out the corresponding file name or even the inode number. The user has to use debugfs(8), commands ncheck and icheck to translate the ext2blk number printed out by dump into an inode number, then into a file name.

Each reel requires a new process, so parent processes for reels already written just hang around until the entire tape is written.

The estimated number of tapes is not correct if compression is on.

It would be nice if dump knew about the dump sequence, kept track of the tapes scribbled on, told the operator which tape to mount when, and provided more assistance for the operator running restore.

Dump cannot do remote backups without being run as root, due to its security history. Presently, it works if you set it setuid (like it used to be), but this might constitute a security risk. Note that you can set RSH to use a remote shell program instead.

AUTHOR The dump/restore backup suite was ported to Linux s Second Extended File System by Remy Card <card@Linux.EU.Org>. He maintained the initial versions of dump (up and including 0.4b4, released in January 1997).

Starting with 0.4b5, the new maintainer is Stelian Pop <stelian@popies.net>.

AVAILABILITY The dump/restore backup suite is available from <http://dump.source- forge.net>

HISTORY A dump command appeared in Version 6 AT&T UNIX.

BSD version 0.4b41 of January 2, 2006 DUMP(8)