Version 74 Documentation
Child pages
  • The cpconftool Script
For cPanel & WHM version 74
Skip to end of metadata
Go to start of metadata

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 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)). 

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 /usr/local/cpanel/bin/cpconftool  script accepts the following arguments:

ArgumentDescriptionExample
--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-modulesList 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 --restore and --backup arguments to restore or backup specific modules.

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

Back up a configuration

To back up a configuration, perform the following steps:

  1. Log in via SSH as the root user and navigate to the /usr/local/cpanel directory.

  2. 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

  3. 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-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:

 Apache configuration...
/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
 Backups configuration...
/var/cpanel/backups/config
/var/cpanel/backups
/var/cpanel/backups/extras
 cPanel theme configuration...
/var/cpanel/activate/features/set_paperlantern_as_default
/var/cpanel/activate/features/paper_lantern
/var/cpanel/customizations/*
 Exim configuration...
/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
 MySQL® configuration...
/etc/my.cnf
 WHM (whmconf) configuration...
/etc/cpupdate.conf
/etc/wwwacct.conf
/etc/wwwacct.conf.shadow
/etc/stats.conf
/var/cpanel/cpanel.config


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.

To restore a configuration from a backup file, run the following command, where 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.
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 /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 &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 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, 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 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 the modsec2.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