Skip to content

Methods

Jump to bottom Edit New page
Pavel Zinin edited this page Oct 15, 2018 · 16 revisions

VMEmperor API methods

All methods are HTTP REST API methods taking JSON payload with specified arguments as application/json Content-Type.

How to run Examples

Some examples are provided in form of RFC 2616

POST http://localhost:8889/xxx
content-type: application/json
{
  "uuid" : "xxx"
}

These examples are intended to run with REST client, for example

Table Of Contents

Common Errors

Required argument not given

Return code 400

Malformed JSON

Return code 500

Wrong UUID
{
  "status": "bad request",
  "message": "{\"message\": \"Failed to initialize object of type <TYPE> with UUID <UUID>\", \"details\": [\"UUID_INVALID\", \"<TYPE>\", \"<UUID>\"]}"
}

Return code 400

Login

These methods should be used for authentication. They set a cookie.

POST /login

Performs authentication using external authentication source

Arguments

Name Type Required
username string Yes
password string Yes

Normal response

{"status": "success", "login": "provided username"}

return code 200

Errors

Wrong username/password

Return code 401, response:

{"status": "error", "message": "wrong credentials"}

POST /adminauth

Performs authentication using XenServer capabilities.

Arguments & response identical to /login

For administrator only

These methods are available only for administrators authenticated via /adminauth

GET /alltemplates

Get all the information about all templates. The field description is available at XenAPI website.

POST /turntemplate

Enable/disable template. If template is enabled, it has a vmemperor tag on it and shown in /tmpllist available for all users.

Arguments

Name Description See also
uuid Template UUID /alltemplates
action on to enable template, off to disable

After Login

These methods will only work with authentication cookie acquired with /login or /adminauth

POST /createvm

Creates a new VM. If os_kind is set for a template, the automatic method of installation is chosen. os_kind is a hint for flavour of automatic installation that is either guessed from template's reference-label attribute or may be set manually in template's other_config. Read more

Arguments

Name Description Required See also
template UUID of a template to install VM from Yes /tmpllist
storage UUID of a storage repository to create virtual hard disk on Yes /poollist
network UUID of a network to attach to VM Yes /netlist
vdi_size Size of a virtual hard disk to create, in megabytes Yes
ram_size Size of a virtual RAM allocation, in megabytes Yes
name_label Human-readable name of the virtual machine Yes
hostname Hostname to be set automatically Automatic install
mirror_url Installation repository URL Optional for automatic install
ip Static IP address No for DHCP during automatic install
gateway Static IP gateway No for DHCP during automatic install
netmask Static IP netmask No for DHCP during automatic install
dns0 Static IP DNS 1 No for DHCP during automatic install
dns1 Static IP DNS 2 No for DHCP during automatic install
username Username to be set automatically Automatic install
password Password to be set automatically Automatic install
fullname User's full name to be set automatically No
partition Disk partition scheme (Documentation TODO) Automatic install

Normal response

returns an async task id

{
  "task": "task_uuid"
}

To check installation status, use /taskstatus

POST /taskstatus

Check status of an async task

Argument

task : string

Unique task ID

Normal response

Depends on the type of task

Standard (/destroyvm, /startstopvm, /destroyvdi, /rebootvm)
  1. Task is in progress
{
  "created": "2018-10-08T14:05:24",
  "status": "pending",
  "progress": 0.0 <-- could be from 0.0 to 1.0
}
  1. Task ended with an error
{
  "created": "2018-10-08T13:53:35",
  "status": "failure",
  "progress": 1.0,
  "finished": "2018-10-08T13:54:56",
  "error_info": [
    "BOOTLOADER_FAILED", <-- error name
    "OpaqueRef:84393a83-a638-a05e-2a93-7c6c5594b085",
    "Could not access http://mirror.centos.org/centos/6/os/x86_64/isolinux/vmlinuz\n" <-- startup error message
  ]
}
  1. Task ended successfully
{
  "created": "2018-10-08T13:53:35",
  "status": "success",
  "progress": 1.0,
  "finished": "2018-10-08T13:54:56"
}
VM Installation (/createvm)

For VM installation task, as folows:

{
  "uuid": "VM UUID",
  "state": "some_vm_state",
  "message": "human readable messsage"
}

Here, state might be one of cloned (when a template is cloned into a VM), installing (OS is being installed), installed (OS has been installed), failed (Installation error),

For example, if VM network connection has been failed, it might return something like this:

{
  "uuid": null,
  "state": "error",
  "message": "{\"message\": \"Failed to initialize object of type Network with UUID 920b8d47-9945-63d8-4b04-ad06c65d950: ['UUID_INVALID', 'network', '920b8d47-9945-63d8-4b04-ad06c65d950']\", \"details\": null}"
}

Errors

Invalid task id

Empty response, code 404

POST /vminfo

Single VM information

Normal response

{
  "PV_drivers_up_to_date": true,
  "PV_drivers_version": {
    "build": "0",
    "major": "6",
    "micro": "80",
    "minor": "6"
  },
  "access": [
    {
      "access": [
        "all"
      ],
      "userid": "users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb"
    }
  ],
  "disks": {
    "OpaqueRef:22908078-40ac-a8c2-3cb2-c5c69501a1b2": {
      "VDI": "f6a0f7fc-2ecb-4351-b668-c191e4316d16",
      "attached": true,
      "bootable": true,
      "device": "xvda",
      "mode": "RW",
      "type": "Disk"
    },
    "OpaqueRef:badd9f42-f46f-5564-24ce-ad5400a82d2e": {
      "VDI": "db199908-f133-4c7f-b06c-10ac2784ad5JSONd",
      "attached": true,
      "bootable": true,
      "device": "xvdb",
      "mode": "RO",
      "type": "CD"
    }
  },
  "domain_type": "hvm",
  "guest_metrics": "OpaqueRef:f8f19c2d-8e63-7c1a-9785-432ab81e42b2",
  "install_time": "2018-09-25T15:35:58+00:00",
  "memory_actual": "1073733632",
  "metrics": "OpaqueRef:f41de3c8-7f6e-8401-0e96-4db67cd0299a",
  "name_label": "Test VM2",
  "networks": {
    "0": {
      "MAC": "c2:ff:21:05:26:61",
      "VIF": "OpaqueRef:69daed43-3503-4592-96a2-51b0e929b161",
      "attached": true,
      "ip": "10.10.10.21",
      "ipv6": "fe80::c0ff:21ff:fe05:2661",
      "network": "920b8d47-9945-63d8-4b04-ad06c65d950a",
      "status": ""
    }
  },
  "os_version": {
    "distro": "ubuntu",
    "major": "18",
    "minor": "04",
    "name": "Ubuntu 18.04.1 LTS",
    "uname": "4.15.0-34-generic"
  },
  "power_state": "Running",
  "ref": "OpaqueRef:f297e37a-ccab-8f57-00d9-b65046fde5a3",
  "start_time": "2018-09-25T15:47:30+00:00",
  "uuid": "754ef052-1825-f54b-82db-d77ad71f7a7c"
}

The format is the same as a single initial record VMList

Errors

Access denied
{
   "status": "access denied", "message": "Unauthorized attempt (no info
  on access rights): needs privilege 'launch'"
}

(for now you need launch privilege to call /vminfo)

POST /startstopvm

Start or stop a VM

Arguments

Name Description Required See also
uuid Virtual machine UUID Yes VMList
enable true - start VM, false - stop VM Yes (This is JSON bool)

Normal response

{
  "task": "<unique task ID>"
}

code 200

Notes

Any enable value besides "False" in any register and false resolves to true

POST /rebootvm

Reboot a VM

Arguments

Name Description Required See also
uuid Virtual machine UUID Yes VMList

Normal response

{
  "task": "<unique task ID>"
}

code 200

POST /destroyvm

Destroy a VM

Arguments

Name Description Required See also
uuid Virtual machine UUID Yes VMList

Normal response

{
  "task": "<unique task ID>"
}

code 200

POST /destroyvdi

Destroy a VM

Arguments

Name Description Required See also
uuid VDI UUID Yes /vdilist

Normal response

{
  "task": "<unique task ID>"
}

code 200

GET /tmpllist

Get template list

Normal response

[
  {
    "hvm": false,
    "name_label": "Ubuntu Lucid Lynx 10.04 (32-bit)",
    "os_kind": "ubuntu",
    "ref": "OpaqueRef:bc91c4f9-5f42-6f6a-5da2-1c5e413b633c",
    "uuid": "0e9d218d-03ef-49be-934a-dbc47c206957"
  },
  ...
]
Template record fields
Name Type Description
hvm bool true if the template has hardware-assisted virtualization enabled
name_label string Human-readable template name
os_kind string If present, indicates that this template provides automatic installation of certain Linux distribution family. For now, only ubuntu, debian and centos are supported
ref string Unique template ID for session (ignore it for now)
uuid string Unique template ID

GET /poollist

List of all pools, hosts and their capabilities

Example

[
  {
    "networks": [
      {
        "uuid": "920b8d47-9945-63d8-4b04-ad06c65d950a",
        "name_label": "Pool-wide network associated with eth0"
      },
      {
        "uuid": "9d7f44b3-56c4-04ee-8088-e35f9ecedc19",
        "name_label": "second net"
      }
    ],
    "storage_resources": [
      {
        "uuid": "88458f94-2e69-6332-423a-00eba8f2008c",
        "name_label": "Local storage (Available 558 GB)"
      }
    ],
    "hdd_available": 558.404296875,
    "host_list": [
      {
        "name_label": "emperordev",
        "resident_VMs": [
          "OpaqueRef:534dc785-f818-cd62-0d94-2da05796db77"
        ],
        "software_version": {
          "product_version": "7.2.0",
          "product_version_text": "7.2",
          "product_version_text_short": "7.2",
          "platform_name": "XCP",
          "platform_version": "2.3.0",
          "product_brand": "XenServer",
          "build_number": "release/falcon/master/8",
          "hostname": "f7d02093adae",
          "date": "2017-05-11",
          "dbv": "2017.0517",
          "xapi": "1.9",
          "xen": "4.7.2-2.2",
          "linux": "4.4.0+10",
          "xencenter_min": "2.7",
          "xencenter_max": "2.7",
          "network_backend": "openvswitch",
          "db_schema": "5.120"
        },
        "cpu_info": {
          "cpu_count": "4",
          "socket_count": "1",
          "vendor": "GenuineIntel",
          "speed": "3093.038",
          "modelname": "Intel(R) Core(TM) i3-2100 CPU @ 3.10GHz",
          "family": "6",
          "model": "42",
          "stepping": "7",
          "flags": "fpu de tsc msr pae mce cx8 apic sep mca cmov pat clflush acpi mmx fxsr sse sse2 ht syscall nx lm constant_tsc arch_perfmon rep_good nopl nonstop_tsc eagerfpu pni pclmulqdq monitor est ssse3 cx16 sse4_1 sse4_2 popcnt xsave avx hypervisor lahf_lm arat epb pln pts dtherm xsaveopt",
          "features": "1d9ae3bf-bfebfbff-00000001-28100800",
          "features_pv": "17c9cbf5-94b82203-2191cbf5-00000003-00000001-00000000-00000000-00000000-00000000",
          "features_hvm": "17cbfbff-95ba2223-2993fbff-00000003-00000001-00000000-00000000-00000000-00000000"
        },
        "memory_total": 24493.37109375,
        "memory_free": 21992.6015625,
        "live": true,
        "memory_available": 21962.97265625
      }
    ],
    "url": "http://10.10.10.18:80/",
    "description": "testing",
    "uuid": "9e104b41-7211-2542-49ad-33b6c1958428",
    "templates_enabled": [
      {
        "hvm": false,
        "name_label": "Ubuntu Lucid Lynx 10.04 (32-bit)",
        "os_kind": "ubuntu",
        "ref": "OpaqueRef:bc91c4f9-5f42-6f6a-5da2-1c5e413b633c",
        "uuid": "0e9d218d-03ef-49be-934a-dbc47c206957"
      },
      ...
    ]
  }
]

Description

List of pools, and each of them have the following keys

networks

List of all available networks in the form of their uuid (unique id) and name_label (name)

storage_resources

List of all available storage resources (SRs, storage repositories) to create new virtual block devices on in the for of their uuid (unique id) and name_label (name). name_label also contains free space Available

hdd_available

Free storage space available on this pool (in GB, float)

host_list

List of all hosts in this pool. See "host_list description" below

url

XenAPI URL (doubt we really need to expose it)

description

Pool description (human-readable)

uuid

Pool unique ID

templates_enabled

List of all templates that are available for use in installation process. This list is identical to /tmpllist. Template is enabled, if it has vmemperor tag set.

host_list description

host_list is a list with a record for each host in a pool.

The record has the following fields:

Name Description
name_label host name (human-readable)
resident_VMs list of all refs of VMS on current host. See ref field in VMList
software_version XenServer product version (the keys are self-explanatory)
cpu_info host CPU information (count, vendor, model, flags,...)
memory_total Total amount of RAM available on this host, in megabytes
memory_free Total amount of free RAM available on this host, in megabytes
memory_available Total amount of free RAM available for VM usage right now on this host, in megabytes
live true if this host is up, false otherwise

GET /netlist

List of all networks available for the user

Example

[
  {
    "PIFs": [
      "OpaqueRef:b28b5fcc-1c55-0559-63a3-bcdb4ea71361"
    ],
    "VMs": [
      "2e2f14ce-77bb-2a25-00a2-d66816321561",
      "754ef052-1825-f54b-82db-d77ad71f7a7c"
    ],
    "access": [
      {
        "access": [
          "all"
        ],
        "userid": "users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb"
      }
    ],
    "name_description": "",
    "name_label": "Pool-wide network associated with eth0",
    "other_config": {
      "gateway": "10.10.10.254",
      "ip_begin": "10.10.10.20",
      "ip_disable_gw": "True",
      "ip_end": "10.10.10.30",
      "netmask": "255.255.255.0",
      "vmemperor": "{\"access\": {\"SqlAlchemyAuthenticator\": {\"users/1\": [\"all\"]}, \"LDAPIspAuthenticator\": {\"users/1\": [\"all\"]}}}"
    },
    "ref": "OpaqueRef:e8e5bccd-f9d0-74bd-f5d5-728b57df7bcc",
    "uuid": "920b8d47-9945-63d8-4b04-ad06c65d950a"
  }
]

Entry description

PIFs: List of physical interfaces' ref's available on this network

VMs: List of VMs connected to this network represented through their unique IDs (uuid)

access: Read AccessRights

name_label: Human-readable network name

network_description: Human-readable network description

uuid: Unique ID (used in API calls)

ref: Unique ID for a session

other_config: Copy of corresponding XenAPI field. See XenAPI documentation for details.

GET /isolist

List of all ISO images available for using in virtual CDROM devices

Example

[
  {
    "SR": "0997d0ec-8a0b-1678-8e99-ca5754da4c9f",
    "VMs": [],
    "location": "systemrescuecd-x86-5.0.1.iso",
    "name_description": "",
    "name_label": "systemrescuecd-x86-5.0.1.iso",
    "ref": "OpaqueRef:5dbba233-dc67-6056-ee0a-369c9401750d",
    "uuid": "07d14688-86cd-41ce-93d8-c88f9f7a590d",
    "virtual_size": "485711872"
  },
...
]

Entry description

Name Description
SR Storage repository (ISO image source) unique ID
VMs uuid's of VMs that have this ISO connected
location ISO image name or device file name (for physical devices)
name_label ISO image name or device human-readable label (for physical devices)
ref Unique reference for this iso for a session
uuid ISO's unique ID. Used in /createvm and other API calls
virtual_size Disk size in bytes

GET /vdilist

Example

[
  {
    "SR": "88458f94-2e69-6332-423a-00eba8f2008c",
    "VMs": [
      "754ef052-1825-f54b-82db-d77ad71f7a7c"
    ],
    "access": [
      {
        "access": [
          "all"
        ],
        "userid": "users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb"
      }
    ],
    "name_description": "Created by template provisioner",
    "name_label": "0",
    "ref": "OpaqueRef:7b0c056d-51a8-324d-3fb4-c905c7e8e3a3",
    "uuid": "f6a0f7fc-2ecb-4351-b668-c191e4316d16",
    "virtual_size": "8589934592"
  },
  ...
]

Entry description

Same as /isolist with access field according to AccessRights

POST /vnc

Get a VNC console WebSocket URL. The url is usable in NoVNC.

Arguments

uuid : Virtual machine UUID

Response Example

ws://10.10.10.102:8889/console?secret=SJVib9ao4JnxfFjtaSUHfDdu0Y5flIrMSvP6WARC5I4

This URL is intented to use without authorization cookie. Authorization information is stored in a secret parameter

WebSocket /console

VNC Console. Retreive URL with /vnc method. Use without authorization

POST /netinfo

Get information about a single network. See also: /netlist

Arguments

uuid - network UUID

Normal response

Same as single entry in /netlist with specified uuid

POST /vdiinfo

Get information about a single VDI (virtual disk image - virtual hard disk). See also: /vdilist

Arguments

uuid - vdi UUID

Normal response

Same as single entry in vdilist with specified uuid

POST /isoinfo

Get information about a single ISO image available for use in OS installation. See also: /isolist

Arguments

uuid - ISO UUID

Normal response

Same as single entry in isolist with specified uuid

POST /vmdiskinfo

Get information about all disks connected to specified VM

Arguments

uuid - VM UUID

Normal response

Example

This is example output when a VM has one ISO and one virtual hard disk connected

{
  "OpaqueRef:22908078-40ac-a8c2-3cb2-c5c69501a1b2": {
    "SR": "88458f94-2e69-6332-423a-00eba8f2008c",
    "VDI": "f6a0f7fc-2ecb-4351-b668-c191e4316d16",
    "VMs": [
      "754ef052-1825-f54b-82db-d77ad71f7a7c"
    ],
    "access": [
      {
        "access": [
          "all"
        ],
        "userid": "users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb"
      }
    ],
    "attached": false,
    "bootable": true,
    "device": "xvda",
    "mode": "RW",
    "name_description": "Created by template provisioner",
    "name_label": "0",
    "ref": "OpaqueRef:7b0c056d-51a8-324d-3fb4-c905c7e8e3a3",
    "type": "Disk",
    "virtual_size": "8589934592"
  },
  "OpaqueRef:badd9f42-f46f-5564-24ce-ad5400a82d2e": {
    "SR": "7266873e-f721-4e89-15b4-77fee0a3e66f",
    "VDI": "db199908-f133-4c7f-b06c-10ac2784ad5d",
    "VMs": [
      "754ef052-1825-f54b-82db-d77ad71f7a7c",
      "2e2f14ce-77bb-2a25-00a2-d66816321561"
    ],
    "attached": false,
    "bootable": true,
    "device": "xvdb",
    "location": "guest-tools-7.11.0-1.iso",
    "mode": "RO",
    "name_description": "",
    "name_label": "guest-tools.iso",
    "ref": "OpaqueRef:b62b7e1b-5ab1-ed62-45fe-60a42d6602a9",
    "type": "CD",
    "virtual_size": "71077888"
  }
}
Output format

The output format is a dictionary of all connected ISOs and hard disks with keys being unique IDs of virtual block devices, and values being the same as entries in /vdilist and /isolist merged with entries from disks dictionary of /vminfo. Its possible values are CD for ISO images and Disk for virtual hard disks.

POST /vmnetinfo

Get information about all networks connected to specified VM

Arguments

uuid - VM UUID

Normal response

Example

This is example output when a VM is connected to one virtual network

{
  "0": {
    "MAC": "c2:ff:21:05:26:61",
    "PIFs": [
      "OpaqueRef:b28b5fcc-1c55-0559-63a3-bcdb4ea71361"
    ],
    "VIF": "OpaqueRef:69daed43-3503-4592-96a2-51b0e929b161",
    "VMs": [
      "2e2f14ce-77bb-2a25-00a2-d66816321561",
      "754ef052-1825-f54b-82db-d77ad71f7a7c"
    ],
    "access": [
      {
        "access": [
          "all"
        ],
        "userid": "users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb"
      }
    ],
    "attached": false,
    "name_description": "",
    "name_label": "Pool-wide network associated with eth0",
    "network": "920b8d47-9945-63d8-4b04-ad06c65d950a",
    "other_config": {
      "gateway": "10.10.10.254",
      "ip_begin": "10.10.10.20",
      "ip_disable_gw": "True",
      "ip_end": "10.10.10.30",
      "netmask": "255.255.255.0",
      "vmemperor": "{\"access\": {\"SqlAlchemyAuthenticator\": {\"users/1\": [\"all\"]}, \"LDAPIspAuthenticator\": {\"users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb\": [\"all\"]}}}"
    },
    "ref": "OpaqueRef:e8e5bccd-f9d0-74bd-f5d5-728b57df7bcc",
    "status": ""
  }
}
Output format

The output format is the networks field of /vminfo merged with corresponding records as in /netinfo

GET /userlist

List of all users in the system

Normal response

[
  {
    "id": "570e9a59-e3bd-42c5-87ee-d46b312dbfcb",
    "name": "Example User",
    "username": "user"
  },
  ...
]

GET /grouplist

List of all groups in the system

Normal response

[
  {
    "id": "5b8527e5-cff7-403e-bb74-485f3d71c9dd",
    "name": "users",
    "username": "users"
  },
  ...
]

POST /getaccess

Get access information of an object. Access information defines who can use specified object. Only certain types of objects (VM - virtual machines, Network - virtual networks and VDI - virtual hard disks) are subject to access control system.

Arguments

Name Type Description
type string one of VM, Network and VDI
uuid string Unique ID of object of type type

Normal response

{
  "access": [
    {
      "access": [
        "all"
      ],
      "userid": "users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb"
    }
  ]
}

The format is described here.

POST /setaccess

Get access information of an object. Access information defines who can use specified object. Only certain types of objects (VM - virtual machines, Network - virtual networks and VDI - virtual hard disks) are subject to access control system.

Arguments

Name Type Description See also
type string one of VM, Network and VDI AccessRights
uuid string Unique ID of object of type type
action string One of available actions, see here
revoke bool set to true if we should revoke the action
user string User id to grant/revoke action /userlist
group string Group id to grant/revoke action. Set this OR user, not both /grouplist

Example

Grant action all of some VM to group users from /grouplist example

POST http://localhost:8889/setaccess
content-type: application/json
{
"type":"VM",
"uuid":"2cd6a07a-4a2f-d82d-988b-05fd5ecdab26",
"group":"5b8527e5-cff7-403e-bb74-485f3d71c9d",
"action":"all"
}

In case of normal exit, it returns 200 OK with empty body.

POST /netaction

Attach (create a virtual device and connect to) or detach (remove virtual device and disconnect from) a network

Arguments

Name Type Description See also
uuid string VM UUID /vmlist
net string Network UUID /netlist
action string attach or detach depending on what you need to do

POST /attachdetachvdi

Attach or detach a VDI (virtual hard disk)

Arguments

Name Type Description See also
uuid string VM UUID /vmlist
vdi string VDI UUID /vdilist
action string attach or detach depending on what you need to do

Examples

Detach a VDI from a VM
  1. Call GET /vdilist to ensure that a VDI is attached
[
  {
    "SR": "88458f94-2e69-6332-423a-00eba8f2008c",
    "VMs": [
      "2cd6a07a-4a2f-d82d-988b-05fd5ecdab26"
    ],
    "access": [
      {
        "access": [
          "all"
        ],
        "userid": "users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb"
      }
    ],
    "name_description": "Created by template provisioner",
    "name_label": "0",
    "ref": "OpaqueRef:e83b3997-b405-1a4d-dfd9-28e194605964",
    "uuid": "3b4b879b-20e5-4cf2-b530-a544cef2451f",
    "virtual_size": "9663676416"
  }
]
  1. Call POST /vminfo with uuid from VMs list to ensure that VM is halted
{
  ...
  "disks": {
    "OpaqueRef:7066aaf6-e79e-2523-cd63-16635508d6a1": {
      "VDI": "db199908-f133-4c7f-b06c-10ac2784ad5d",
      "attached": false,
      "bootable": true,
      "device": "xvdb",
      "mode": "RO",
      "type": "CD"
    },
    "OpaqueRef:7d276560-5ec3-3028-7afc-d2af14ee9653": {
      "VDI": "3b4b879b-20e5-4cf2-b530-a544cef2451f",
      "attached": false,
      "bootable": true,
      "device": "xvda",
      "mode": "RW",
      "type": "Disk"
    }
  },
  ...
  "power_state": "Halted",
  ...
  "uuid": "2cd6a07a-4a2f-d82d-988b-05fd5ecdab26"
}
  1. Detach with POST /attachdetachvdi 
POST http://localhost:8889/attachdetachvdi
content-type: application/json
{
"uuid": "2cd6a07a-4a2f-d82d-988b-05fd5ecdab26",
"vdi": "3b4b879b-20e5-4cf2-b530-a544cef2451f",
"action": "detach"
}
{"status": "ok"}
  1. You can also detach ISOs with this method
POST http://localhost:8889/attachdetachvdi
content-type: application/json
{
"uuid": "2cd6a07a-4a2f-d82d-988b-05fd5ecdab26",
"vdi": "db199908-f133-4c7f-b06c-10ac2784ad5d",
"action": "detach"
}
{"status": "ok"}
  1. Check that disks are detached with POST /vminfo:
POST http://localhost:8889/vminfo
content-type: application/json
{
"uuid":"2cd6a07a-4a2f-d82d-988b-05fd5ecdab26"
}
{
...
  "disks": null,
...
  "uuid": "2cd6a07a-4a2f-d82d-988b-05fd5ecdab26"
}

Attach a VDI to a VM

Ensure that VDI is not attached (/vdilist) and VM is halted (/vminfo), use previous chapter for reference.

POST http://localhost:8889/attachdetachvdi
content-type: application/json
{
"uuid": "2cd6a07a-4a2f-d82d-988b-05fd5ecdab26",
"vdi": "3b4b879b-20e5-4cf2-b530-a544cef2451f",
"action": "attach"
}
{"status": "ok"}

Check that disk is attached. In this example we'll use /vmdiskinfo

POST http://localhost:8889/vmdiskinfo
content-type: application/json
{
"uuid": "2cd6a07a-4a2f-d82d-988b-05fd5ecdab26"
}
{
  "OpaqueRef:9a8848b4-6f54-239e-9a73-829992ec2444": {
    "SR": "88458f94-2e69-6332-423a-00eba8f2008c",
    "VDI": "3b4b879b-20e5-4cf2-b530-a544cef2451f",
    "VMs": [
      "2cd6a07a-4a2f-d82d-988b-05fd5ecdab26"
    ],
    "access": [
      {
        "access": [
          "all"
        ],
        "userid": "users/570e9a59-e3bd-42c5-87ee-d46b312dbfcb"
      }
    ],
    "attached": false,
    "bootable": true,
    "device": "",
    "mode": "RW",
    "name_description": "Created by template provisioner",
    "name_label": "0",
    "ref": "OpaqueRef:e83b3997-b405-1a4d-dfd9-28e194605964",
    "type": "Disk",
    "virtual_size": "9663676416"
  }
}

POST /attachdetachiso

Attach/detach ISO Request format is identical to /attachdetachvdi. To get list of all ISOs, use /isolist

GET /playbooks

Get playbooks list available for execution.

Normal response

[
  {
    "name": "WordPress",
    "description": "WordPress CentOS Setup",
    "requires": {
      "os_version": [
        {
          "distro": "centos",
          "major": 6
        },
        {
          "distro": "redhat"
        }
      ]
    },
    "variables": {
      "wp_version": {
        "description": "WordPress version",
        "type": "str",
        "value": "4.2.4"
      },
      "wp_sha256sum": {
        "description": "WordPress release SHA256",
        "type": "str",
        "value": "42ca594afc709cbef8528a6096f5a1efe96dcf3164e7ce321e87d57ae015cc82"
      },
      "mysql_port": {
        "description": "MySQL port",
        "type": "int",
        "value": 3306
      },
      "server_hostname": {
        "description": "WordPress server hostname",
        "type": "str",
        "value": "www.example.com"
      },
      "auto_up_disable": {
        "description": "Disable automatic updates",
        "type": "bool",
        "value": false
      },
      "core_update_level": {
        "description": "Core Update Level",
        "type": "option",
        "options": {
          "true": {
            "description": "Development, minor, and major updates are all enabled"
          },
          "false": {
            "description": "Development, minor, and major updates are all disabled"
          },
          "minor": {
            "description": "Minor updates are enabled, development, and major updates are disabled"
          }
        },
        "value": true
      }
    },
    "inventory": null,
    "single": false,
    "id": "wordpress-nginx"
  }
]

Entry description

All these fields are taken from vmemperor.conf file of the corresponding playbook. Read more about playbooks

Name Type Description Required
name string Human-readable name of the playbook Yes
description string Human-readable description of the playbook Yes
requires dictionary Read here No
variables dictionary Read here No
inventory string Read here No
id string Unique id of the playbook Yes

POST /executeplaybook

Executes an Ansible playbook on specified hosts (if no inventory is specified in vmemperor.conf file). Otherwise, executes on that inventory. VMEmperor should know IP addresses of specified VMs so Xen guest tools should be installed.

A playbook is executed using root user. A VM should have SSH access granted to ansible-playbook binary. During auto-installation, VMEmperor imports a pubkey specified in ansible_pubkey entry of the application config file to a machine and uses it to get access. Hence the default config option is ~/.ssh/id_rsa.pub

Arguments

Name Type Description Required
vms list of strings list of VMs to execute playbook on. A user should have launch access on each machine Yes, if no inventory is specified in config
playbook string Playbook ID to execute Yes
Any variable name specified in vmemperor.conf file as specified If you want to override default value of a variable specified in vmemperor.conf, add it to your POST request's JSON No

Example

We'll use playbook given in previous section as an example.

We'll override auto_up_disable to true

POST http://localhost:8889/executeplaybook
content-type: application/json
{
"vms": ["2cd6a07a-4a2f-d82d-988b-05fd5ecdab26"],
"playbook": "wordpress-nginx",
"auto_up_disable": true
}
{
  "task": "vmemperor-xy9wdrcg-playbook-wordpress-nginx"
}

Check task status via /taskstatus

POST http://localhost:8889/taskstatus
content-type: application/json
{
  "task": "vmemperor-xy9wdrcg-playbook-wordpress-nginx"
}
{
  "returncode": 4
}

/taskstatus returns execution return code. If it's non-zero, it makes sense for administrator to check log files. Log files are located in ./ansible_logs relative to VMEmperor working directory by default (specified by ansible_logs variable in config file). Check the log files in subdirectory with task name. It has two files, stdout and stderr. For example, if a VM is halted, it'll print something like this:

fatal: [test centos]: UNREACHABLE! => {"changed": false, "msg": "Failed to connect to the host via ssh: ssh: connect to host 10.10.10.20 port 22: No route to host\r\n", "unreachable": true}
	to retry, use: --limit @/tmp/vmemperor-xy9wdrcg-playbook-wordpress-nginx/site.retry

In case of normal return , returncode would be 0

{
  "returncode": 0
}
Add a custom footer
Add a custom sidebar

Clone this wiki locally