WHM API 1 Function Calls – Transfer and Restore Walkthrough

WHM API 1 Function Calls – Transfer and Restore Walkthrough

Overview

There are several WHM API 1 function calls that are involved in the Transfer and Restore process. This document explains the relationship between these API calls and the order in which you should use them.

Note

For more information about each function, such as the input and output parameters, click the function’s name.

Function calls in order

Plan the transfer session

Function Calls
Description
WHM API 1 Functions – available_transfer_modules This function lists the available transfer modules. These are the modules into which you will enqueue sessions.
WHM API 1 Functions – transfer_module_schema This function displays the transfer module schema. This will help you format the input parameters for the items that you wish to transfer.

Start the transfer session

Stage Order Function Call Description
CREATE 1 WHM API 1 – create_remote_user_transfer_session These functions create remote transfer sessions. This is where you provide the credentials to log in to the remote server.
CHECK 2 WHM API 1 – retrieve_transfer_session_remote_analysis This function performs an analysis on a transfer session. This will provide you with a list of accounts the system will transfer and how much space they will use on the target server.
3 WHM API 1 – validate_system_user This function validates whether you can create a system account on the target server. This will help you avoid account name conflicts.
QUEUE 4 WHM API 1 – enqueue_transfer_item This function allows you to add a transfer item to the transfer queue. Transfer items are accounts and packages that you wish to transfer in a transfer session.
START 5 WHM API 1 – start_transfer_session This function starts the transfer session.

Monitor the transfer session

You can use the following function calls at any stage of the transfer and restore process:

Function Call
Description
WHM API 1 – get_transfer_session_state This function checks the status of a transfer session.
WHM API 1 – fetch_transfer_session_log This function displays a transfer session log.
WHM API 1 – pause_transfer_session This function pauses an active transfer session. To restart a transfer session, use WHM API 1 – start_transfer_session again.

Walkthrough for Root Transfer Session

In this example, we have two servers: remote.example.com and local.example.com.

We are logged into the local server with the security token cpsess1234567890

We want to transfer the site transferme.com that is owned by the account transferme from the remote server to the local server.

The size of transferme.com is 123,456,789 bytes.

Also, we want to transfer the package package1 from the remote server to the local server.

Finally, the root password for the remote server is abcd1234.

Plan the transfer session

Note

If you already know the modules that you need and the schema of each module, you can skip this step.

The next step is to retrieve a list of the transfer modules that are available on your server. Use the WHM API 1 – available_transfer_modules function call as follows:

URL: https://local.example.com:2087/cpsess1234567890/json-api/available_transfer_modules?api.version=1
PHP:
 Click to view…

 This will return a list of transfer modules as follows:

 Click to view…

 

In our example, we will to use the FeatureListRemoteRoot module to transfer the feature lists, PackageRemoteRoot module to transfer packages, and AccountRemoteRoot to transfer the accounts. We will need the schema of each transfer module to format the data for transfer.

The WHM API 1 – transfer_module_schema function call retrieves each schema for us:

URL: https://local.example.com:2087cpsess1234567890/json-api/transfer_module_schema?api.version=1&module=FeatureListsRemoteRoot

https://local.example.com:2087/cpsess1234567890/json-api/transfer_module_schema?api.version=1&module=PackageRemoteRoot

https://local.example.com:2087/cpsess1234567890/json-api/transfer_module_schema?api.version=1&module=AccountRemoteRoot

PHP:
 Click to view…
 Click to view…
 Click to view…

The results of each schema will resemble the following:

 Click to view…

 

Create the transfer session

The first step in the process is to create the transfer session. Use the WHM API 1 – create_remote_root_transfer_session function call as follows:

URL: https://local.example.com:2087/cpsess1234567890/json-api/create_remote_root_transfer_session?api.version=1&remote_server_type=cpanel&host=remote.example.com&port=22&user=root&password=abcd1234&transfer_threads=1&restore_threads=1&unrestricted_restore=1&copy_reseller_privs=0&enable_custom_pkgacct=1&compressed=0&unencrypted=0&low_priority=0
PHP:
 Click to view…

This function call generates a transfer session ID in the transfer_session_id output parameter:

 Click to view…

 

The transfer session ID is remoteexamplecopya20140211211719FxjU.

Check the transfer session

At this point, analyze the transfer session with the WHM API 1 – retrieve_transfer_session_remote_analysis function call to confirm that it contains all of the items that you wish to transfer.

URL: https://local.example.com:2087/cpsess1234567890/json-api/retrieve_transfer_session_remote_analysis?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU
PHP:
 Click to view…

This will return a list of transfer session settings, local and remote groups and users, databases and database users, and packages and accounts (items) that the transfer session contains.

 Click to view…

 

Notice that the items and the dbs containers are empty. We will fill those containers with accounts, packages, databases, and database users soon.

To validate whether you can transfer a username to the target server, use the WHM API 1 – validate_system_user function call to ensure that the username is not reserved or currently in use.

URL: https://local.example.com:2087/cpsess1234567890/json-api/validate_system_user?api.version=1&user=transferme
PHP:
 Click to view…

The results contain several boolean values that you can use to check the username:

 Click to view…

Queue the transfer item

At this point, we will use the WHM API 1 – enqueue_transfer_item function call to add a transfer item (package or account) to the transfer session. The structure of the function call depends on the transfer module into which we wish to enqueue the transfer item.

URL: https://local.example.com:2087/cpsess1234567890/json-api/enqueue_transfer_item?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU&module=AccountRemoteRoot&user=transferme&size=123456789&localuser=transferme&detected_remote_user=transferme&domain=transferme.com&replaceip=all&reseller=0&force=0&ip=0&skiphomedir=0&shared_mysql_server=0&skipres=1&skipacctdb=0&skipaccount=0&xferpoint=1
PHP:
 Click to view…

This function does not return much more than a success message:

 Click to view…

 

We also need to add the transfer of the package1 package to the queue, which we can do with the following:

URL: https://local.example.com:2087/cpsess1234567890/json-api/enqueue_transfer_item?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU&module=PackageRemoteRoot&package=package1
PHP:
 Click to view…

Confirmation

If we run the WHM API 1 – retrieve_transfer_session_remote_analysis function call again, it will show that we have added package and accounts to the items container and databases and database users to the dbscontainer of the transfer session.

 Click to view…

 

Start the transfer session

After you add all the transfer items to the transfer session, start the transfer session with the WHM API 1 – start_transfer_session function call.

URL: https://local.example.com:2087/json-api/cpsess1234567890/start_transfer_session?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU
PHP:
 Click to view…

The function call returns the process ID that handles the transfer session.

 Click to view…

 

Congratulations, you have started the transfer session.

Monitor the transfer session

To determine the state of a transfer session, use the WHM API 1 – get_transfer_session_state function call.

URL: https://local.example.com:2087/cpsess1234567890/json-api/get_transfer_session_state?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU
PHP:
 Click to view…

It will respond with one of the following states:

  • TRANSFER_PENDING
  • TRANSFER_INPROGRESS
  • RESTORE_PENDING
  • RESTORE_INPROGRESS
  • COMPLETED
  • FAILED

The following example shows that the transfer session is in progress:

 Click to view…

 

Since the transfer session is in progress, we can take a look at the master log for the transfer session with the WHM API 1 – fetch_transfer_session_log function call:

URL: https://local.example.com:2087/cpsess1234567890/json-api/fetch_transfer_session_log?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU&logfile=master.log
PHP:
 Click to view…

The following example shows the contents of a log file:

 Click to view…

 

You will need to create a script to parse this log file to determine the progress of the transfer or restore operation.

Pause and restart the transfer session

URL: https://local.example.com:2087/json-api/pause_transfer_session?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU
PHP:
 Click to view…

The success message will be minimal:

 Click to view…

 

If you wish to restart the transfer session, use the WHM API 1 – start_transfer_session function call again:

URL: https://local.example.com:2087/cpsess1234567890/json-api/start_transfer_session?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU
PHP:
 Click to view…

 

Walkthrough for User Transfer Session

In this example, we have two servers: remote.example.com and local.example.com.

We are logged into the local server with the security token cpsess1234567890

We want to transfer the site transferme.com that is owned by the account transferme from the remote server to the local server.

The size of transferme.com is 123,456,789 bytes.

Finally, the password for the account transferme on the remote server is abcd1234.

Plan the transfer session

The only transfer queue that you will use for a user-based transfer session is AccountRemoteUser.

Create the transfer session

The first step in the process is to create the transfer session. Use the WHM API 1 – create_remote_user_transfer_session function call as follows:

URL: https://local.example.com:2087/cpsess1234567890/json-api/create_remote_user_transfer_session?api.version=1&host=remote.example.com&password=abcd1234!&unrestricted_restore=1
PHP:
 Click to view…

This function call will generate a transfer session ID in the transfer_session_id output parameter:

 Click to view…

The transfer session ID is remoteexamplecopya20140211211719FxjU.

Check the transfer session

To validate whether a username can be transferred to the target server, use the WHM API 1 – validate_system_user function call to ensure that the username isn’t reserved or currently in use.

URL: https://local.example.com:2087/cpsess1234567890/json-api/validate_system_user?api.version=1&user=transferme
PHP:
 Click to view…

The results contain several boolean values that you can use to check the username:

 Click to view…

Queue the transfer item

At this point, we use the WHM API 1 – enqueue_transfer_item function call to add a transfer item (package or account) to the transfer session. The structure of the function call depends on the transfer module into which we wish to enqueue the transfer item.

URL: https://local.example.com:2087/cpsess1234567890/json-api/enqueue_transfer_item?api.version=1&user=transferme&transfer_session_id=remoteexamplecomnoroo20140501194105g7qG&module=AccountRemoteUser&localuser=transferme
PHP:
 Click to view…

This function does not return much more than a success message:

 Click to view…

 

Start the transfer session

After you add all the transfer items to the transfer session, start the transfer session with the WHM API 1 – start_transfer_session function call.

URL: https://local.example.com:2087/cpsess1234567890/json-api/start_transfer_session?api.version=1&transfer_session_id=remoteexamplecomnoroo20140501194105g7qG
PHP:
 Click to view…

The function call returns the process ID that handles the transfer session.

 Click to view…

 

Congratulations, you have started the transfer session.

Monitor the transfer session

To determine the state of a transfer session, use the WHM API 1 – get_transfer_session_state function call.

URL: https://local.example.com:2087/cpsess1234567890/json-api/get_transfer_session_state?api.version=1&transfer_session_id=remoteexamplecomnoroo20140501194105g7qG
PHP:
 Click to view…

It will respond with one of the following states:

  • TRANSFER_PENDING
  • TRANSFER_INPROGRESS
  • RESTORE_PENDING
  • RESTORE_INPROGRESS
  • COMPLETED
  • FAILED

The following example shows that the transfer session is in progress:

 Click to view…

 

Since the transfer session is in progress, we can take a look at the master log for the transfer session with the WHM API 1 – fetch_transfer_session_log function call:

URL: https://local.example.com:2087/cpsess1234567890/json-api/fetch_transfer_session_log?api.version=1&transfer_session_id=remoteexamplecomnoroo20140501194105g7qG&logfile=master.log
PHP:
 Click to view…

The following example shows the contents of a log file:

 Click to view…

You will need to create a script to parse this log file to determine the progress of the transfer or restore operation.

Pause and restart the transfer session

URL: https://local.example.com:2087/json-api/pause_transfer_session?api.version=1&transfer_session_id=remoteexamplecomnoroo20140501194105g7qG
PHP:
 Click to view…

The success message will be minimal:

 Click to view…

 

If you wish to restart the transfer session, use the WHM API 1 – start_transfer_session function call again:

URL: https://local.example.com:2087/cpsess1234567890/start_transfer_session?api.version=1&transfer_session_id=remoteexamplecomnoroo20140501194105g7qG

Was this article helpful?

Related Articles

Leave A Comment?