XenServer Software Development Kit Guide 4.1.0 Published March 2008 1.
XenServer Software Development Kit Guide XenServer Software Development Kit Guide: Release 4.1.0 Published March 2008 Copyright © 2008 Citrix Systems, Inc. Xen®, Citrix™, Enterprise Edition™, XenServer™, Express Edition™, XenCenter™ and logos are either registered trademarks or trademarks of Citrix Systems, Inc. in the United States and/or other countries. Other company or product names are for informational purposes only and may be trademarks of their respective owners.
XenServer Software Development Kit Guide 3
Table of Contents 1. Introduction .................................................................................................................. 1 2. Getting Started ............................................................................................................ 2 2.1. System Requirements and Preparation ............................................................... 2 2.2. Downloading ..................................................................................................... 2 2.
XenServer Software Development Kit Guide 5.2.4. CentOS 4.5/5.0 .................................................................................... 5.3. Adding Xenstore entries to VMs ....................................................................... 5.4. Security enhancements ................................................................................... 5.5. Advanced settings for network interfaces .......................................................... 5.5.1. ethtool settings ................
List of Figures 3.1. Graphical overview of API classes for managing VMs, Hosts, Storage and Networking .................................................................................................................................. 9 3.2. A VM object with 2 associated VDIs .........................................................................
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. A free version, Express Edition, is available to download at http://www.xensource.com/.
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 to a .
Getting Started 3. From any other machine, fire up a web browser and type http:/// 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 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.
Overview of the XenServer API enumeration of the templates on a XenServer installation for yourself then you can execute the "xe template-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" field set to true. One way to do this by calling VM.get_all_records(session) where the session parameter is the reference we acquired from our Session.login_with_password call earlier.
Overview of the XenServer API Although inactive sessions will timeout eventually, the server has a hardcoded limit of 200 concurrent sessions. Once this limit has been reached fresh logins will evict the oldest session objects, causing their associated session references to become invalid.
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.) SR 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 PBD A PBD (Physical Block Device) object represents an attachment between a Host and a SR (Storage Repository) object. Fields include "currentlyattached" (which specifies whether the chunk of storage represented by the specified SR object) is currently available to the host; and "device_config" (which specifies storage-driver specific parameters that determines how the low-level storage devices are configured on the specified host -- e.g.
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: • name_label and name_description: a human-readable name/description for the disk (e.g.
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; and the VDIs reside within the same SR. 3.3.1.3.
Overview of the XenServer API 3.3.3.1. Host storage configuration: PBDs Let us start by considering the PBD class. A PBD_create(...
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. The [ref] and [uuid] are not used; a new reference and uuid will be generated for the VM.
Chapter 4. Using the API This chapter describes how to use the XenServer Management API from real programs to manage XenServer 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: session.xenapi.login_with_password("root", "") ... finally: session.xenapi.session.logout() 4.1.3.
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. To determine when the booting has finished, wait for the in-guest agent to report internal statistics through the VM_guest_metrics object 4.1.5.
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. 4.2.2. C# The C# bindings are contained within the directory /SDK/client-examples/csharp/XenSdk.
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 • watch-all-events.py: registers for all events and prints details when they occur. 4.2.4.
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. Note the use of try: finally: to make sure the program logs out of its session at the end. if __name__ == "__main__": if len(sys.argv) <> 5: print "Usage:" print sys.
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. Note the live flag passed to the VM.
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.
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 fi 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. The workings of these mechanisms are described in this chapter.
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). 5. Client to Master/443: XML-RPC: VM.get_consoles(...). 6. Master/443 to Client: Returns a list of console objects associated with the VM. 7. Client to Master/443: XML-RPC: VM.get_location(...). 8.
XenServer API extensions xe vm-param-set uuid=uuid disable_pv_vnc=1 2. Start the VM. 3. Use the CLI to retrieve the underlying domain ID of the VM with: xe vm-list params=dom-id uuid=uuid --minimal 4. 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. The first round downloads the kernel and ramdisk from the network repository and boots them.
XenServer API extensions • The device /dev/xen/evtchn, which is accessed via xs_evtchn_open() in libxenctrl. A handle 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. the ability to make arbitrary hypercalls), and these are simply prohibited on restricted handles.
XenServer API extensions For example, to enable TX checksumming on a virtual NIC via the xe CLI: xe vif-param-set uuid= other-config:ethtool-tx="on" or: xe vif-param-set 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= other-config:ethtool-duplex="half" 5.5.2. Miscellaneous settings You can also set a VIF or PIF to enable promiscuous mode via the promiscuous key.
XenServer API extensions • local-storage • xenserver-tools Additionally, other_config["i18n-original-value-"] 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.
Index 31
