The cpconftool Script

whmadvanced backups

Valid for versions 84 through the latest version

Version:

84

Last modified: 2020 December 2

Overview

Use the /usr/local/cpanel/bin/cpconftool script to back up and restore configuration settings. The script groups the configuration settings for different services into modules.

Modules

You can use this script to back up and restore the following modules:

Apache® — cPanel & WHM uses Apache to host websites.
Note:
- The Apache module also modifies the servers’ ModSecurity® settings. Apache uses ModSecurity to provide intrusion detection and prevention on your web server.
- The Apache backup, restoration, and transfer processes differ from other modules. For more information, read the Apache Module Differences section below.
AutoSSL — The AutoSSL feature automatically issues free, Domain-Validated SSL certificates to users’ domains.

Note:

This module does not modify the SSL Provider. To update your SSL provider, use WHM’s Manage AutoSSL interface (WHM » Home » SSL/TLS » Manage AutoSSL).
Backups — cPanel & WHM uses backups to copy or archive data. You can use this data to recover to a previous state.

Note:

The backup module does not include legacy backup settings.
cPanel themes — cPanel & WHM uses cPanel themes to generate the cPanel and the WHM interfaces.
cPHulk — The cPHulk service helps to protect your server against brute force attacks.
Note:
- The script does not copy history reports.
- The script appends whitelist- and blacklist-management configuration settings. It does not replace these configuration settings.
Exim — cPanel & WHM uses Exim as the server’s main mail transfer agent.
GreyListing — The Greylisting feature defends email users against spam.
ModSecurity — This open-source web application firewall helps to detect and prevent intrusion. For more information, read our ModSecurity® documentation.
MySQL® — cPanel & WHM uses MySQL as the server’s database management.

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 settings that aren’t user-specific. 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:

Note:

You can rename a backup file. The --restore and --prerestore_backup options do not rely on the file’s name. You could include modules in the filename.

--modules — (Required) A comma-separated list of the modules to restore or back up.

Note:

The Apache module also contains some ModSecurity settings. Use the ModSecurity module to affect only the ModSecurity settings.
```
--modules=cpanel::smtp::exim,cpanel::system::mysql
```
--backup — Generate a backup file. For more information, read the Back up a configuration module section below.
```
--backup --modules=cpanel::smtp::exim
```
--restore — Restore from a backup file. For more information, read the Restore configuration settings section below.
Important:
- Make certain that you specify the full path to the backup file.
- We strongly recommend that you create a backup before you restore a module. Use either the --backup or the --prerestore_backup option.
```
--restore=/home/whm-config-backup-all-1.1-1411229033.tar.gz --modules=cpanel::smtp::exim
```

--list-modules — List the available modules on your server.

Note:

You do not need to include the --modules option.

The output will resemble the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


cpanel::easy::apache
cpanel::smtp::exim
cpanel::system::autossloptions
cpanel::system::backups
cpanel::system::greylist
cpanel::system::hulk
cpanel::system::modsecurity
cpanel::system::mysql
cpanel::system::whmconf
cpanel::ui::themes

--query-module-info — List information about the version of the module.
```
--query-module-info --modules=cpanel::smtp::exim
```
--verbose — Display details about the operation that the script performs.

Note:

You can only pass this option with the --backup or --restore options.
```
--backup --modules=cpanel::smtp::exim --verbose
```
--prerestore_backup — Restore the original version of the file. The script creates a backup before it restores the module.

Note:

The --prerestore_backup option is always active for Apache restorations.
```
--restore=/home/whm-config-backup-all-1.1-1411229033.tar.gz --modules=cpanel::smtp::exim --prerestore_backup
```

Back up a configuration module

To back up a configuration module, 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 configuration modules, run the following command:

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

The script will display a list of available configuration modules. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


cpanel::easy::apache
cpanel::smtp::exim
cpanel::system::autossloptions
cpanel::system::backups
cpanel::system::greylist
cpanel::system::hulk
cpanel::system::modsecurity
cpanel::system::mysql
cpanel::system::whmconf
cpanel::ui::themes

To back up the configuration module, run the following command. In the following example, configuration::to::backup represents the configuration module name:
```
/usr/local/cpanel/bin/cpconftool --backup --modules=configuration::to::backup
```
The script will display a confirmation message that resembles the following example:
1 2

Backup Successful /home/whm-config-backup-1562881772.tar.gz
Note:

The script will generate a unique backup filename. In this example, the script generated the backup as the whm-config-backup-1562881772.tar.gz file.

Configuration backup contents

When you back up a configuration, the system uses the settings contained in certain files for each module. You can list the files that your server uses for a particular module. For example, to list the files for the Exim module, run the following command:

/usr/local/cpanel/bin/cpconftool --backup --modules=cpanel::smtp::exim --verbose

You can run this command for any module. You will receive output similar to the following example:

Click to view...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


Backing up /etc/cpanel_exim_system_filter …
Backing up /etc/blocked_incoming_email_country_ips …
Backing up /var/cpanel/config/email/trust_x_php_script …
Backing up /var/cpanel/config/email/query_apache_for_nobody_senders …
Backing up /etc/exim.conf …
Backing up /var/cpanel/custom_mailips …
Backing up /etc/mail/spamassassin/KAM.cf …
Backing up /etc/spammers …
Backing up /etc/mail/spamassassin/CPANEL.cf …
Backing up /etc/mail/spamassassin/P0f.cf …
Backing up /etc/mail/spamassassin/deadweight.cf …
Backing up /etc/trustedmailhosts …
Backing up /etc/blocked_incoming_email_domains …
Backing up /etc/cpanel_mail_netblocks …
Backing up /etc/greylist_trusted_netblocks …
Backing up /var/cpanel/per_domain_mailips …
Backing up /etc/mail/spamassassin/kam_heavyweights.cf …
Backing up /etc/global_spamassassin_enable …
Backing up /etc/spammeripblocks …
Backing up /etc/exim.conf.localopts …
Backing up /var/cpanel/custom_mailhelo …
Backing up /etc/exim.conf.local …
Backing up /etc/backupmxhosts …
Backing up /etc/neighbor_netblocks …
Backing up /etc/mail/spamassassin/deadweight2.cf …
Backing up /var/cpanel/use_rdns_for_helo …
Backing up /etc/blocked_incoming_email_countries …
Backing up /etc/mail/spamassassin/deadweight2_meta.cf …
Backing up /etc/senderverifybypasshosts …
Backing up /etc/mail/spamassassin/BAYES_POISON_DEFENSE.cf …
Backing up /etc/skipsmtpcheckhosts …
Backing up /etc/mail/spamassassin/deadweight2_sub.cf …
Backup Successful
/home/whm-config-backup-cpanel__smtp__exim-90.001000-1604326024.tar.gz

Restore configuration settings

Important:

The Apache configurations may require additional steps. For more details, see the Apache module differences section below.

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 module, the following actions occur:

The system restores all of the configuration files.

Note:

The script removes any configuration files on the destination server that did not exist the source server.
The /usr/local/cpanel/bin/cpconftool script tests whether the configuration settings are valid.
The /usr/local/cpanel/bin/cpconftool script runs the /usr/local/cpanel/scripts/buildeximconf script.

If the test fails, the script reverts the changes.
If the test succeeds, the script restarts the service.

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 configuration settings

Warning:

If you use this script to transfer configuration settings, you may encounter undesired behavior. Instead, we strongly recommend that you use WHM’s Transfer Tool interface (WHM » Home » Transfers » Transfer Tool).

To transfer configuration settings, perform the following steps:

Perform the backup process for the configuration module on the source server.
Copy the .tar.gz file from the previous step from the source server to the destination server.
Perform the restoration process for the configuration module on the destination server.

Apache module differences

Important:

When you restore the Apache module, the /usr/local/cpanel/bin/cpconftool script removes Apache’s default include files. If Apache fails to start, run the /usr/local/cpanel/scripts/rebuildhttpdconf script with the --help flag and restart Apache.

To restore configuration settings from a backup file, run the following command. In the following example, /home/backup.tar.gz represents the full path to the desired backup file:

/usr/local/cpanel/bin/cpconftool --restore=/home/backup.tar.gz --modules=cpanel::easy::apache

The script performs the following tasks:

The script moves the /var/cpanel/secdatadir file to the same location on the destination server.
The script moves the /var/cpanel/modsec_cpanel_conf_datastore file to the same location on the destination server.
The script determines the ModSecurity® Vendors configuration settings on your server.
The script then determines the active or inactive rules that you set on your script.
The script moves the ModSecurity configuration settings to the destination server.

The script does not perform the following tasks:

The script does not move the modsec2.conf, modsec2.user.conf, or modsec2.cpanel.conf files. Any differences in Apache configurations could cause Apache to fail to restart.
The script modifies the ModSecurity settings in the current modsec2.*.conf files but does not replace them.
If the user has control of the modsec2.user.conf file, the script archives this file. The script also archives any file the modsec2.user.conf configuration file includes.

Warning:

We strongly recommend that you do not manually extract these files.