Child pages
  • WHM API 1 Functions - backup_destination_set
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. 

 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
  • SFTP
  • WebDAV
  • Local
  • Custom
  • We added this transport type in version 11.42:
    • AmazonS3
  • We added these transport types in version 66:
    • Rsync
    • GoogleDrive
  • We added this transport type in version 74:
    • S3Compatible

Warning:

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

  • Amazon S3™
  • Rsync
  • S3 Compatible
  • SFTP
  • WebDAV with SSL Enabled

Local

disabled Boolean

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.Could not list files in destination: example
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 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 on the remote server.

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
timeoutinteger

Required

The session timeout.

A positive integer between 30 and 300, measured in seconds.30
passwordstring

Required

The Amazon S3 Access Key'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
timeoutinteger

The session timeout.

This parameter defaults to 30.

A positive integer between 30 and 300, measured in seconds.300
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 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
timeoutinteger

The session timeout.

This parameter defaults to 30.

A positive integer between 30 and 300, measured in seconds.300
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 GoogleDrive parameters

 Click to view...

Note:

 We added the GoogleDrive type in cPanel & WHM version 66.

ParameterTypeDescriptionPossible valuesExample
folderstring

The path to the backups directory on the remote server.

This parameter defaults to a blank value.

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

Required

The Google Drive client ID.

A valid string.aBcdeFgHIjK123
client_secretstring

Required

The Google Drive client secret.

A valid string.

aBcde123FgHIjK456
timeoutinteger

The session timeout.

This parameter defaults to 30.

A positive integer between 30 and 300, measured in seconds.300

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 S3Compatible parameters

 Click to view...

Note:

 We added the S3Compatible type in cPanel & WHM version 74.

ParameterTypeDescriptionPossible valuesExample
hoststring

Required

The S3-compatible provider's server.

A valid string.www.s3example.com
folderstring

The path to the backups directory on the remote server.

This parameter defaults to a blank value.

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

Required

The S3-compatible bucket.

A valid string.ChockFullOfNuts
aws_access_key_idstring

Required

The S3-compatible provider key ID.

A valid string.123456789
timeoutinteger

Required

The session timeout.

A positive integer between 30 and 300, measured in seconds.300
passwordstring

Required

The S3-compatible provider key's password or secret.

A secure password.12345luggage

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
timeoutinteger

The session timeout.

This value defaults to 30.

A positive integer between 30 and 300, measured in seconds.300
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
timeoutinteger

The session timeout.

This parameter defaults to 30.

A positive integer between 30 and 300, measured in seconds.300
usernamestring

Required

The remote server account's username.

A valid username.username
passwordstring

Required

The remote server account's password.

A secure password.12345luggage

Returns

This function only returns metadata.