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

1. Introduction

cPanel & WHM ships many third‑party dependencies as RPMs. To customize these packages on Red‑Hat–based systems, you must rebuild the RPM and reinstall it. This method is commonly used for customizing applications such as Roundcube.

Note: RPMs work only on Red‑Hat systems. You must log in via SSH as root to install RPMs.

2. Before You Begin

2.1 Install the `rpm-build` Package

Run the following command:

yum install rpm-build

2.2 Enable the cPanel Development Target

Run these scripts to enable and update the cpanel-devel target:

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

Some cPanel‑provided RPMs require additional packages not included by default. These must be installed before rebuilding.

2.3 Install All Prerequisites

Check the RPM’s .spec file:

BuildRequires: — packages needed for building
Requires: — packages needed for installation

Example:

BuildRequires: cpanel-mysql >= 8.0.20

2.4 Verify Required RPMs

Run:

/scripts/sysup

If all prerequisites exist, you will see: All Needed RPMS are installed.

3. Build and Install Custom RPMs

3.1 Create the `.rpmmacros` File

Create /root/.rpmmacros with:

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

3.2 Create Required Directory Structure

Create the following directories if they do not exist:

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

Or run:

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

Important: Directory names must be capitalized exactly as shown.

3.3 Install the Source RPM (SRPM)

Install the SRPM using:

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

This installs:

.spec file → /root/rpmbuild/SPECS/
sources, patches → /root/rpmbuild/SOURCES/

3.4 Edit the `.spec` File

Modify the .spec file to apply your customizations.

Example configuration section:

%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/

3.5 Rebuild the RPM

Run:

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

The new RPM will be created in:

/root/rpmbuild/RPMS/

If dependency errors appear, install missing packages with yum.

3.6 Install the Custom RPM

Navigate to the RPMS directory and run:

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

4. Prevent Overwriting by cPanel Updates

Warning: This step may freeze updates for this RPM.

Add your custom RPM to the local versions list:

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

Verify in:

/var/cpanel/rpm.versions.d/local.versions

5. Restore the Original cPanel RPM

To revert to the official cPanel RPM:

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

Conclusion

Building and installing custom RPMs on Red‑Hat systems allows you to tailor cPanel & WHM’s third‑party components to your needs. By following these steps—preparing the environment, modifying the SRPM, rebuilding, and managing update behavior—you can safely deploy and maintain custom RPM packages.