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

For cPanel & WHM version 66

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

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

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 finish.
  • Uncompressed — Select this setting to save all of your information in an uncompressed format. This setting uses more disk space, but runs faster than Compressed backups.
  • Incremental — Select this setting to save all of your files in the "directory tree." This setting uses hard links to save disk space. However, only files different from the previous backup will use disk space.

Maximum destination timeout in seconds

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

Note:

Ensure that the number of seconds that you enter will provide enough time for the system to upload your largest backup file.

Minimum Free Disk Space Check

Select this checkbox to check whether the server contains the minimum free disk space available for local backups.

If you do not select this setting, the server will run backups, regardless of the free disk space available.

Warning:

If the server runs out of free disk space, critical services may no longer function until you create more available space.

After you select the Minimum Disk Free Space Check checkbox, perform the following steps:

  1. Enter the amount of free disk space that the backup system requires before it performs backups.
  2. Select one of the following units of measurement.
    • MB — Megabytes.
    • Percent — Percent of disk space available.

Scheduling and Retention

The Scheduling and Retention settings allow you to specify when to run the backup process. 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. If you select this setting, then you must perform the following actions:

  1. Select which days 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. If you select this setting, then you must perform the following actions:

  1. Select which day of the week 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 month, on the days of the month that you select. If you select this setting, then you must perform the following actions:

  1. Select the day or days of the month 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.

Retention behavior

When a complete backup finishes, the system deletes the oldest backup. When the system backup partially completes (fails), the system will not delete the oldest backup, and it will continue to retain the oldest backups. This procedure ensures that the system retains at least one retained complete backup.

After the next complete backup finishes, the system will delete the oldest backups to return to the desired number of backups.

Each Strictly enforce retention, regardless of backup success setting overrides the standard behavior for that backup type. If you select this option, the system will always retain only the desired number of backups with at least one complete backup.

If you run daily backups and retain four of them, the system will retain the latest four backup files:

After the system successfully completes the next backup (5), it deletes the oldest backup (1):

After the next backup partially finishes (6F), the system does not delete the oldest backup (2):

If several more backups partially finish (7F, 8F, and 9F), the system will continue to retain the oldest backups:

After the next complete backup finishes (10), the system deletes the oldest backups so that it only retains 4 backups:

If you run daily backups and retain four of them, the system will retain the latest four backup files:

After the system successfully completes the next backup (5), it deletes the oldest backup (1):

After the system generates a partial backup (6F), it deletes the oldest backup:

After several more partial backups (7F and 8F), the system only retains partial backups:

Then, after the next partial backup (9F), the system must retain the last successful backup (5), so it deletes the oldest partial backup in order to retain only four backup files:

After the next complete backup finishes (10), the system can delete the oldest backup (5) so that it only retains 4 backups, with at least one successful backup.

Files

The Files settings allow you to configure the information that you wish to back up. Select Enable or Disable for your preferred settings.

Warnings:

  • You must select either the Backup Accounts checkbox or the Backup System Files checkbox in order to run backups. You may also select both.
  • Although you do not need to back up your system files to back up account data, we strongly recommend that you back up your system files.
SettingDescription
Backup Accounts

Select the Backup Accounts checkbox to create backups for cPanel accounts. Click Select Users to select individual cPanel accounts to back up; this opens the Backup User Selection interface (Home >> Backup >> Backup User Selection).

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

Warnings:

  • If you do not enable this option, your server will not back up suspended accounts, regardless of the setting in the Backup User Selection interface (Home >> Backup >> Backup User Selection).
  • The system cannot back up the contents of a suspended user's public_ftp directory. For more information, read our What Happens When You Suspend an Account documentation.
  • Backup Access Logs — Select Enable to back up your server's access logs and the /usr/local/cpanel/domlogs file.
  • Backup Bandwidth Data — Select Enable to back up your server's bandwidth data. 
  • Use Local DNS — Select the method to back up the Domain Name System (DNS) information:
    • Disable — The system backs up DNS information from the DNS cluster.
    • Enable — The system backs up DNS information from the server that hosts 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.
  • 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.

Warnings:

  • We strongly recommend that you also save your backups to a remote Additional Destinations location.
  • 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.
  • We strongly recommend that you do not perform backups to remote filesystems (for example, NFS, CIFS, smbfs, or other types of network drive systems). While you can store a backup directly to a remote filesystem, cPanel & WHM does not support this configuration. We strongly recommend that you work with a qualified system administrator to manage this custom backup path to avoid potential risks.
  • 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.

Notes:

  • By default, the system saves backup files locally, to the /backup/ directory.
  • We strongly recommend that you do not perform backups to remote filesystems (for example; NFS, CIFS, smbfs, or other types of network drive systems). While you can store a backup directly to a remote filesystem, cPanel & WHM does not support this configuration. We strongly recommend that you work with a qualified system administrator to manage this custom backup path to avoid potential risks.
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 Enable 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 Disable, 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 can only use Rsync 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
  • Google Drive™

Select Additional Local Directory to transmit data locally. This method is more secure, however, you lose the advantages of a remote back up.

Select a tab to view information for that destination type:

Important:

To use this destination type, you must possess an Amazon S3 account. To do this, follow the directions in Amazon's Sign Up for Amazon S3 documentation.

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 you enter in the Bucket text box exists in the bucket.

Note:

This setting is optional.

Bucket

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

Note:

A bucket contains your Amazon S3 directories and files. 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.
TimeoutEnter themaximum 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 before time expires, 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 Pure-FTPD or ProFTPD on remote FTP servers. Unexpected results may occur with some FTP server software.

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.
TimeoutEnter the maximum 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 before the time expires, 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.
Passive FTP

Select whether to use passive FTP.

Note:

FTP servers behind NAT firewalls require that you select Enable.

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 Enable 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 Disable, 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 option to use key-based authentication. We strongly recommend that you use this method.
  • Password Authentication — Select this option to use password-based authentication.
Key Authentication Options

If you selected Key Authentication 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. The private key resides in the /root/.ssh/keyname file, where keyname represents the key's name.

    Notes:

    • Click Generate a new key to generate a new private key. A message of success will appear at the bottom of the interface.
      • The system will also add the private key's file path in the Private Key text box.
    • The private key's corresponding public key resides in the /root/.ssh/keyname.pub file.
  • The passphrase for this server, in the Passphrase text box.
Password Authentication Options

If you selected Password Authentication for the Authentication Type setting, enter the password for the account on the remote server in the Remote Password text box.

TimeoutEnter the maximum 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 before the time expires, 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 the 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.
TimeoutEnter the maximum 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 before the time expires, 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. Google Drive uses an encrypted connection.

Folder

Enter a directory where you would like to store backups, relative to the remote account's directory root. Backups will be stored under this directory in subdirectories named by date.

Note:

This setting is optional.

Client IDEnter the client ID for the access credentials.
Client secretEnter the client secret for the access credentials.
Generate CredentialsClick this button to generate the necessary credentials from your client ID and client secret.
TimeoutEnter the maximum 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 900.
  • If the server does not respond before the time expires, 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 Name

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

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, Rsync destinations use port 22

Remote Account UsernameThe username for the account on the remote server.
Authentication Type

Select how you wish to authenticate to the remote server:

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

If you selected Key Authentication 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. The private key resides in the /root/.ssh/keyname file, where keyname represents the key's name.

    Notes:

    • Click Generate a new key to generate a new private key. A success message will appear at the bottom of the interface.
    • The system will also add the private key's file path in the Private Key text box.
    • The private key's corresponding public key resides in the /root/.ssh/keyname.pub file.
  • The passphrase for this server, in the Passphrase text box.

Password Authentication OptionsIf you selected Password Authentication for the Authentication Type setting, enter the password for the account on the remote server in the Remote Password text box.

Warning:

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:

This setting is optional.

Remote Host

Provide the hostname or IP address of the remote server.

Important:

  • Do 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:

This setting is optional.

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 before the time expires, 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 following statements about the script's operations are true:

  • 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 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 up-to-date backup files exist but you wish to perform an additional backup, run the following command:

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

You can use the /usr/local/cpanel/scripts/pkgacct script to create a cpmove archive for an account. For more information, read The pkgacct Script documentation. 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.

Additional documentation