1RPMINSPECT(1) Red Hat RPMINSPECT(1)
3
7 rpminspect - compare package builds
8
10 rpminspect -c FILE [ OPTIONS ] before_build [ after_build ]
11
13 rpminspect is a tool designed to help developers maintain build policy
14 compliance and consistency among releases. The tool has two primary
15 modes of operation. The first is what can be considered an analysis
16 mode. This runs against a single RPM or Koji build (a build being a
17 source RPM and all of its built packages for multiple architectures).
18 The analysis mode checks for package consistency and compliance. Vari‐
19 ous inspections can be configured via the configuration file, profile
20 in use, or local rpminspect.yaml file. The other mode is build compar‐
21 ison. This mode performs all of the same inspections as analysis mode
22 as well as comparisons between a before and after package or build.
23 There is no explicit option to run rpminspect in either mode; the mode
24 of operation is determined by specifying either one or two inputs. One
25 input means analysis mode, two inputs means comparison mode.
26 rpminspect originated at Red Hat as an auditing tool used to ensure
28 builds complied with certain release rules and policies. Over time it
29 grew to incorporate other checks, such as making sure debugging symbols
30 are accurate and various security policies were followed. Users are
31 encouraged to contribute tests for new functionality, report bugs, and
32 submit updates to the rules in the corresponding vendor data pack‐
33 age(s).
34 The software is made available as this command line program and an ac‐
36 companying library. This is intentional. Our findings over time have
37 shown that simple tools with a flexible design are more easy to inte‐
38 grate in to continuous integration systems. The library allows devel‐
39 opment of other frontends or integration in to existing frontends. The
40 thought is that most developers will interact with rpminspect through
41 the command line and most integrations of rpminspect will report re‐
42 sults through some sort of existing frontend (e.g., GitHub Actions).
43 Everything about an rpminspect run is configurable at runtime through
44 command line options as well as a configuration file. The command line
45 options override the configuration file which overrides the compiled in
46 defaults.
47
49 -c FILE, --config=FILE
50 Configuration file. This is the only required option. The con‐
51 figuration file is generally provided by a product vendor in the
52 form of /usr/share/rpminspect/VENDOR.yaml. Wrapper scripts are
53 common to prevent the need to specify the configuration file on
54 the command line (e.g., rpminspect-fedora runs rpminspect with
55 the fedora.yaml configuration file).
56 -p NAME, --profile=NAME
58 Optional configuration profile to use. A configuration profile
59 provides overrides to the main configuration file. The idea is
60 the main configuration is loaded, then if you specify a profile
61 name rpminspect will load that configuration file and any values
62 specified will override what came from the default configuration
63 file. Think of the main configuration file as the common one
64 and profile configuration files are optional overlays. In the
65 data package, profiles should be of the form PROFILENAME.yaml
66 and exist in the 'profiledir' subdirectory. If you specify a
67 PROFILENAME to this option, rpminspect will search for the pro‐
68 file in 'profiledir'. You can also pass a PATH to this option
69 and rpminspect will attempt to load the profile from that file.
70 It is common for vendors to provide a set of profiles in addi‐
71 tion to a main configuration file.
72 The format of a profile configuration file is the same as the
74 configuration file, just call it NAME.yaml and place it in the
75 'profiledir' for the appropriate vendor. For example, the pro‐
76 file 'scl' for Fedora should have a configuration file named
77 /usr/share/rpminspect/profiles/fedora/scl.yaml.
78 -T LIST, --tests=LIST
80 If specified, this option assumes all inspections are disabled
81 except the names of the ones you specify with this option.
82 Specify a comma-separated list of inspections to run (default:
83 ALL). The names of available inspections can be found with the
84 -l option. You can also specify the name ALL to explicitly say
85 run all inspections. NOTE: This option is mutually exclusive
86 with the -E option.
87 -E LIST, --exclude=LIST
89 If specified, this option assumes all inspections are enabled
90 except the names of the ones you specify with this option.
91 Specify a comma-separated list of inspections to skip (default:
92 none). The names of available inspections can be found with the
93 -l option. You can also specify the name ALL to explicitly say
94 skip all inspections, though that makes the program do nothing.
95 NOTE: This option is mutually exclusive with the -T option.
96 -a LIST, --arches=LIST
98 Comma-separated list of architectures to inspect packages on.
99 By default rpminspect will gather all available architectures
100 for the builds you specify, but you may want to restrict a run
101 to just x86_64 or just aarch64. You can do that with this op‐
102 tion. If you do specify this option, be sure to include the
103 'src' architecture to inspect source packages and 'noarch' to
104 include noarch packages. The architectures you list here are
105 validated against the available architectures in the Koji hub
106 and any invalid ones will report an error.
107 For the purposes of RPM packaging and rpminspect, both 'noarch'
109 and 'src' are considered architectures. Please keep that in
110 mind when using this option.
111 -r STR, --release=STR
113 String identifying the product release for the specified build
114 or builds. Normally rpminspect will determine this by looking
115 for a "dist tag" at the end of the NVR. For build comparisons,
116 the determined product releases must match in order for rpmin‐
117 spect to continue. If you want to compare builds from different
118 products, you will need to specify a product release manually.
119 You will also need to specify the product release if the builds
120 you are comparing lack any kind of product release identifier at
121 the end of the NVR.
122 rpminspect can be configured to favor the newest or oldest prod‐
124 uct release string in case they do not match. This may be use‐
125 ful when comparing builds from one product release to another.
126 -n, --no-rebase
128 Disable rebased build detection. When comparing two builds or
129 two packages, rpminspect will look at the package names, version
130 numbers, and release numbers. If the names and versions match
131 but the releases vary, the package is not considered a rebase
132 because the assumption is this is a maintenance type build on an
133 existing package. Non-rebase comparisons enforce more strict
134 rules for certain inspections. If the package names match but
135 the version numbers differ, rpminspect considers the comparison
136 to be between rebased builds. Rebased comparisons relax those
137 strict rules in order to eliminate a lot of false positives in
138 the output. If you want to always disable the rebase checking
139 and enforce the strict rules, you can pass this option.
140 -b TYPE, --build-type=TYPE
142 Set the Koji build type to TYPE. By default, rpminspect will
143 try to automatically determine the build type of the inputs. In
144 some cases you may want to explicitly set the type if it is hav‐
145 ing trouble determining the build type. This option is most
146 useful when using locally provided Koji input subdirectories.
147 Supported build types can be seen with the -l option.
148 -o FILE, --output=FILE
150 Write the results to the name output file. By default, results
151 go to stdout.
152 -F TYPE, --format=TYPE
154 Write the inspection results in the TYPE format. The default
155 format is text. Available formats can be seen with the -l op‐
156 tion.
157 -t TAG, --threshold=TAG
159 Result threshold that triggers a non-zero exit code. By default
160 this is VERIFY, which maps to a result code seen in the output.
161 You can set this to any of the valid result codes. Available
162 result codes are OK, INFO, VERIFY, or BAD. The argument expects
163 the result threshold specified as a string. Case does not mat‐
164 ter.
165 -s TAG, --suppress=TAG
167 Results suppression threshold. By default all results are re‐
168 ported, but you can use this option to suppress results below a
169 reporting level. The values are the same as for the -t option
170 above. For example, to only show VERIFY and higher results,
171 pass "-s VERIFY" at run time.
172 -l, --list
174 List available output formats and inspections
175 -w PATH, --workdir=PATH
177 Temporary working directory to use (default: /var/tmp/rpmin‐
178 spect). You can specify a tilde (~) character in the PATH spec‐
179 ification and rpminspect will expand it. Keep in mind that the
180 PATH you specify with ~ must exist in order for expansion to
181 work.
182 -f, --fetch-only
184 Only download files in specified builds, do not perform any in‐
185 spections (implies -k). This option is intended as a conve‐
186 nience for developers as well as for easier integration in to
187 different CI workflows. Note that this option does not change
188 the working directory (-w) to the current working directory. If
189 this is undesirable, use the -w option to set it to a different
190 location. For example, to download to the current working di‐
191 rectory you can pass "-w $(pwd)".
192 You may specify one or more builds when using the fetch only mode.
194 -k, --keep
196 Do not remove temporary working files before exit. Useful at
197 times for debugging.
198 -d, --debug
200 Enable debugging mode. This mode generates additional output on
201 stdout and stderr.
202 -D, --dump-config
204 Dump configuration settings in use in YAML format. The output
205 of this option will be the combined settings after reading the
206 configuration file, any profile specified, and any local config‐
207 uration file. Useful for debugging to ensure settings have been
208 read in correctly.
209 -v, --verbose
211 Verbose inspection output. By default, only warnings or fail‐
212 ures are reported. This option also displays informational
213 findings. Use this mode with -l to display long descriptions of
214 output formats and inspections.
215 -?, --help
217 Display usage information.
218 -V, --version
220 Display version information.
221
223 rpminspect requires very little to run. Assuming you meet the runtime
224 requirements to either build the software from source or you have in‐
225 stalled it on your operating system, you are ready to use it. The only
226 required arguments are the '-c' option to specify the configuration
227 file and at least one input. The input may be an RPM package (local or
228 remote), a Koji build (either local or remote), or a Koji task ID.
229 When provided with a single input, rpminspect runs in analysis mode.
230 When two inputs are provided, it performs all of the analysis checks as
231 well as comparison checks.
232 Use the -l option to list available inspections (add -v to get detailed
234 descriptions of the inspections). By default, all inspections will be
235 run. You can restrict the program to a subset of inspections by list‐
236 ing their short names and separating them with commas (no spaces). Or
237 you can list inspections to skip by listing the short name prefixed
238 with a `!' in the same comma-delimited list.
239
241 rpminspect uses the term 'build' to refer to inputs. Builds may be lo‐
242 cal RPM packages, regular Koji builds specified using Koji syntax (the
243 NVR or name, version, and release of a package with hyphens separating
244 each part), Koji module builds, locally cached Koji builds (regular or
245 module), Koji scratch builds (task ID number), or locally cached Koji
246 scratch builds. Any valid Koji build identifier works when specifying
247 Koji builds, such as the build ID number or the package NVR. The only
248 exception to this rule is scratch builds. You must use the Koji task
249 ID number for scratch builds. For more information on Koji build spec‐
250 ification, please see the Koji documentation.
251 If you specify a directory tree containing the output of a properly
253 structured Koji build, rpminspect can use that directly. This may be
254 useful for multiple runs of rpminspect against a specific previous
255 build where you are trying to fix something in a new build compared
256 against the old one.
257 Local and remote RPM packages may be specified directly too if you just
259 want to use rpminspect on a single RPM. You may specify a single RPM
260 package or two if you want rpminspect to perform the comparison inspec‐
261 tions. A URL to an RPM specified as an input causes rpminspect to try
262 and download that package.
263 Examples:
265 rpminspect -T ALL -k zlib-1.2.7-1.fc29 zlib-1.2.7-2.fc29
267 rpminspect -T license,elfsyms perl-5.28.0-47.fc6
269 perl-5.28.1-1.fc6
270 rpminspect -T !manpage x3270-3.6ga5-6.fc31 x3270-3.6ga6-1.fc31
272 rpminspect -T ALL -a ppc64le zsh-5.7.1-3.fc31 zsh-5.7.1-4.fc31
274 rpminspect -E disttag -a ppc64le zsh-5.7.1-3.fc31
276 zsh-5.7.1-4.fc31
277 rpminspect -T ALL https://dl.fedoraproject.org/pub/fe‐
279 dora/linux/releases/36/Everything/x86_64/os/Pack‐
280 ages/l/less-590-3.fc36.x86_64.rpm
281 rpminspect -T ALL /home/developer/rpm‐
283 build/RPMS/less-590-3.fc36.x86_64.rpm /home/developer/rpm‐
284 build/RPMS/less-590-4.fc36.x86_64.rpm
285 rpminspect /home/developer/rpm‐
287 build/SRPMS/less-590-4.fc36.src.rpm
288 The end result of running rpminspect is a report on standard output ex‐
290 plaining what was found. Descriptions of actions developers can take
291 are provided in the findings.
292
294 The most common use of rpminspect in continuous integration environ‐
295 ments is to fetch and analyze builds directly from Koji. That is why
296 rpminspect can speak to Koji directly and download files. If you are
297 running rpminspect locally, you can simulate inputs this way by con‐
298 structing a local directory that looks like a Koji build as rpminspect
299 would download it. Start by creating a subdirectory. It can be called
300 anything, but the convention rpminspect follows is to name the subdi‐
301 rectory after the Koji build specification in NVR syntax. For example,
302 less-590-3.fc36 would be the subdirectory name. The next thing to do
303 is create subdirectories in there for each architecture and the source
304 RPM. Any 'noarch' packages need to go in a noarch subdirectory.
305 As an example, let's consider a source RPM that you rebuild locally.
307 Take zlib-1.2.12-5.fc37.src.rpm as the example. You rebuild this lo‐
308 cally using either rpmbuild or mock and it generates all of the sub‐
309 packages from the source RPM. To construct a build input directory for
310 rpminspect, you would create a directory named 'zlib-build'. Within
311 that directory, create two new subdirectories called 'src' and 'x86_64'
312 (assuming you built on x86_64. Put the source RPM in 'zlib-build/src/'
313 and put all of the x86_64 binary RPMs in 'zlib-build/x86_64/'. You may
314 now use 'zlib-build' as an input for rpminspect and it will treat it
315 the same way it treats Koji builds.
316
318 rpminspect exits 0 if all inspections pass, 1 if at least one inspec‐
319 tion did not pass. rpminspect exits 3 if the specified profile is not
320 found, and 2 if any other program error occurred.
321
323 Please report bugs at https://github.com/rpminspect/rpminspect using
324 the Issues tab.
325
327 rpm(8)
328
330 David Cantrell <dcantrell@redhat.com>
331rpminspect February 2019 RPMINSPECT(1)