Skip to content
RPM build deviation analysis tools
C Python Shell Meson Roff C++ Makefile
Branch: master
Clone or download
Latest commit 01ade0b Oct 17, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.copr Adjust .copr/Makefile so it can make release SRPM files Oct 8, 2019
contrib Add contrib report-json2html.py Sep 19, 2019
data Remove most autotools files. Sep 10, 2019
doc Add logo PNG to docs/ directory. Oct 7, 2019
lib s can be NULL when strreplace() is called, it's just a no-op Oct 17, 2019
src
tests Stubbed out test_manpage.py test cases. Oct 17, 2019
utils Drop the GITHASH and GITDATE work from utils/release.sh Oct 8, 2019
.travis.yml *sigh* Sep 23, 2019
AUTHORS Update AUTHORS file Oct 11, 2019
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Aug 30, 2019
COPYING Add COPYING file with GPLv3 in it. Mar 22, 2019
Dockerfile.test Convert spec dependencies to package names. Oct 17, 2019
README Update the README Oct 8, 2019
TODO
meson.build New release (0.8) Oct 17, 2019
meson_options.txt Support -Dtests=false as a way to skip the test suite. Sep 25, 2019
rpminspect.spec.in Convert spec dependencies to package names. Oct 17, 2019

README

==========
rpminspect
==========

RPM build deviation analysis tools.  rpminspect looks at the output of an
RPM build (e.g., the output of a Koji build) and examines the contents of
the build artifacts to report:

    * Policy compliance
    * Changes from a previous build to the current build
    * General correctness and best practices

rpminspect is the frontend tool and librpminspect provides the inspection
engine and individual inspections.  The program is configured through the
rpminspect.conf file and runtime data is provided by a vendor specific
rpminspect-data package.  The rpminspect-data-generic package in this source
tree provides a template for constructing the vendor specific data package.


Build Types Support
-------------------

rpminspect expects its input to either be local RPM packages or a Koji
build.  Koji produces certain types of builds that are not supported by
rpminspect.  Right now, the following input types are supported:

    * Local RPM packages (source or binary)
    * Koji builds (i.e., an SRPM run with 'rpmbuild -ba' on all specified
                   architectures)
    * Modules (https://docs.fedoraproject.org/en-US/modularity/)

More information on Koji can be found at https://pagure.io/koji

If comparing local RPM packages, rpminspect assumes the before and after
specifications are peers whereas for a Koji build, rpminspect will figure
out peers (e.g., in the gcc package, gcc-gfortran in the before build is
peered with gcc-gfortran in the after build).


Intended Audience
-----------------

Developers, QE, release engineers, and system administrators who regularly
build RPMs for use in some environment or product.

From an individual user standpoint, rpminspect is intended to be a command
line tool you can use as a linter of sorts.  rpminspect reports and that's
it.  rpminspect can output information in JSON format which is intended to
make it easier to integrate in to automated workflows or web frontends.

The reporting uses certain classifications for different things found, but
it up to the end user to determine what to do with that information.  If
rpminspect is integrated in to a build tool, the JSON data may be more
useful as you can construct decision making around those results.


Build Requirements
------------------

A typical Linux system with a toolchain for building C software using
meson and ninja, plus the following libraries (make sure the header files
are available):

    * json-c
          http://json-c.github.io/json-c/

    * xmlrpc-c
          http://xmlrpc-c.sourceforge.net/

    * libxml-2.0
          http://xmlsoft.org/

    * rpm
          https://github.com/rpm-software-management/rpm

    * libarchive
          https://www.libarchive.org/

    * elfutils
          https://sourceware.org/elfutils/

    * kmod
          https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git

    * zlib
          https://www.zlib.net/

    * mandoc (formerly mdocml)
          https://mandoc.bsd.lv/

    * iniparser
          http://ndevilla.free.fr/iniparser/

    * libyaml
          https://github.com/yaml/libyaml

    * file (for libmagic)
          http://www.darwinsys.com/file/

    * OpenSSL or LibreSSL
          https://www.openssl.org/
          http://www.libressl.org/

    * libcap-ng
          https://github.com/stevegrubb/libcap-ng

Additionally, the follow packages are required for running the unit tests:

    * CUnit (including headers)
          http://cunit.sourceforge.net/

Most distributions include the above projects in prebuilt and packaged
form.  If those are available, you should use those packages.

In Fedora for example, you can run the following to install the required
packages:

    dnf install json-c-devel xmlrpc-c-devel libxml2-devel rpm-devel \
                libarchive-devel elfutils-devel kmod-devel zlib-devel \
                libmandoc-devel iniparser-devel libyaml-devel file-devel \
                openssl-devel libcap-ng-devel meson ninja-build CUnit CUnit-devel \
                gcc


Runtime Requirements
--------------------

In addition to the libraries that will be linked in to librpminspect, there
are a number of userspace programs required:

    /usr/bin/desktop-file-validate
    /usr/bin/zcmp
    /usr/bin/bzcmp
    /usr/bin/xzcmp
    /usr/bin/eu-elfcmp
    /usr/bin/msgunfmt
    /usr/bin/diff

The provided spec file template uses the Fedora locations for these files,
but in the program they are assumed to be in PATH at runtime.  These tools
are used by different inspections at runtime. Most distributions include the
above tools. If they are available, you should use those packages.

In Fedora for example, you can run the following to install these programs:

    dnf install desktop-file-utils gzip bzip2 xz elfutils gettext diffutils

The 'shellsyntax' inspection uses the actual shell programs listed in the
shells setting in the rpminspect.conf.  Since this can vary by system, you
should make sure the are available in the system PATH.  Or you can just not
use the shellsyntax inspection.  The spec file for rpminspect includes weak
dependencies on the default list of shells.


Building
--------

If you got the source from a released tarball or from cloned from git, you
can do this:

    meson setup build
    ninja -C build

For more information on meson and ninja, see these sites:

    https://mesonbuild.com/
    https://ninja-build.org/


Releasing
---------

Releases are made using the release.sh script:

    ./utils/release.sh -b -t -p -g

This will increment the x.y version number, create a new tarball, sign it,
and create a signed git tag.  All of that is pushed to github and then a
release entry is made and the tarball and detached signature are uploaded
there.

You can run the release.sh script directly and it will generate a release
tarball from the source you have.  The command line options enable the
version incrementing, git commits, tags, and pushes.

The release will generate tar.xz file, a detached GPG signature of the
tar.xz file, and a SRPM.  The SRPM file is suitable for import in to
Fedora's dist-git and systems similar to it.


How To Use
----------

SETUP

Make sure you have installed the program and corresponding data file
collection.  On Fedora, this can be done using dnf:

    dnf install rpminspect rpminspect-data-fedora

The first package is the actual program.  The rpminspect-data-fedora package
delivers data files used by the various inspections performed by rpminspect.
It also delivers the rpminspect.conf configuration file.  Have a look at
this file and make sure it will work for your environment.  The idea is to
easily support per-vendor data packages.  For example, if CentOS needs
different settings, it should provide an rpminspect-data-centos package.

Ideally the configuration file should not need changing.  If you do find
mistakes, please file an issue or send a pull request to the project:

    https://github.com/rpminspect/rpminspect-data-fedora

The aim should be the vendor-specific data packages providing everything a
developer needs to successfully run rpminspect locally for that product.

USAGE

rpminspect is run from the command line.  The inputs must be local RPM
packages, a Koji build specification (NVR), a Koji module specification, or
a locally cached Koji build output (regular build or module).  For inputs
originating from Koji, rpminspect will talk to Koji and download the build
artifacts.  For repeated runs, you may want to cache a remote build locally
to avoid downloading it with each run.

Here is a simple invocation using tmux as an example:

    $ rpminspect -v tmux-2.9a-2.fc31 tmux-2.9a-3.fc31

This just runs with verbose mode enabled and compares tmux-2.9a-2.fc31 to
tmux-2.9a-3.fc31.  rpminspect will download the packages for these builds
and run the inspections.

If you want to keep temporary files created during the run, pass -k.
rpminspect will tell you where those files after it finishes.

You can list available inspections with the -l option:

    $ rpminspect -l

Say you only want to run the license inspection on the builds above:

    $ rpminspect -v -k -T license tmux-2.9a-2.fc31 tmux-2.9a-3.fc31

Now let's say you want to run the license and manpage inspections:

    $ rpminspect -v -k -T license,manpage tmux-2.9a-2.fc31 tmux-2.9a-3.fc31

And lastly, what if you want to run *all* inspections except the license
one:

    $ rpminspect -v -k -E license tmux-2.9a-2.fc31 tmux-2.9a-3.fc31

What about specify a locally cached build?  First, let's start by caching
the builds we have been using:

    $ mkdir ~/builds
    $ rpminspect -v -w ~/builds -f tmux-2.9a-2.fc31
    $ rpminspect -v -w ~/builds -f tmux-2.9a-3.fc31

Now let's run all the inspections but specify the locally cached builds:

    $ rpminspect -v ~/builds/tmux-2.9a-2.fc31 ~/builds/tmux-2.9a-3.fc31

Easy.  Again, these locally cached builds must look like what rpminspect
would download from koji.  Hence using rpminspect to first download it.

rpminspect can also run inspections on local RPM packages.  Similar to Koji
inputs, you may specify a single RPM or two RPMs to compare.  For example:

    $ rpminspect -v ~/rpmbuild/RPMS/x86_64/tmux-2.9a-2.fc31.x86_64.rpm

Or:

    $ cd ~/rpmbuild/RPMS/x86_64
    $ rpminspect -v tmux-2.9a-2.fc31.x86_64.rpm tmux-2.9a-3.fc31.x86_64.rpm

All of the other command line options that apply to Koji tests work for
local RPM packages.

For more information, see the man page for rpminspect(1).  And see the
--help output for information on command line option syntax.


Contributing
------------

Patches are welcome as are bug reports.  There are a lot to do in this
project.  Some things to keep in mind:

    * Please follow existing coding style in files you modify.  Things like
      variable and function naming, spacing, and indentation.  I want to
      avoid wildly varying coding styles throughout the tree.

    * New inspections in librpminspect need to be in the form of an
      inspect_NAME.c file with a driver added to the main struct.  You may
      add static and non-static support functions to your inspect_NAME.c file
      and expose those as part of the librpminspect API.  If the support
      functions are generic enough, feel free to start a new source file.

    * Test cases or updates to existing test cases need to accompany patches
      and new code submissions.

    * Use the standard C library whenever possible.  Code using glib,
      libbsd, or any other type of generic utility library is going to be
      reviewed and likely rejected until it is modified to use the standard C
      library.

    * That said, inspections are expected to make use of available libraries
      for performing their work.  When given the option between a library
      and forking an execing a program, please use the library.  This is not
      always possible, but in many cases it is.

    * Alternative libraries intended to replace a build requirement are ok
      so long as configure.ac and the corresponding Makefile.am templates
      are modified to conditionalize everything.  For example, if there is
      a compatible but different json-c library, it's ok to add configure
      options that would be something like:

          --disable-json-c --enable-other-json-c

      If this requires modification in the code, try to minimize the use
      of cpp macros.

    * See the TODO file for a current list of things that need work.


Licensing and Copyright
-----------------------

The project is licensed under the GNU General Public License version 3 or,
at your option, any later version.  A number of contributions have been
under the Apache License 2.0 and GPLv3+ allows for that.

Copyright statements are in the boilerplates of each source file.
You can’t perform that action at this time.