Version 74 Documentation
Child pages
  • Backup Configuration
For cPanel & WHM version 74
Skip to end of metadata
Go to start of metadata

(WHM >> Home >> Backup >> Backup Configuration)

Overview

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

Notes:

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.

Warning:

When you set the toggle to Disable, you also disable WHM's File and Directory Restoration interface (WHM >> Home >> Backups >> File and Directory Restoration) and hide cPanel's File and Directory Restoration  interface (cPanel >> Home >> Files >> File and Directory Restoration). For more information, read the How to Manage Metadata Settings documentation.

Backup Type

Select 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 a combination of hard links and files for speed and to save 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 enable the system 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 amount of free disk space available. This setting defaults to Enabled.

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, you can 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:
    • % — Percent of available disk space.
    • MB — Megabytes.

Scheduling and Retention

The Scheduling and Retention settings allow you to specify when to run the backup process. Select 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, 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, 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 first or 15th day of each month. If you select this setting, then you must perform the following actions:

  1. Select which days of the month 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. When the daily backup completes, the monthly backup copies the daily backup.

Retention behavior

When the system completes a backup, the system deletes the oldest backup. When the system backup partially completes (the backup 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 backup completes, 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 setting, the system will always retain the desired number of backups with at least one completed 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 completes (6F), the system doesnot 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 completes (10), the system deletes the oldest backups so that it only retains four 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:

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 completes (10), the system can delete the oldest backup (5) so that it only retains four 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.
  • The backup process for an account near or over its quota may fail because the system cannot write necessary files, such as a database lock file.
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 (WHM >> Home >> Backup >> Backup User Selection).

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

Warnings:

  • Backup Access Logs — Select Enable to back up your server's access logs and the /usr/local/apache/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. Use this 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 from the /var/lib/mysql/ directory.
Per Account and Entire MySQL DirectoryPerform a comprehensive backup that copies all of the databases for each individual account and 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.

  • The backup process and the transfer process use separate queues. If each backup completes 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 back up 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 and avoid potential risks.
  • We strongly recommend that you use unique filepaths when you store multiple-server backups in a shared filesystem. This action prevents backup file conflicts.
  • 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.

Warnings:

  • If you do not select the Retain backups in the default backup directory setting and do notspecify a destination in the Additional Destinations section, the system will return the following error:

    Error: Nowhere to back up: no enabled destinations found and retaining local copies is disabled.
  • If you do not select the Retain backups in the default backup directory setting, you will disable WHM's File and Directory Restoration interface (WHM >> Home >> Backups >> File Restoration) and hide cPanel's File and Directory Restoration interface (cPanel >> Home >> Files >> File Restoration). For more information, read the How to Manage Metadata Settings documentation.
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.

    • The location that you specify in the Default Backup Directory text box must match the mount point in the /etc/fstab file. Otherwise, the backup will fail and the system will log an error similar to the following message:

      You have enabled BACKUPMOUNT in the /var/cpanel/backups/config file, but there is no mount point that matches /mnt/disk/backupMAIN in the /etc/fstab file.
    • After the backup process finishes, the system dismounts the drive.

Warning:

When you set the toggle to Enable, you will disable WHM's File and Directory Restoration interface (WHM >> Home >> Backups >> File Restoration) and hide cPanel's File and Directory Restoration interface (cPanel >> Home >> Files >> File Restoration). For more information, read the How to Manage Metadata Settings documentation.

If you select Disable, the Backup Configuration process does not check the /etc/fstab file for a mounted backup drive.

Additional Destinations

You can save your backups to additional destinations. Select a destination type from the menu and click Create new destination. A new section for the selected destination type will appear.

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.

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 section, the system will return the following error:

Error: Nowhere to back up: no enabled destinations found and retaining local copies is disabled.


Notes:

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.

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.


Select a tab to view information for that destination type:

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 save data to another local filesystem.

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 this additional destination.

Backup Directory

Enter the directory path, relative to the account's home directory, 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 completes, the system dismounts the drive. 

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

Important:

To use this destination type, you must possess an Amazon S3 account. To create an account, 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 this additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Folder

Enter the name of the directory where you wish to store backups.

Notes:

This setting is optional.

Bucket

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

Note:

You must first create your bucket in the Amazon S3 management console.

Access Key ID

Enter the access key ID in this text box. Your server uses the access key to authenticate with the Amazon S3 account.

Note:

For more information about access keys for Amazon S3, read Amazon's Managing Access Keys for Your AWS Account documentation.

Secret Access Key

Enter the secret access key in this text box.

Note:

For more information about secret access keys for Amazon S3, read Amazon's Managing Access Keys for Your AWS Account documentation.

TimeoutThe 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 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. The system will retry the transfer when it runs the backup process again.

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 this additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Script

Enter your custom transport script's absolute path.

Note:

For more information on custom transport scripts, read the How to Create a Custom Transport Script for Backups documentation.

Backup Directory

Enter the directory path, relative to the account's home directory, 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.
TimeoutThe 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 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. The system will retry the transfer when it runs the backup process again.

Warnings:

  • Make certain that your FTP server supports the MLSD (Machine List Directory) or LIST commands. If the FTP server does not support these commands, the backup system cannot use the FTP server as a remote FTP server.

  • We strongly recommend that you use Pure-FTPD or ProFTPD on remote FTP servers. Unexpected results may occur with some FTP server software.

    • If you use Pure-FTPD, ensure that the DisplayDotFiles yes statement resides in the /etc/pure-ftpd.conf file.
    • If you use Pro-FTPD, ensure that the ListOptions -a statement resides in the /etc/proftpd.conf file.
  • If you use the Very Secure FTP daemon (vsftpd), ensure that you set the force_dot_files setting to yes in the /etc/vsftpd.conf file. For more information about vsftpd, read the vsftpd documentation.
  • 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 save data to another local filesystem.
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 this additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Backup Directory

Enter the directory path, relative to the account's home directory, 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.
TimeoutThe 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 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. The system will retry the transfer when it runs the backup process again.

Passive FTP

Select whether to use passive FTP.

Note:

FTP servers behind NAT firewalls require that you select Enable.

Important:

To use this destination type, you must possess a Google Drive account. To create a Google Drive account, visit the Google® Create your Google Account page.

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 this additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Folder

Enter a directory where you would like to store backups, relative to the remote account's directory root. The system will store backups under this directory in subdirectories which use a date-based naming convention.

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.
TimeoutThe 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 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. The system will retry the transfer when it runs the backup process again.

Note:

You can only use the Rsync transport with incremental backups.

Warning:

We recommend that you 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 save data to another local filesystem.

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 this additional destination.

Backup Directory

Enter the directory path, relative to the account's home directory, 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.
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, perform the following actions:

Enter the full path of the private key on this server in the Private Key text box.

  1. Click on a key's name in the Private Keys list to add that private key's filepath to the Private Key text box.

  2. To generate a new private key, click Generate a new key and then Generate Key. A success message will appear at the bottom of the interface.

  3. The private key resides in the /root/.ssh/keyname file, where keyname represents the key's name. The private key's corresponding public key resides in the /root/.ssh/keyname.pub file.

Enter 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.
Timeout
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 attempts to contact the server two additional times.

  • If the server does not respond after those attempts, the system administrator receives an email that notes the failed attempts. The system will retry the transfer when it runs the backup process again.

Note:

The interface currently only recognizes the default value of 30 seconds.

Important:

To use this destination type, you must possess an account with your S3-compatible provider.

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 this additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Folder

Enter the name of the directory where you wish to store your backup.

Notes:

This setting is optional.

S3 Endpoint

Enter the fully qualified domain name (FQDN) for the remote server where your bucket resides.

Note:

The system backs up files to the destination server through a secured connection via SSL/TLS. The FQDN that you enter must be the same as the FQDN on the server's SSL/TLS certificate, or the connection will fail.

Bucket

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

Note:

You must first create the bucket through your S3-compatible provider.

Access Key ID

Enter the access key ID in this text box. Your server uses the access key to authenticate with your S3-compatible account.

Note:

You must first generate an access key ID through your S3-compatible provider.

Secret Access Key

Enter the secret access key in this text box.

Note:

You must first generate a secret access key ID through your S3-compatible provider.

TimeoutThe 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 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. The system will retry the transfer when it runs the backup process again.

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 this additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Backup Directory

Enter the directory path, relative to the account's home directory, 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, perform the following actions:

Enter the full path of the private key on this server in the Private Key text box.

  1. Click on a key's name in the Private Keys list to add that private key's filepath to the Private Key text box.

  2. To generate a new private key, click Generate a new key and then Generate Key. A success message will appear at the bottom of the interface.

  3. The private key resides in the /root/.ssh/keyname file, where keyname represents the key's name. The private key's corresponding public key resides in the /root/.ssh/keyname.pub file.

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

TimeoutThe 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 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. The system will retry the transfer when it runs the backup process again.

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 this additional destination.

Warning:

Only transfer system backup files over encrypted connections.

Backup Directory

Enter the directory path, relative to the account's home directory, 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.
Port

The port to use to communicate with the remote server.

By default, WebDAV destinations use port 80. 

Secure connections use port 443.

cPanel & WHM uses port 2077 for non-SSL connections and port 2078 for SSL connections.

SSL Enabled

Select 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.
Timeout
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 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. The system will retry the transfer when it runs the backup process again.

Note:

The interface currently only recognizes the default value of 30 seconds.

Save Configuration

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

Note:

The Supports Incrementals? column indicates whether your selected transport can use incremental backups.

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

Additional documentation

cPanel, WebHost Manager, and WHM are registered trademarks of cPanel, Inc. for providing its computer software that facilitates the management and configuration of Internet web servers. ®2018 All rights reserved.