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 the whmconf 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:

--restore=/home/whm-config-backup-all-1.1-1411229033.tar.gz

--modules=cpanel::smtp::exim --backup

1
2
3
4
5
6

cpanel::smtp::exim
cpanel::system::backups
cpanel::system::mysql
cpanel::system::whmconf
cpanel::easy::apache
cpanel::ui::themes

--modules=cpanel::smtp::exim --backup

Back up a configuration

To back up a configuration, perform the following steps:

1. Log in to the server as the root user via SSH.
2. Navigate to the /usr/local/cpanel directory.
3. To list available configurations, run the following command:

   /usr/local/cpanel/bin/cpconftool --list-modules

   The system will display a list of available configuration options. For example:

   1 2 3 4 5 6

   cpanel::ui::themes cpanel::easy::apache cpanel::system::backups cpanel::system::mysql cpanel::system::whmconf cpanel::smtp::exim

4. Run the following command to back up the configuration, where configuration::to::backup represents the configuration name:

   /usr/local/cpanel/bin/cpconftool --backup --modules=configuration::to::backup

   The system will display a confirmation message that resembles the following example:

   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 the whm-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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

/etc/cpanel/ea4
/var/cpanel/easy
/etc/apache2/conf.d
/etc/apache2/conf
/usr/local/apache/conf
/var/cpanel/secdatadir
/var/cpanel/modsec_cpanel_conf_datastore
/var/cpanel/conf/apache/main
/var/cpanel/conf/apache/local
/usr/local/apache/conf/includes
/var/cpanel/templates/apache*/local

1
2
3

/var/cpanel/backups/config
/var/cpanel/backups
/var/cpanel/backups/extras

1
2
3

/var/cpanel/activate/features/set_paperlantern_as_default
/var/cpanel/activate/features/paper_lantern
/var/cpanel/customizations/* 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

/etc/exim.conf
/etc/exim.conf.local
/etc/exim.conf.localopts
/etc/mail/spamassassin/BAYES_POISON_DEFENSE.cf
/etc/mail/spamassassin/CPANEL.cf
/etc/mail/spamassassin/KAM.cf
/etc/mail/spamassassin/P0f.cf
/etc/global_spamassassin_enable
/var/cpanel/config/email/query_apache_for_nobody_senders
/var/cpanel/config/email/trust_x_php_script
/var/cpanel/custom_mailhelo
/var/cpanel/custom_mailips
/var/cpanel/exim_ipv4_sort_bias
/var/cpanel/per_domain_mailips
/etc/backupmxhosts
/etc/cpanel_mail_netblocks
/etc/greylist_trusted_netblocks
/etc/neighbor_netblocks
/etc/senderverifybypasshosts
/etc/skipsmtpcheckhosts
/etc/spammeripblocks
/etc/trustedmailhosts
/usr/local/cpanel/etc/exim/acls/*
/usr/local/cpanel/etc/exim/acls.dist

/etc/my.cnf

1
2
3
4
5

/etc/cpupdate.conf
/etc/wwwacct.conf
/etc/wwwacct.conf.shadow
/etc/stats.conf
/var/cpanel/cpanel.config

Restore a configuration

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

When you restore a configuration, the following actions occur:

1. 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.
2. The /usr/local/cpanel/bin/cpconftool script tests whether the configuration is valid.
3. 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

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 service 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 &ldquo;mail.&rdquo; onto Mailman URLs</span>:\nProcessing post action for <span class=\"setting_label\">Use pre-4.1-style MySQL<sup>&reg;</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:

1. Perform the backup process for the desired configuration on the origin server.
2. Copy the .tar.gz file that the backup process creates from the origin server to the destination server.
3. 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, or modsec2.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 the modsec2.user.conf configuration includes.
  Warning:

  We strongly recommend that you do not manually extract these files