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.
Notes:
- 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)).
The /usr/local/cpanel/bin/cpconftool
script
To use this script, run the following command as the root
user:
/usr/local/cpanel/bin/cpconftool --argument
Arguments
The
script accepts the following arguments:/usr/local/cpanel/bin/cpconftool
Argument | Description | Example |
---|---|---|
--restore | Restore a backup file. For more information, read the Restore a configuration section below.
| --restore=/home/whm-config-backup-all-1.1-1411229033.tar.gz |
--backup | Generate a backup file. For more information, read the Back up a configuration section below.
| --modules=cpanel::smtp::exim --backup
|
--list-modules | List the available modules on your server. | The output will resemble the following example: cpanel::smtp::exim cpanel::system::backups cpanel::system::mysql cpanel::system::whmconf cpanel::easy::apache cpanel::ui::themes |
--modules | A comma-separated list of the modules to restore or back up. Note: You can pass this argument with the | --modules=cpanel::smtp::exim --backup |
Back up a configuration
To back up a configuration, perform the following steps:
- Log in via SSH as the
root
user and navigate to the/usr/local/cpanel
directory. To list available configurations, run the following command:
bin/cpconftool --list-modules
The system will display a list of available configurations. For example:
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:bin/cpconftool --backup --modules=configuration::to::backup
The system will display a confirmation message that resembles the following example:
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 the
whm-config-backup-configuration__to__backup
file.-10.550000-1452006507.tar.gz
Configuration backup contents
When you back up a configuration, the system backs up the following files for each type of configuration:
Note:
Each file that this section lists will only exist when the configuration requires it.
Restore a configuration
Important:
When you restore an EasyApache 4 configuration backup with the /usr/local/cpanel/bin/cpconftool
script, it removes Apache's default include files. If Apache fails to start, run the /scripts/rebuildhttpdconf
script and restart Apache.
backup.tar.gz
represents the path to the desired backup file and config::to::restore
represents the configuration to restore:bin/cpconftool --restore=backup.tar.gz --modules=config::to::restore --prerestore_backup
Notes:
- 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.
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/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:
Restore Successful --- cpanel::system::whmconf: post_restore: data: "<span class=\"b2\">Your changes have been saved.</span><br /><br /><span class=\"b2\">Restarting cPanel daemons...</span><span class=\"b2\">done.</span><br /><br /><span class=\"b2\">Updating your system to reflect any changes...</span><br /><pre>Processing post action for <span class=\"setting_label\">Thunderbird and Outlook autodiscover and autoconfig support (enables proxy subdomain and SRV record creation)</span>:\nThe master proxysubdomains setting changed state so we do not need to update the autodiscover domains.\nProcessing post action for <span class=\"setting_label\">Conserve memory</span>:\nProcessing post action for <span class=\"setting_label\">Standardized Hooks - Debug Mode</span>:\nProcessing post action for <span class=\"setting_label\">Include mailman in disk usage calculations</span>:\nProcessing post action for <span class=\"setting_label\">Include databases in disk usage calculations</span>:\nProcessing post action for <span class=\"setting_label\">Mail authentication via domain owner password</span>:\nProcessing post action for <span class=\"setting_label\">Number of failed or deferred messages a domain may send before protections can be triggered</span>:\nProcessing post action for <span class=\"setting_label\">Enable Email Archiving support</span>:\nProcessing post action for <span class=\"setting_label\">Email delivery retry time</span>:\nProcessing post action for <span class=\"setting_label\">Allow cPanel & WHM to determine the best value for your MySQL innodb_buffer_pool_size configuration?</span>:\nProcessing post action for <span class=\"setting_label\">Allow cPanel & WHM to determine the best value for your MySQL max_allowed_packet configuration?</span>:\nProcessing post action for <span class=\"setting_label\">Allow cPanel & WHM to determine the best value for your MySQL open_files_limit configuration?</span>:\nProcessing post action for <span class=\"setting_label\">cPanel PHP max execution time</span>:\nProcessing post action for <span class=\"setting_label\">cPanel PHP max POST size</span>:\nProcessing post action for <span class=\"setting_label\">cPanel PHP max upload size</span>:\nProcessing post action for <span class=\"setting_label\">cPanel PHP loader</span>:\nProcessing post action for <span class=\"setting_label\">Allow users to relay mail if they use an IP address through which someone has validated an IMAP or POP3 login within the last hour (Pop-before-SMTP)</span>:\nProcessing post action for <span class=\"setting_label\">Proxy subdomains</span>:\nCreating proxy domain DNS entries in background. This process can take several minutes to complete.\nProcessing post action for <span class=\"setting_label\">Require SSL</span>:\nProcessing post action for <span class=\"setting_label\">Enable Analog stats</span>:\nProcessing post action for <span class=\"setting_label\">Enable Awstats stats</span>:\nProcessing post action for <span class=\"setting_label\">Enable BoxTrapper spam trap</span>:\nProcessing post action for <span class=\"setting_label\">Enable Horde Webmail</span>:\nProcessing post action for <span class=\"setting_label\">Enable Mailman mailing lists</span>:\nmailman...(XID jcptbq) The \xE2\x80\x9Cmailman\xE2\x80\x9D service is disabled.\nWaiting for \xE2\x80\x9Cmailman\xE2\x80\x9D to stop \xE2\x80\xA6\xE2\x80\xA6\xE2\x80\xA6finished.<br />\n<br />\n...Done\nRestarting mailman\nConfiguration file passes test! New configuration file was installed.\n\n\n\n/etc/exim.pl.local installed!\nSPF is disabled in exim or unavailable, enabling SPF for SpamAssassin\nRefreshing SMTP Mail protection.\nSMTP Mail protection has been disabled. All users may make outbound smtp connections.\nDisabled scgi-bin since suexec is enabled or the webserver runs as the user\nDistilled successfully\nProcessing post action for <span class=\"setting_label\">Enable Apache SpamAssassin\xE2\x84\xA2 spam filter</span>:\nProcessing post action for <span class=\"setting_label\">Enable Apache SpamAssassin\xE2\x84\xA2 Spam Box delivery for messages marked as spam (user configurable)</span>:\nProcessing post action for <span class=\"setting_label\">Enable Webalizer stats</span>:\nProcessing post action for <span class=\"setting_label\">Restrict outgoing SMTP to root, exim, and mailman (FKA SMTP Tweak)</span>:\nProcessing post action for <span class=\"setting_label\">Prefix “mail.” onto Mailman URLs</span>:\nProcessing post action for <span class=\"setting_label\">Use pre-4.1-style MySQL<sup>®</sup> passwords</span>:\n</pre><span class=\"b2\">Done.</span></div>\n</body>\n</html>\n" status: 1 statusmsg: Update WHMhostmgr Succeeded restore: data: warnings: [] status: 1 statusmsg: "Whostmgr::Config::Restore::System::WHMConf: ok"
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 destination 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 destination 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 existing
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. You can find these files in the tarball that you manually extract.Warning:
We strongly recommend that you do not manually extract these files.
Additional documentation