rpminspect - Man Page

rpminspect -c FILE [ Options ] before_build [ after_build ]

rpminspect is a tool designed to help developers maintain build policy compliance and consistency among releases.  The tool has two primary modes of operation.  The first is what can be considered an analysis mode.  This runs against a single RPM or Koji build (a build being a source RPM and all of its built packages for multiple architectures). The analysis mode checks for package consistency and compliance. Various inspections can be configured via the configuration file, profile in use, or local rpminspect.yaml file.  The other mode is build comparison.  This mode performs all of the same inspections as analysis mode as well as comparisons between a before and after package or build.  There is no explicit option to run rpminspect in either mode; the mode of operation is determined by specifying either one or two inputs.  One input means analysis mode, two inputs means comparison mode.

rpminspect originated at Red Hat as an auditing tool used to ensure builds complied with certain release rules and policies.  Over time it grew to incorporate other checks, such as making sure debugging symbols are accurate and various security policies were followed. Users are encouraged to contribute tests for new functionality, report bugs, and submit updates to the rules in the corresponding vendor data package(s).

The software is made available as this command line program and an accompanying library.  This is intentional.  Our findings over time have shown that simple tools with a flexible design are more easy to integrate in to continuous integration systems.  The library allows development of other frontends or integration in to existing frontends.  The thought is that most developers will interact with rpminspect through the command line and most integrations of rpminspect will report results through some sort of existing frontend (e.g., GitHub Actions).  Everything about an rpminspect run is configurable at runtime through command line options as well as a configuration file.  The command line options override the configuration file which overrides the compiled in defaults.

-c FILE, --config=FILE

Configuration file.  This is the only required option.  The configuration file is generally provided by a product vendor in the form of /usr/share/rpminspect/VENDOR.yaml.  Wrapper scripts are common to prevent the need to specify the configuration file on the command line (e.g., rpminspect-fedora runs rpminspect with the fedora.yaml configuration file).

-p NAME, --profile=NAME

Optional configuration profile to use.  A configuration profile provides overrides to the main configuration file.  The idea is the main configuration is loaded, then if you specify a profile name rpminspect will load that configuration file and any values specified will override what came from the default configuration file.  Think of the main configuration file as the common one and profile configuration files are optional overlays.  In the data package, profiles should be of the form PROFILENAME.yaml and exist in the 'profiledir' subdirectory.  If you specify a PROFILENAME to this option, rpminspect will search for the profile in 'profiledir'.  You can also pass a PATH to this option and rpminspect will attempt to load the profile from that file.  It is common for vendors to provide a set of profiles in addition to a main configuration file.

The format of a profile configuration file is the same as the configuration file, just call it NAME.yaml and place it in the 'profiledir' for the appropriate vendor.  For example, the profile 'scl' for Fedora should have a configuration file named /usr/share/rpminspect/profiles/fedora/scl.yaml.

-T LIST, --tests=LIST

If specified, this option assumes all inspections are disabled except the names of the ones you specify with this option.  Specify a comma-separated list of inspections to run (default: ALL).  The names of available inspections can be found with the -l option.  You can also specify the name ALL to explicitly say run all inspections.  NOTE:  This option is mutually exclusive with the -E option.

-E LIST, --exclude=LIST

If specified, this option assumes all inspections are enabled except the names of the ones you specify with this option.  Specify a comma-separated list of inspections to skip (default: none).  The names of available inspections can be found with the -l option.  You can also specify the name ALL to explicitly say skip all inspections, though that makes the program do nothing.  NOTE:  This option is mutually exclusive with the -T option.

-a LIST, --arches=LIST

Comma-separated list of architectures to inspect packages on.  By default rpminspect will gather all available architectures for the builds you specify, but you may want to restrict a run to just x86_64 or just aarch64.  You can do that with this option.  If you do specify this option, be sure to include the 'src' architecture to inspect source packages and 'noarch' to include noarch packages.  The architectures you list here are validated against the available architectures in the Koji hub and any invalid ones will report an error.

For the purposes of RPM packaging and rpminspect, both 'noarch' and 'src' are considered architectures.  Please keep that in mind when using this option.

-r STR, --release=STR

String identifying the product release for the specified build or builds. Normally rpminspect will determine this by looking for a "dist tag" at the end of the NVR.  For build comparisons, the determined product releases must match in order for rpminspect to continue.  If you want to compare builds from different products, you will need to specify a product release manually.  You will also need to specify the product release if the builds you are comparing lack any kind of product release identifier at the end of the NVR.

rpminspect can be configured to favor the newest or oldest product release string in case they do not match.  This may be useful when comparing builds from one product release to another.

-n,  --no-rebase

Disable rebased build detection.  When comparing two builds or two packages, rpminspect will look at the package names, version numbers, and release numbers.  If the names and versions match but the releases vary, the package is not considered a rebase because the assumption is this is a maintenance type build on an existing package.  Non-rebase comparisons enforce more strict rules for certain inspections.  If the package names match but the version numbers differ, rpminspect considers the comparison to be between rebased builds.  Rebased comparisons relax those strict rules in order to eliminate a lot of false positives in the output.  If you want to always disable the rebase checking and enforce the strict rules, you can pass this option.

-b TYPE, --build-type=TYPE

Set the Koji build type to TYPE.  By default, rpminspect will try to automatically determine the build type of the inputs.  In some cases you may want to explicitly set the type if it is having trouble determining the build type.  This option is most useful when using locally provided Koji input subdirectories.  Supported build types can be seen with the -l option.

-o FILE, --output=FILE

Write the results to the name output file.  By default, results go to stdout.

-F TYPE, --format=TYPE

Write the inspection results in the TYPE format.  The default format is text.  Available formats can be seen with the -l option.

-t TAG, --threshold=TAG

Result threshold that triggers a non-zero exit code.  By default this is VERIFY, which maps to a result code seen in the output.  You can set this to any of the valid result codes.  Available result codes are OK, INFO, VERIFY, or BAD.  The argument expects the result threshold specified as a string.  Case does not matter.

-s TAG, --suppress=TAG

Results suppression threshold.  By default all results are reported, but you can use this option to suppress results below a reporting level.  The values are the same as for the -t option above.  For example, to only show VERIFY and higher results, pass "-s VERIFY" at run time.

-l,  --list

List available output formats and inspections

-w PATH, --workdir=PATH

Temporary working directory to use (default: /var/tmp/rpminspect).  You can specify a tilde (~) character in the PATH specification and rpminspect will expand it.  Keep in mind that the PATH you specify with ~ must exist in order for expansion to work.

-f,  --fetch-only

Only download files in specified builds, do not perform any inspections (implies -k).  This option is intended as a convenience for developers as well as for easier integration in to different CI workflows.  Note that this option does not change the working directory (-w) to the current working directory.  If this is undesirable, use the -w option to set it to a different location. For example, to download to the current working directory you can pass "-w $(pwd)".

You may specify one or more builds when using the fetch only mode.

-k,  --keep

Do not remove temporary working files before exit.  Useful at times for debugging.

-d,  --debug

Enable debugging mode.  This mode generates additional output on stdout and stderr.

-D,  --dump-config

Dump configuration settings in use in YAML format.  The output of this option will be the combined settings after reading the configuration file, any profile specified, and any local configuration file.  Useful for debugging to ensure settings have been read in correctly.

-v,  --verbose

Verbose inspection output.  By default, only warnings or failures are reported.  This option also displays informational findings.  Use this mode with -l to display long descriptions of output formats and inspections.

-?,  --help

Display usage information.

-V,  --version

Display version information.

rpminspect requires very little to run.  Assuming you meet the runtime requirements to either build the software from source or you have installed it on your operating system, you are ready to use it.  The only required arguments are the '-c' option to specify the configuration file and at least one input.  The input may be an RPM package (local or remote), a Koji build (either local or remote), or a Koji task ID.  When provided with a single input, rpminspect runs in analysis mode.  When two inputs are provided, it performs all of the analysis checks as well as comparison checks.

Use the -l option to list available inspections (add -v to get detailed descriptions of the inspections).  By default, all inspections will be run.  You can restrict the program to a subset of inspections by listing their short names and separating them with commas (no spaces).  Or you can list inspections to skip by listing the short name prefixed with a `!' in the same comma-delimited list.

rpminspect uses the term 'build' to refer to inputs.  Builds may be local RPM packages, regular Koji builds specified using Koji syntax (the NVR or name, version, and release of a package with hyphens separating each part), Koji module builds, locally cached Koji builds (regular or module), Koji scratch builds (task ID number), or locally cached Koji scratch builds.  Any valid Koji build identifier works when specifying Koji builds, such as the build ID number or the package NVR.  The only exception to this rule is scratch builds.  You must use the Koji task ID number for scratch builds.  For more information on Koji build specification, please see the Koji documentation.

If you specify a directory tree containing the output of a properly structured Koji build, rpminspect can use that directly.  This may be useful for multiple runs of rpminspect against a specific previous build where you are trying to fix something in a new build compared against the old one.

Local and remote RPM packages may be specified directly too if you just want to use rpminspect on a single RPM.  You may specify a single RPM package or two if you want rpminspect to perform the comparison inspections.  A URL to an RPM specified as an input causes rpminspect to try and download that package.

Examples:

rpminspect -T ALL -k zlib-1.2.7-1.fc29 zlib-1.2.7-2.fc29

rpminspect -T license,elfsyms perl-5.28.0-47.fc6 perl-5.28.1-1.fc6

rpminspect -T !manpage x3270-3.6ga5-6.fc31 x3270-3.6ga6-1.fc31

rpminspect -T ALL -a ppc64le zsh-5.7.1-3.fc31 zsh-5.7.1-4.fc31

rpminspect -E disttag -a ppc64le zsh-5.7.1-3.fc31 zsh-5.7.1-4.fc31

rpminspect -T ALL https://dl.fedoraproject.org/pub/fedora/linux/releases/36/Everything/x86_64/os/Packages/l/less-590-3.fc36.x86_64.rpm

rpminspect -T ALL /home/developer/rpmbuild/RPMS/less-590-3.fc36.x86_64.rpm /home/developer/rpmbuild/RPMS/less-590-4.fc36.x86_64.rpm

rpminspect /home/developer/rpmbuild/SRPMS/less-590-4.fc36.src.rpm

The end result of running rpminspect is a report on standard output explaining what was found.  Descriptions of actions developers can take are provided in the findings.

The most common use of rpminspect in continuous integration environments is to fetch and analyze builds directly from Koji.  That is why rpminspect can speak to Koji directly and download files.  If you are running rpminspect locally, you can simulate inputs this way by constructing a local directory that looks like a Koji build as rpminspect would download it.  Start by creating a subdirectory.  It can be called anything, but the convention rpminspect follows is to name the subdirectory after the Koji build specification in NVR syntax.  For example, less-590-3.fc36 would be the subdirectory name. The next thing to do is create subdirectories in there for each architecture and the source RPM.  Any 'noarch' packages need to go in a noarch subdirectory.

As an example, let's consider a source RPM that you rebuild locally. Take zlib-1.2.12-5.fc37.src.rpm as the example.  You rebuild this locally using either rpmbuild or mock and it generates all of the subpackages from the source RPM.  To construct a build input directory for rpminspect, you would create a directory named 'zlib-build'. Within that directory, create two new subdirectories called 'src' and 'x86_64' (assuming you built on x86_64.  Put the source RPM in 'zlib-build/src/' and put all of the x86_64 binary RPMs in 'zlib-build/x86_64/'.  You may now use 'zlib-build' as an input for rpminspect and it will treat it the same way it treats Koji builds.

rpminspect exits 0 if all inspections pass, 1 if at least one inspection did not pass.  rpminspect exits 3 if the specified profile is not found, and 2 if any other program error occurred.

Please report bugs at https://github.com/rpminspect/rpminspect using the Issues tab.

rpm(8)

David Cantrell <dcantrell@redhat.com>