Child pages
  • WHM API 1 Functions - backup_destination_add
Skip to end of metadata
Go to start of metadata

Description

This function adds a backup destination.

Examples


 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/json-api/backup_destination_add?api.version=1&name=destination%20name&type=Local&path=%2Fmylocaldir&mount=0&no_mount_fail=0
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/backup_destination_add?api.version=1&name=destination%20name&type=Local&path=%2Fmylocaldir&mount=0&no_mount_fail=0
 Command Line
whmapi1 backup_destination_add name=destination_name type=Local path=%2Fmylocaldir mount=0 no_mount_fail=0


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.
  • If you run CloudLinux™, you must use the full path of the whmapi1 command:

    /usr/local/cpanel/bin/whmapi1

 Output (JSON)
{
    "data": {
        "id": "11111111"
    },
    "metadata": {
        "version": 1,
        "reason": "OK",
        "result": 1,
        "command": "backup_destination_add"
    }
}
 Output (XML)
<result>
   <data>
      <id>111111</id>
   </data>
   <metadata>
      <version>1</version>
      <reason>OK</reason>
      <result>1</result>
      <command>backup_destination_add</command>
   </metadata>
</result>


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
name
string

Required

The backup destination's name.

A valid string.
destination_name
typestring

Required

The type of transport.

Note:

The type value determines which additional parameters to use with the function.

  • Custom
  • FTP
  • Local
  • SFTP
  • WebDAV
  • AmazonS3

    Note:

    We added this transport type in version 11.42.

  • Rsync
  • GoogleDrive

    Note:

    We added these transport types in version 66.

  • S3Compatible

    Note:

    We added this transport type in version 74.

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

disabledBoolean

Required

Whether to disable the backup destination.

  • 1 — Disabled.
  • 0 — Enabled.
0
upload_system_backupstring

Whether to upload system backups.

This parameter defaults to off.

  • on — Enabled.
  • off — Disabled.
on

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

ReturnTypeDescriptionPossible valuesExample
idstring

The backup destination's ID.

A valid string.11111111