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

 

Description

This function edits a backup destination's configuration settings.

Examples 


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/backup_destination_set?api.version=1&type=name=WebDav&id=0W1ei2rd3A4lI5sT6he7Be8st&name=WebDavPlace&upload_system_backup=off&ssl=1&path=%2Fhome%2Fexample&port=21&host=hostname.example.com&username=username&timeout=30&password=12345luggage
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/backup_destination_set?api.version=1&type=name=WebDav&id=0W1ei2rd3A4lI5sT6he7Be8st&name=WebDavPlace&upload_system_backup=off&ssl=1&path=%2Fhome%2Fexample&port=21&host=hostname.example.com&username=username&timeout=30&password=12345luggage
 Command Line
whmapi1 backup_destination_set type=name=WebDav id=0W1ei2rd3A4lI5sT6he7Be8st name=WebDavPlace upload_system_backup=off ssl=1 path=/home/example port=21 host=hostname.example.com username=username timeout=30 password=12345luggage

Notes:

  • You must URI-encode values.
  • For more information and additional output options, read our Guide to WHM API 1 documentation or run the whmapi1 --help command. 
  • We introduced this functionality in cPanel & WHM version 11.52.0.8.

 Output (JSON)
{
    "metadata": {
        "version": 1,
        "reason": "OK",
        "result": 1,
        "command": "backup_destination_set"
    }
}
 Output (XML)
<result>
   <metadata>
      <version>1</version>
      <reason>OK</reason>
      <result>1</result>
      <command>backup_destination_set</command>
   </metadata>
</result>


Note:

Use WHM's API Shell interface (WHM >> Home >> Development >> API Shell) to directly test WHM API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
idstring

Required

The backup destination IDs.

A valid string.0W1ei2rd3A4lI5sT6he7Be8st
name
string

The backup destination's name.

Note:

If you do not set this parameter, the system retains the current setting.

A valid string.
destination
typestring

The type of transport.

Notes:

  • The type value determines which additional parameters to use with the function.
  • If you do not set this parameter, the system retains the current setting.
  • FTP
  • Local
  • SFTP
  • WebDav
  • Custom
  • AmazonS3

Warning:

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

  • Amazon S3™
  • SFTP
  • WebDAV with SSL Enabled

Local

disabledBoolean

Whether to disable the backup destination.

Note:

If you do not set this parameter, the system retains the current setting.

  • 1 — Disabled.
  • 0 — Enabled.
0
disable_reasonstring

An error message that explains why the backup is disabled.

Note:

If you do not set this parameter, the system retains the current setting.

A valid string.proton decay
upload_system_backupstring

Whether to upload the system files.

Note:

If you do not set this parameter, the system retains the current setting.

  • on — Upload.
  • off — Do not upload.
off

Additional FTP parameters

 Click to view...
ParameterTypeDescriptionPossible valuesExample
hoststring

Required

The remote server's hostname.

A valid hostname.backups.example.com
portinteger

The remote server's FTP port.

This parameter defaults to 21.

 

A positive integer.

21
pathstring

Required

The path to the backups directory on the remote server.

A valid file path./backups
passiveBoolean

Whether to use passive FTP.

This parameter defaults to 1.

  • 1 — Use passive FTP.
  • 0 — Use active FTP.
1
timeoutstring

The session timeout.

This parameter defaults to 30.

A positive integer, in seconds.360
usernamestring

Required

The remote server account's username.

A valid username.username
passwordstring

Required

The remote server account's password.

A secure password.12345luggage

Additional local parameters

 Click to view...
ParameterTypeDescriptionPossible valuesExample
mountBoolean

Whether the path is mounted.

This parameter defaults to 0.

  • 1 — The path is mounted.
  • 0 — The path is not mounted.
0
pathstring

Required

The path to the backups directory.

A valid absolute file path./home/backups
no_mount_failBoolean

Whether to fail the backup attempt if the mount fails.

This parameter defaults to a blank value.

  • 1 — Fail the backup attempt.
  • 0 — Do not fail the backup attempt.
0

Additional sftp parameters

 Click to view...
ParameterTypeDescriptionPossible valuesExample
hoststring

Required

The remote server's hostname.

A valid hostname.backups.example.com
portinteger

The remote server's FTP port.

This parameter defaults to 21.

A positive integer.

21
pathstring

Required

The path to the backups directory on the remove server.

A valid file path./backups
timeoutstring

The session timeout.

This value defaults to 30.

A positive integer, in seconds.360
usernamestring

Required

The remote server account's username.

A valid username.username

authtype

string

Required

The authorization type.

  • password
  • key

password

passwordstring

If the authtype parameter's value is password, the remote server account's password.

This parameter defaults to a blank value.

A secure password.12345luggage
privatekeystring

If the authtype parameter's value is key, the path to the private key file.

This parameter defaults to a blank value.

A valid absolute file path./home/backups/key
passphrasestring

If the authtype parameter's value is key, the private key file's passphrase.

This parameter defaults to a blank value.

A secure passphrase.12345luggage

Additional webdav parameters

 Click to view...
ParameterTypeDescriptionPossible valuesExample
hoststring

Required

The remote server's hostname.

A valid hostname.backups.example.com
portinteger

The remote server's FTP port.

This parameter defaults to 21.

A positive integer.

21
pathstring

Required

The path to the backups directory on the remove server.

A valid file path./backups
sslBoolean

Whether to use SSL.

This parameter defaults to 1.

  • 1 — Use SSL.
  • 0 — Do not use SSL.
1
timeoutstring

The session timeout.

This parameter defaults to 30.

A positive integer, measured in seconds.360
usernamestring

Required

The remote server account's username.

A valid username.username
passwordstring

Required

The remote server account's password.

A secure password.12345luggage

Additional custom parameters  

 Click to view...
ParameterTypeDescriptionPossible valuesExample
scriptstring

Required

The name of the user-supplied transport solution script.

A valid absolute file path./home/backups/beammeupscotty.pl
hoststring

Required

The remote server's hostname.

A valid hostname.backups.example.com
pathstring

Required

The path to the backups directory on the remove server.

A valid file path./backups
timeoutstring

The session timeout.

This parameter defaults to 30.

A positive integer, measured in seconds.360
usernamestring

Required

The remote server account's username.

A valid username.username
passwordstring

Required

The remote server account's password.

A secure password.12345luggage

Additional AmazonS3 parameters

 Click to view...

Note:

 We added the AmazonS3 type in cPanel & WHM version 11.42.

ParameterTypeDescriptionPossible valuesExample
folderstring

The path to the backups directory.

This parameter defaults to a blank value.

A valid file path, relative to the root directory.subfolder
bucketstring

Required

The Amazon S3™ bucket.

A valid string.ChockFullOfNuts
aws_access_key_idstring

Required

The Amazon S3 Access Key ID.

A valid string.123456789
timeoutstring

Required

The session timeout.

A positive integer, measured in seconds.360
passwordstring

Required

The Amazon S3 Access Key's password.

A secure password.12345luggage

Returns

This function only returns metadata.