RPMINSPECT(1)

RPMINSPECT(1) — okay bestie, welcome to the Red Hat manual page for rpminspect, and we're about to make it make sense 💖✨

✨ NAME ✨

rpminspect — compare package builds. That's the whole name, no cap.

🌸 SYNOPSIS 🌸

rpminspect -c FILE [ OPTIONS ] before_build [ after_build ]

💖 DESCRIPTION 💖

rpminspect is a tool that helps developers keep build policy compliance and consistency across releases. It's giving compliance queen 👑. It has two primary modes of operation. First up: what we call analysis mode. That one runs against a single RPM or Koji build (and bestie, a build is a source RPM plus all its built packages for multiple architectures). Analysis mode checks package consistency and compliance. You can configure various inspections through the configuration file, the profile in use, or a local rpminspect.yaml file. Then there's build comparison. That mode does every inspection analysis mode does, and also compares a before and after package or build. There's no explicit option to pick a mode; the mode is decided by how many inputs you give it. One input = analysis mode, two inputs = comparison mode. Periodt 💅.

rpminspect started at Red Hat as an auditing tool, making sure builds complied with certain release rules and policies. Over time it grew to include other checks — like verifying debugging symbols are accurate and that 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). You're invited, bestie 💌.

The software comes as this command line program and an accompanying library. That's on purpose. 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 lets you develop other frontends or integrate 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. So the order is: command line options > configuration file > compiled in defaults. Iconic 🌈.

✨ OPTIONS ✨

okay bestie, here's the whole menu 💅 every flag, every default, nothing skipped, no cap:

• -c FILE, --config=FILE — the configuration file. This is the only required option, periodt. Usually a product vendor hands it to you as /usr/share/rpminspect/VENDOR.yaml, and wrapper scripts are super common so you don't have to type it out every single time (like, rpminspect-fedora literally just runs rpminspect with the fedora.yaml configuration file, iconic).
• -p NAME, --profile=NAME — optional configuration profile to use, and it's giving overlay. The main config loads first, then if you name a profile, rpminspect loads that config file too and anything in it overrides what came from the default configuration file. Think of the main config as the base look and profiles as the optional accessories ✨. In the data package, profiles should be named PROFILENAME.yaml and live in the profiledir subdirectory. Hand this option a PROFILENAME and rpminspect goes hunting for it in profiledir. You can also pass a PATH here and it'll try to load the profile straight from that file. Vendors commonly ship a whole set of profiles alongside the main configuration file, obsessed.

The format of a profile config file is the exact same as the configuration file — just name it NAME.yaml and drop it in the profiledir for the right 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 — pass this and rpminspect assumes all inspections are off except the ones you name. Give it a comma-separated list of inspections to run (default: ALL). You can find the names of available inspections with the -l option. You can also literally write the name ALL to explicitly say "run everything". ⚠️ NOTE: this option is mutually exclusive with the -E option — pick one, bestie, you can't have both.
• -E LIST, --exclude=LIST — the reverse vibe: pass this and rpminspect assumes all inspections are enabled except the ones you name. Comma-separated list of inspections to skip (default: none). Names of available inspections? Same deal, check with -l. You can also write ALL to skip literally everything, though that makes the program do absolutely 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 gathers every available architecture for the builds you specify, but maybe you only want a run on just x86_64 or just aarch64 — this is how you do that. If you do use it, make sure you include 'src' to inspect source packages and 'noarch' to include noarch packages, fr. The architectures you list get validated against the available architectures in the Koji hub, and any invalid ones will report an error.

For RPM packaging and rpminspect purposes, both 'noarch' and 'src' count as architectures. Keep that in mind when you use this option, okay?

• -r STR, --release=STR — a string identifying the product release for the build(s) you specified. Normally rpminspect figures this out by looking for a "dist tag" at the end of the NVR. For build comparisons, the determined product releases must match or rpminspect won't continue. Want to compare builds from different products? You'll need to specify a product release manually. Same if the builds you're comparing have no product release identifier at the end of the NVR at all.

rpminspect can be configured to favor the newest or oldest product release string when they don't match — lowkey handy when comparing builds across product releases.

• -n, --no-rebase — disables rebased build detection. When comparing two builds or two packages, rpminspect peeks at the package names, version numbers, and release numbers. Names and versions match but releases differ? That's not considered a rebase, because the assumption is it's a maintenance-type build on an existing package. Non-rebase comparisons enforce stricter rules for certain inspections. Names match but versions differ? Now it's a rebased comparison, and rebased comparisons relax those strict rules to eliminate a ton of false positives in the output. If you want to always kill the rebase checking and enforce the strict rules, pass this option.
• -b TYPE, --build-type=TYPE — sets the Koji build type to TYPE. By default rpminspect tries to auto-determine the build type of the inputs. Sometimes it's struggling and you wanna be explicit — this option is most useful when you're 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 named output file. Default is stdout, so without this everything just spills onto your terminal 🫶.
• -F TYPE, --format=TYPE — write the inspection results in the TYPE format. 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. Default is VERIFY, which maps to a result code you'll see in the output. You can set it to any valid result code: OK, INFO, VERIFY, or BAD. The argument expects the result threshold as a string. Case does not matter, slay.
• -s TAG, --suppress=TAG — results suppression threshold. By default all results are reported, but this option lets you suppress results below a reporting level. Same values as 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 put a tilde (~) in the PATH and rpminspect will expand it. But heads up: the PATH you specify with ~ must exist for the expansion to work.
• -f, --fetch-only — only download files in specified builds, do not perform any inspections (implies -k). This one's a convenience for developers plus easier integration into different CI workflows. Note that this option does not change the working directory (-w) to the current working directory. If that's not the vibe, use -w to set it somewhere else. 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 generates additional output on stdout and stderr.
• -D, --dump-config — dump configuration settings in use in YAML format. The output is the combined settings after reading the configuration file, any profile specified, and any local configuration file. Super useful for debugging to make sure settings were 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.

---

🌸 USAGE 🌸

rpminspect requires very little to run, bestie. Assuming you meet the runtime requirements — either build the software from source or have it installed on your OS — you're ready to go 💖. 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.

Give it a single input and rpminspect runs in analysis mode. Give it two inputs and it performs all of the analysis checks plus comparison checks. Two for one, we love to see it 👑

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. Easy.

🛠️ RPMINSPECT BUILD INPUTS

Okay bestie, so rpminspect calls its inputs a 'build'. That's the word. Builds can be so many things and honestly the range is iconic:

• local RPM packages
• regular Koji builds specified using Koji syntax (that's the NVR — 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)
• locally cached Koji scratch builds

Any valid Koji build identifier works when you're specifying Koji builds — like the build ID number, or the package NVR. Any of them. The one exception is scratch builds: for those you must use the Koji task ID number. No substitutes, periodt. 💅

Want more on Koji build specification? Go read the Koji documentation, they got you.

---

If you hand it a directory tree containing the output of a properly structured Koji build, rpminspect can just use that directly. When is that the move? Say you're running rpminspect over and over against one specific previous build while you're trying to fix something in a new build compared against the old one. Obsessed, honestly. 🫶

Local and remote RPM packages can be specified directly too, if all you want is rpminspect on a single RPM. You can pass one RPM package, or two if you want rpminspect to do the comparison inspections. And if you give it a URL to an RPM as an input? It will try and download that package. ✨

Examples, bestie:

CFG=/usr/share/rpminspect/vendor.yaml

rpminspect -c $CFG -T ALL -k zlib-1.2.7-1.fc29 zlib-1.2.7-2.fc29

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

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

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

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

rpminspect -c $CFG -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 -c $CFG -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 -c $CFG /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. And inside the findings you get descriptions of actions developers can take. It's not just "here's a problem" — it's "here's a problem and here's what to do." Main character energy tbh. 👑

Heads up: the vendor data packages for rpminspect usually include a wrapper script of the form rpminspect-VENDOR, where VENDOR is typically fedora, centos, or redhat. If a wrapper script like this exists in the vendor data package, you should use it to invoke rpminspect with that vendor's configuration file. And here's the cute part: if you use the wrapper script, you do not need the -c option to specify the configuration file. 🎀

---

🏗️ CONSTRUCTING LOCAL BUILD INPUTS

So the most common use of rpminspect in continuous integration environments is to fetch and analyze builds directly from Koji. That is literally why rpminspect can speak to Koji directly and download files. 💅

But if you're running rpminspect locally, you can simulate inputs this way: construct a local directory that looks like a Koji build as rpminspect would download it. Slay.

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. 🌸

Next thing: create subdirectories in there for each architecture and the source RPM. And any noarch packages need to go in a noarch subdirectory. Don't forget her. 🦋

Let's do a real one. 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:

1. Create a directory named zlib-build.
2. Within that directory, create two new subdirectories called src and x86_64 (assuming you built on x86_64, bestie).
3. Put the source RPM in zlib-build/src/.
4. 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. Same energy, local edition. ✨

---

🚦 EXIT STATUS

• 0 — rpminspect exits 0 if all inspections pass. Ate. 💖
• 1 — exits 1 if at least one inspection did not pass. 😭
• 3 — exits 3 if the specified profile is not found.
• 2 — exits 2 if any other program error occurred.

---

🐛 BUGS

Please report bugs at https://github.com/rpminspect/rpminspect using the Issues tab. Don't be shy, they want to hear from you. 🙈

---

👀 SEE ALSO

• rpm(8)

---

👑 AUTHOR

David Cantrell <dcantrell@redhat.com>

---

And that's the whole page, bestie!! 🫶 This was rpminspect from way back in February 2019, living in section RPMINSPECT(1) of your friendly neighbourhood manual. Go build something iconic with it. 💅✨🌈