Last modified: December 2, 2020
Overview
The /usr/local/cpanel/bin/cpconftool
script backs up, restores, and transfers server configurations. This is useful, for example, when you migrate your cPanel & WHM accounts to a new server.
You can use this script to back up, restore, and transfer the following configurations:
- Apache® — cPanel & WHM uses the Apache configuration to host websites.
Note:
- The Apache configuration also contains the system’s ModSecurity® configuration. Apache uses ModSecurity to provide intrusion detection and prevention on your web server.
- For more information about Apache backups, restoration, and transfers, read the More about Apache configurations section below.
- Backups — cPanel & WHM uses the backups configuration as the system’s primary back up and restore tool.
Note:The backup configuration does not include legacy backup configurations.
- cPanel themes — cPanel & WHM uses the cPanel theme configuration in order to generate the cPanel and WHM interfaces.
- Exim — cPanel & WHM uses Exim as the system’s main mail transfer agent.
- MySQL® — cPanel & WHM uses the MySQL configuration as the system’s primary operations tool.
Note:
WHM’s Transfer Tool interface (WHM >> Home >> Transfers >> Transfer Tool) does not allow you to back up, restore, or transfer MySQL configurations. You must use this script to perform these actions.
- WHM (
whmconf
) — cPanel & WHM uses thewhmconf
configuration to back up and restore WHM’s common non-user-specific settings (for example, the settings from WHM’s Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings) and WHM’s Basic WebHost Manager Setup interface (WHM >> Home >> Server Configuration >> Basic WebHost Manager Setup)).
Run the script
To use this script, run the following command as the root
user:
/usr/local/cpanel/bin/cpconftool --option
Options
The /usr/local/cpanel/bin/cpconftool --option
script accepts the following options:
Option | Description | Example | ||
---|---|---|---|---|
--restore |
Restore a backup file. For more information, read the Restore a configuration section below.
Important:
Make certain that you specify the backup file’s full path with this option.
|
|
||
--backup |
Generate a backup file. For more information, read the Back up a configuration section below. |
|
||
--list-modules |
List the available modules on your server. |
|
||
--modules |
A comma-separated list of the modules to restore or back up.
Note:
You can pass this option with the |
|
Back up a configuration
To back up a configuration, perform the following steps:
- Log in to the server as the
root
user via SSH. - Navigate to the
/usr/local/cpanel
directory. - To list available configurations, run the following command:
The system will display a list of available configuration options. For example:
/usr/local/cpanel/bin/cpconftool --list-modules
1 2 3 4 5 6
cpanel::ui::themes cpanel::easy::apache cpanel::system::backups cpanel::system::mysql cpanel::system::whmconf cpanel::smtp::exim
- Run the following command to back up the configuration, where
configuration::to::backup
represents the configuration name:The system will display a confirmation message that resembles the following example:/usr/local/cpanel/bin/cpconftool --backup --modules=configuration::to::backup
1 2
Backup Successful /home/whm-config-backup-configuration__to__backup-10.550000-1452006507.tar.gz
Note:The system will generate a unique backup filename. In this example, the system generated the backup as thewhm-config-backup-configuration__to__backup-10.550000-1452006507.tar.gz
file.
Configuration backup contents
When you back up a configuration, the system backs up the following files for each type of configuration:
|
|
|
|
|
|
|
|
/etc/my.cnf
|
|
Restore a configuration
/usr/local/cpanel/bin/cpconftool
script, it removes Apache’s default include files. If Apache fails to start, run the /usr/local/cpanel/scripts/rebuildhttpdconf
script and restart Apache.
To restore a configuration from a backup file, run the following command, where /home/backup.tar.gz
represents the full path to the desired backup file and config::to::restore
represents the configuration to restore:
/usr/local/cpanel/bin/cpconftool --restore=/home/backup.tar.gz --modules=config::to::restore --prerestore_backup
- The
--prerestore_backup
parameter is optional and causes the system to restore the original version of the file. - The
--prerestore_backup
parameter is always active for Apache restorations and allows you to troubleshoot your system if an Apache configuration fails to restore.
When you restore a configuration, the following actions occur:
- The system restores all of the configuration files.
Note:If one of the configuration files exists on the destination server but does not exist on the origin server, the system removes that file.
- The
/usr/local/cpanel/bin/cpconftool
script tests whether the configuration is valid. - The
/usr/local/cpanel/bin/cpconftool
script runs the/usr/local/cpanel/scripts/buildeximconf
script.- If the test fails, the system reverts the changes.
- If the test succeeds, the system restarts the configuration.
The restoration process returns output that resembles the following example:
|
|
Transfer a configuration
To transfer a configuration, perform the following steps:
- Perform the backup process for the desired configuration on the origin server.
- Copy the
.tar.gz
file that the backup process creates from the origin server to the destination server. - Perform the restoration process for the desired configuration on the destinations server.
More about Apache configurations
When you back up and restore an Apache server, ModSecurity performs the following tasks for you:
- The system moves the
var/cpanel/secdatadir
file to the same location on the destinations server. - The system moves the
/var/cpanel/modsec_cpanel_conf_datastore
file to the same location on the destination server. - The system determines the ModSecurity Vendors configurations on your server, along with the inactive or active rules set on your system, and moves them to the destination server.
- The system determines the ModSecurity configurations on your server and then moves them to the destination server.
cPanel & WHM does not perform the following tasks for you:
- The system does not move the
modsec2.conf
,modsec2.user.conf
, ormodsec2.cpanel.conf
files. The system does not move these files due to the differences in the Apache configurations, which may cause Apache to fail to restart. - When the system moves the ModSecurity configurations, it modifies these configurations in the current
modsec2.*.conf
files, but does not replace them. - If the user possess control of the
modsec2.user.conf
configurations, the system archives this file and any file themodsec2.user.conf
configuration includes.Warning:We strongly recommend that you do not manually extract these files