Page tree
Skip to end of metadata
Go to start of metadata

Overview

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

Note:

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

Functions in order

Plan the transfer session

functionsDescription
WHM API 1 Functions - available_transfer_modulesThis function lists the available transfer modules. These are the modules into which you will enqueue sessions.
WHM API 1 Functions - transfer_module_schemaThis 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

StageOrderfunctionDescription
CREATE1

WHM API 1 - create_remote_user_transfer_session

or

WHM API 1 Functions - create_remote_root_transfer_session

These functions create remote transfer sessions. This is where you provide the credentials to log in to the remote server.
CHECK2WHM API 1 - retrieve_transfer_session_remote_analysisThis 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.
3WHM API 1 - validate_system_userThis function validates whether you can create a system account on the target server. This will help you avoid account name conflicts.
QUEUE4WHM API 1 - enqueue_transfer_itemThis 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.
START5WHM API 1 - start_transfer_sessionThis function starts the transfer session.

Monitor the transfer session

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

functionDescription
WHM API 1 - get_transfer_session_stateThis function checks the status of a transfer session.
WHM API 1 - fetch_transfer_session_logThis function displays a transfer session log.
WHM API 1 - pause_transfer_sessionThis function pauses an active transfer session. To restart a transfer session, use the start_transfer_session function again.

Walkthrough for Root Transfer Session

In this example, the following statements are true:

  • We have two servers: remote.example.com and hostname.example.com.
  • We are logged into the local server with the security token cpsess##########
  • We want to transfer the site example.com that is owned by the account username from the remote server to the local server.
  • The size of example.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 luggage12345.  

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 as follows:

URL:

https://hostname.example.com:2087/cpsess##########/json-api/available_transfer_modules?api.version=1

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1);
$_result = $xmlapi->xmlapi_query('available_transfer_modules' , $settings);

print $_result;

 This will return a list of transfer modules as follows:

 Click to view...

 {
  "data": {
    "modules": {
      "LegacyAccountBackup": "6000",
      "FeatureListRemoteRoot": "1000",
      "PackageRemoteRoot": "2000",
      "AccountLocal": "5000",
      "AccountRemoteRoot": "3000",
      "AccountRemoteUser": "4000"
    }
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "available_transfer_modules"
  }
}

 

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 retrieves each schema for us:

URL:

https://hostname.example.com:2087/cpsess##########/json-api/transfer_module_schema?api.version=1&module=FeatureListsRemoteRoot
 
https://hostname.example.com:2087/cpsess##########/json-api/transfer_module_schema?api.version=1&module=PackageRemoteRoot
 
https://hostname.example.com:2087/cpsess##########/json-api/transfer_module_schema?api.version=1&module=AccountRemoteRoot

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'module' => 'FeatureListRemoteRoot');
$_result = $xmlapi->xmlapi_query('transfer_module_schema' , $settings);

print $_result;
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'module' => 'PackageRemoteRoot');
$_result = $xmlapi->xmlapi_query('transfer_module_schema' , $settings);

print $_result;
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'module' => 'AccountRemoteRoot');
$_result = $xmlapi->xmlapi_query('transfer_module_schema' , $settings);

print $_result;

The results of each schema will resemble the following:

 Click to view...

 {
  "data": {
    "schema": {
      "keys": {
        "detected_remote_user": {
          "def": "char(255) DEFAULT NULL"
        },
        "ip": {
          "def": "int(1) DEFAULT 0"
        },
        "skipbwdata": {
          "def": "int(1) DEFAULT 0"
        },
        "customip": {
          "def": "char(255) DEFAULT NULL"
        },
        "size": {
          "def": "BIGINT UNSIGNED DEFAULT 1"
        },
        "shared_mysql_server": {
          "def": "int(1) DEFAULT 0"
        },
        "domain": {
          "def": "char(255) DEFAULT NULL"
        },
        "cpmovefile": {
          "def": "text"
        },
        "skiphomedir": {
          "def": "int(1) DEFAULT 0"
        },
        "user": {
          "def": "char(255) DEFAULT NULL"
        },
        "skipacctdb": {
          "def": "int(1) DEFAULT 0"
        },
        "skipres": {
          "def": "int(1) DEFAULT 0"
        },
        "reseller": {
          "def": "int(1) DEFAULT 0"
        },
        "skipaccount": {
          "def": "int(1) DEFAULT 0"
        },
        "copypoint": {
          "def": "text"
        },
        "force": {
          "def": "int(1) DEFAULT 0"
        },
        "xferpoint": {
          "def": "int(1) DEFAULT 0"
        },
        "replaceip": {
          "def": "char(255) DEFAULT NULL"
        },
        "localuser": {
          "def": "char(255) DEFAULT NULL"
        }
      },
      "required": [
        "user",
        "localuser"
      ],
      "primary": [
        "user"
      ]
    }
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "transfer_module_schema"
  }
}

 

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 as follows:

URL:

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

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_debug(1);
$xmlapi->set_output('json');

$settings = array(
    'api.version'=>1, 
    'remote_server_type' => 'cpanel', 
    'host' => 'remote.example.com', 
    'port' => '22', 
    'user' => 'root', 
    'password' => 'luggage12345', 
    'transfer_threads' => '1', 
    'restore_threads' => '1', 
    'enable_custom_pkgacct' => '1', 
    'unrestricted_restore' => '1', 
    'copy_reseller_privs' => '0', 
    'compressed' => '0', 
    'unencrypted' => '0', 
    'low_priority' => '0'
);

$_result = $xmlapi->xmlapi_query('create_remote_root_transfer_session' , $settings);

print $_result;

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

 Click to view...

{
  "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"
  }
}

 

The transfer session ID is vm5docscpanelcopya20140430200606V06z.

Check the transfer session

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

URL:

https://hostname.example.com:2087/cpsess##########/json-api/retrieve_transfer_session_remote_analysis?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id' => 'remoteexamplecopya20140211211719FxjU');
$_result = $xmlapi->xmlapi_query('retrieve_transfer_session_remote_analysis' , $settings);

print $_result;

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...
{  "data": {
    "options": {
      "skip_reseller_privs": null,
      "unrestricted": "0"
    },
    "transfer_session_id": "vm5docscpanelnoroo201402251939519hmy",
    "config": {
      "shared_mysql_server": null
    },
    "local": {
      "groups": {
        "never": 1,
        "gonna": 1,
        "give": 1,
        "you": 1,
        "up": 1
      },
      "users": {
        "never": 1,
        "gonna": 1,
        "let": 1,
        "you": 1,
        "down": 1
      },
      "dbs": null,
      "available_ips": [
         
      ]
    },
    "remote": {
      "version": 0,
      "resellers": {
         
      },
      "has_disk_used": 0,
      "dbs": null,
      "host": null,
      "has_xfertool": 0,
      "has_owners": 0,
      "server_type": null
    },
    "items": {
      "packages": [
         
      ],
      "accounts": [
         
      ]
    }
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "retrieve_transfer_session_remote_analysis"
  }
}

 

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 to ensure that the username is not reserved or currently in use.

URL:

https://hostname.example.com:2087/cpsess##########/json-api/validate_system_user?api.version=1&user=username

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'user' => 'transferme');
$_result = $xmlapi->xmlapi_query('validate_system_user' , $settings);

print $_result;

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

 Click to view...
{
  "data": {
    "valid_for_transfer": 1,
    "reserved": 1,
    "exists": 1,
    "valid_for_new": 1
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "validate_system_user"
  }
}

Queue the transfer item

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

URL:

https://hostname.example.com:2087/cpsess##########/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...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array(
 'api.version'=>1, 
 'transfer_session_id' => 'remoteexamplecomnoroo20140501194105g7qG', 
 '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', 
 'skipbwdata' => '0', 
 'skipaccount' => '0', 
 'xferpoint' => '1'
);
$_result = $xmlapi->xmlapi_query('enqueue_transfer_item' , $settings);

print $_result;

This function only returns metadata:

 Click to view...

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

 

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

URL:

https://hostname.example.com:2087/cpsess##########/json-api/enqueue_transfer_item?api.version=1&transfer_session_id=remoteexamplecopya20140211211719FxjU&module=PackageRemoteRoot&package=package1

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array(
 'api.version' => '1', 
 'transfer_session_id' => "remoteexamplecopya20140211211719FxjU',
 'module' => 'PackageRemoteRoot',
 'package' => 'package1'
);
$_result = $xmlapi->xmlapi_query('enqueue_transfer_item' , $settings);

print $_result;

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.

URL:

https://hostname.example.com:2087/cpsess##########/json-api/start_transfer_session?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG');
$_result = $xmlapi->xmlapi_query('start_transfer_session' , $settings);

print $_result;

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

 Click to view...

{
  "data": {
    "pid": "90210"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "start_transfer_session"
  }
}

 

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.

URL:

https://hostname.example.com:2087/cpsess##########/json-api/get_transfer_session_state?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG');
$_result = $xmlapi->xmlapi_query('get_transfer_session_state' , $settings);

print $_result;

It will respond with one of the following states:

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

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

 Click to view...

{
  "data": {
    "state_name": "TRANSFER_INPROGRESS"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "get_transfer_session_state"
  }
}

 

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:

URL:

https://hostname.example.com:2087/cpsess##########/json-api/fetch_transfer_session_log?api.version=1&transfer_session_id=vm5docscpanelcopya20140224163412sylG&logfile=master.log

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array(
    'api.version'=>1, 
    'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG' , 
    'logfile' => 'master.log'
);
$_result = $xmlapi->xmlapi_query('fetch_transfer_session_log' , $settings);

print $_result;

The following example shows the contents of a log file:

 Click to view...

 {
  "data": {
    "log":
 
"{\"pid\":\"14358\",\"contents\":{\"action\":\"start\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"copyacct\",\"action\":\"initiator\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"1.6\",\"action\":\"version\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"3\",\"action\":\"queue_count\",\"queue\":\"TRANSFER\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"3\",\"action\":\"queue_count\",\"queue\":\"RESTORE\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"vm5.docs.cpanel.net\",\"action\":\"remotehost\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14360\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"action\":\"start\",\"queue\":\"TRANSFER\",\"item_name\":\"Account\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14360\",\"contents\":{\"msg\":\"item-TRANSFER_AccountRemoteRoot_fredfred\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"TRANSFER\",\"child_number\":1,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_fredfred\"},\"type\":\"control\"}\n{\"pid\":\"14361\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"action\":\"start\",\"queue\":\"TRANSFER\",\"item_name\":\"Account\",\"child_number\":2},\"type\":\"control\"}\n{\"pid\":\"14361\",\"contents\":{\"msg\":\"item-TRANSFER_AccountRemoteRoot_colin\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"TRANSFER\",\"child_number\":2,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_colin\"},\"type\":\"control\"}\n{\"pid\":\"14362\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"action\":\"start\",\"queue\":\"TRANSFER\",\"item_name\":\"Account\",\"child_number\":3},\"type\":\"control\"}\n{\"pid\":\"14362\",\"contents\":{\"msg\":\"item-TRANSFER_AccountRemoteRoot_stacy\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"TRANSFER\",\"child_number\":3,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_stacy\"},\"type\":\"control\"}\n{\"pid\":\"14362\",\"contents\":{\"msg\":{\"warnings\":0,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":null,\"altered_items\":null},\"skipped_items\":0,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"TRANSFER\",\"child_number\":3,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_stacy\"},\"type\":\"control\"}\n{\"pid\":\"14361\",\"contents\":{\"msg\":{\"warnings\":0,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":null,\"altered_items\":null},\"skipped_items\":0,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"TRANSFER\",\"child_number\":2,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_colin\"},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"action\":\"start\",\"queue\":\"RESTORE\",\"item_name\":\"Account\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"msg\":\"item-RESTORE_AccountRemoteRoot_stacy\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"logfile\":\"item-RESTORE_AccountRemoteRoot_stacy\"},\"type\":\"control\"}\n{\"pid\":\"14365\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"action\":\"start\",\"queue\":\"RESTORE\",\"item_name\":\"Account\",\"child_number\":2},\"type\":\"control\"}\n{\"pid\":\"14365\",\"contents\":{\"msg\":\"item-RESTORE_AccountRemoteRoot_colin\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"RESTORE\",\"child_number\":2,\"logfile\":\"item-RESTORE_AccountRemoteRoot_colin\"},\"type\":\"control\"}\n{\"pid\":\"14360\",\"contents\":{\"msg\":{\"warnings\":0,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":null,\"altered_items\":null},\"skipped_items\":0,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"TRANSFER\",\"child_number\":1,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_fredfred\"},\"type\":\"control\"}\n{\"pid\":\"14360\",\"contents\":{\"action\":\"complete\",\"queue\":\"TRANSFER\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14362\",\"contents\":{\"action\":\"complete\",\"queue\":\"TRANSFER\",\"child_number\":3},\"type\":\"control\"}\n{\"pid\":\"14361\",\"contents\":{\"action\":\"complete\",\"queue\":\"TRANSFER\",\"child_number\":2},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"msg\":{\"warnings\":2,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":[],\"altered_items\":[]},\"skipped_items\":10,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"logfile\":\"item-RESTORE_AccountRemoteRoot_stacy\"},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"action\":\"start\",\"queue\":\"RESTORE\",\"item_name\":\"Account\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"msg\":\"item-RESTORE_AccountRemoteRoot_fredfred\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"logfile\":\"item-RESTORE_AccountRemoteRoot_fredfred\"},\"type\":\"control\"}\n{\"pid\":\"14365\",\"contents\":{\"msg\":{\"warnings\":4,\"dangerous_items\":1,\"contents\":{\"dangerous_items\":[[[\"Mysql\",\"_restore_mysql\",104],\"MySQL:
 Skipping grants for these MySQL databases: colin_%. These databases 
don't exist in the 
archive.\",null]],\"altered_items\":[[[\"Mysql\",\"_update_dbname\",437],\"mySQL
 database \u201ccolin_testdatabase\u201d restored as 
\u201ctestdatabase\u201d\",[\"Rename\",\"\/scripts5\/rename_mysql_db\",{\"new\":\"testdatabase\",\"orig\":\"colin_testdatabase\"}]],[[\"Mysql\",\"_update_dbuser_name\",348],\"mySQL
 user \u201ccolin\u201d restored as 
\u201ccolin\u201d\",[\"Rename\",\"\/scripts5\/rename_mysql_user\",{\"new\":\"colin\",\"orig\":\"colin\"}]]]},\"skipped_items\":10,\"altered_items\":1,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"RESTORE\",\"child_number\":2,\"logfile\":\"item-RESTORE_AccountRemoteRoot_colin\"},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"msg\":{\"warnings\":2,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":[],\"altered_items\":[]},\"skipped_items\":11,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"logfile\":\"item-RESTORE_AccountRemoteRoot_fredfred\"},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"action\":\"complete\",\"queue\":\"RESTORE\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14365\",\"contents\":{\"action\":\"complete\",\"queue\":\"RESTORE\",\"child_number\":2},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"action\":\"complete\",\"child_number\":0},\"type\":\"control\"}\n"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "fetch_transfer_session_log"
  }
}

 

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://hostname.example.com:2087/cpsess##########/json-api/pause_transfer_session?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecopya20140211211719FxjU');
$_result = $xmlapi->xmlapi_query('pause_transfer_session' , $settings);

print $_result;

The success message will be minimal:

 Click to view...

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

 

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

URL:

https://hostname.example.com:2087/cpsess##########/json-api/start_transfer_session?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';


$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecopya20140211211719FxjU');
$_result = $xmlapi->xmlapi_query('start_transfer_session' , $settings);

print $_result;

 

Walkthrough for User Transfer Session

The following statements are true:

  • In this example, we have two servers: remote.example.com and hostname.example.com.
  • We are logged into the local server with the security token cpsess##########
  • We want to transfer the site example.com that is owned by the account example from the remote server to the local server.
  • The size of example.com is 123,456,789 bytes.
  • Finally, the password for the account transferme on the remote server is luggage12345.

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 as follows:

URL:

https://hostname.example.com:2087/cpsess##########/json-api/create_remote_user_transfer_session?api.version=1&unrestricted_restore=1&host=hostname.example.com&password=12345luggage

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_debug(1);
$xmlapi->set_output('json');

$settings = array(
    'api.version'=>1, 
    'host' => 'remote.example.com', 
    'password' => 'luggage12345',
);

$_result = $xmlapi->xmlapi_query('create_remote_user_transfer_session' , $settings);

print $_result;

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

 Click to view...

{
  "data": {
    "transfer_session_id": "vm5docscpanelnoroo201402251939519hmy"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "create_remote_user_transfer_session"
  }
}

The transfer session ID is vm5docscpanelnoroo201402251939519hmy.

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 to ensure that the username isn't reserved or currently in use.

URL:

https://hostname.example.com:2087/cpsess##########/json-api/validate_system_user?api.version=1&user=username

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST'); 
$root_user = getenv('REMOTE_USER'); 
$root_pass = getenv('REMOTE_PASSWORD'); 

$xmlapi = new xmlapi($ip , $root_user , $root_pass); 
$xmlapi->set_output('json'); 

$settings = array(
  'api.version'=>1, 
  'user' => 'transferme'
); 

$_result = $xmlapi->xmlapi_query('validate_system_user' , $settings); 

print $_result;

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

 Click to view...
{
  "data": {
    "valid_for_transfer": 1,
    "reserved": 1,
    "exists": 1,
    "valid_for_new": 1
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "validate_system_user"
  }
}

Queue the transfer item

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

URL:

https://hostname.example.com:2087/cpsess##########/json-api/enqueue_transfer_item?api.version=1&user=transferme&transfer_session_id=remoteexamplecomnoroo20140501194105g7qG&module=AccountRemoteUser&localuser=transferme

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array(
 'api.version'=>1, 
 'transfer_session_id' => 'remoteexamplecomnoroo20140501194105g7qG', 
 'module'=>'AccountRemoteUser', 
 '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', 
 'skipbwdata' => '0', 
 'skipaccount' => '0', 
 'xferpoint' => '1'
);
$_result = $xmlapi->xmlapi_query('enqueue_transfer_item' , $settings);

print $_result;

This function only returns metadata:

 Click to view...

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

 

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.

URL:

https://hostname.example.com:2087/cpsess##########/json-api/start_transfer_session?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG');
$_result = $xmlapi->xmlapi_query('start_transfer_session' , $settings);

print $_result;

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

 Click to view...
{
  "data": {
    "pid": "90210"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "start_transfer_session"
  }
}

 

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.

URL:

https://hostname.example.com:2087/cpsess##########/json-api/get_transfer_session_state?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';


$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');


$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');


$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG');
$_result = $xmlapi->xmlapi_query('get_transfer_session_state' , $settings);


print $_result;

It will respond with one of the following states:

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

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

 Click to view...
{
  "data": {
    "state_name": "TRANSFER_INPROGRESS"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "get_transfer_session_state"
  }
}

 

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:

URL:

https://hostname.example.com:2087/cpsess##########/json-api/fetch_transfer_session_log?api.version=1&transfer_session_id=vm5docscpanelcopya20140224163412sylG&logfile=master.log

PHP:
 Click to view...
include_once '../xmlapi.php';


$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');


$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');


$settings = array(
 'api.version'=>1, 
 'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG' , 
 'logfile' => 'master.log'
);
$_result = $xmlapi->xmlapi_query('fetch_transfer_session_log' , $settings);


print $_result;

The following example shows the contents of a log file:

 Click to view...
 {
  "data": {
    "log":
 
"{\"pid\":\"14358\",\"contents\":{\"action\":\"start\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"copyacct\",\"action\":\"initiator\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"1.6\",\"action\":\"version\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"3\",\"action\":\"queue_count\",\"queue\":\"TRANSFER\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"3\",\"action\":\"queue_count\",\"queue\":\"RESTORE\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"msg\":\"vm5.docs.cpanel.net\",\"action\":\"remotehost\",\"child_number\":0},\"type\":\"control\"}\n{\"pid\":\"14360\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"action\":\"start\",\"queue\":\"TRANSFER\",\"item_name\":\"Account\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14360\",\"contents\":{\"msg\":\"item-TRANSFER_AccountRemoteRoot_fredfred\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"TRANSFER\",\"child_number\":1,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_fredfred\"},\"type\":\"control\"}\n{\"pid\":\"14361\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"action\":\"start\",\"queue\":\"TRANSFER\",\"item_name\":\"Account\",\"child_number\":2},\"type\":\"control\"}\n{\"pid\":\"14361\",\"contents\":{\"msg\":\"item-TRANSFER_AccountRemoteRoot_colin\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"TRANSFER\",\"child_number\":2,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_colin\"},\"type\":\"control\"}\n{\"pid\":\"14362\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"action\":\"start\",\"queue\":\"TRANSFER\",\"item_name\":\"Account\",\"child_number\":3},\"type\":\"control\"}\n{\"pid\":\"14362\",\"contents\":{\"msg\":\"item-TRANSFER_AccountRemoteRoot_stacy\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"TRANSFER\",\"child_number\":3,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_stacy\"},\"type\":\"control\"}\n{\"pid\":\"14362\",\"contents\":{\"msg\":{\"warnings\":0,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":null,\"altered_items\":null},\"skipped_items\":0,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"TRANSFER\",\"child_number\":3,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_stacy\"},\"type\":\"control\"}\n{\"pid\":\"14361\",\"contents\":{\"msg\":{\"warnings\":0,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":null,\"altered_items\":null},\"skipped_items\":0,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"TRANSFER\",\"child_number\":2,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_colin\"},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"action\":\"start\",\"queue\":\"RESTORE\",\"item_name\":\"Account\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"msg\":\"item-RESTORE_AccountRemoteRoot_stacy\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"logfile\":\"item-RESTORE_AccountRemoteRoot_stacy\"},\"type\":\"control\"}\n{\"pid\":\"14365\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"action\":\"start\",\"queue\":\"RESTORE\",\"item_name\":\"Account\",\"child_number\":2},\"type\":\"control\"}\n{\"pid\":\"14365\",\"contents\":{\"msg\":\"item-RESTORE_AccountRemoteRoot_colin\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"RESTORE\",\"child_number\":2,\"logfile\":\"item-RESTORE_AccountRemoteRoot_colin\"},\"type\":\"control\"}\n{\"pid\":\"14360\",\"contents\":{\"msg\":{\"warnings\":0,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":null,\"altered_items\":null},\"skipped_items\":0,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"TRANSFER\",\"child_number\":1,\"logfile\":\"item-TRANSFER_AccountRemoteRoot_fredfred\"},\"type\":\"control\"}\n{\"pid\":\"14360\",\"contents\":{\"action\":\"complete\",\"queue\":\"TRANSFER\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14362\",\"contents\":{\"action\":\"complete\",\"queue\":\"TRANSFER\",\"child_number\":3},\"type\":\"control\"}\n{\"pid\":\"14361\",\"contents\":{\"action\":\"complete\",\"queue\":\"TRANSFER\",\"child_number\":2},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"msg\":{\"warnings\":2,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":[],\"altered_items\":[]},\"skipped_items\":10,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"stacy\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"logfile\":\"item-RESTORE_AccountRemoteRoot_stacy\"},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"action\":\"start\",\"queue\":\"RESTORE\",\"item_name\":\"Account\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"msg\":\"item-RESTORE_AccountRemoteRoot_fredfred\",\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"item_name\":\"Account\",\"action\":\"process-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"logfile\":\"item-RESTORE_AccountRemoteRoot_fredfred\"},\"type\":\"control\"}\n{\"pid\":\"14365\",\"contents\":{\"msg\":{\"warnings\":4,\"dangerous_items\":1,\"contents\":{\"dangerous_items\":[[[\"Mysql\",\"_restore_mysql\",104],\"MySQL:
 Skipping grants for these MySQL databases: colin_%. These databases 
don't exist in the 
archive.\",null]],\"altered_items\":[[[\"Mysql\",\"_update_dbname\",437],\"mySQL
 database \u201ccolin_testdatabase\u201d restored as 
\u201ctestdatabase\u201d\",[\"Rename\",\"\/scripts5\/rename_mysql_db\",{\"new\":\"testdatabase\",\"orig\":\"colin_testdatabase\"}]],[[\"Mysql\",\"_update_dbuser_name\",348],\"mySQL
 user \u201ccolin\u201d restored as 
\u201ccolin\u201d\",[\"Rename\",\"\/scripts5\/rename_mysql_user\",{\"new\":\"colin\",\"orig\":\"colin\"}]]]},\"skipped_items\":10,\"altered_items\":1,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"colin\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"RESTORE\",\"child_number\":2,\"logfile\":\"item-RESTORE_AccountRemoteRoot_colin\"},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"msg\":{\"warnings\":2,\"dangerous_items\":0,\"contents\":{\"dangerous_items\":[],\"altered_items\":[]},\"skipped_items\":11,\"altered_items\":0,\"message\":null},\"item_type\":\"AccountRemoteRoot\",\"item\":\"fredfred\",\"item_name\":\"Account\",\"action\":\"success-item\",\"queue\":\"RESTORE\",\"child_number\":1,\"logfile\":\"item-RESTORE_AccountRemoteRoot_fredfred\"},\"type\":\"control\"}\n{\"pid\":\"14363\",\"contents\":{\"action\":\"complete\",\"queue\":\"RESTORE\",\"child_number\":1},\"type\":\"control\"}\n{\"pid\":\"14365\",\"contents\":{\"action\":\"complete\",\"queue\":\"RESTORE\",\"child_number\":2},\"type\":\"control\"}\n{\"pid\":\"14358\",\"contents\":{\"action\":\"complete\",\"child_number\":0},\"type\":\"control\"}\n"
  },
  "metadata": {
    "version": 1,
    "reason": "OK",
    "result": "1",
    "command": "fetch_transfer_session_log"
  }
}

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://hostname.example.com:2087/cpsess##########/json-api/pause_transfer_session?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG');
$_result = $xmlapi->xmlapi_query('pause_transfer_session' , $settings);

print $_result;

The success message will be minimal:

 Click to view...
{
  "metadata": {
    "version": 1,
    "reason": "OK.",
    "result": 1,
    "command": "pause_transfer_session"
  }
}

 

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

URL:

https://hostname.example.com:2087/cpsess##########/json-api/start_transfer_session?api.version=1&transfer_session_id=exampleservercopya20140206192428NtyW

PHP:
 Click to view...
include_once '../xmlapi.php';

$ip = getenv('REMOTE_HOST');
$root_user = getenv('REMOTE_USER');
$root_pass = getenv('REMOTE_PASSWORD');

$xmlapi = new xmlapi($ip , $root_user , $root_pass);
$xmlapi->set_output('json');

$settings = array('api.version'=>1, 'transfer_session_id'=>'remoteexamplecomnoroo20140501194105g7qG');
$_result = $xmlapi->xmlapi_query('start_transfer_session' , $settings);

print $_result;

 

Additional documentation