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.

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

Description

This function adds a transfer session to a queue.

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.

Examples


 JSON API

AccountLocal:

https://hostname.example.com:2087/cpsess##########/json-api/enqueue_transfer_item?api.version=1&transfer_session_id=vm5docscpanelcopya20140211211719FxjU&module=AccountLocal&user=username&size=1&localuser=username

AccountRemoteUser:

https://hostname.example.com:2087/cpsess##########/json-api/enqueue_transfer_item?api.version=1&user=user&transfer_session_id=remoteexamplecomnoroo20140501194105g7qG&module=AccountRemoteUser&localuser=username&overwrite_with_delete=1
AccountRemoteRoot:
https://hostname.example.com:2087/cpsess##########/json-api/enqueue_transfer_item?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU&module=AccountRemoteRoot&user=user&size=1&localuser=username&detected_remote_user=user&domain=example.com&replaceip=all&reseller=0&force=0&ip=0&skiphomedir=0&shared_mysql_server=0&skipres=1&skipacctdb=0&skipaccount=0&xferpoint=1&overwrite_with_delete=1
PackageRemoteRoot:
https://hostname.example.com:2087/cpsess##########/json-api/enqueue_transfer_item?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU&module=PackageRemoteRoot&package=package1

 XML API
https://hostname.example.com:2087/cpsess##########/xml-api/enqueue_transfer_item?api.version=1&transfer_session_id=vm5docscpanelcopya20140211211719FxjU&module=AccountRemoteUser&user=username&size=1&localuser=username&overwrite_with_delete=1
 Command Line
whmapi1 enqueue_transfer_item transfer_session_id=vm5docscpanelcopya20140211211719FxjU module=AccountRemoteUser user=username size=1 localuser=username overwrite_with_delete=1


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)


{
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "enqueue_transfer_item"
  }
}

 Output (XML)
<result>
    <metadata>
        <version>1</version>
        <reason>OK</reason>
        <result>1</result>
        <command>enqueue_transfer_item</command>
    </metadata>
</result>


Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample
transfer_session_id
string

Required

The transfer session's ID.

A valid string.
 Click to view...

 vm5docscpanelcopya20140211211719FxjU



modulestring

Required

The transfer system module.

  • LegacyAccountBackup This module restores legacy-account backup files.
  • FeatureListRemoteRoot This module transfers the feature list from the remote server.
  • PackageRemoteRoot This module transfers the package settings.
  • AccountLocal — This module restores backup files.
  • AccountRemoteRoot — This module uses the root credentials to transfer account settings that are not a part of a package.
  • AccountRemoteUser — This module uses the account's user credentials to transfer account settings that are not a part of a package.

Notes:

  • The module parameter determines which additional parameters to use with the function.
  • You must perform each module action as a separate step.

AccountRemoteRoot

sizeinteger

The size of the content to transfer.

This parameter defaults to 1.

A valid positive integer that measures the size of the content, in bytes.
1

Additional AccountLocalAccountRemoteRoot, and AccountRemoteUser parameters

 Click to view...
ParameterTypeDescriptionPossible valuesExample
userstring

Required

The account to transfer.

A valid username.user
localuserstring

Required

The local account's username.

Note:

If the user and localuser parameters do not match, you cannot use the skipacct or force parameters.

A valid username.localuser
detected_remote_userstringThe user account name that the remote server returns when you query the user account.A valid username.user
domainstringThe domain name.A valid string.example.com
ipBoolean

Whether to assign a dedicated IP address to the transferred account.

Note:

If no dedicated IP address exists, the system assigns the account to a shared IP address.

  • 1 — Assign a dedicated IP address.
  • 0 — Do not assign a dedicated IP address.
1
customipstring

The custom IP address to assign to the transferred account.

Note:

This parameter requires that the IP parameter has a value of 1.

A valid IP address.192.168.0.1
replaceipstringThe lines in the domain's zonefile to replace with the new IP address.
  • all — Replace all of the IP addresses in the zone file with the new IP address.
  • basic — Replace only the proxy, sub, mail, www, and main A records in the zone file with the new IP address.
all
resellerBooleanWhether to make the account a reseller.
  • 1 — Reseller account.
  • 0Not a reseller account.
0
forceBoolean

Whether to overwrite an account with an identical username.

This parameter performs the following actions:

  • Restores the cPanel account on the destination server.
  • Overwrites all account settings, data, and databases.
  • Ignores errors and warnings for naming conflicts.

Note:

  • The values you enter for the user and localuser parameters must match.
  • You cannot use this parameter if you called the WHM API 1 create_remote_root_transfer_session function with the unrestricted_restore parameter set to 1.
  • 1 — Overwrite the account.
  • 0 — Do not overwrite the account.
0
mail_locationstring

The server on which the account's email will reside after it completes the transfer.

Note:

  • We added this parameter in cPanel & WHM version 88.
  • The system will use the .local option if:
    • The system cannot use the cPanel & WHM linked server node when you call the .existing option.
    • The cPanel & WHM linked server node's ALIAS value is invalid.

This parameter defaults to .existing.

  • .local — The local server.
  • .existing — Use the location defined in the account's backup data.
  • ALIAS — A remote cPanel & WHM linked server node's alias. For example, the example-alias for the servernode.example.com domain.
example-alias
overwrite_sameowner_dbsBooleanWhether to allow the system to overwrite the account's existing databases with the databases in the backup file.
  • 1 — Overwrite
  • 0 — Do not overwrite.
0
overwrite_sameowner_dbusersBooleanWhether to allow the system to overwrite the account's existing database users with the database users in the backup file.
  • 1 — Overwrite
  • 0 — Do not overwrite.
0
overwrite_with_deleteBoolean

Whether to replace and delete all directories and files on the destination server. 

Warning:

If you use this parameter, the system deletes every directory and file on the destination server. The system does not delete the directories and files from the source server.

Note:

  • Only use this parameter for the AccountRemoteRoot and AccountRemoteUser modules.
  • We added this parameter in cPanel & WHM version 88.
  • 1 — Overwrite.
  • 0 — Do not overwrite.
1
skiphomedirBooleanWhether to skip the contents of the home directory.
  • 1 — Skip.
  • 0 — Restore.
0
shared_mysql_serverBoolean

Whether one of the following conditions is true:

  • The target and remote servers share the same remote MySQL server.
  • The target server is the remote MySQL server for the remote server.
  • The remote server is the remote MySQL server for the target server.
  • 1 — One is true.
  • 0 — None are true.
0
skipresBooleanWhether to skip restoration of the account's reseller permissions.
  • 1 — Skip.
  • 0 — Restore.
1
skipacctdbBooleanWhether to skip the transfer of the account's databases.
  • 1 — Skip.
  • 0 — Restore.
0
skipbwdataBooleanWhether to skip the transfer of the account's bandwidth data.
  • 1 — Skip.
  • 0 — Restore.
0
skipaccountBoolean

Whether to skip the recreation of the account.

Note:

This parameter is similar to the force parameter, but performs none of the account creation steps.

  • 1 — Skip.
  • 0 — Restore.
0
xferpointBoolean

Whether to use the Express Transfer feature.

Note:

Only use this parameter for the AccountRemoteRoot module.

  • 1 — Use.
  • 0 — Do not use.
0

Additional FeatureListRoot parameters

 Click to view...
ParameterTypeDescriptionPossible valuesExample
featureliststring

Required

The feature list's name.

A valid string.user_features

Additional LegacyAccountBackup parameters

 Click to view...
ParameterTypeDescriptionPossible valuesExample
userstring

Required

The account's username.

A valid string.user
restoretypestring

Required

The backup type to restore.

  • monthly
  • weekly
  • daily
daily
restoreallBooleanWhether to recreate the account on the target server.
  • 1 — Recreate.
  • 0 — Do not recreate.
0
restoreipBooleanWhether to assign the account's dedicated IP address that is stored in the backup file.
  • 1 — Assign.
  • 0 — Do not assign.
0
restoremailBooleanWhether to restore the account's mail data.
  • 1 — Restore.
  • 0 — Do not restore.
0
restoremysqlBooleanWhether to restore MySQL database data
  • 1 — Restore.
  • 0 — Do not restore.
0
restorebwdataBooleanWhether to restore bandwidth data.
  • 1 — Restore.
  • 0 — Do not restore.
0
restoresubsBooleanWhether to restore the account's subdomains.
  • 1 — Restore.
  • 0 — Do not restore.
0
unrestricted_restoreBoolean

Whether to bypass the Restricted Restore system.

Note:

We introduced this parameter in cPanel & WHM version 11.46.

  • 1 — Bypass.
  • 0 — Do not bypass.

    Note:

    In cPanel & WHM version 11.46, you must set this value to 1.

0
overwrite_all_dbsBoolean

Whether to allow the system to overwrite all of the account's databases with the databases in the backup file.

Note:

You may use only one of the following parameters:

  • overwrite_all_dbs
  • overwrite_sameowner_dbs
  • Both the mysql_dbs_to_restore and pgsql_dbs_to_restore parameters.

If you do not use any of these parameters, the system will restore all of the databases on the account, but will not overwrite any of them.

Warning:

The Restricted Restore feature does not allow an account to overwrite data that it does not own. If the transfer session's unrestricted_restore parameter has a value of 0, the overwrite_all_dbs parameter will automatically change to a value of 0 and the overwrite_sameowner_dbs parameter will change to a value of 1. This prevents the restore system from overwriting databases that the account does not own.

  • 1 — Overwrite.
  • 0 — Do not overwrite.
 0
overwrite_sameowner_dbsBooleanWhether to allow the system to overwrite the account's existing databases with the databases in the backup file.
  • 1 — Overwrite.
  • 0 — Do not overwrite.
0
overwrite_sameowner_dbusersBoolean

Whether to allow the system to overwrite the account's existing database users with the database users in the backup file.

  • 1 — Overwrite.
  • 0 — Do not overwrite.
0
mysql_dbs_to_restorestring

The MySQL databases to restore, which will overwrite those databases on the account.

Note:

The default value is to select and overwrite all databases.

Warning:

The Restricted Restore feature does not allow an account to overwrite data that it does not own. If the transfer session's unrestricted_restore parameter has a value of 0, this parameter is ignored.

A database name or list of database names.


msdb1,msdb2,msdb3
pgsql_dbs_to_restorestring

The PostgreSQL® databases to restore, which will overwrite those databases on the account.

If you do not use this parameter, the system selects and overwrites all databases.

Note:

The default value is to select and overwrite all databases.

Warning:

The Restricted Restore feature does not allow an account to overwrite data that it does not own. If the transfer session's unrestricted_restore parameter has a value of 0, the system ignores this parameter.

A database name or list of database names.


pgdb1,pgdb2,pgdb3

Additional PackageRemoteRoot parameters

 Click to view...
ParameterTypeDescriptionPossible valuesExample
packagestring

Required

The package's name

A valid string.user_package

Returns

This function only returns metadata.