Table of Contents 1. Introduction ........................1 2. Getting Started ......................2 2.1. System Requirements and Preparation ............... 2 2.2. Downloading ..................... 2 2.3. Installation ......................2 2.4. What's new ....................... 2 2.5. Content Map ..................... 2 2.6. Building Samples for the Linux Platform ............. 3 2.7.
List of Figures 3.1. Graphical overview of API classes for managing VMs, Hosts, Storage and Network- ing ..........................9 3.2. A VM object with 2 associated VDIs ................. 11...
Chapter 1. Introduction Welcome to the developer’s guide for XenServer. Here you will find the information you need in order to understand and use the Software Development Kit (SDK) that XenServer provides. This information will provide you with some of the architectural background and thinking that underpins the APIs, the tools that have been provided, and how to quickly get off the ground.
Chapter 2. Getting Started 2.1. System Requirements and Preparation The XenServer SDK is packaged as a Linux VM that must be imported into a XenServer Host. This document refers to the SDK virtual machine interchangeably as an SDK and an SDK VM. The first step towards working with the SDK is to install XenServer.
Getting Started Directory Description /SDK/docs/html/ Contains index.html, the HTML version of the reference for the API /SDK/windows-cli a Windows version of the CLI xe.exe /SDK/client-examples/c C examples and a Makefile to build them /SDK/client-examples/c/src C source for the language bindings /SDK/client-examples/csharp/XenSdk.net Microsoft Visual Studio 2005 solution which includes the C# language bindings (which compile...
Page 10
Getting Started From any other machine, fire up a web browser and type http://<SDK IP address>/ The full URL you need is also displayed in the “Message of the Day” in the SDK VM console after it has completed booting.
Chapter 3. Overview of the XenServer 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.
Overview of the XenServer API enumeration of the templates on a XenServer installation for yourself then you can execute the "xe tem- plate-list" CLI command.) To get a list of templates via the API, we need to find the VM objects on the server that have their "is_a_template"...
Overview of the XenServer API Although inactive sessions will timeout eventually, the server has a hardcoded limit of 200 concurrent ses- sions. Once this limit has been reached fresh logins will evict the oldest session objects, causing their as- sociated session references to become invalid. So if you want your applications to play nice with others accessing the server concurrently, then the best policy is to create a single session at start-of-day, use this throughout the applications (note that sessions can be used across multiple separate client-server network connections) and then explicitly logout when possible.
Page 14
Overview of the XenServer API fields include "virtual_size" and "sharable". (When we called VM.provision on the VM template in our previous example, some VDI objects were automatically created to represent the newly created disks, and attached to the VM object.) An SR (Storage Repository) aggregates a collection of VDIs and encapsulates the properties of physical storage on which the VDIs' bits reside.
Overview of the XenServer API A PBD (Physical Block Device) object represents an attachment between a Host and a SR (Storage Repository) object. Fields include "currently- attached" (which specifies whether the chunk of storage represented by the specified SR object) is currently available to the host; and "device_config"...
Page 16
Overview of the XenServer API 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: •...
Overview of the XenServer API Figure 3.2. A VM object with 2 associated VDIs For expository purposes, Figure 3.2, “A VM object with 2 associated VDIs” presents a graphical example that shows the relationship between VMs, VBDs, VDIs and SRs. In this instance a VM object has 2 attached VDIs: there are 2 VBD objects that form the connections between the VM object and its VDIs;...
Overview of the XenServer API 3.3.3.1. Host storage configuration: PBDs Let us start by considering the PBD class. A PBD_create(...) call takes a number of parameters including: Parameter Description host physical machine on which the PBD is available the Storage Repository that the PBD connects to device_config a string-to-string map that is provided to the host's SR-backend-driver, containing the low-level parameters required to configure the physical storage...
Overview of the XenServer API Argument Description uuid the uuid of the VM; required only if not using the reference For example: curl http://root:foo@xenserver/export&uuid=[VM UUID]&task_id= [task ID] -o export To export just the metadata, use the URI http://server/export_metadata The import protocol is similar, using HTTP(S) PUT. The [session_id] and [task_id] arguments are as for the export.
Chapter 4. Using the API This chapter describes how to use the XenServer Management API from real programs to manage XenServ- er Hosts and VMs. The chapter begins with a walk-through of a typical client application and demonstrates how the API can be used to perform common tasks. Example code fragments are given in python syntax but equivalent code in C and C# would look very similar.
Using the API • Remember to log out of active sessions to avoid leaking them; and • Be prepared to log in again to the server if a SESSION_INVALID error is caught. In the following fragment a connection via the Unix domain socket is established and a session created: import XenAPI session = XenAPI.xapi_local() try:...
Using the API session.xenapi.VM.start(vm, False, False) All API calls are by default synchronous and will not return until the operation has completed or failed. For example in the case of VM.start the call does not return until the VM has started booting. Note When the VM.start call returns the VM will be booting.
Using the API Events also contain a monotonically increasing ID, the name of the class of object and a snapshot of the object state equivalent to the result of a get_record(). Clients register for events by calling event.register() with a list of class names or the special string "*". Clients receive events by executing event.next() which blocks until events are available and returns the new events.
Using the API Dependencies:• XML-RPC library (libxml2.so on GNU Linux) • Curl library (libcurl2.so) One simple example is included within the SDK called test_vm_ops. The example demonstrates how to query the capabilities of a host, create a VM, attach a fresh blank disk image to the VM and then perform various powercycle operations.
Using the API • permute.py: selects a set of VMs and uses XenMotion to move them simultaneously between hosts; • powercycle.py: selects a set of VMs and powercycles them; • shell.py: a simple interactive shell for testing; • vm_start_async.py: demonstrates how to invoke operations asynchronously; and •...
Page 26
Using the API import sys, time import XenAPI Next the commandline arguments containing a server URL, username, password and a number of iterations are parsed. The username and password are used to establish a session which is passed to the function main, which is called multiple times in a loop.
Page 27
Using the API # use a rotation as a permutation hosts = [hosts[-1]] + hosts[:(len(hosts)-1)] Each VM is then moved via XenMotion to the new host under this rotation (i.e. a VM running on host at position 2 in the list will be moved to the host at position 1 in the list etc.) In order to execute each of the movements in parallel, the asynchronous version of the VM.pool_migrate is used and a list of task references constructed.
Using the API if not(allok): print "One of the tasks didn't succeed at", \ time.strftime("%F:%HT%M:%SZ", time.gmtime()) idx = 0 for task in tasks: record = records[task] vm_name = session.xenapi.VM.get_name_label(vms[idx]) host_name = session.xenapi.host.get_name_label(hosts[idx]) print "%s : %12s %s -> %s [ status: %s; result = %s; error = %s ]" % \ (record["uuid"], record["name_label"], vm_name, host_name, record["status"], record["result"], repr(record["error_info"])) idx = idx + 1...
Page 29
Using the API # Check if there's a VM by the uuid specified ${XE} vm-list params=uuid | grep -q " ${vmuuid}$" if [ $? -ne 0 ]; then echo "error: no vm uuid \"${vmuuid}\" found" exit 2 The script then checks the power state of the VM and if it is running, it attempts a clean shutdown. The event system is used to wait for the VM to enter state "Halted".
Chapter 5. XenServer API extensions The XenAPI is a general and comprehensive interface to managing the life-cycles of Virtual Machines, and offers a lot of flexibility in the way that XenAPI providers may implement specific functionality (e.g. storage provisioning, or console handling). XenServer has several extensions which provide useful functionality used in our own XenCenter interface.
XenServer API extensions 2. Master/443 to Client: Returns a session reference to be used with subsequent calls. 3. Client to Master/443: XML-RPC: VM.get_by_name_label(...). 4. Master/443 to Client: Returns a reference to a particular VM (or the "control domain" if you want to retrieve the physical host console).
XenServer API extensions xe vm-param-set uuid=uuid disable_pv_vnc=1 Start the VM. Use the CLI to retrieve the underlying domain ID of the VM with: xe vm-list params=dom-id uuid=uuid --minimal On the host console, connect to the text console directly by: /usr/lib/xen/bin/xenconsole domid This configuration is an advanced procedure, and we do not recommend that the text console is directly used for heavy I/O operations.
XenServer API extensions The network retrieval enables users to install the upstream Red Hat vendor kernel directly from their network repository. An updated XenServer kernel is also provided on the xs-tools.iso built-in ISO image which fixes various Xen-related bugs. 5.2.3. SUSE Enterprise Linux 10 SP1 This requires a two-round boot process.
XenServer API extensions • The device /dev/xen/evtchn, which is accessed via xs_evtchn_open() in libxenctrl. A han- dle can be restricted using xs_evtchn_restrict(). • The device /proc/xen/privcmd, accessed through xs_interface_open() in libxenctrl. A handle is restricted using xc_interface_restrict(). Some privileged commands are naturally hard to restrict (e.g.
XenServer API extensions For example, to enable TX checksumming on a virtual NIC via the xe CLI: xe vif-param-set uuid=<VIF UUID> other-config:ethtool-tx="on" xe vif-param-set uuid=<VIF UUID> other-config:ethtool-tx="true" To set the duplex setting on a physical NIC to half duplex via the xe CLI: xe vif-param-set uuid=<VIF UUID>...
XenServer API extensions • local-storage • xenserver-tools Additionally, other_config["i18n-original-value-<field name>"] gives the value of that field when the SR was created. If XenCenter sees a record where SR.name_label equals other_config["i18n-original-value-name_label"] (that is, the record has not changed since it was created during XenServer installation), then internationalization will be applied. In other words, Xen- Center will disregard the current contents of that field, and instead use a value appropriate to the user's own language.
Need help?
Do you have a question about the DL385 - ProLiant - G5 and is the answer not in the manual?
Questions and answers