- Created by Documentation, last modified on Feb 18, 2019
disable_authentication_provider
disable_failing_authentication_providers
enable_authentication_provider
get_available_authentication_providers
get_provider_client_configurations
get_provider_configuration_fields
get_provider_display_configurations
get_users_authn_linked_accounts
set_provider_client_configurations
set_provider_display_configurations
twofactorauth_generate_tfa_config
twofactorauth_get_user_configs
cpgreylist_is_server_netblock_trusted
cpgreylist_list_entries_for_common_mail_provider
cpgreylist_load_common_mail_providers_config
cpgreylist_save_common_mail_providers_config
cpgreylist_trust_entries_for_common_mail_provider
cpgreylist_untrust_entries_for_common_mail_provider
create_cpgreylist_trusted_host
delete_cpgreylist_trusted_host
Description
This function creates a transfer session as the root
user.
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 | 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 containsPermitRootLogin=No
, you must use another user and their password on the remote server, and then escalate to theroot
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 theroot
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. |
| 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
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©_reseller_privs=0&compressed=0&unencrypted=0&low_priority=0
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©_reseller_privs=0&compressed=0&unencrypted=0&low_priority=0
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:
- 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
{ "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" } }
<result> <data> <analyze_rawout>Fetching information from remote host: “10.1.100.35” … … Done Fetching information from remote host: “10.1.100.35” … … Done </analyze_rawout> <create_rawout>Basic credential check … … Done Fetching information from remote host: “10.1.100.35” … … Done Fetching WHM Version … Done Testing “vm5.docs.cpanel.net” for transfer streaming support with password authentication....<strong>Streaming Supported</strong> Remote Server Type: “WHM1130” </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:
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 |
| sudo |
root_password | string |
Note: Use this parameter if the | A secure password. | 12345luggage |
sshkey_name | string | The SSH key's name. Notes:
| 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 |
| 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. |
Note: If you use cPanel & WHM version 11.46, you must set this parameter to a value of If you want to pass the | 1 |
copy_reseller_privs | Boolean | Required Whether to transfer reseller privileges. |
| 1 |
compressed | Boolean | Required Whether to compress data before transfer. |
| 1 |
unencrypted | Boolean | Required Whether to not use SSL to encrypt data. |
| 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 |
low_priority | Boolean | Required Whether to run the remote server processes at low priority in order to reduce impact on server performance. |
| 1 |
enable_custom_pkgacct | Boolean | Required Whether to use a custom |
| 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 |
---|---|---|---|---|
| string | The HTML output from the analysis of the remote server connection. | A valid string. | Click to view... Fetching information from remote host: “10.1.100.35” … … Done Fetching information from remote host: “10.1.100.35” … … Done
|
create_rawout | string | The HTML output from the creation of the remote server connection. | A valid string. | Click to view... Basic credential check … … Done Fetching information from remote host: “10.1.100.35” … … Done Fetching WHM Version … Done Testing “vm5.docs.cpanel.net” for transfer streaming support with password authentication....<strong>Streaming Supported</strong> Remote Server Type: “WHM1130” |
transfer_session_id | string | The transfer session's ID. | A valid string. | vm5docscpanelcopya20140430200606V06z |
Function information
API Version:
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:
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
or2087
) to call WHM API functions.
Find a function
Related functions
-
Page:WHM API 1 Functions - restore_modules_summary — This function lists backup modules and their descriptions.
-
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 - available_transfer_modules — This function lists all available transfer modules.
-
Page:WHM API 1 Functions - create_remote_root_transfer_session — This function creates a transfer session as the
root
user.