HP BL680c XenServer Software Development Kit Guide 4.1.0 - Page 16

Overview of the XenServer API

10

and have a corresponding

session reference

. Indeed in the rest of this chapter, for the sake of brevity, we

will stop mentioning sessions altogether.

3.3.1.1. Creating a new blank disk image

The first step is to instantiate the disk image on physical storage. We do this via a call to

VDI.create(...)

.

The

VDI.create

call takes a number of parameters, including:

•

name_label

and

name_description

: a human-readable name/description for the disk (e.g. for convenient

display in the UI etc.). These fields can be left blank if desired.

•

SR

: the object reference of the Storage Repository representing the physical storage in which the VDI's

bits will be placed.

•

read_only

: setting this field to true indicates that the VDI can

only

be attached to VMs in a read-only

fashion. (Attempting to attach a VDI with its

read_only

field set to true in a read/write fashion results

in error.)

Invoking the

VDI.create

call causes the XenServer installation to create a blank disk image on physical

storage, create an associated VDI object (the datamodel instance that refers to the disk image on physical

storage) and return a reference to this newly created VDI object.

The way in which the disk image is represented on physical storage depends on the type of the SR in which

the created VDI resides. For example, if the SR is of type "lvm" then the new disk image will be rendered

as an LVM volume; if the SR is of type "nfs" then the new disk image will be a sparse VHD file created on

an NFS filer. (You can query the SR type through the API using the

SR.get_type(..)

call.)

3.3.1.2. Attaching the disk image to a VM

So far we have a running VM (that we assumed the existence of at the start of this example) and a fresh

VDI that we just created. Right now, these are both independent objects that exist on the XenServer Host,

but there is nothing linking them together. So our next step is to create such a link, associating the VDI

with our VM.

The attachment is formed by creating a new "connector" object called a VBD (

Virtual Block Device

). To

create our VBD we invoke the

VBD.create(...)

call. The

VBD.create(..)

call takes a number of parameters

including:

•

VM

: the object reference of the VM to which the VDI is to be attached

•

VDI

: the object reference of the VDI that is to be attached

•

mode

: specifies whether the VDI is to be attached in a read-only or a read-write fashion

•

userdevice

: specifies the block device inside the guest through which applications running inside the VM

will be able to read/write the VDI's bits.

•

type

: specifies whether the VDI should be presented inside the VM as a regular disk or as a CD. (Note that

this particular field has more meaning for Windows VMs than it does for Linux VMs, but will not explore

this level of detail in this chapter.)

Invoking

VBD.create

makes a VBD object on the XenServer installation and returns its object reference.

However, this call in itself does not have any side-effects on the running VM (i.e. if you go and look inside

the running VM you will see that the block device has not been created). The fact that the VBD object

exists but that the block device in the guest is not active, is reflected by the fact that the VBD object's

currently_attached

field is set to false.

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 16

Creating a new blank disk image, 3.3.1.2. Attaching the disk image to a VM

Page 16 highlights