HP BL680c XenServer Software Development Kit Guide 4.1.0 - Page 11

5

Chapter 3. Overview of the XenServer

API

In this chapter we introduce the XenServer API (hereafter referred to as just "the API") and its associated

object model. The API has the following key features:

•

Management of all aspects of XenServer Host:

Through the API one can manage VMs, storage,

networking, host configuration and pools. Performance and status metrics can also be queried via the API.

•

Persistent Object Model:

The results of all side-effecting operations (e.g. object creation, deletion

and parameter modifications) are persisted in a server-side database that is managed by the XenServer

installation.

•

An event mechanism:

Through the API, clients can register to be notified when persistent (serv-

er-side) objects are modified. This enables applications to keep track of datamodel modifications per-

formed by concurrently executing clients.

•

Synchronous and asynchronous invocation:

All API calls can be invoked synchronously (i.e. block

until completion); any API call that may be long-running can also be invoked

asynchronously

. Asyn-

chronous calls return immediately with a reference to a

task

object. This task object can be queried

(through the API) for progress and status information. When an asynchronously invoked operation com-

pletes, the result (or error code) is available via the task object.

•

Remotable and Cross-Platform:

The client issuing the API calls does not have to be resident on the

host being managed; nor does it have to be connected to the host via ssh in order to execute the API.

API calls make use of the XML-RPC protocol to transmit requests and responses over the network.

•

Secure and Authenticated Access:

The XML-RPC API server executing on the host accepts secure

socket connections. This allows a client to execute the APIs over the https protocol. Further, all the API

calls execute in the context of a login session generated through username and password validation at

the server. This provides secure and authenticated access to the XenServer installation.

3.1. Getting Started with the API

We will start our tour of the API by describing the calls required to create a new VM on a XenServer instal-

lation, and take it through a start/suspend/resume/stop cycle. This is done without reference to code in any

specific language; at this stage we just describe the informal sequence of RPC invocations that accomplish

our "install and start" task.

3.1.1. Authentication: acquiring a session reference

The first step is to call

Session.login(username, password)

. The API is session based, so before you

can make other calls you need to authenticate with the server. Assuming the username and password are

authenticated correctly, the result of this call is a

session reference

. Subsequent API calls take the session

reference as a parameter. In this way we ensure that only API users who are suitably authorized can perform

operations on a XenServer installation.

3.1.2. Acquiring a list of templates to base a new VM installation on

The next step is to query the list of "templates" on the host. Templates are specially-marked VM objects

that specify suitable default parameters for a variety of supported guest types. (If you want to see a quick

Section	Page
XenServer Software Development Kit Guide	1
Table of Contents	4
Chapter 1. Introduction	7
Chapter 2. Getting Started	8
2.1. System Requirements and Preparation	8
2.2. Downloading	8
2.3. Installation	8
2.4. What's new	8
2.5. Content Map	8
2.6. Building Samples for the Linux Platform	9
2.7. Building Samples for the Windows Platform	9
2.8. Running the CLI	9
2.8.1. Tab Completion	9
2.9. Accessing SDK reference	9
Chapter 3. Overview of the XenServer API	11
3.1. Getting Started with the API	11
3.1.1. Authentication: acquiring a session reference	11
3.1.2. Acquiring a list of templates to base a new VM installation on	11
3.1.3. Installing the VM based on a template	12
3.1.4. Taking the VM through a start/suspend/resume/stop cycle	12
3.1.5. Logging out	12
3.1.6. \	13
3.2. Object Model Overview	13
3.3. Working with VIFs and VBDs	15
3.3.1. Creating disks and attaching them to VMs	15
3.3.1.1. Creating a new blank disk image	16
3.3.1.2. Attaching the disk image to a VM	16
3.3.1.3. Hotplugging the VBD	17
3.3.2. Creating and attaching Network Devices to VMs	17
3.3.3. Host configuration for networking and storage	17
3.3.3.1. Host storage configuration: PBDs	18
3.3.3.2. Host networking configuration: PIFs	18
3.4. Exporting and Importing VMs	18
3.5. Where to look next	19
Chapter 4. Using the API	20
4.1. Anatomy of a typical application	20
4.1.1. Choosing a low-level transport	20
4.1.2. Authentication and session handling	20
4.1.3. Finding references to useful objects	21
4.1.4. Invoking synchronous operations on objects	21
4.1.5. Using Tasks to manage asynchronous operations	22
4.1.6. Subscribing to and listening for events	22
4.2. Language bindings	23
4.2.1. C	23
4.2.2. C#	24
4.2.3. Python	24
4.2.4. Command Line Interface (CLI)	25
4.3. Complete application examples	25
4.3.1. Simultaneously migrating VMs using XenMotion	25
4.3.2. Cloning a VM via the XE CLI	28
Chapter 5. XenServer API extensions	30
5.1. VM console forwarding	30
5.1.1. Retrieving VNC consoles via the API	30
5.1.2. Disabling VNC forwarding for Linux VM	31
5.2. Paravirtual Linux installation	32
5.2.1. Red Hat Enterprise Linux 4.1/4.4	32
5.2.2. Red Hat Enterprise Linux 4.5/5.0	32
5.2.3. SUSE Enterprise Linux 10 SP1	33
5.2.4. CentOS 4.5/5.0	33
5.3. Adding Xenstore entries to VMs	33
5.4. Security enhancements	33
5.5. Advanced settings for network interfaces	34
5.5.1. ethtool settings	34
5.5.2. Miscellaneous settings	35
5.6. Internationalization for SR names	35
5.7. Hiding objects from XenCenter	36

HP BL680c XenServer Software Development Kit Guide 4.1.0 - Page 11

Overview of the XenServer API, 3.1. Getting Started with the API, 3.1.1. Authentication:

Page 11 highlights