How to Build and Install Custom RPMs on Red-Hat Systems

Overview

WebPros International, LLC distributes many of cPanel & WHM’s third-party dependencies as RPMs. To customize these dependencies on your Red-Hat®-based system, you must custom-build the RPM and then reinstall it. For instance, this method is used to build and install Roundcube customizations.

Note:

• RPMs are compatible with Red-Hat systems only. Refer to our System Requirements for information on supported Red-Hat systems.
• You must log in via SSH as the root user to install an RPM.

Before You Begin

Perform the following steps to ensure your system is ready to build and install an RPM:

1. Install the rpm-build package.

   Use the following command to install the rpm-build package on your system:

   yum install rpm-build

2. Enable the devel target for cPanel & WHM.

   Run the update_local_rpm_versions and check_cpanel_pkgs scripts before installing a custom RPM. These scripts ensure that the devel target is enabled and up-to-date. The devel target installs the development versions of RPMs, which cPanel & WHM utilizes for compiling SRPMs locally.

   To do this, execute the following commands:

   	Command
   1	/scripts/update_local_rpm_versions --edit target_settings.cpanel-devel installed
   2	/scripts/check_cpanel_pkgs --targets cpanel-devel --fix

   Note: To rebuild some cPanel-provided RPMs, you might need to install additional RPMs that cPanel & WHM does not include in default installations. These additional RPMs contain files that the system only needs for rebuilding, not for running, the cPanel-provided RPMs.

3. Install additional prerequisites.

   Before you can build and install a custom-built RPM, you must install all of its prerequisites. You can find all of an RPM’s prerequisites, along with required version numbers, in its .spec file.

   • Lines in the .spec file beginning with BuildRequires: indicate a prerequisite required for the RPM's build process.
   • Lines in the .spec file beginning with Requires: indicate a prerequisite necessary for the RPM's installation.

   For example, BuildRequires: cpanel-mysql >= 8.0.20 indicates that the RPM requires the cpanel-mysql RPM of MySQL® version 8.0.20 or higher.

4. Ensure that all necessary RPMs are installed.

   Run the /scripts/sysup script to confirm that all prerequisite RPMs are installed.

   • If all these RPMs are present on your server, you will receive the message: All Needed RPMS are installed.
   • If you encounter an error message, resolve those installation problems first to prevent additional errors when building and installing your custom RPM.

Build and Install Custom RPMs

Perform the following steps to build and install Roundcube customizations in cPanel & WHM version 58 and later:

1. Create the .rpmmacros file.

   Use your preferred text editor to create the .rpmmacros file in the /root/ directory.

   Add the following contents to the file:

   	Content
   1	%_topdir /root/rpmbuild
   2	# enable debug RPM package by commenting this out.
   3	%debug_package %{nil}

2. Create the directories to rebuild the RPM.

   If not already present on your server, create the following directories:

   • /root/rpmbuild/BUILD
   • /root/rpmbuild/SPECS
   • /root/rpmbuild/SOURCES
   • /root/rpmbuild/BUILDROOT
   • /root/rpmbuild/RPMS
   • /root/rpmbuild/SRPMS

   Run the following command to create these directories:

   mkdir -p /root/rpmbuild/BUILD /root/rpmbuild/SPECS /root/rpmbuild/SOURCES /root/rpmbuild/BUILDROOT /root/rpmbuild/RPMS /root/rpmbuild/SRPMS

   Important: You must use these exact names for the BUILD, SPECS, SOURCES, BUILDROOT, RPMS, and SRPMS directories. The entire name for each of these directories must be capitalized.

3. Install the source RPM.

   Use the rpm command to install the source RPM (SRPM).

   • The .spec file will be installed to the /root/rpmbuild/SPECS/ directory.
   • The source tarball, patches, and any additional files for the RPM will be installed to the /root/rpmbuild/SOURCES/ directory.

   Note: You can find the correct SRPM for your version of cPanel & WHM on our httpupdate server. Click your server’s version of cPanel & WHM, and then click the src/ directory to view a list of all available SRPMs for that version.

   Your command will resemble the following example:

   rpm -Uvh http://httpupdate.cpanel.net/RPM/11.42/src/cpanel-php54-5.4.23-4.cp1142.src.rpm

   When the installation completes, you will see a message similar to the following example:

   Retrieving http://httpupdate.cpanel.net/RPM/11.42/src/cpanel-php54-5.4.23-4.cp1142.src.rpm 1:cpanel-php54 ########################################### [100%]

4. Edit the .spec file.

   Use your preferred text editor to modify the .spec file located in the /root/rpmbuild/SPECS/ directory. Add the desired configuration settings for your RPM.

   Note: To change any of the sources that ship with the SRPM, modify the files in the /root/rpmbuild/SOURCES/ directory.

   The following example section of a .spec file includes the SOAP protocol:

   %configure --prefix=%{_prefix} \
   --with-libdir=%{_lib} \
   --verbose \
   --enable-static \
   --with-mcrypt=%{_3rdparty_prefix} \
   --with-iconv --enable-mbstring \
   --with-gd \
   --enable-soap \
   --enable-mbregex \
   --with-imap-ssl --with-imap=%{_3rdparty_libdir}/imap/

5. Rebuild the RPM.

   Run the rpmbuild command on the modified .spec file to build the new RPM locally. Your command should resemble the following example:

   rpmbuild -bb /root/rpmbuild/SPECS/php.spec

   The rpmbuild tool writes the RPM and any subpackages to the /root/rpmbuild/RPMS/ directory.

   Note: The system may report dependency issues when you run this command. If so, install these dependencies using yum before you proceed.

6. Update your RPM with the --force option.

   Navigate to the /root/rpmbuild/RPMS/ directory and execute the rpm command to install your new custom-built RPM.

   Your command will resemble the following example, where cpanel-php54-5.4.23-4.cp1142.x86_64.rpm represents the RPM you wish to update:

   rpm -Uvh cpanel-php54-5.4.23-4.cp1142.x86_64.rpm --force

7. Prevent unintentional updates.

   Warning: This step is optional and may freeze updates to this RPM, potentially preventing future cPanel & WHM upgrades. However, if this step is not performed, cPanel & WHM may overwrite your custom RPM during its next update or upgrade.

   To prevent unintentional updates, add your custom RPM to the list of local RPMs using the /scripts/update_local_rpm_versions script. Your command will resemble the following example:

   /scripts/update_local_rpm_versions --add srpm_versions.cpanel-php54 5.4.23-4.cp1142

   To verify your custom RPM’s configuration, view the /var/cpanel/rpm.versions.d/local.versions file.

   The contents of the local.versions file should resemble the following example:

   ---
   file_format:
     version: 2
   srpm_versions:
     cpanel-php54: 5.4.23-4.cp1142

Return to the cPanel & WHM Version of an RPM

Perform the following steps if you wish to revert to the cPanel & WHM version of an RPM:

1. Run the following command to remove the custom RPM from the local.versions file:

   /scripts/update_local_rpm_versions --del srpm_versions.cpanel-php54

2. Run the following script to reinstall the cPanel & WHM version of the RPM:

   /scripts/check_cpanel_pkgs

Additional Documentation

• Install Distro Packages
• Rebuild RPM Database
• System Update
• The check_cpanel_pkgs Script
• The find_and_fix_rpm_issues-script
• The cPanel Glossary