Page tree
Skip to end of metadata
Go to start of metadata

 

For cPanel & WHM version 11.50

( Home >> Backup >> Backup Configuration )

Overview

The Backup Configuration interface allows system administrators to customize their scheduled backups.

Warning:

We strongly recommend that you only use the Backup Configuration interface to configure backups of your server. We plan to remove the Legacy Backup Configuration interface (Home >> Backup >> Legacy Backup Configuration) from WHM in a future release.

Note:

The system applies the current Backup Configuration settings to accounts that you create or transfer.

To enable and run backups, you must complete both of the following steps:

  1. Select Enable for the Backup Status setting in this interface's Global Settings section.
  2. Select your desired settings for the Backup Configuration feature.
  3. Use the Backup User Selection interface (Home >> Backup >> Backup User Selection) to enable backups for each desired cPanel user.

    Note:

    To enable or disable the Backup Configuration feature for all users, select the checkbox in the top right corner of the Backup User Selection interface.

Global Settings

You can configure the following global backup settings:

SettingDescription
Backup Status

Enable this setting to run the updated Backup Configuration feature. This setting defaults to Enable.

Backup Type

Choose one of the following options to determine how the system stores backup files:

  • Compressed — Select this setting to save all of your information in a compressed format. This setting uses less disk space, but requires more time to complete.
  • Uncompressed — Select this setting to save all of your information in an uncompressed format. This setting uses more disk space, but is faster than Compressed backups.
  • Incremental — Select this setting to store only one uncompressed backup file. The system saves updated account information to the existing backup file, and remove the old information that these updates replace. This setting limits your restoration settings, but runs faster and uses less disk space than other backup types.

    Warning:

    If you choose to use Incremental backups, you cannot restore the account to a time before your last backup.

Maximum destination timeout in seconds

Enter the maximum number of seconds to allow a backup process to upload a single backup file or restore a single backup file.

Note:

We strongly recommend that you enter a number of seconds that is large enough for the system to upload your largest backup file.

Scheduling and Retention

The Scheduling and Retention settings allow you to specify when the backup process runs. You may choose to run backups on a daily, weekly, or monthly basis, or you may use a combination of these settings. Select the checkboxes that correspond to the timing settings that you wish to use.

Note:

You must select at least one of the following settings.

SettingDescription
Backup Daily

Your system creates a new backup on each of the days of the week that you select. When you select this setting, you must also configure the following settings:

  1. Select the days of the week on which you wish to run backups.
  2. In the Retain Daily backups text box, enter the maximum number of daily backup files to store on your system at any given time. Enter any number between 1 and 9999.
Backup Weekly

Your system creates a new backup once each week, on the day that you select. When you select this setting, you must also configure the following settings:

  1. Select the day of the week on which you wish to run backups.
  2. In the Retain Weekly backups text box, enter the maximum number of weekly backups to store on your system at any given time. Enter any number between 1 and 9999.
Backup Monthly

Your system creates a new backup either once or twice per week, on the days of the month that you select. When you select this setting, you must also configure the following settings:

  1. Select the day or days of the month on which you wish to run backups.
  2. In the Retain Monthly backups text box, enter the maximum number of monthly backups to store on your system at any given time. Enter any number between 1 and 9999.

Note:

If you run daily and monthly backups on the same day, the daily backup runs first, and then the monthly backup copies the daily backup.

Files

The Files settings allow you to configure the information that you wish to back up. Select the checkboxes that correspond to the settings that you wish to use.

Warning:

You must select either the Backup Accounts or Backup System Files checkbox in order to run backups.

SettingDescription
Backup Accounts

Back up the user files in each cPanel user's home directory.

Note:

Click Select Users to open the Backup User Selection interface (Home >> Backup >> Backup User Selection).

After you select this setting, select the type of data to include in the backup file:

  • Backup Suspended Accounts — Select the Enable button to back up suspended accounts.

    Warning:

    If you do not enable this option, your server will not back up suspended accounts, regardless of their settings in the Backup User Selection interface ( Home >> Backup >> Backup User Selection ).

  • Backup Access Logs — Select the Enable button to back up your server's access logs and the /usr/local/cpanel/domlogs file.
  • Backup Bandwidth Data — Select the Enable button to back up your server's bandwidth data. 
  • Use Local DNS — Select the method to use to back up DNS information:
    • Disable — The system backs up DNS information from the DNS cluster.
    • Enable — The system backs up DNS information from the server for the domain.
Backup System Files

Back up your server's system files.

Notes:

  • The system stores many of these files in the /etc directory.
  • You must enable this setting for server restoration, but it is not necessary for account restoration. We strongly recommend that you enable this setting.
  • For more information, read our System Backups documentation.

Databases

Select one of the following options for the Backup SQL Databases setting, to determine how to back up SQL databases:

SettingDescription
Per Account OnlyOnly back up the databases for each account. This setting uses the mysqldump utility.
Entire MySQL DirectoryBack up all of the databases on the server. This backs up the entire /var/lib/mysql/ directory.
Per Account and Entire MySQL DirectoryPerform a comprehensive backup that copies all of the databases for each individual account, as well as all of the databases on the server.

Configure Backup Directory

The following settings allow you to specify where you wish to save your backups.

Warning:

  • We strongly recommend that you save your backups to a remote location in addition to a local destination.
  • If you do not select the Retain backups in the default backup directory setting and do not specify a destination in the Additional Destinations setting, the system will return the following error: Error: Nowhere to back up: no enabled destinations found and retaining local copies is disabled.
  • The backup process and the transfer process use separate queues. If each backup finishes much faster than each transfer, backup files can accumulate on the server and fill the hard drive.
  • Perform backups to NFS mount points at your own risk. If you choose a NFS mount point, you risk data loss if there is a network interruption or if you did not properly configure NFS.
  • To prevent performance degradation, the system automatically disables quotas on non-root filesystems that contain a backup destination.
SettingDescription
Default Backup Directory

To change the default backup directory, enter the absolute path to the desired directory location.

Note:

By default, the system saves backup files locally, to the /backup/ directory.

Retain backups in the default backup directory.

Select this checkbox to retain each account backup in the /backup/ directory after the backups transfer to another destination.

If you do not select this setting, your server deletes account backup files from the /backup/ directory only after the following events occur:

  • The system successfully transfers the backup file to at least one additional destination.
  • The system attempts, successfully or unsuccessfully, to transfer the backup file to all of your additional destinations.

Note:

This setting does not cause the system to remove system backup files, directories, or other files.

Mount Backup Drive as Needed.

Select the Enable button to mount a backup drive. This setting requires a separate mount point and causes the Backup Configuration process to check the /etc/fstab file for a backup mount.

  • If a mount exists with the same name as the staging directory, the Backup Configuration process mounts the drive and backs up the information to the mount. 
  • After the backup process finishes, it dismounts the drive. 

If you select the Disable button, the Backup Configuration process does not check the /etc/fstab file for a mount.

Additional Destinations

You can save your backups to additional destinations. Each additional destination may increase the amount of time that the backup process requires. If the process runs too long, it may interfere with the next backup process.

Notes:

  • To restore backups that exist in the additional destinations that you create, perform a remote restoration. For more information, read our Remote Restoration documentation.
  • If you use the Incremental backup type, you cannot add additional destinations.
  • To save your updated destination but not validate your changes, click Save Destination.
  • To automatically validate your information after you save your changes, click Save and Validate Destination.

Select a destination type from the menu and click Create new destination. A new section for the selected destination type will appear.

Warning:

Only transfer system backup files over encrypted connections. The following destination types use encrypted connections:

  • Amazon S3™
  • SFTP
  • WebDAV with SSL Enabled

The Additional Local Directory type does not transfer your data from the server, so that method is secure.

Select a tab to view information for that destination type:

SettingDescription
Destination NameEnter a destination name for your backup files. This name appears in your destination table.
Transfer System Backups to Destination

Select this checkbox to transfer system backups to an additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Folder

Enter the name of the folder in which you wish to store your backups. Make certain that the folder is in the bucket that you enter in the Bucket text box.

Note:

This setting is optional.

Bucket

Enter the name of the bucket in which you wish to store your backup.

Note:

A bucket is the container in which your Amazon S3 folders and files reside. You must create your bucket in the Amazon S3 management console.
Access Key IDAfter you generate an access key, enter the access key ID in this text box. Your server uses the access key to authenticate with the Amazon S3 account.
Secret Access KeyAfter you generate an access key, enter the secret access key in this text box. Unless you specify a new password, the server uses the existing password.
TimeoutEnter the maximum amount of time in seconds that you want the server to wait for a response from the remote server before it generates errors.
  • You must enter a number between 30 and 300.
  • If the server does not respond in this time frame, it makes two additional attempts to contact the server.
  • If the server does not respond after those attempts, the system administrator receives an email that notes the failed attempts, and the system attempts a transfer again the next time that backups run.

Warning:

We strongly recommend that you use SFTP instead of FTP.

SettingDescription
Destination NameEnter a destination name for your backup file. This name appears in your destination table.
Transfer System Backups to Destination

Select this checkbox to transfer system backups to an additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Backup Directory

Enter the directory path in which you wish to store backups.

Note:

This setting is optional.

Remote Host

Enter the hostname or IP address for the remote server. 

Important:

  • Do not include http://, https://, a trailing port, or path information in the address that you enter. 
  • Do not use local hosts or loopback addresses.
PortEnter the port to use to communicate with the remote server. By default, FTP destinations use port 21.
Remote Account UsernameEnter the username of the account on the remote server.
Remote PasswordEnter the password for the account on the remote server. Unless you enter a new password, the server uses the existing password.
TimeoutEnter the maximum amount of time in seconds that you want the server to wait for a response from the remote server before it generates errors.
  • You must enter a number between 30 and 300.
  • If the server does not respond in this time frame, it makes two additional attempts to contact the server.
  • If the server does not respond after those attempts, the system administrator receives an email that notes the failed attempts, and the system attempts a transfer again the next time that backups run.
PassiveFTP

Select whether to use passive FTP.

Note:

FTP servers behind NAT firewalls require that you select the Enable button.

SettingDescription
Destination NameEnter a destination name for your backup. This name appears in your destination table.
Transfer System Backups to Destination

Select this checkbox to transfer system backups to an additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Backup Directory

Enter the directory path in which you wish to store backups.

Note:

This setting is optional.

Mount Backup Drive as Needed.

Select the Enable button to mount a backup drive. This setting requires a separate mount point and causes the Backup Configuration process to check the /etc/fstab file for a backup mount.

  • If a mount exists with the same name as the staging directory, the Backup Configuration process mounts the drive and backs up the information to the mount. 
  • After the backup process finishes, it dismounts the drive. 

If you select the Disable button, the Backup Configuration process does not check the /etc/fstab file for a mount.

SettingDescription
Destination NameEnter a destination name for your backup file. This name appears in your destination table.
Transfer System Backups to Destination

Select this checkbox to transfer system backups to an additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Backup Directory

Enter the directory path in which you wish to store backups.

Note:

This setting is optional.

Remote Host

Enter the hostname or IP address of the remote server. 

Important:

  • Do not include http://, https://, a trailing port, or path information in the address that you enter. 
  • Do not use local hosts or loopback addresses.
PortEnter the port to use to communicate with the remote server. By default, SFTP destinations use port 22.
Remote Account UsernameEnter the username of the account on the remote server.
Authentication Type

Select how you wish to authenticate to the remote server:

  • Key Authentication — Select this button to use key-based authentication. We strongly recommend that you use this method.
  • Password Authentication — Select this button to use password-based authentication.
Key Authentication Options

If you selected the Key Authentication button for the Authentication Type setting, enter the following information:

  • The full path of the private key on this server, in the Private Key text box.

    Note:

    Click Generate a new key to generate a new private key. 

  • The passphrase for this server, in the Passphrase text box.
Password Authentication Options

If you selected the Password Authentication button for the Authentication Type setting, enter the password for the account on the remote server in the Remote Password text box. Unless you specify a new password, the server uses the existing password.

TimeoutEnter the maximum amount of time in seconds that you want the server to wait for a response from the remote server before it generates errors.
  • You must enter a number between 30 and 300.
  • If the server does not respond in this time frame, it makes two additional attempts to contact the server.
  • If the server does not respond after those attempts, the system administrator receives an email that notes the failed attempts, and the system attempts a transfer again the next time that backups run.
SettingDescription
Destination NameEnter a destination name for your backup files. This name appears in your destination table.
Transfer System Backups to Destination

Select this checkbox to transfer system backups to an additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Backup Directory

Enter the directory path in which you wish to store backup files.

Note:

This setting is optional.

Remote Host

Enter the hostname or IP address of the remote server. 

Important:

  • Do not include http://, https://, a trailing port, or path information in the address that you enter. 
  • Do not use local hosts or loopback addresses.
Port

The port to use to communicate with the remote server.

  • By default, WebDAV destinations use port 80
  • Port 443 is a secure port.
  • cPanel & WHM uses port 2077 for non-SSL connections and port 2078 for SSL connections.
SSL EnabledSelect this checkbox to enable SSL. WebDAV destinations require that you enable SSL encryption.
Remote Account UsernameThe username for the account on the remote server.
Remote PasswordThe password for the account on the remote server. Unless you specify a new password, your server uses the existing password.
TimeoutEnter the maximum amount of time in seconds that you want the server to wait for a response from the remote server before it generates errors.
  • You must enter a number between 30 and 300.
  • If the server does not respond in this time frame, it makes two additional attempts to contact the server.
  • If the server does not respond after those attempts, the system administrator receives an email that notes the failed attempts, and the system attempts a transfer again the next time that backups run.

We strongly recommend that only advanced users create custom backup destinations.

SettingDescription
Destination NameEnter a destination name for your backup files. This name appears in your destination table.
Transfer System Backups to Destination

Select this checkbox to transfer system backups to an additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Script

Enter your custom transport script's absolute path.

Note:

For more information, read the Create a custom transport script section below.

Backup Directory

Specify the directory path in which you wish to store backups.

Note:

$body

Remote Host

Provide the hostname or IP address of the remote server. 

Important:

  • The address should not include http://, https://, a trailing port, or path information. 
  • Do not use local hosts or loopback addresses.
Remote Account Username

The username of the account on the remote server.

Note:

$body

Remote PasswordThe password for the account on the remote server. Unless you specify a new password, your server will use the existing password.
TimeoutEnter the maximum amount of time in seconds that you want the server to wait for a response from the remote server before it generates errors.
  • You must enter a number between 30 and 300.
  • If the server does not respond in this time frame, it will make two additional attempts to contact the server.
  • If the server does not respond after those attempts, the system administrator will receive an email that notes the failed attempts, and the system will attempt a transfer again the next time backups run .

Create a custom transport script

The custom transport script is a script that you must provide for each custom backup destination.

Script commands

The script must implement the following commands:

CommandParameters
getRemote file, local file
putLocal file, remote file
lsPath
mkdirPath
chdirPath
rmdirPath
deletePath

Backups run these commands while the system transports the backup file and validates the destination.

Script operation

  • The script runs once per command.
  • The script cannot save state information between commands.
  • The system does not reuse the connection between commands. Instead, whenever the script runs, the system creates the connection to the remote custom destination, and drops it after the script runs.
  • The system passes information to the script in the following order: 
    1. Command name.
    2. Current directory.
    3. Command specific parameters.
    4. Host.
    5. Username.

By default, the system passes the directory on the remote system to use for the operation to the script. Because the system drops the connection to the directory between operations, the user must save the directory.

If the script returns output to STDERR, it will fail. The system logs any data that the script returns to STDERR as part of the failure.

The following commands return output to STDOUT to return data back to the user:

  • chdir — Prints the new working directory on the remote system. This is necessary because the remote system may exist in a different working directory than the user anticipated, based on the contents of the path parameter (for example, special characters).
  • ls — Print output that is identical to the output of the ls -l command. For example:

     -rwxr-xr-1 root root 3171 Jan 18 12:23 temp.txt

     

    • If you enter a password when you create the custom destination, the system passes it to the script in the PASSWORD environment variable. The password does not display on the command line.

You can view an example destination script in the /usr/local/cpanel/scripts/custom_backup_destination.pl.skeleton file.

Save Configuration

After you configure the desired settings, click Save Configuration at the bottom of the Backup Configuration interface.

To reset all of the settings in the Backup Configuration interface to the default settings, click Reset.

Run backups manually

To run a backup manually, run the following command:

/usr/local/cpanel/bin/backup

If the backup is up-to-date but you still wish to perform a backup, run the following command:

/usr/local/cpanel/bin/backup --force

To use a custom packaging script, perform the following steps:

  1. Copy the /usr/local/cpanel/scripts/pkgacct file and modify it.
  2. Store the modified pkgacct file in the /var/cpanel/lib/Whostmgr/Pkgacct/pkgacct directory.
  3. Run the /usr/local/cpanel/bin/backup command with the --allow-override flag.

Backup files and directories

When you select Backup Configuration Files, cPanel & WHM backs up the following files and directories:

cPanel & WHM backs up the following files and directories:

Files

/etc/exim.conf
/etc/exim.conf.local
/etc/exim.conf.localopts
/etc/namedb/named.conf
/etc/rc.conf
/etc/named.conf
/etc/proftpd.conf
/etc/localdomains
/etc/httpd/conf/httpd.conf
/etc/group
/etc/shadow
/etc/master.passwd
/etc/passwd
/etc/fstab
/etc/ips
/etc/ips.remotemail
/etc/ips.remotedns
/etc/reservedips
/etc/reservedipreasons
/etc/quota.conf
/etc/wwwacct.conf
/etc/remotedomains
/etc/rndc.conf
/etc/secondarymx
/etc/my.cnf
/root/.my.cnf
/usr/local/apache/conf/httpd.conf

Directories

/etc/namedb
/etc/valiases
/etc/proftpd
/etc/vdomainaliases
/etc/ssl
/etc/vfilters
/usr/local/frontpage
/usr/share/ssl
/usr/local/cpanel/3rdparty/mailman
/var/lib/rpm
/var/lib/named/chroot/var/named/master
/var/named
/var/cpanel
/var/spool/cron
/var/cron/tabs
/var/spool/fcron
/var/log/bandwidth
/var/ssl
/var/lib/mysql 

To configure system backups to include custom files or directories, create a new file or directory in the /var/cpanel/backups/extras directory (for example, /var/cpanel/backups/extras/etc). In that file, enter an absolute path to any files that you wish to back up (for example, /etc/example.conf).

Note:

The server administrator can edit the /etc/my.cnf file to change the MySQL data directory location. In such a case, WHM will back up the directory at its new location.

 

Additional documentation

  • Backup Restoration — Restore your backup with the Backup Restoration interface.
  • Remote Restoration — Restore backups in the Additional Destinations locations that you created.
  • System Backups — Upload system backups to your chosen backup destinations.