Packaging PBS Pro for Third Party Linux Repositories
This design document was written in accordance with the OpenPBS Design Document Guidelines.
Forum discussion is located here: http://community.pbspro.org/t/packaging-pbs-pro-for-third-party-linux-repositories/1345
Overview
Linux vendors (e.g. RedHat, SUSE, Ubuntu, etc.) maintain package repositories that provide access to many pre-built open source software packages. These repositories, together with package management tools (e.g. yum, zypper, apt-get, etc.) provide administrators with a convenient means of obtaining and installing software they wish to make available for their users. Now that PBS Professional is open source, it should be included in the Linux vendor repositories. This design is intended to identify changes that are necessary for PBS Pro to conform to packaging requirements of each Linux vendor. The scope of this document shall be limited to current versions of RedHat/CentOS and SUSE/OpenSUSE.
Glossary of Terms
| Term | Definition |
|---|---|
| FHS | Filesystem Hierarchy Standard - Describes the location to which files are to be installed under Linux. This is a component of the Linux Standard Base. |
| ISV | Independent Software Vendor - An entity that develops software and distributes it outside of a Linux vendor's toolchain. As per the Linux Standard Base, such software is to be installed under /opt |
| LSB | Linux Standard Base - See https://wiki.linuxfoundation.org/lsb/start |
| repo | A package repository supplied and maintained by a Linux vendor |
| RPM | RedHat Package Manager - A file format and packaging tools developed based upon the Linux Standard Base. Despite the name, RPM is used by both RedHat and SUSE. |
Technical Details
Each Linux vendor has their own requirements for packaging software. These requirements govern where files may be installed, who owns them, and various checks that must pass before the vendor will accept a package into their repository. PBS Pro must conform to the requirements from each vendor. The requirements for RedHat and OpenSUSE may be found here:
- RedHat: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/rpm_packaging_guide/index
- OpenSUSE: https://en.opensuse.org/openSUSE:Packaging_guidelines
Once PBS Pro is made to conform to these guidelines and requirements the changes must be maintained for future releases. This includes conforming to any new changes that are made to either document.
Producing Packages
Both RedHat and SUSE utilize the RPM package format and tools for packaging, distributing, and managing software components. Producing packages in RPM format involves the use of the rpmbuild command. The command takes a spec file, a tarball, and optional patches as input. The tarball is created by using GNU autotools to build PBS Pro on a Linux system. A detailed set of instructions to build and package PBS Pro under Linux may be found here: Building OpenPBS Using rpmbuild
File Locations
The FHS describes where the different files that make up PBS Pro should be installed. PBS Pro is currently built and installed as an ISV application using /opt/pbs as its default top level directory (a.k.a. prefix). ISV applications are typically installed under /opt while packages available through a Linux vendor repo are installed under the /usr directory. The GNU autotools and their vendor specific macros take much of the guesswork out of where a file should be installed provided it has been properly identified (e.g. shared library, executable, configuration file, etc.) within the Makefile.am files in the source code. The prefix directory may be defined by the packager when building PBS Pro by supplying the --prefix parameter to the configure script or adjusting the value of Prefix in the spec file.
Integrating PBS Pro into vendor repositories means that it will no longer be packaged as an ISV application. As a result, different rules in the FHS must be applied. Rather than using /opt/pbs as the prefix, it must be changed to /usr. This has the potential to cause problems with the operation of PBS Pro components that may mistakenly be hard coded to use /opt/pbs as the prefix. When this occurs, the files must be updated relative to the prefix used during packaging and installation.
Packaging Checks
The rpmlint command line utility performs a set of checks against an existing RPM package or development tree used to produce an RPM package. It identifies several potential packaging problems that should be resolved by the developer(s) responsible for packaging the product. While the majority of the warnings rpmlint produces are legitimate issues that should be addressed, some are overly pedantic and may simply be suppressed. By examining other packages provided in the RedHat and OpenSUSE repositories, we gain an understanding of which warnings each vendor will permit and which must be addressed. The PBS Pro GitHub repository contains a file named pbspro-rpmlintrc that may be adjusted to suppress the warnings that may be ignored. The table below describes the warnings and errors currently present in the pbspro-server RPM package. The warnings and errors were identified by running:
rpmlint pbspro-server-19.1.5-0.x86_64.rpm | grep -v 'specfiles checked' | awk '{print $2 $3}' | sort -u
The rpmlint command takes the --explain parameter with the warning/error type as an argument. This is helpful to determine how the existing behavior deviates from the standard.
| Name | Type | Description | Fix or Suppress |
|---|---|---|---|
| dangerous-command-in-%post | Warning | One of the following commands is present in the %post section: cp, mv, ln, tar, rpm, chmod, chown, rm, cpio, install, perl, userdel, groupdel | For Cray systems running IMPS (CLE 6 and beyond) the PBS Pro init script is installed from the %post section in the spec file because pbs_postinstall is not run. For other systems the pbs_postinstall script copies the /etc/init.d/pbs into place. The /etc/init.d/pbs script should be installed as part of the RPM package, no longer requiring pbs_postinstall or the spec file to copy it. |
| dangerous-command-in-%preun | Warning | One of the following commands is present in the %post section: cp, mv, ln, tar, rpm, chmod, chown, rm, cpio, install, perl, userdel, groupdel | Once the previous warning is addressed, it should no longer be necessary to remove /etc/init.d/pbs when uninstalling PBS. The modulefiles installed for Cray should remain as PBS_EXEC/etc/modulefile and the Cray install instructions edit to instruct the admin to copy the file manually if they choose. |
| devel-file-in-non-devel-package | Warning | Static libraries and header files should be part of a separate devel RPM | Create a new devel RPM and remove them from the RPMs we currently create. |
| dir-or-file-in-opt | Error | Packages for a Linux vendor repository should not install files under /opt | PBS Pro is currently packaged as an ISV application. The warning should be suppressed in this case. When packaging for Linux vedor repositories, a different prefix will be used and this error should disappear. |
| explicit-lib-dependency | Error | RPM manage librariy dependencies internally and does not need them listed as a Requires: line in the spec file | Remove libedit and libical Requires: lines from spec file |
| manpage-not-compressed | Warning | Online man pages should be compressed | The tool /usr/lib/rpm/redhat/brp-compress is responsible for compressing online man pages as part of the build and package. The tool does not take the prefix into account when it is run and does not look for man pages under /opt. Commands must be added in the %install section to simulate this behavior. When packing for Linux vendor repositories, brp-compress will work as expected. The following code should be added after %make_install in pbspro.spec.in and pbspro.spec: mandir=$(find %{buildroot} -type d -name man) |
| no-changelogname-tag | Error | The must be a %changelog section in the spec file | The %changelog section in the spec file normally appears at the very end. It is not intended to capture all changes to PBS Pro, but only changes the spec file itself. None of the spec files in OpenHPC (and there are several) have a %changelog section. In fact, the TravisCI script they use prohibits one from being present. The %changelog section should resemble the following, listing the changes in descending order (from the most recent one first), and also choosing an arbitrary <revision number> for example, "1.1": %changelog |
| no-documentation | Warning | The package must contain documentation. | The README and LICENSE files should be packaged at the minimum. The man pages should also be tagged with %doc. The %files section for each package should be updated accordingly. An administrator may use the --excludedocs flag to prevent installation of the online man pages. The following lines will need to be added for each package: %dir %{pbs_prefix}/share/doc/%{name} |
| non-conffile-in-etc | Warning | Files to be installed in /etc must be designated as configuration files. | Tag files in /etc/profile.d in the %files section of the spec file for each RPM as follows: %config(noreplace) %{_sysconfdir}/profile.d/* |
| non-executable-script | Error | All files containing a shebang as the first line should have their executable bit set. | Add the executable bit to affected files. There are several instances this, but they are limited to files in the src/cmds/scripts directory. |
| non-standard-executable-perm | Error | Any executable having permissions other than 0755. | This affects pbs_iff and pbs_rcp, which must be installed as SUID (04755). Suppress this message. |
| non-standard-group | Warning | There are a well defined set of groups that each package must belong to. Use "rpmlint --explain non-standard-group" to display these. | The group for PBS Pro is currently defined as "System/Base", but should be changed to "System Environment/Base". |
| only-non-binary-in-usr-lib | Warning | Non-binary files belong in directories under %{pbs_prefix}/share, and only binary files belong in the lib directory. | This warning is different from others because it does not mention specific files that break this rule. Suggestion is to move anything that is not a library file under %{pbs_prefix}/share/pbs. When /usr is the prefix, this will need to be something like /usr/share/pbs/ rather than /opt/pbs/lib. It would also be a good idea to rename all of the archive libraries to include a pbs component (e.g. libnet.a → libpbsnet.a). |
| postin-without-ldconfig | Error | Package contains a library and its %post scriptlet doesn't call ldconfig. | The ldconfig command must be called from the %post section to create the necessary symbolic links for shared libraries. The following command should be sufficient: ldconfig %{_libdir} |
| postun-without-ldconfig | Error | Package contains a library and its %postun doesn't call ldconfig. | The ldconfig command must be called from the %postun section to create the necessary symbolic links for shared libraries. The following command should be sufficient: ldconfig %{_libdir} |
| script-without-shebang | Error | This text file has executable bits set or is located in a path dedicated for executables, but lacks a shebang and cannot thus be executed. If the file is meant to be an executable script, add the shebang, otherwise remove the executable bits or move the file elsewhere. | The only file this affects is /opt/pbs/lib/libpbs.la which is generated by libtool. Upon examining the contents of /usr/lib64 on a CentOS system, there were several .la files with the executable bit set. It should be sufficient to suppress this message. |
| setuid-binary | Error | The file is setuid; this may be dangerous, especially if this file is setuid root. Sometimes file capabilities can be used instead of setuid bits. | This should be suppressed along with non-standard-executable-perm. |
| shared-lib-calls-exit | Warning | This library package calls exit() or _exit(), probably in a non-fork() context. Doing so from a library is strongly discouraged - when a library function calls exit(), it prevents the calling program from handling the error, reporting it to the user, closing files properly, and cleaning up any state that the program has. It is preferred for the library to return an actual error code and let the calling program decide how to handle the situation. | All calls to exit() or _exit() must be removed from libpbs.so |
Development Package
There are files contained in the pbspro-server and pbspro-execution RPMs that belong in a development RPM. The RPM itself should be named pbspro-devel-*.rpm, where the asterisk represents the version and release portion of the file name. The following files should be moved into this RPM:
- %{prefix}/lib/*.a
- %{prefix}/include/*
Project Documentation Main Page