Product documentation
XenServer
8 Citrix Hypervisor 8.2 CU1
View PDF

Getting Started

November 21, 2023
Contributed by: 
X X

XenServer includes a Remote Procedure Call (RPC) based API providing programmatic access to the extensive set of XenServer management features and tools. You can call the XenServer Management API from a remote system or from local to the XenServer host.

It’s possible to write applications that use the XenServer Management API directly through raw RPC calls. However, the task of developing third-party applications is greatly simplified by using a language binding. These language bindings expose the individual API calls as first-class functions in the target language. The XenServer SDK provides language bindings for the C, C#, Java, Python, and PowerShell programming languages.

System Requirements and Preparation

The first step towards using the SDK is to install XenServer. XenServer is available for download at https://www.xenserver.com/downloads. For detailed instructions on how to set up your development host, see the Install XenServer. When the installation is complete, note the host IP address and the host password.

Downloading

The SDK is packaged as a ZIP file and is available as a free download from https://www.xenserver.com/downloads.

The Python module is also available as a package on PyPi. See section SDK Languages - Python for details.

SDK Languages

The extracted contents of the SDK ZIP file are in the XenServer-SDK directory. The following is an overview of its structure. Where necessary, subdirectories have their own individual README files.

Note:

The contents of the SDK ZIP consist of library binaries and their source code. Previous releases of the SDK ZIP included a number of examples for each of the SDK languages to help you get started with the SDK. These examples have now been removed from the SDK ZIP and are available at XenServer SDK usage examples on GitHub.

The examples provided aren’t the same across all the SDK languages. If you intend to use one language, it’s advisable to browse the sample code available in the others as well.

The top level of the XenServer-SDK directory includes the XenServer Management API Reference document. This document provides an overview of the API types and classes.

The API supports two wire formats, one based upon XML-RPC and one based upon JSON-RPC (v1.0 and v2.0 are both recognised). For more information on the API semantics and the wire protocol of the RPC messages, see section XenServer Management API. The format supported by each of the SDK languages is specified in the following paragraphs.

C

The XenServer-SDK directory contains the following folders that are relevant to C programmers:

  • libxenserver: The XenServer SDK for C.

    • bin: The libxenserver compiled library.

    • src: The libxenserver source code and a Makefile to build it. Every API object is associated with a header file, which contains declarations for all the object’s API functions. For example, the type definitions and functions required to invoke VM operations are all contained in xen_vm.h.

RPC protocol:

The C SDK supports the XML-RPC protocol.

Platform supported:

  • Linux
  • Windows (under cygwin)

Library:

The library is generated as libxenserver.so that is linked by C programs.

Note:

This library is not backwards compatible. To interact with hosts running older versions of XenServer or Citrix Hypervisor, it is advisable to use the library of the same version as the host.

Dependencies:

The library is dependent upon the XML toolkit from the GNOME project, by Daniel Veillard, et al. It is packaged as libxml2-devel on CentOS and libxml2-dev on Debian.

Building the source code:

To compile the source code type make in the libxenserver/src directory. To build on Windows with cygwin type make CYGWIN=1.

Examples:

Examples on the usage of the C SDK can be found at libxenserver usage examples on GitHub.

C #

The XenServer-SDK directory contains the following folders that are relevant to C# programmers:

  • XenServer.NET: The XenServer SDK for C#.NET.

    • XenServer.NET.x.y.z.nupkg: The compiled library shipped as a NuGet package.

    • src: XenServer.NET source code shipped as a Microsoft Visual Studio project. Every API object is associated with one C# file. For example, the functions implementing the VM operations are contained within the file VM.cs.

RPC protocol:

The C# SDK supports the JSON-RPC v2.0 protocol.

Platform supported:

  • Windows
  • Linux

The compiled library targets .NET Framework version 4.5 and .NET Standard 2.0.

Library:

The library is generated as a Dynamic Link Library XenServer.dll that C# programs can reference.

The C# SDK is backwards compatible and can be used to interact with hosts running all versions of XenServer or Citrix Hypervisor (from XenServer 7.3 and Citrix Hypervisor 8.0 onwards).

Dependencies:

Newtonsoft JSON.NET by James Newton-King. We use a patched version of the library (Newtonsoft.Json.CH.dll) shipped with XenServer.NET and recommend that you use this one, although others may work.

Installation:

To use the NuGet package in your code, add its location as a NuGet source:

nuget sources Add -Name "Offline Package" -Source "/full/path/to/package/directory"

Then install the package:

nuget install XenServer.NET

Building the source code:

Open the project XenServer.csproj in Visual Studio 2022. You should now be ready to build the source code.

Examples:

Examples on the usage of the C# SDK can be found at XenServer.NET usage examples on GitHub.

Java

The XenServer-SDK directory contains the following folders that are relevant to Java programmers:

  • XenServerJava: The XenServer SDK for Java

    • xen-api-x.y.z.jar: Java archive file containing the compiled library.

    • xen-api-x.y.z-javadoc.jar: Java archive file containing the documentation.

    • xen-api-x.y.z-sources.jar: Java archive file containing the source code as a Maven project. Every API object is associated with one Java file. For example the functions implementing the VM operations are contained within the file VM.java.

RPC protocol:

The Java SDK supports the XML-RPC protocol.

Platform supported:

  • Linux
  • Windows

Library:

  • The library is a Java archive file xenserver.jar that is linked by Java programs.

Note:

This library is generally, but not fully, backwards compatible. To interact with hosts running older versions of XenServer or Citrix Hypervisor, it is advisable to use the library of the same version as the host.

Dependencies:

XenServerJava is dependent upon Apache XML-RPC by the Apache Software Foundation.

Examples:

Examples on the usage of the Java SDK can be found at XenServerJava usage examples on GitHub.

PowerShell

The XenServer-SDK directory contains the following folders that are relevant to PowerShell users:

  • XenServerPowerShell: The XenServer SDK for PowerShell.

    • XenServerPSModule: The XenServer PowerShell module.

    • src: C# source code for the XenServer PowerShell cmdlets.

RPC protocol:

The PowerShell SDK supports the JSON-RPC v2.0 protocol.

Platform supported:

  • Windows
  • Linux

This library requires .NET 6.0 and PowerShell 7.2 or greater.

Library:

  • XenServerPSModule

Note:

This module is generally, but not fully, backwards compatible. To interact with hosts running older versions of XenServer or Citrix Hypervisor, it is advisable to use the module of the same version as the host.

Dependencies:

  • Newtonsoft JSON.NET by James Newton-King. We use a patched version of the library (Newtonsoft.Json.CH.dll) shipped with the XenServer PowerShell module, although others may work.
  • XenServer.NET, the C# SDK for XenServer.

Installation:

  1. Extract the contents of the SDK ZIP file.

    Note:

    Some web browsers may mark the SDK ZIP file as “blocked” during the download. To import the module successfully you will need to unblock the SDK ZIP file before extracting its contents. To unblock the SDK ZIP file, right-click on it and launch the Properties dialog. Click the Unblock button, then the Apply or OK button.

  2. Navigate to the extracted XenServer-SDK\XenServerPowerShell directory and copy the whole folder XenServerPSModule into your PowerShell modules directory.

    • On Windows this will normally be $env:UserProfile\Documents\PowerShell\Modules for per-user configuration, or $env:ProgramFiles\PowerShell\7\Modules for system-wide configuration.
    • On Linux this will be ~/.local/share/powershell/Modules for per-user configuration, or /usr/local/share/powershell/Modules for system-wide configuration.

    For more information see PowerShell’s documentation on module paths:

    Get-Help about_PSModulePath
<!--NeedCopy-->

  3. Open a PowerShell 7 prompt as administrator.

    To do this, open the Windows Start menu by clicking the Start icon, find the item PowerShell 7, right-click it and select Run as administrator.

  4. Determine the current execution policy:

    Get-ExecutionPolicy
<!--NeedCopy-->

    If the current policy is Restricted, you need to set it to RemoteSigned:

    Set-ExecutionPolicy RemoteSigned
<!--NeedCopy-->

    You should understand the security implications of this change. If you are unsure, see PowerShell’s documentation on execution policies:

    Get-Help about_Execution_Policies
<!--NeedCopy-->

    If the current policy is AllSigned, you will be able to use the XenServer PowerShell module, but it will be inconvenient because this policy requires even scripts that you write on the local computer to be signed. You may want to change it to RemoteSigned, as above.

    If the current policy is RemoteSigned, ByPass, or Unrestricted there is nothing to do.

  5. Exit the privileged instance of PowerShell.

  6. Open a PowerShell 7 prompt as a regular user (click Start > PowerShell 7) and import the XenServer PowerShell module:

    Import-Module XenServerPSModule
<!--NeedCopy-->

  7. If you wish to load specific environment settings when the XenServer PowerShell module is loaded, create the file XenServerProfile.ps1 and put it in the folder containing your $PROFILE file for per-user configuration, or in $PSHOME for system-wide configuration.

    • On Windows these will normally be $env:UserProfile\Documents\PowerShellfor per-user configuration, or $env:ProgramFiles\PowerShell\7 for system-wide configuration.

    • On Linux these will be ~/.config/powershell for per-user configuration, or /opt/microsoft/powershell/7 for system-wide configuration.

Getting help:

For an overview of the XenServer PowerShell module, type:

Get-Help about_XenServer
<!--NeedCopy-->

You can obtain a list of all available cmdlets by running:

Get-Command -Module XenServerPSModule
<!--NeedCopy-->

For help with a specific command use:

Get-Help [CommandName]
<!--NeedCopy-->

See Using the XenServer PowerShell module for an overview of the module cmdlets and their structure, and a number of walk-throughs on how to perform certain specialized tasks.

Building and debugging the source code:

Open the project XenServerPowerShell.csproj in Visual Studio 2022. You should now be ready to build the source code.

If in Debug mode, clicking Start will launch a PowerShell 7 prompt as an external process and import the compiled XenServerPowerShell.dll as a module (without, however, processing the scripts, types, and formats shipped within the XenServer PowerShell module). You should now be ready to debug the cmdlets.

Examples:

Examples on the usage of the XenServer Powershell module can be found at XenServer PowerShell Module usage examples on GitHub.

Python

The XenServer-SDK directory contains the following folders that are relevant to Python developers:

  • XenServerPython: This directory contains the XenServer Python module XenAPI.py.

Alternative installation

The Python module is also available as a package on PyPi. To install the package, enable the virtual environment where it will be used and run

pip install XenAPI

RPC protocol:

The Python module supports the XML-RPC protocol.

Platform supported:

  • Linux
  • Windows

Library:

  • XenAPI.py

Dependencies:

  • xmlrpclib

Examples:

Examples on the usage of the XenServer Powershell module can be found at XenAPI.py usage examples on GitHub.

Command line interface (CLI)

Besides using raw RPC or one of the supplied SDK languages, third-party software developers can integrate with XenServer hosts by using the xe command line interface xe. The xe CLI is installed by default on XenServer hosts. A stand-alone remote CLI is also available for Linux. On Windows, the xe.exe CLI executable is installed along with XenCenter.

Platform supported:

  • Linux
  • Windows

Library:

  • None

Binary:

  • xe on Linux
  • xe.exe on Windows

Dependencies:

  • None

The CLI allows almost every API call to be directly invoked from a script or other program, silently taking care of the required session management. The xe CLI syntax and capabilities are described in detail in the Command line interface documentation.

Note:

When running the CLI from a XenServer host console, tab completion of both command names and arguments is available.

Getting Started
November 21, 2023
Contributed by: 
X X
November 21, 2023
Contributed by: 
X X

In this article

Site feedback | Privacy and legal terms | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.