Update the system's backup configuration

This function configures a server's backup system. The system saves these settings in the /var/cpanel/backups/config file.

SecurityBasicAuth
Request
query Parameters
backup_daily_enable
integer
Default: 1

Whether to enable daily backups.

  • 1 — Enable.
  • 0 — Disable.
Enum: 0 1
Example: backup_daily_enable=1
backup_daily_retention
integer >= 0
Default: 5

The number of daily backups to retain.

Example: backup_daily_retention=5
backup_monthly_dates
integer [ 1 .. 31 ]
Default: 1

Which days of the month to run backups.

Note:

To add multiple days, use a comma-delimited list.

Example: backup_monthly_dates=1
backup_monthly_enable
integer
Default: 0

Whether to enable monthly backups.

  • 1 — Enable.
  • 0 — Disable.
Enum: 0 1
Example: backup_monthly_enable=0
backup_monthly_retention
integer >= 0
Default: 1

The number of monthly backups to retain.

Example: backup_monthly_retention=5
backup_weekly_day
integer [ 1 .. 6 ]
Default: 0

Which day of the week to run weekly backups.

  • 0 — Sunday.
  • 1 — Monday.
  • 2 — Tuesday.
  • 3 — Wednesday.
  • 4 — Thursday.
  • 5 — Friday.
  • 6 — Saturday.
Example: backup_weekly_day=1
backup_weekly_enable
integer
Default: 0

Whether to enable weekly backups.

  • 1 — Enable.
  • 0 — Disable.
Enum: 0 1
Example: backup_weekly_enable=0
backup_weekly_retention
integer >= 0
Default: 4

The number of weekly backups to retain.

Example: backup_weekly_retention=4
backupaccts
integer
Default: 1

Whether to back up cPanel user accounts.

  • 1 — Back up.
  • 0 — Do not back up.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

Enum: 0 1
Example: backupaccts=1
backupbwdata
integer
Default: 1

Whether to back up bandwidth tracking data.

  • 1 — Back up.
  • 0 — Do not back up.
Enum: 0 1
Example: backupbwdata=1
backupdays
string [ 0 .. 6 ]
Default: "0,2,4,6"

Which days of the week to run daily backups.

  • 0 — Sunday.
  • 1 — Monday.
  • 2 — Tuesday.
  • 3 — Wednesday.
  • 4 — Thursday.
  • 5 — Friday.
  • 6 — Saturday.

Note:

For multiple days, use a comma-delimited list.

Example: backupdays=0,1,2,3,4,5,6
backupdir
string
Default: "/backup"

The primary backup directory.

Example: backupdir=/backup
backupenable
integer
Default: 0

Whether to enable backups.

  • 1 — Enable.
  • 0 — Disable.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

Enum: 0 1
Example: backupenable=0
backupfiles
integer
Default: 1

Whether to back up system files.

  • 1 — Back up.
  • 0 — Do not back up.
Enum: 0 1
Example: backupfiles=1
backuplogs
integer
Default: 0

Whether to back up the error logs.

  • 1 — Back up.
  • 0 — Do not back up.
Enum: 0 1
Example: backuplogs=0
backupmount
integer
Default: 0

Whether to mount a backup partition.

  • 1 — Mount.
  • 0 — Do not mount.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

Enum: 0 1
Example: backupmount=0
backupsuspendedaccts
integer
Default: 0

Whether to back up suspended accounts.

  • 1 — Back up.
  • 0 — Do not back up.
Enum: 0 1
Example: backupsuspendedaccts=0
backuptype
string
Default: "compressed"

The type of backup to create.

  • compressed
  • uncompressed
  • incremental
Enum: "compressed" "uncompressed" "incremental"
Example: backuptype=compressed
check_min_free_space
integer
Default: 1

Whether to ensure that the destination server possesses the minimum free disk space available.

  • 1 — Check the free disk space on the destination server.
  • 0 — Do not check the free disk space on the destination server.
Enum: 0 1
Example: check_min_free_space=1
disable_metadata
integer
Default: 0

Whether the backup system will create metadata when a backup runs.

  • 1 — Disable metadata creation.
  • 0 — Enable metadata creation.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

Enum: 0 1
Example: disable_metadata=0
errorthreshhold
integer >= 0
Default: 3

The number of times that the system will try to use the additional backup destination.

Example: errorthreshhold=3
force_prune_daily
integer
Default: 0

Whether to strictly enforce the value of the backup_daily_retention parameter.

  • 1 — Strictly enforce the backup_daily_retention parameter.
  • 0 — Only enforce the backup_daily_retention parameter after a successful complete backup.
Enum: 0 1
Example: force_prune_daily=0
force_prune_monthly
integer
Default: 0

Whether to strictly enforce the value of the backup_monthly_retention parameter.

  • 1 — Strictly enforce the backup_monthly_retention parameter.
  • 0 — Only enforce the backup_monthly_retention parameter after a successful complete backup.
Enum: 0 1
Example: force_prune_monthly=0
force_prune_weekly
integer
Default: 0

Whether to strictly enforce the value of the backup_weekly_retention parameter.

  • 1 — Strictly enforce the backup_weekly_retention parameter.
  • 0 — Only enforce the backup_weekly_retention parameter after a successful complete backup.
Enum: 0 1
Example: force_prune_weekly=0
gziprsyncopts
string
Default: ""

The gzip environment variables.

Example: gziprsyncopts=--rysncable
keeplocal
integer
Default: 1

Whether to delete backups from the local directory.

  • 1 — Delete.
  • 0 — Do not delete.

Note:

This setting affects whether the system enables the File and Directory Restoration interfaces in cPanel and in WHM. For more information, read the How to Manage Metadata Settings documentation.

Enum: 0 1
Example: keeplocal=1
linkdest
integer
Default: 0

Whether to check the rsync function for hardlink support.

  • 1 — Check.
  • 0 — Do not check.
Enum: 0 1
Example: linkdest=0
localzonesonly
integer
Default: 0

Whether to use a local zone file from the /var/named/domain.tld file or the dnsadmin daemon, where domain.tld represents the target domain.

  • 1 — Use the /var/named/domain.tld file.
  • 0 — Use dnsadmin.
Enum: 0 1
Example: localzonesonly=0
maximum_restore_timeout
integer >= 0
Default: 21600

How long a restoration will attempt to run, in seconds. If the restoration does not succeed in this amount of time, it will stop.

Example: maximum_restore_timeout=21600
maximum_timeout
integer >= 0
Default: 7200

How long a backup will attempt to run, in seconds. If the backup does not succeed in this amount of time, it will stop.

Example: maximum_timeout=7200
min_free_space
integer >= 0
Default: 5

The minimum amount of free disk to check for on the destination server.

Note:

If the value of the min_free_space_unit parameter is percent, the maximum value is 100.

Example: min_free_space=1024
min_free_space_unit
string
Default: "percent"

The units of measurement of disk space for the min_free_space return.

  • MB — Megabytes.
  • percent — Percent available.
Enum: "MB" "percent"
Example: min_free_space_unit=MB
mysqlbackup
string
Default: "accounts"

The backup method to use for MySQL® databases.

  • accounts — Back up databases in each account's archive.
  • dir — Back up the entire MySQL directory.
  • both — Back up databases in each account's archive and the entire MySQL directory.
Enum: "accounts" "dir" "both"
Example: mysqlbackup=accounts
postbackup
integer
Default: 0

Whether to run the /usr/local/cpanel/scripts/postcpbackup script after the backup finishes.

  • 1 — Run.
  • 0 — Do not run.
Enum: 0 1
Example: postbackup=0
prebackup
integer
Default: 1

Whether to run the /usr/local/cpanel/scripts/precpbackup script before the system processes backups.

  • 1 — Run.
  • 0 — Do not run.
Enum: 0 1
Example: prebackup=1
psqlbackup
integer
Default: 0

Whether to back up PostgreSQL® databases.

  • 1 — Back up.
  • 0 — Do not back up.
Enum: 0 1
Example: psqlbackup=0
remote_restore_staging_dir
string

The directory that temporarily stores a remote backup's data during a backup restoration. The data is a compressed (.tar.gz) or uncompressed (.tar) account tarball.

Important:

The system restores backups one at a time. The backup staging directory must be large enough to contain the largest remote backup file that you wish to restore. For example, if you wish to restore three backups, sized 1.5 GB, 528 MB, and 950 MB each, your backup staging directory must be able to hold at least 1.5 GB.

Note:

The system empties the directory after the system restores the backup.

Example: remote_restore_staging_dir=/backup
Responses
200

HTTP Request was successful.

Response Schema: application/json
object
get/backup_config_set
Request samples 
whmapi1 --output=jsonpretty \
  backup_config_set
Response samples
application/json
{
  • "metadata": {
    • "command": "backup_config_set",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}
©2025 WebPros International, LLC All rights reserved.Privacy PolicyTrademarks