WHM API 1 Functions - create_remote_root_transfer_session

The source and target servers must be able to communicate over port 2087 to use this feature. They must also be able to communicate over the port that your servers use for SSH connections. For more information about the ports that cPanel & WHM uses, read our How to Configure Your Firewall for cPanel Services documentation.

Note:

For more information about how this function works with other functions in the transfer and restore process, read our Guide to Transfer and Restore API Functions documentation.

Authentication

There are several methods that you can use to authenticate a transfer session with the remote server:

`PermitRootLogin=Yes`

The simplest authentication method is to use the root user and password. To do this, the sshd_config file on the remote server must contain the following value: PermitRootLogin=Yes

The following table displays the correct parameters and values for this authentication method:

Parameter	Value
`user`	`root`
`password`	`root`'s password

You can also use the SSH public key to authenticate the root user. If the SSH public key is encrypted, include the SSH key's passphrase.

The following table displays the correct parameters and values for this authentication method:

Parameter	Value if the SSH Key is not encrypted	Value if the SSH Key is encrypted
`user`	`root`	`root`
`sshkey_name`	The `root` user's SSH key.	The `root` user's SSH key.
`sshkey_passphrase`	(none)	The `root` user's SSH key passphrase.

`PermitRootLogin=No`

Many server administrators do not permit direct root logins on their servers.

If the remote server's sshd_config file contains PermitRootLogin=No, you must use another user and their password on the remote server, and then escalate to the root user.
If the system administrator used WHM's Manage Wheel Group Users interface (WHM >> Home >> Security Center >> Manage Wheel Group Users) to grant the user su access, then you will need to specify su and the root password.
If the user has sudo access, you do not need the root password.

The following table displays the correct parameters and values for this authentication method:

Parameter	Value if the user has `sudo` access	Value if the user has `su` access
`user`	The username.	The username.
`password`	The user's password.	The user's password.
`root_escalation_method`	`sudo`	`su`
`root_password`	(none)	The `root` user's password.

You can also use an SSH public key instead of a password to authenticate that user. If the SSH public key is encrypted, include the SSH key's passphrase.

The following table displays the correct parameters and values for this authentication method:

Parameter	`sudo`	`su`
`user`	The username.	The username.
`sshkey_name`	The user's SSH key.	The user's SSH key.
`sshkey_passphrase` (If encrypted)	The user's SSH key passphrase.	The user's SSH key passphrase.
`root_escalation_method`	`sudo`	`su`
`root_password`	(none)	The `root` user's password.

Examples

JSON API

https://hostname.example.com:2087/cpsess##########/json-api/create_remote_root_transfer_session?api.version=1&remote_server_type=cpanel&host=remote.example.com&port=22&user=root&password=12345luggage&transfer_threads=1&restore_threads=1&unrestricted_restore=1&copy_reseller_privs=0&compressed=0&unencrypted=0&low_priority=0

XML API

https://hostname.example.com:2087/cpsess##########/xml-api/create_remote_root_transfer_session?api.version=1&remote_server_type=cpanel&host=remote.example.com&port=22&user=root&password=12345luggage&transfer_threads=1&restore_threads=1&unrestricted_restore=1&copy_reseller_privs=0&compressed=0&unencrypted=0&low_priority=0

Command Line

whmapi1 create_remote_root_transfer_session remote_server_type=cpanel host=remote.example.com port=22 user=root password=12345luggage transfer_threads=1 restore_threads=1 unrestricted_restore=1 copy_reseller_privs=0 compressed=0 unencrypted=0 low_priority=0

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": {
    "analyze_rawout":
 "Fetching information from remote host: \u201c10.1.100.35\u201d \u2026 
\u2026\nDone\nFetching information from remote host: 
\u201c10.1.100.35\u201d \u2026 \u2026\nDone\n",
    "create_rawout":
 "Basic credential check \u2026 \u2026\nDone\nFetching information from 
remote host: \u201c10.1.100.35\u201d \u2026 \u2026\nDone\nFetching WHM 
Version \u2026\nDone\nTesting \u201cvm5.docs.cpanel.net\u201d for 
transfer streaming support with password 
authentication....<strong>Streaming 
Supported</strong>\nRemote Server Type: \u201cWHM1130\u201d\n",
    "transfer_session_id": "vm5docscpanelcopya20140430200447f69g"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "create_remote_root_transfer_session"
  }
}

Output (XML)

<result>
    <data>
        <analyze_rawout>Fetching information from remote host: &#x201C;10.1.100.35&#x201D; &#x2026; &#x2026;
        Done
        Fetching information from remote host: &#x201C;10.1.100.35&#x201D; &#x2026; &#x2026;
        Done
    </analyze_rawout>
    <create_rawout>Basic credential check &#x2026; &#x2026;
    Done
    Fetching information from remote host: &#x201C;10.1.100.35&#x201D; &#x2026; &#x2026;
    Done
    Fetching WHM Version &#x2026;
    Done
    Testing
 &#x201C;vm5.docs.cpanel.net&#x201D; for transfer streaming 
support with password authentication....<strong>Streaming 
Supported</strong>
    Remote Server Type: &#x201C;WHM1130&#x201D;
</create_rawout>
<transfer_session_id>vm5docscpanelcopya20140430200606V06z</transfer_session_id>
</data>
<metadata>
    <version>1</version>
    <reason>OK</reason>
    <result>1</result>
    <command>create_remote_root_transfer_session</command>
</metadata>
</result>

Note:

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

Parameters

Parameter	Type	Description	Possible values	Example
`host`	string	Required The remote server's hostname or IP address.	A valid hostname or IP address.	`remote.example.com`
`port`	integer	Required The remote server's SSH port number.	A positive integer.	`22`
`user`	string	Required The username to use to connect to the remote server.	A valid username.	`root`
`password`	string	The username's password. Note: Use this parameter if you will authenticate to the remote server with a password. Do not use this parameter if you will authenticate to the remote server with an SSH key.	A secure password.	`12345luggage`
`root_escalation_method`	string	The escalation method to use to connect to the remote server. Note: Use this parameter if the `sshd_config` file's `PermitRootLogin` value is `No`.	`su` `sudo`	`sudo`
`root_password`	string	`root`'s password on the remote server. Note: Use this parameter if the `sshd_config` file's `PermitRootLogin` value is `No` and you will use the `root` user's password to escalate access.	A secure password.	`12345luggage`
`sshkey_name`	string	The SSH key's name. Notes: Use this parameter if you will authenticate to the remote server with an SSH key. Do not use this parameter if you will authenticate to the remote server with a password. SSH keys are available in WHM's Manage root's SSH Keys interface (WHM >> Home >> Security Center >> Manage root’s SSH Keys).	A valid string.	`FrancisScott`
`sshkey_passphrase`	string	The SSH key's passphrase. Note: Use this parameter if you will authenticate to the remote server with an SSH key, and the key is encrypted.	A secure passphrase.	`kkwtoowoygidsa`
`transfer_threads`	integer	Required The number of CPU threads to use for transfer sessions.	A valid integer.	`1`
`restore_threads`	string	Required The number of CPU threads to use for restore sessions.	A valid integer.	`1`
`unrestricted_restore`	Boolean	Required Whether to skip the Restricted Restore system. Note: We introduced this parameter in cPanel & WHM version 11.46.	`1` — Skip. `0` — Do not skip. Note: If you use cPanel & WHM version 11.46, you must set this parameter to a value of `1`. If you want to pass the `force` parameter in the WHM API 1 enqueue_transfer_item function, you must set this parameter to a value of `0`.	`1`
`copy_reseller_privs`	Boolean	Required Whether to transfer reseller privileges.	`1` — Transfer. `0` — Do not transfer.	`1`
`compressed`	Boolean	Required Whether to compress data before transfer.	`1` — Compress. `0` — Do not compress.	`1`
`unencrypted`	Boolean	Required Whether to not use SSL to encrypt data.	`1` — Do not use SSL. `0` — Use SSL.	`0`
`use_backups`	Boolean	Required Whether to use an existing backup instead of packaging the data again if the backup is less than 24 hours old.	`1` — Use an existing backup. `0` — Package the data.	`1`
`low_priority`	Boolean	Required Whether to run the remote server processes at low priority in order to reduce impact on server performance.	`1` — Run at low priority. `0` — Run at high priority.	`1`
`enable_custom_pkgacct`	Boolean	Required Whether to use a custom `pkgacct` scripts on the remote server for the transfer session.	`1` — Use a custom `pkgacct` script. `0` — Do not use a custom script.	`1`
`sphera_user`	string	Note: We deprecated this parameter in cPanel & WHM version 11.46.
`sphera_password`	string	Note: We deprecated this parameter in cPanel & WHM version 11.46.
`sphera_host`	string	Note: We deprecated this parameter in cPanel & WHM version 11.46.

Returns

Return Type Description Possible values Example

analyze_rawout

string

The HTML output from the analysis of the remote server connection.

A valid string.

Click to view...

Fetching information from remote host: &#x201C;10.1.100.35&#x201D; &#x2026; &#x2026;
        Done
        Fetching information from remote host: &#x201C;10.1.100.35&#x201D; &#x2026; &#x2026;
        Done

create_rawout

string

The HTML output from the creation of the remote server connection.

A valid string.

Click to view...

Basic credential check &#x2026; &#x2026;
    Done
    Fetching information from remote host: &#x201C;10.1.100.35&#x201D; &#x2026; &#x2026;
    Done
    Fetching WHM Version &#x2026;
    Done
    Testing
 &#x201C;vm5.docs.cpanel.net&#x201D; for transfer streaming 
support with password authentication....<strong>Streaming 
Supported</strong>
    Remote Server Type: &#x201C;WHM1130&#x201D;

transfer_session_id

string

The transfer session's ID.

A valid string.

vm5docscpanelcopya20140430200606V06z

Function information

API Version:

WHM API 1

Available in:

WHM 11.44+

Methods:

GET, POST

Required Parameters:

host, port, user, transfer_threads, restore_threads, unrestricted_restore, copy_reseller_privs, compressed, unencrypted, use_backups, enable_custom_pkgacct, low_priority

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

Page:

WHM API 1 Functions - abort_transfer_session — This function aborts an active transfer session.
Page:

WHM API 1 Functions - analyze_transfer_session_remote — This function checks the remote server's credentials, which a transfer session uses to connect.
Page:

WHM API 1 Functions - remote_basic_credential_check — This function checks the SSH credentials on the remote server.
Page:

WHM API 1 Functions - restore_modules_summary — This function lists backup modules and their descriptions.
Page:

Guide to Transfer and Restore API Functions

Child pages

WHM API 1 Functions - create_remote_root_transfer_session

Description

Authentication

PermitRootLogin=Yes

PermitRootLogin=No

Examples

Parameters

Returns

Function information

About WHM API 1

Find a function

Search

Related functions

`PermitRootLogin=Yes`

`PermitRootLogin=No`