Skip to content
This repository has been archived by the owner on Mar 16, 2020. It is now read-only.

Transfer Plugin API

Jump to bottom
Rob Dobson edited this page Aug 9, 2013 · 3 revisions

cleanup

Cleans up resources (VMs, VM boot disk VDIs) that were left over from a VDI that was unexposed due to a timeout or failed API calls. All other API calls trigger cleanup too.

Args

None

Returns

The string "OK" on success.

expose

Exposes a specified VDI on the network. The call blocks until the transfer services are set up and ready to accept connections from the caller.

Args
Argument Required? Info
transfer_mode yes "http", "bits" or "iscsi".
vdi_uuid yes VDI UUID of disk to expose.
network_uuid yes The virtual network that the VDI should be visible on. May be "management", in order to appear on the network that xapi is using for management traffic.
read_only no "true" or "false". Defaults to "false".
network_mode no "dhcp" or "manual". Defaults to "dhcp"
use_ssl no "True" or "False". Defaults to "False". SSL is only supported for HTTP and BITS transfers.
network_port no the port number to listen on. If omitted, a suitable default port 80, 443, or 3260 is used. Non-default port is only supported for HTTP and BITS transfers.
network_mac no MAC address of the virtual interface created for the VM exposing the VDI. If missing, it is randomly generated.
timeout_minutes no non-negative integer. If given and not "0", the VDI is automatically unexposed timeout minutes after last TCP connection to the host. If this argument is missing or "0", the VDI will never time out.
get_log no "true or false". Defaults to "false". If set to true, on a unexpose call lighttpd logs are exported from the TransferVM into Dom0 (/var/log/transfervm) for collection manually, or by xenbug tool.
expose_vhd no "true or false". Defaults to false. If this parameter is set to true, the Transfer VM will expose the specified vdi_uuid as a vhd, and return the address of the vhd in the Transfer VM record under the parameter name url_full_vhd.
network_ip no If `network_mode` is "manual".
network_mask no If `network_mode` is "manual".
network_gateway no If `network_mode` is "manual".
Returns

A record handle; an opaque string describing this session, to be given to subsequent calls.

Raises
  • VDINotFound if the VDI uuid is not known to this XenServer host.
  • VDIInUse if the VDI is already exposed or mounted to some VM.
  • SnapshotTreeTooLong if the number of snapshots is 15 or greater.

expose_forest

Exposes the entire VDI forest. One Transfer VM will be created per VDI tree, and each VM will have a number of VDIs attached, one for each of the leaves of the tree. The transfer mode is always set to use BITS.

Args
Argument Required? Info
vm_uuids yes a comma seperated list of vm_uuids wished to be exposed.
network_uuid yes The virtual network that the VDI should be visible on. May be "management", in order to appear on the network that xapi is using for management traffic.
read_only no "true" or "false". Defaults to "false".
network_mode no "dhcp" or "manual". Defaults to "dhcp"
use_ssl no "True" or "False". Defaults to "False". SSL is only supported for HTTP and BITS transfers.
network_port no the port number to listen on. If omitted, a suitable default port 80, 443, or 3260 is used. Non-default port is only supported for HTTP and BITS transfers.
timeout_minutes no non-negative integer. If given and not "0", the VDI is automatically unexposed timeout minutes after last TCP connection to the host. If this argument is missing or "0", the VDI will never time out.
get_log no "true or false". Defaults to "false". If set to true, on a unexpose call lighttpd logs are exported from the TransferVM into Dom0 (/var/log/transfervm) for collection manually, or by xenbug tool.
network_ip no If `network_mode` is "manual".
network_mask no If `network_mode` is "manual".
network_gateway no If `network_mode` is "manual".
Returns

A comma-separated list of record handles will be returned (for all the created Transfer VMs).

get_import_instructions

A method for returning the series of import instructions to indicate the steps that the client should take to import an exported snapshot tree into a XenServer. Calling this method involves first uploading the metadata file for the exported VM to an empty VDI. The uuid of this disk is then passed to the plugin, and a list of instructions is generated and returned.

Args
Argument Required? Info
vdi_uuid yes The UUID of the VDI which contains the exported VM metadata.
Returns

A list of instructions to be followed by the client in order to import a snapshot tree into a XenServer host.

get_record

Retrieves a record associated with a Transfer VM (the reference for which is retuned by an expose call).

Args
Argument Required? Info
record_handle Either or The record handle returned by expose.
vdi_uuid Either or UUID of a VDI on this XenServer, which may or may not be exposed.
Raises
  • VDINotFound if the VDI uuid is not known to this XenServer host.
Returns

An XML file describing the status and expose configuration of the VDI.

Here is a sample output:

<?xml version="1.0"?>
<transfer_record
  username="70f8e0b297fcdd94"
  status="exposed"
  url_path="/vdi_uuid_4b26aeff-bc12-44f0-a5b6-2e07ec37e75c"
  record_handle="dda7a17f-2621-a77a-0464-6d95a19fbbc3"
  ip="10.80.238.238"
  transfer_mode="bits"
  url_full="http://70f8e0b297fcdd94:8c21f66590fcb08e@10.80.238.238:80/vdi_uuid_4b26aeff-bc12-44f0-a5b6-2e07ec37e75c"
  device="xvdn"
  use_ssl="false"
  password="8c21f66590fcb08e"
  port="80"
  vdi_uuid="4b26aeff-bc12-44f0-a5b6-2e07ec37e75c">
</transfer_record>

The attributes are as follows:

If the VDI is currently not in use:

  • vdi_uuid
  • status: = "unused"

If the VDI is currently mounted to a VM, but not exposed by the transfer plugin:

  • vdi_uuid
  • status: = "inuse"

If the VDI is currently exposed by the transfer plugin:

  • vdi_uuid
  • status: = "exposed"
  • transfer_mode: string "iscsi", "http" or "bits".
  • ip
  • port
  • use_ssl
  • username
  • password

If the VDI is currently exposed with transfer_mode = "iscsi":

  • iscsi_iqn
  • iscsi_lun
  • iscsi_sn

If the VDI is currently exposed with transfer_mode = "http" or "bits":

  • url_path
  • url_full

If the VDI is currently exposed with use_ssl = "True":

  • ssl_cert: A self-signed openssl certificate (including the public key), generated for this expose session.

number_of_ip_addresses_needed

This call returns for a list of vm_uuids, the number of transfervms required to expose the forest, and hence the number of IP addresses needed for static allocation as opposed to the default reliance on DHCP.

Args
Argument Required? Info
vm_uuids yes A list of vm_uuids separated by commas.
Returns

The number of IP addresses required to expose the forest with static network addresses.

Raises
  • SnapshotTreeTooLong if the number of snapshots is 15 or greater.

prepare_transfer_vm_template

Ensures that a Transfer VM template is installed on the host that the call is being made against. This call will take care of importing new templates if an updated template has been installed on the system.

Args

None

Returns

The Transfer VM template for the specified host.

save_logs

Attempts to retrieve logs from the Transfer VM and store them in dom0 (/var/log).

Args
Argument Required? Info
record_handle yes The record handle returned by expose.
Returns

The URL from where the logs where downloaded.

Raises
  • VDINotFound if the VDI uuid is not known to this XenServer host.
  • VDINotInUse if the VDI is not currently exposed by the transfer plugin.
  • LogsNotFound if exposed log files cannot be found within the default timeout. (30 seconds).
Clone this wiki locally