Child pages
  • How to Build and Install Custom RPMs
Skip to end of metadata
Go to start of metadata

Overview

cPanel, Inc. ships many of cPanel & WHM's third-party dependencies as RPMs. In order to customize these dependencies on your server, you must custom-build the RPM and then reinstall it. For example, use this method to build and install Roundcube customizations in cPanel & WHM version 58 and later.

Note:

You must log in through SSH as the root user to install an RPM. 

Before you begin


Perform the following steps to ensure your system's readiness to build and install an RPM:

Install the rpm-build package

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

yum install rpm-build

 


Enable the devel target for cPanel & WHM

Run the update_local_rpm_versions and check_cpanel_rpms scripts before you install a custom RPM. These scripts ensure that the devel target is enabled and up-to-date. The devel target installs the devel versions of RPMs, which cPanel & WHM uses to compile SRPMs locally.

To do this, run the following commands:

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

Note:

To rebuild some cPanel-provided RPMs, you may need to install additional RPMs that cPanel & WHM does not include in default installations. These additional RPMs contain files that the system only needs to rebuild, but not run, the cPanel-provided RPMs.

 


Install additional prerequisites

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

  • Lines in the .spec file that begin with BuildRequires: indicate a prerequisite that the RPM requires for the build process.
  • Lines in the .spec file that begin with Requires: indicate a prerequisite that the RPM requires for installation.

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

 


Ensure that you have installed all necessary RPMs

Run the /scripts/sysup script to ensure that you have installed all of the prerequisite RPMs.

  • If all of these RPMs exist on your server, you will receive the following message: All Needed RPMS are installed.
  • If you receive an error message, correct those installation problems first to avoid additional errors when you build and install 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:

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:

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

 

 

 


 

Create the directories to rebuild the RPM

If not 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 names for the BUILDSPECSSOURCESBUILDROOTRPMS, and SRPMS directories. You must capitalize the entire name for each of these directories.  

 


 

Install the source RPM

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

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

Note:

You can find the correct SRPM for your version of cPanel & WHM on our httpupdate server. Click on your server's version of cPanel & WHM, and then click on 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 finishes, you will see a message that resembles 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%]

 


 

Edit the .spec file

Use your preferred text editor to modify the .spec file 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/ \

 


 

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 dependencies issues when you run this command. If so, install these dependencies with yum before you continue.

 


 

Run the command to update your RPM with force

Navigate to the /root/rpmbuild/RPMS/ directory and run 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 that you wish to update:

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

 


 

Prevent unintentional updates

Warning:

This step is optional and may freeze updates to this RPM and prevent future cPanel & WHM upgrades. However, if you do not perform this step, cPanel & WHM may overwrite your custom RPM on its next update or upgrade.

To prevent unintentional updates, add your custom RPM to the list of local RPMs in 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 return to the cPanel & WHM version of an RPM:

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

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

 


 

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

/scripts/check_cpanel_rpms

Additional documentation