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

Description

This function creates a transfer session as the root user.

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
userroot
passwordroot'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
userrootroot
sshkey

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
userThe username.The username.
passwordThe user's password.The user's password.
root_escalation_methodsudosu
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:

Parametersudosu
userThe username.The username.
sshkeyThe 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_methodsudosu
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:

  • 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

ParameterTypeDescriptionPossible valuesExample
hoststring

Required

The remote server's hostname or IP address.

A valid hostname or IP address.remote.example.com
portinteger

Required

The remote server's SSH port number.

A positive integer.22
userstring

Required

The username to use to connect to the remote server.

A valid username.root
passwordstring

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_methodstring

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_passwordstring

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_namestring

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_passphrasestring

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_threadsinteger

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_restoreBoolean

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.

1
copy_reseller_privsBoolean

Required

Whether to transfer reseller privileges.

  • 1 — Transfer.
  • 0 — Do not transfer.
1
compressedBoolean

Required

Whether to compress data before transfer.

  • 1 — Compress.
  • 0 — Do not compress.
1
unencryptedBoolean

Required

Whether to not use SSL to encrypt data.

  • 1 — Use SSL.
  • 0 — Do not 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_priorityBoolean

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_pkgacctBoolean

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_userstring

Note:

We deprecated this parameter in cPanel & WHM version 11.46.

  
sphera_passwordstring

Note:

We deprecated this parameter in cPanel & WHM version 11.46.

  
sphera_hoststring

Note:

We deprecated this parameter in cPanel & WHM version 11.46.

  

Returns

ReturnTypeDescriptionPossible valuesExample

analyze_rawout

stringThe 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_rawoutstringThe 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_idstringThe transfer session's ID.A valid string.
vm5docscpanelcopya20140430200606V06z