We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.

We will continue to maintain our API documentation on this server.

Developer Documentation
Child pages
  • WHM API 1 Functions - backup_destination_get
Skip to end of metadata
Go to start of metadata

Guide to WHM API 1

Return Data

Filter Output

Sort Output

Paginate Output

Output Columns

Call cPanel API 2 and UAPI


 cPanel Analytics

participate_in_analytics


Description

Use this function to obtain a backup destination's settings.

Examples

 JSON API
https://hostname.example.com:2087/cpsess##########/json-api/backup_destination_get?api.version=1&id=0W1ei2rd3A4lI5sT6he7Be8st
 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/backup_destination_get?api.version=1&id=0W1ei2rd3A4lI5sT6he7Be8st
 Command Line
whmapi1 backup_destination_get id=0W1ei2rd3A4lI5sT6he7Be8st


Notes:

  • Unless otherwise noted, 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": {
        "disabled": "0",
        "local_subdir": "/",
        "mount": "0",
        "name": "destination name",
        "path": "/mylocaldir",
        "we_mounted_it": "0",
        "type": "Local",
        "id": "0W1ei2rd3A4lI5sT6he7Be8st",
        "no_mount_fail": "0"
    },
    "metadata": {
        "version": 1,
        "reason": "OK",
        "result": 1,
        "command": "backup_destination_get"
    }
}
 Output (XML)
<result>
   <data>
      <disabled>0</disabled>
      <local_subdir>/</local_subdir>
      <mount>0</mount>
      <name>destination name</name>
      <path>/mylocaldir</path>
      <we_mounted_it>0</we_mounted_it>
      <type>Local</type>
      <id>0W1ei2rd3A4lI5sT6he7Be8st</id>
      <no_mount_fail>0</no_mount_fail>
   </data>
   <metadata>
      <version>1</version>
      <reason>OK</reason>
      <result>1</result>
      <command>backup_destination_get</command>
   </metadata>
</result>


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
id
string

Required

The backup destination's ID.

A valid string.
0W1ei2rd3A4lI5sT6he7Be8st

Returns

ReturnTypeDescriptionPossible valuesExample
name
string

The backup destination's name.

A valid string.
destination
typestring

The type of backup destination.

Note:

This value determines which parameters you can use with the function.

  • Custom
  • FTP
  • Local
  • SFTP
  • WebDAV

  • AmazonS3

    Note:

    We added this backup destination type in cPanel & WHM version 11.42.

  • Rsync

    Note:

    We added this backup destination type in cPanel & WHM version 66.

  • GoogleDrive

    Note:

    We added this backup destination type in cPanel & WHM version 66.

  • S3Compatible

    Note:

    We added this backup destination type in cPanel & WHM version 74.

  • Backblaze

    Note:

    We added this backup destination type in cPanel & WHM version 78.

Local

disabledBoolean

Shows whether the backup destination is disabled.

  • 1 — The destination is disabled.
  • 0 — The destination is enabled.
0
disable_reasonstring

An error message that explains why the transport is disabled.

Note:

You will only see this return when the transport is disabled.

A valid string.Could not list files in destination: example

Additional AmazonS3 returns

 Click to view...

Note:

 The AmazonS3 type is available in cPanel & WHM version 11.42 and later.

ReturnTypeDescriptionPossible valuesExample
folderstringThe path to the backups directory.A valid file path, relative to the root directory.subfolder
bucketstring

The Amazon S3™ bucket.

A valid string.ChockFullOfNuts
aws_access_key_idstring

The Amazon S3 Access Key ID.

A valid string.123456789
timeoutstring

The session timeout.

A positive integer, in seconds.360

Additional Backblaze returns

 Click to view...

Note:

We added the Backblaze type in cPanel & WHM version 78.

ReturnTypeDescriptionPossible valuesExample
application_keystring

The application key's name.

A valid string.A123b45CD678e9
application_key_idstring

The application key ID that authenticates the Backblaze B2 account.

A valid string.12a345B678c9
bucket_idstring

The bucket's ID string.

A valid string.a12b34cd5678e9f
bucket_namestring

The bucket's name.

A valid string.ChockFullOfNuts
pathstring

The path to the backups directory on the remote server.

A valid file path.backups
timeoutinteger

The session timeout.

A positive integer, measured in seconds.

180

Additional Custom returns  

 Click to view...
ReturnsTypeDescriptionPossible valuesExample
scriptstring

The name of the user-supplied transport solution script.

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

The remote server's hostname.

A valid hostname. backups.example.com
pathstring

The path to the remote server's backups directory.

A valid file path./backups
timeoutstringThe session timeout.A positive integer, in seconds.360
usernamestring

The remote server account's username.

A valid username.username

Additional FTP returns

 Click to view...
ReturnTypeDescriptionPossible valuesExample
hoststring

The remote server's hostname.

A valid hostname.backups.example.com
portintegerThe remote server's FTP port.

A positive integer.

21
pathstring

The path to the remote server's backups directory.

A valid file path./backups
passiveBooleanWhether the remote server uses passive FTP.
  • 1 — Use passive FTP.
  • 0 — Use active FTP.
1
timeoutstringThe session timeout.A positive integer, in seconds.360
usernamestring

The remote server account's username.

A valid username.username

Additional GoogleDrive returns

 Click to view...

Note:

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

ReturnTypeDescriptionPossible valuesExample
folderstring

The path to the backups directory on the remote server.

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

The Google Drive client ID.

A valid string.aBcdeFgHIjK123
client_secretstring

The Google Drive client secret.

A valid string.

aBcde123FgHIjK456
timeoutinteger

The session timeout.

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

Additional Local returns

 Click to view...
ReturnTypeDescriptionPossible valuesExample
mountBoolean

Whether the path is mounted.

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

The path to the backups directory.

A valid absolute file path./home/backups
no_mount_failBooleanWhether the backup attempt will fail if the mount fails.
  • 1 — Fail the backup attempt.
  • 0 — Do not fail the backup attempt.
0

Additional Rsync returns

 Click to view...

Note:

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

ReturnTypeDescriptionPossible valuesExample
hoststring

The remote server's hostname.

A valid string.www.s3example.com
port integerThe remote server's port.A positive integer.21
folderstring

The path to the backups directory on the remote server.

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

The type of authorization to use to access the remote server.

  • password
  • key
ChockFullOfNuts
usernamestringThe username with which to access the remote server.A valid account name.user
passwordstringThe password for the username on the remote server.A valid string.12345lugage
privatekeystringIf the authtype return's value is key, the the private key file's path.A valid absolute file path./home/backups/key
timeoutinteger

The session timeout.

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

Additional S3Compatible returns

 Click to view...

Note:

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

ReturnTypeDescriptionPossible valuesExample
hoststring

The S3-compatible provider's server.

A valid string.www.s3example.com
folderstring

The path to the backups directory on the remote server.

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

The S3-compatible bucket.

A valid string.ChockFullOfNuts
aws_access_key_idstring

The S3-compatible provider key ID.

A valid string.123456789
timeoutinteger

The session timeout.

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

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

A secure password.12345luggage

Additional SFTP returns

 Click to view...
ReturnTypeDescriptionPossible valuesExample
hoststring

The remote server's hostname.

A valid hostname.backups.example.com
portintegerThe remote server's FTP port.

A positive integer.

21
pathstring

The path to the remote server's backups directory.

A valid file path./backups
timeoutstringThe session timeout.A positive integer, in seconds.360
usernamestring

The remote server account's username.

A valid username.username

authtype

string

The authorization type.

  • password
  • key

password

privatekeystringIf the authtype return's value is key, the the private key file's path.A valid absolute file path./home/backups/key

Additional WebDAV returns

 Click to view...
ReturnTypeDescriptionPossible valuesExample
hoststring

The remote server's hostname.

A valid hostname.backups.example.com
portintegerThe remote server's FTP port.

A positive integer.

21
pathstring

The path to the remote server's backups directory.

A valid file path./backups
sslBooleanWhether the remote server uses SSL.
  • 1 — Use SSL.
  • 0 — Do not use SSL.
1
timeoutstringThe session timeout.A positive integer, in seconds.360
usernamestring

The remote server account's username.

A valid username.username

Function information

API Version:

WHM API 1

Available in:

WHM 11.38+

Methods:

GET, POST

Required Parameters:

id

Return Formats:

JSON, XML

Important:

cPanel & WHM version 66 deprecated XML output.

About WHM API 1

WHM API 1 performs functions and accesses data in WHM.

Notes:

  • Some functions and parameters may require that you authenticate as the root user.
  • You must use the appropriate WHM ports (2086 or 2087) to call WHM API functions.

Find a function

Related functions