Create remote server transfer session as root user

This function creates a transfer session as the root user.

Important:

For 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:

Authenticate as root

If you use SSH to authenticate as the root user, the remote server's SSH must accept root logins. For more information read OpenSSH's sshd_config documentation.

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 an 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.

Authenticate as a user

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

  • If the remote server forbids root logins, you must use another user and their password on the remote server, and then escalate to the root user. For more information read OpenSSH's sshd_config documentation.
  • 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.
SecurityBasicAuth
Request
query Parameters
comm_transport
required
string
Default: "ssh"

The method by which the transfer system will execute commands on the remote system.

  • ssh — Use SSH. The function uses the remote server's indicated SSH port value.
  • whostmgr — Use the remote server's secure WHM port. This will reject invalid TLS handshakes.
  • whostmgr_insecure — Use the remote server's secure WHM port, but ignores any TLS verification failures.
Enum: "ssh" "whostmgr" "whostmgr_insecure"
Example: comm_transport=ssh
compressed
required
integer

Whether to compress data before transfer.

  • 1 — Compress.
  • 0 — Do not compress.
Enum: 0 1
Example: compressed=1
copy_reseller_privs
required
integer

Whether to transfer reseller privileges.

  • 1 — Transfer.
  • 0 — Do not transfer.
Enum: 0 1
Example: copy_reseller_privs=1
enable_custom_pkgacct
required
integer

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.
Enum: 0 1
Example: enable_custom_pkgacct=1
required
string or string

The remote server's hostname or IP address.

Example: host=192.168.0.0
low_priority
required
integer

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.
Enum: 0 1
Example: low_priority=1
restore_threads
required
integer >= 1

The number of CPU threads to use for restore sessions.

Example: restore_threads=1
transfer_threads
required
integer >= 1

The number of CPU threads to use for transfer sessions.

Example: transfer_threads=1
unencrypted
required
integer

Whether to not use SSL to encrypt data.

  • 1 — Do not use SSL.
  • 0 — Use SSL.
Enum: 0 1
Example: unencrypted=0
unrestricted_restore
required
integer

Whether to skip the Restricted Restore system.

  • 1 — Skip.
  • 0 — Do not skip.

Note:

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.

Enum: 0 1
Example: unrestricted_restore=1
use_backups
required
integer

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.
Enum: 0 1
Example: use_backups=1
user
required
string

The username to use to connect to the remote server.

Example: user=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.

Example: password=123456luggage
port
integer [ 1 .. 65535 ]
Default: 22

The remote server's SSH port number.

Example: port=22
root_escalation_method
string

The escalation method to use to connect to the remote server.

  • su
  • sudo

Note:

Use this parameter if the sshd_config file's PermitRootLogin value is No.

Enum: "su" "sudo"
Example: root_escalation_method=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.

Example: root_password=123456luggage
sshkey_name
string

The SSH key's name.

Note:

  • 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).
Example: sshkey_name=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.

Example: sshkey_passphrase=kkwtoowoygidsa
Responses
200

HTTP Request was successful.

Response Schema: application/json
object
object
get/create_remote_root_transfer_session
Request samples 
whmapi1 --output=jsonpretty \
  create_remote_root_transfer_session \
  host='192.168.0.0' \
  user='root' \
  transfer_threads='1' \
  restore_threads='1' \
  unrestricted_restore='1' \
  comm_transport='ssh' \
  copy_reseller_privs='1' \
  compressed='1' \
  unencrypted='0' \
  use_backups='1' \
  low_priority='1' \
  enable_custom_pkgacct='1'
Response samples
application/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": "vm5docscpanelcopya20140430200606V06z"
    },
  • "metadata": {
    • "command": "create_remote_root_transfer_session",
    • "reason": "OK",
    • "result": 1,
    • "version": 1
    }
}
©2024 WebPros International, LLC All rights reserved.Privacy PolicyTrademarks