5.1 The Red Hat Package Manager

The Red Hat Package Manager (RPM) is a freely available packaging system for software distribution and installation. In addition to Red Hat and Red Hat-based distributions, both SuSE and Caldera are among the Linux distributions that use RPM.

Using RPM is straightforward. A single command, rpm, has options to perform all package management functions except building packages.^[1] For example, to find out if the Emacs editor is installed on your system, you could say:

^[1] In older versions of RPM, the build options were part of the rpm command.

% rpm -q emacs
emacs-21.2-18

The rpmbuild command is used to build both binary and source packages.

5.1.1 The rpm Command

RPM packages are built, installed, and queried with the rpm command. RPM package names usually end with a .rpm extension. rpm has a set of modes, each with its own options. The format of the rpm command is:

rpm  [options ] [packages ]

With a few exceptions, as noted in the lists of options that follow, the first option specifies the rpm mode (install, query, update, etc.), and any remaining options affect that mode.

Options that refer to packages are sometimes specified as package-name and sometimes as package-file. The package name is the name of the program or application, such as gif2png. The package file is the name of the RPM file, such as gif2png-2.4.6-1.i386.rpm.

RPM provides a configuration file for specifying frequently used options. The default global configuration is usually /usr/lib/rpm/rpmrc, the local system configuration file is /etc/rpmrc, and users can set up their own $HOME/.rpmrc files. You can use the --showrc option to show the values RPM will use for all the options that may be set in an rpmrc file:

rpm --showrc

The rpm command includes FTP and HTTP clients, so you can specify an ftp:// or http:// URL to install or query a package across the Internet. You can use an FTP or HTTP URL wherever package-file is specified in the commands presented here.

Any user can query the RPM database. Most of the other functions require superuser privileges.

5.1.1.1 General options

The following options can be used with all modes:

--dbpath path

Use path as the path to the RPM database instead of the default /var/lib/rpm.

-?, --help

Print a long usage message (running rpm with no options gives a shorter usage message).

--pipe command

Pipe the rpm output to command.

--quiet

Display only error messages.

--rcfile filelist

Get configuration from the files in the colon-separated filelist. If --rcfile is specified, there must be at least one file in the list and the file must exist. filelist defaults to /var/lib/rpm/rpmrc:/usr/lib/rpm/redhat/rpmrc:~/.rpmrc.

--root dir

Perform all operations within the directory tree rooted at dir.

-v

Verbose. Print progress messages.

--version

Print the version number of rpm.

-vv

Print debugging information.

5.1.1.2 Install, upgrade, and freshen options

Use the install command to install or upgrade an RPM package. The install syntax is:

rpm -i  [install-options ] package_file  ... 
rpm --install  [install-options ] package_file  ...

To install a new version of a package and remove an existing version at the same time, use the upgrade command instead:

rpm -U  [install-options ] package_file  ... 
rpm --upgrade  [install-options ] package_file  ...

If the package doesn't already exist on the system, -U acts like -i and installs it. To prevent that behavior, you can freshen a package instead; in that case, rpm upgrades the package only if an earlier version is already installed. The freshen syntax is:

rpm -F  [install-options ] package_file  ...
rpm --freshen  [install-options ] package_file  ...

package-file can be specified as an FTP or HTTP URL to download the file before installing it. See Section 5.1.1.11.

The installation and upgrade options are:

--aid

If rpm suggests additional packages, add them to the list of package files.

--allfiles

Install or upgrade all files.

--badreloc

Used with --relocate to force relocation even if the package is not relocatable.

--excludedocs

Don't install any documentation files.

--excludepath path

Don't install any file whose filename begins with path.

--force

Force the installation. Equivalent to using all of --replacepkgs, --replacefiles, and --oldpackage.

-h, --hash

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

--ignorearch

Install even if the binary package is intended for a different architecture.

--ignoreos

Install binary package even if the operating systems don't match.

--ignoresize

Don't check disk space availability before installing.

--includedocs

Install documentation files. This is needed only if excludedocs: 1 is specified in an rpmrc file.

--justdb

Update the database only; don't change any files.

--nodeps

Don't check whether this package depends on the presence of other packages.

--nodigest

Don't verify package or header digests.

--noorder

Don't reorder packages to satisfy dependencies before installing.

--nopost

Don't execute any post-install script.

--nopostun

Don't execute any post-uninstall script.

--nopre

Don't execute any pre-install script.

--nopreun

Don't execute any pre-uninstall script.

--noscripts

Don't execute any pre-install or post-install scripts. Equivalent to specifying all of --nopre, --nopost, --nopreun, and --nopostun.

--nosignature

Don't verify package or header signatures.

--nosuggest

Don't suggest packages that provide a missing dependency.

--notriggerin

Don't execute any install trigger scriptlet.

--notriggerun

Don't execute any uninstall trigger scriptlet.

--notriggerpostun

Don't execute any post-uninstall trigger scriptlet.

--notriggers

Don't execute any scripts triggered by package installation.

--oldpackage

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

--percent

Print percent-completion messages as files are unpacked. Useful for running rpm from other tools.

--prefix path

Set the installation prefix to path for relocatable binary packages.

--relocate oldpath=newpath

For relocatable binary files, change all file paths from oldpath to newpath. Can be specified more than once to relocate multiple paths.

--repackage

Repackage the package files before erasing. Rename the package as specified by the macro %_repackage_name_fmt and save it in the directory specified by the macro %_repackage_dir (by default /var/tmp).

--replacefiles

Install the packages even if they replace files from other installed packages.

--replacepkgs

Install the packages even if some of them are already installed.

--test

Go through the installation to see what it would do, but don't actually install the package. This option lets you test for problems before doing the installation.

5.1.1.3 Query options

The syntax for the query command is:

rpm -q  [package-options ] [information-options ]
rpm --query  [package-options ] [information-options ]

There are two subsets of query options. Package selection options determine what packages to query, and information selection options determine what information to provide.

5.1.1.4 Package selection options

package_name

Query the installed package package_name.

-a, --all

Query all installed packages.

-f file, --file file

Find out what package owns file.

--fileid md5

Query package with the specified MD5 digest.

-g group, --group group

Find out what packages have group group.

--hdrid sha1

Query package with the specified SHA1 digest in the package header.

-p package_file, --package package_file

Query the uninstalled package package_file, which can be a URL. If package_file is not a binary package, it is treated as a text file containing a package manifest, with each line of the manifest containing a path or one or more whitespace-separated glob expressions to be expanded to paths. These paths are then used instead of package_file as the query arguments. The manifest can contain comments that begin with a hash mark (#).

--pkgid md5

Query the package with a package identifier that is the given MD5 digest of the combined header and contents.

--querybynumber num

Query the numth database entry. Useful for debugging.

-qf, --queryformat num

Specify the format for displaying the query output, using tags to represent different types of data (e.g., NAME, FILENAME, DISTRIBUTION). The format specification is a variation of the standard printf formatting, with the type specifier omitted and replaced by the name of the header tag inclosed in brackets ({ }). For example:

%{NAME}

The tag names are case-insensitive. Use --querytags (see Section 5.1.1.10) to view a list of available tags. The tag can be followed by :type to get a different output format type. The possible types are:

armor

Wrap a public key in ASCII armor.

base64

Encode binary data as 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

Use hexadecimal format.

octal

Use octal format.

perms

Format file permissions.

shescape

Escape single quotes for use in a script.

triggertype

Display trigger suffix.

--specfile specfile

Query specfile as if it were a package. Useful for extracting information from a spec file.

--tid tid

List packages with the specified transaction identifier (tid). The tid is a Unix timestamp. All packages installed or erased in a single transaction have the same tid.

--triggeredby pkg

List packages that are triggered by the installation of package pkg.

--whatrequires capability

List packages that require the given capability to function.

--whatprovides capability

List packages that provide the given capability.

5.1.1.5 Information selection options

-c, --configfiles

List configuration files in the package. Implies -l.

--changelog

Display the log of change information for the package.

-d, --docfiles

List documentation files in the package. Implies -l.

--dump

Dump information for each file in the package. This option must be used with at least one of -l, -c, or -d. The output includes the following information in this order:

path size mtime md5sum mode owner group isconfig isdoc rdev symlink

--filesbypkg

List all files in each package.

-i, --info

Display package information, including the name, version, and description. Formats the results according to --queryformat if specified.

-l, --list

List all files in the package.

--last

List packages by install time, with the latest packages listed first.

--provides

List the capabilities this package provides.

-R, --requires

List any packages this package depends on.

-s, --state

List each file in the package and its state. The possible states are normal, not installed, or replaced. Implies -l.

--scripts

List any package-specific shell scripts used during installation and uninstallation of the package.

--triggers, --triggerscript

Display any trigger scripts in the package.

5.1.1.6 Uninstall options

The syntax for erase, the uninstall command, is:

rpm -e  package_name  ...
rpm --erase  package_name  ...

The uninstall options are:

--allmatches

Remove all versions of the package. Only one package should be specified; otherwise, an error results.

--nodeps

Don't check dependencies before uninstalling the package.

--nopostun

Don't run any post-uninstall scripts.

--nopreun

Don't run any pre-uninstall scripts.

--noscripts

Don't execute any pre-uninstall or post-uninstall scripts. Equivalent to --nopreun --nopostun.

--notriggerpostun

Don't execute any post-uninstall scripts triggered by the removal of this package.

--notriggers

Don't execute any scripts triggered by the removal of this package. Equivalent to --notriggerun --notriggerpostun.

--notriggerun

Don't execute any uninstall scripts triggered by the removal of this package.

--repackage

Repackage the files before uninstalling them. Rename the package as specified by the macro %_repackage_name_fmt and save it in the directory specified by the macro %_repackage_dir (by default /var/tmp).

--test

Don't really uninstall anything; just go through the motions. Use with -vv for debugging.

5.1.1.7 Verify options

The syntax for the verify command is:

rpm -V|-y|--verify  [package-selection-options ] [verify-options ]

Verify mode compares information about the installed files in a package with information about the files that came in the original package, and displays any discrepancies. The information compared includes the size, MD5 sum, permissions, type, owner, and group of each file. Uninstalled files are ignored.

The package selection options include those available for query mode. In addition, the following verify options are available:

--nodeps

Ignore package dependencies.

--nodigest

Ignore package or header digests.

--nofiles

Ignore attributes of package files.

--nogroup

Ignore group ownership errors.

--nolinkto

Ignore symbolic link errors.

--nomd5

Ignore MD5 checksum errors.

--nomode

Ignore file mode (permissions) errors.

--nordev

Ignore major and minor device number errors.

--nomtime

Ignore modification time errors.

--noscripts

Ignore any verify script.

--nosignature

Ignore package or header signatures.

--nosize

Ignore file size errors.

--nouser

Ignore user ownership errors.

The output is formatted as an eight-character string, possibly followed by an attribute marker, and then the filename. The possible attribute markers are:

c	Configuration file
d	Documentation file
g	Ghost file (contents not included in package)
l	License file
r	Readme file

Each of the eight characters in the string represents the result of comparing one file attribute to the value of that attribute from the RPM database. A period (.) indicates that the file passed that test. The following characters indicate failure of the corresponding test:

5	MD5 sum
D	Device
G	Group
L	Symlink
M	Mode (includes permissions and file type)
S	File size
T	Mtime
U	User

5.1.1.8 Database rebuild options

The syntax of the command to rebuild the RPM database is:

rpm --rebuilddb  [options ]

You also can build a new database:

rpm --initdb  [options ]

The options available with the database rebuild mode are the --dbpath, --root, and -v options described earlier under Section 5.1.1.1.

5.1.1.9 Signature check options

RPM packages may have a PGP signature built into them. PGP configuration information is read from the rpmrc file. There are three types of digital signature options: you can check signatures, add signatures to packages, and import signatures.

The syntax of the signature check mode is:

rpm --checksig  package_file ...
rpm -K  package_file ...

The signature checking options -K and --checksig check the digests and signatures contained in the specified packages to insure the integrity and origin of the packages. Note that RPM now automatically checks the signature of any package when it is read; this option is still useful, however, for checking all headers and signatures associated with a package.

The following options are available for use with signature check mode:

--nogpg

Don't check any GPG signatures.

--nomd5

Don't check any MD5 signatures.

--nopgp

Don't check any PGP signatures.

The syntax for adding signatures to binary packages is:

rpm --addsign  binary-pkgfile ...
rpm --resign  binary-pkgfile ...

Both --addsign and --resign generate and insert new signatures, replacing any that already exist in the specified binary packages.^[2]

^[2] In older versions of RPM, --addsign was used to add new signatures without replacing existing ones, but currently both options work the same way and replace any existing signatures.

The syntax for importing signatures is:

rpm --import  public-key 

The --import option is used to import an ASCII public key to the RPM database so that digital signatures for packages using that key can be verified. Imported public keys are carried in headers, and keys are kept in a ring, which can be queried and managed like any package file.

5.1.1.10 Miscellaneous options

Several additional rpm options are available:

--querytags

Print the tags available for use with the --queryformat option in query mode.

--setperms packages

Set file permissions of the specified packages to those in the database.

--setugids packages

Set file owner and group of the specified packages to those in the database.

--showrc

Show the values rpm will use for all options that can be set in an rpmrc file.

5.1.1.11 FTP/HTTP options

The following options are available for use with FTP and HTTP URLs in install, update, and query modes.

--ftpport port

Use port for making an FTP connection on the proxy FTP server instead of the default port. Same as specifying the macro %_ftpport.

--ftpproxy host

Use host as the proxy server for FTP transfers through a firewall that uses a proxy. Same as specifying the macro %_ftpproxy.

--httpport port

Use port for making an HTTP connection on the proxy HTTP server instead of the default port. Same as specifying the macro %_httpport.

--httpproxy host

Use host as the proxy server for HTTP transfers. Same as specifying the macro %_httpproxy.

5.1.2 The rpmbuild Command

The rpmbuild command is used to build RPM packages. The syntax for rpmbuild is:

rpmbuild - [b |t ]step  [build-options ] spec-file  ...

Specify -b to build a package directly from a spec file, or -t to open a tarred, gzipped file and use its spec file.

Both forms take the following single-character step arguments, listed in the order they would be performed:

p

Perform the prep stage, unpacking source files and applying patches.

l

Do a list check, expanding macros in the files section of the spec file and verifying that each file exists.

c

Perform the build stage. Done after the prep stage; generally equivalent to doing a make.

i

Perform the install stage. Done after the prep and build stages; generally equivalent to doing a make install.

b

Build a binary package. Done after prep, build, and install.

s

Build a source package. Done after prep, build, and install.

a

Build both binary and source packages. Done after prep, build, and install.

The general rpm options described earlier in Section 5.1.1.1 can be used with rpmbuild.

The following additional options can also be used when building an rpm file with rpmbuild:

--buildroot dir

Override the BuildRoot tag with dir when building the package.

--clean

Clean up (remove) the build files after the package has been made.

--nobuild

Go through the motions, but don't execute any build stages. Used for testing spec files.

--rmsource

Remove the source files when the build is done. Can be used as a standalone option with rpm to clean up files separately from creating the packages.

--rmspec

Remove the spec file when the build is done. Like --rmsource, --rmspec can be used as a standalone option with rpmbuild.

--short-circuit

Can be used with -bc and -bi to skip previous stages.

--sign

Add a GPG signature to the package for verifying its identity and origin.

--target platform

When building the package, set the macros %_target, %_target_arch, and %_target_os to the value indicated by platform.

Two other options can be used standalone with rpmbuild to recompile or rebuild a package:

--rebuild source-pkgfile...

Like --recompile, but also build a new binary package. Remove the build directory, the source files, and the spec file once the build is complete.

--recompile source-pkgfile...

Install the named source package, and prep, compile, and install the package.

Finally, the --showrc option is used to show the current rpmbuild configuration:

rpmbuild --showrc

This option shows the values that will be used for all options that can be set in an rpmrc file.

5.1.3 RPM Examples

Query the RPM database to find Emacs-related packages:

% rpm -q -a | grep emacs

Query an uninstalled package, printing information about the package and listing the files it contains:

% rpm -qpil ~/downloads/bash2-doc-2.03-8.i386.rpm

Install a package (assumes superuser privileges):

% rpm -i sudo-1.5.3-6.i386.rpm