Overview

XenServer includes a XML-RPC based API, providing programmatic access to the extensive set of XenServer management features and tools. The XenServer API can be called from a remote system as well as local to the XenServer host. Remote calls are generally made securely over HTTPS, using port 443.

There are five SDKs available, one for each of C, C#, Java, PowerShell, and Python. These are provided under an open-source license (LGPL or GPL with the common linking exception). This allows use (unmodified) in both closed-and open-source applications.

There are also several example code samples also provided for download. Some of the code samples demonstrate creating a VM, running VM power operations, and watching for events.

The XenServer 5.6 SDKs are suitable not just for 5.6, but for use with XenServer 4.0, 4.1, 5.0 and 5.5 servers too, making it possible to address multiple XenServer versions with a single binary. There are, of course, features missing on the older versions, and client programs are expected to check host.software_version["product_version"] to gracefully fall back when appropriate.

  XenServer.NET: The XenServer SDK for C#.NET
       Download XenServer.NET binaries
       Download XenServer.NET samples
       Download XenServer.NET source

  XenServerJava: The XenServer SDK for Java
       Download XenServerJava binaries
       Download XenServerJava samples
       Download XenServerJava source

  libxenserver: The XenServer SDK for C
       Download libxenserver binaries
       Download libxenserver samples and source

  XenServerPSSnapIn: The XenServer SDK for PowerShell
       Download XS-PS Windows installer
       Download XS-PS source

  XenAPI.py: The XenServer Python module
       Download XenAPI.py
       Browse XenServer API examples using Python

  API Reference
       PDF
       HTML
       Javadoc (zip)

  XenServerConsole: A Java client for XenServer consoles
       Download XenServerConsole source

We also publish an appliance-style virtual machine, ready to be imported into a XenServer host. This contains the SDKs above, plus a XenServer simulator, and a complete Linux-based development environment.

  Download SDK VM: Version 5.6.0. 365 MB.
  XenServer SDK Guide
       PDF
       HTML

What is Citrix StorageLink?
Citrix StorageLink lets users automate the configuration and provisioning of the virtual machine storage, taking advantage of advanced features of the attached storage array. StorageLink enables the user to create virtual machines from logical vendor-specific storage repositories that support advanced capabilities such as snapshots, cloning, thin provisioning, and data deduplication. StorageLink also uses advanced storage capabilities to rapidly create virtual machines, increase storage utilization, and provide improved business continuity while lowering total cost of ownership.

Citrix StorageLink seamlessly integrates with storage arrays using either the standards-based SMI-S interface or via a custom vendor-specific StorageLink Storage Adapter.

Citrix StorageLink Gateway SDK (v2.0)

• Documentation for Web Services/SOAP interface for Citrix StorageLink Gateway.

Citrix StorageLink Storage Adapter SDK (v2.0)

• Citrix StorageLink SDK for storage partners.

Citrix StorageLink Gateway SDK (v2.1)

• Documentation for Web Services/SOAP interface for Citrix StorageLink Gateway.

Citrix StorageLink Storage Adapter SDK (v2.1)

• Citrix StorageLink SDK for storage partners.

XenServer Documentation Index

XenServer SDK Forum

Browse and Share Scripts and Samples on the CDN Script Exchange

xvp: An open-source web interface for XenServer, developed at Durham University

Note that the XenServer 5.6 SDKs are also suitable for use with XenServer 4.0, 4.1, 5.0 and 5.5 servers. These older releases are here for historical purposes only.

XenServer SDK Archive

Changes between revision 53 and revision 54:

In XenCenter 5.6 it is now possible to add custom menu items or even whole tabs to the main window. You might do this as an ISV to integrate your own product with XenCenter, or as an end-user to integrate with your company's existing inventory management, for example.

A menu item can run a Microsoft PowerShell script or even an arbitrary executable on the client machine. Tabs are populated with a web page, and can call out to other services on your network or to your VMs.

We welcome your feedback on this new feature, and would love to hear of any use cases that you have. Please comment at the bottom of this page.

Specification

XenCenter Plugins Specification

Tutorials and Examples

HelloWorld Example - PowerShell
HelloWorld Example - C Sharp
XenCenter Plugins - WebUI Tab Example
Citrix Console Plugins for Access Gateway, Netscaler and Branch Repeater
Parameters Hints and Tips
MessageBoard Example - JavaScript

Known issues

PowerShell plugins can sometimes fail to run properly. The symptom is that the plugin appears to run for ever without doing anything.

The underlying cause is that a required folder is never created: the workaround is to create the folder yourself. The folder is XenServerPSSnapIn within the Citrix application data directory. For example, it can normally be found at

C:\Documents and Settings\<user>\Application Data\Citrix\XenServerPSSnapIn

on Windows XP, or

C:\Users\<user>\AppData\Roaming\Citrix\XenServerPSSnapIn

on Windows Vista.

Changes between revision 20 and revision 21:

The following plugins have been written using the XenCenter Plugin specification to add a new tab inside XenCenter to access the console of Access Gateway, Net Scaler and Branch Repeater VMs:

• AccessGatewayVPX.msi
• NetScalerVPX.msi
• BranchRepeaterVPX.msi

Each of the plugins works in a similar way. A XenSearch in the plugin configuration xml toggles enablement of the plugin based on whether the correct tag is present on a selected running VM.

As an example, here is the Access Gateway configuration xml:

<?xml version="1.0" encoding="UTF-8"?>
  <XenCenterPlugin xmlns="http://www.citrix.com/XenCenter/Plugins/schema" version="2" plugin_version="1.0.0.0">
    <TabPage name="webui-tab" url="https://{$ip_address}:9001" search="967e62a3-45a0-4cc9-b7a7-de941ae754b1" />
    <MenuItem name="ui-menu-item" menu="vm" serialized="none" search="967e62a3-45a0-4cc9-b7a7-de941ae754b1">
      <Shell filename="https://{$ip_address}:9001" />
    </MenuItem>
    <MenuItem name="web-menu-item" menu="help" serialized="none">
      <Shell filename="http://citrix.com/accessgateway" />
    </MenuItem>
    <Search uuid="967e62a3-45a0-4cc9-b7a7-de941ae754b1" name="Access Gateway VPX" major_version="2" minor_version="0" show_expanded="yes">
    <Query>
      <QueryScope>
        <VM />
      </QueryScope>
      <GroupQuery type="And">
        <EnumPropertyQuery property="power_state" equals="yes" query="Running" />
        <StringListContainsQuery property="tags" query="Access Gateway VPX" contains="yes" />
      </GroupQuery>
    </Query>
  </Search>
</XenCenterPlugin>

Here are the resources and configuration files for each of the plugins:
NetScalerVPX.xcplugin.xml
NetScalerVPX.resx
BranchRepeaterVPX.xcplugin.xml
BranchRepeaterVPX.resx
AccessGatewayVPX.xcplugin.xml
AccessGatewayVPX.resx

Changes between revision 2 and revision 3:

XenCenter provides parameter sets to your plugin to describe the current selection in the XenCenter resource list. See the plugin specification for the full details of the data in a parameter set.

This page details how to deal with this information using a Shell command, which requires some thought as there are no handy global variables separating everything out as is the case with the PowerShell commands.

Shell commands and parameters

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
<XenCenterPlugin
	xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
	version="1">
	<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
			param="1, goodbye"
		/>
	</MenuItem>
</XenCenterPlugin>

When using a Shell command, your parameters are passed directly as arguments to the plugin executable. In addition to the parameter sets, you will also receive any parameters you define in the param attribute on your XML. Outlined here are several approaches you might take to parse these arguaments, with examples in C#.

Option 1 - No extra params

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
<XenCenterPlugin
	xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
	version="1">
	<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
		/>
	</MenuItem>
</XenCenterPlugin>

This is the simple option. We know that parameter sets come in groups of four arguments so if none of the menu item commands which call that executable define anything in the param attribute we can just read them off in groups.

private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets)
{
     ParamSets = new List<ParameterSet>();
     for (int i = 0; i < args.Length; i += 4)
     {
           ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3]));
     }
}

Option 2 - Fixed number of extra parameters

If you want to use extra parameters in your plugin commands, one option is to define a fixed number of extra parameters that each command must pass.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
<XenCenterPlugin
	xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
	version="1">
	<MenuItem
		name="goodbye-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
			param="goodbye"
		/>
	</MenuItem>
	<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
			param="hello"
		/>
	</MenuItem>
	<MenuItem
		name="quiet-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
			param="BLANK_PARAM"
		/>
	</MenuItem>
</XenCenterPlugin>

In this example you can see each command passes exactly one extra parameter, so we can read that off before moving onto the parameter sets. Commands that don't want to use all the parameters you are expecting can use a dummy keyword to keep the number of parameters consistent.

private static int numberOfExtraParams = 1;
private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets, out List<string> ExtraParams)
        {
            ExtraParams = new List<string>();
            for (int i = 0; i < numberOfExtraParams; i++)
            {
                ExtraParams.Add(args[i]);
            }
            ParamSets = new List<ParameterSet>();
            for (int i = numberOfExtraParams; i < args.Length; i += 4)
            {
                ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3]));
            }
        }

Option 3 - Variable number of extra parameters

Here we are going to use some sort of indicator to help us know how many extra parameters there are going to be before the parameter sets start in our list of arguments. There are several ways to do this, but here we are going to use the first extra parameter as an indicator for how many further extra parameters we should expect.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
<XenCenterPlugin
	xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
	version="1">
	<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
			param="1, goodbye"
		/>
	</MenuItem>
	<MenuItem
		name="busy-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
			param="2, hello, goodbye"
		/>
	</MenuItem>
</XenCenterPlugin>

private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets, out List<string> ExtraParams)
        {
            int numberOfExtraParams = 0;
            numberOfExtraParams = int.Parse(args[0]);
            ExtraParams = new List<string>();
            for (int i = 0; i < numberOfExtraParams; i++)
            {
                ExtraParams.Add(args[i + 1]);
            }
            ParamSets = new List<ParameterSet>();
            for (int i = numberOfExtraParams + 1; i < args.Length; i += 4)
            {
                ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3]));
            }
        }

This is a good technique as it only requires one extra parameter to encode the information and allows flexibility. Another alternative would be to have a marker which signifies that the extra parameters have finished:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
<XenCenterPlugin
	xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
	version="1">
	<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
			param="goodbye, END_EXTRA_PARAMS"
		/>
	</MenuItem>
	<MenuItem
		name="busy-menu-item"
		menu="view"
		serialized="none">
		<Shell
			filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
			window="true"
			param="hello, goodbye, END_EXTRA_PARAMS"
		/>
	</MenuItem>
</XenCenterPlugin>

Changes between revision 3 and revision 4:

		XenCenter provides parameter sets to your plugin to describe the current selection in the XenCenter resource list. See the plugin specification for the full details of the data in a parameter set.
		XenCenter provides parameter sets to your plugin to describe the current selection in the XenCenter resource list. See the [plugin specification|XenCenter Plugins] for the full details of the data in a parameter set.
		This page details how to deal with this information using a Shell command, which requires some thought as there are no handy global variables separating everything out as is the case with the PowerShell commands.
		h2. Shell commands and parameters
		{code}
		<?xml version="1.0" encoding="UTF-8"?>
		<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
		<XenCenterPlugin
		xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
		version="1">
		<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		param="1, goodbye"
		/>
		</MenuItem>
		</XenCenterPlugin>
		{code}
		When using a Shell command, your parameters are passed directly as arguments to the plugin executable. In addition to the parameter sets, you will also recieve any parameters you define in the _param_ attribute on your XML. Outlined here are several approaches you might take to parse these arguaments, with examples in C#.
		When using a Shell command, your parameters are passed directly as arguments to the plugin executable. In addition to the parameter sets, you will also receive any parameters you define in the _param_ attribute on your XML. Outlined here are several approaches you might take to parse these arguaments, with examples in C#.
		h4. Option 1 - No extra params
		{code}
		<?xml version="1.0" encoding="UTF-8"?>
		<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
		<XenCenterPlugin
		xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
		version="1">
		<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		/>
		</MenuItem>
		</XenCenterPlugin>
		{code}
		This is the simple option. We know that parameter sets come in groups of four arguaments so if none of the menu item commands which call that executable define anything in the _param_ attribute we can just read them off in groups.
		This is the simple option. We know that parameter sets come in groups of four arguments so if none of the menu item commands which call that executable define anything in the _param_ attribute we can just read them off in groups.
		{code}
		private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets)
		{
		ParamSets = new List<ParameterSet>();
		for (int i = 0; i < args.Length; i += 4)
		{
		ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3]));
		}
		}
		{code}
		h4. Option 2 - Fixed number of extra parameters
		If you want to use extra parameters in your plugin commands, one option is to define a fixed number of extra parameters that each command must pass.
		{code}
		<?xml version="1.0" encoding="UTF-8"?>
		<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
		<XenCenterPlugin
		xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
		version="1">
		<MenuItem
		name="goodbye-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		param="goodbye"
		/>
		</MenuItem>
		<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		param="hello"
		/>
		</MenuItem>
		<MenuItem
		name="quiet-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		param="BLANK_PARAM"
		/>
		</MenuItem>
		</XenCenterPlugin>
		{code}
		In this example you can see each command passes exactly one extra parameter, so we can read that off before moving onto the parameter sets. Commands that don't want to use all the parameters you are expecting can use a dummy keyword to keep the number of parameters consistent.
		{code}
		private static int numberOfExtraParams = 1;
		private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets, out List<string> ExtraParams)
		{
		ExtraParams = new List<string>();
		for (int i = 0; i < numberOfExtraParams; i++)
		{
		ExtraParams.Add(args[i]);
		}
		ParamSets = new List<ParameterSet>();
		for (int i = numberOfExtraParams; i < args.Length; i += 4)
		{
		ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3]));
		}
		}
		{code}
		h4. Option 3 - Variable number of extra parameters
		Here we are going to use some sort of indicator to help us know how many extra parameters there are going to be before the parameter sets start in our list of arguaments. There are several ways to do this, here we are going to use the first extra parameter as an indicator for how many further extra parameters we should expect.
		Here we are going to use some sort of indicator to help us know how many extra parameters there are going to be before the parameter sets start in our list of arguments. There are several ways to do this, but here we are going to use the first extra parameter as an indicator for how many further extra parameters we should expect.
		{code}
		<?xml version="1.0" encoding="UTF-8"?>
		<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
		<XenCenterPlugin
		xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
		version="1">
		<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		param="1, goodbye"
		/>
		</MenuItem>
		<MenuItem
		name="busy-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		param="2, hello, goodbye"
		/>
		</MenuItem>
		</XenCenterPlugin>
		{code}
		{code}
		private static void SeparateParams(string[] args, out List<ParameterSet> ParamSets, out List<string> ExtraParams)
		{
		int numberOfExtraParams = 0;
		numberOfExtraParams = int.Parse(args[0]);
		ExtraParams = new List<string>();
		for (int i = 0; i < numberOfExtraParams; i++)
		{
		ExtraParams.Add(args[i + 1]);
		}
		ParamSets = new List<ParameterSet>();
		for (int i = numberOfExtraParams + 1; i < args.Length; i += 4)
		{
		ParamSets.Add(new ParameterSet(args[i], args[i + 1], args[i + 2], args[i + 3]));
		}
		}
		{code}
		This is a good technique as it only requires 1 extra parameter to encode the information and allows flexibility. Another alternative would be to have a marker which signifies that the extra parameters have finished:
		This is a good technique as it only requires one extra parameter to encode the information and allows flexibility. Another alternative would be to have a marker which signifies that the extra parameters have finished:
		{code}
		<?xml version="1.0" encoding="UTF-8"?>
		<!DOCTYPE XenCenterPlugin PUBLIC "-//XENCENTERPLUGIN//DTD XENCENTERPLUGIN1//EN" "xencenter-1.dtd">
		<XenCenterPlugin
		xmlns="http://www.citrix.com/XenCenter/Plugins/schema"
		version="1">
		<MenuItem
		name="hello-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		param="goodbye, END_EXTRA_PARAMS"
		/>
		</MenuItem>
		<MenuItem
		name="busy-menu-item"
		menu="view"
		serialized="none">
		<Shell
		filename="Plugins\Citrix\HelloWorld\HelloWorld.exe"
		window="true"
		param="hello, goodbye, END_EXTRA_PARAMS"
		/>
		</MenuItem>
		</XenCenterPlugin>
		{code}

Project Kensho v1.3 Technology Preview

Installing the Project Kensho OVF Tool

Installing XenServer CIM Interfaces

Using the Project Kensho OVF Tool

Project Kensho OVF Tool Advanced Features

Project Kensho and Hyper-V

What is OVF?

Kensho OVF Technology

Project Kensho consists of the following components:
An OVF Tool , which utilizes the OVF standard for the creation and consumption of virtual appliance packages. This utility removes much of the complexities found in conversion and packaging tools.

A CIM interface to the XenServer™ API, which also adds a WSMAN interface to XenServer™. The Xen-CIM component is required by the Project Kensho OVF Tool and installs directly on the XenServer™. It can also be used as an interface for management of XenServer™ and XenServer™ hosted virtual machines.

Project Kensho 1.3 brings a wealth of powerfully simple features to both the Kensho OVF Tool and the CIM interface. These new features enable users to both manage a XenServer™ in new ways as well as reap the benefits of OVF in a XenServer™ and Hyper-V environment.

Kensho OVF Tool

• Compliant with the DMTF OVF 1.0.0 specification
• Compatibility with XenConvert 2.0 OVF content
• Support for importing into and exporting from a user defined XenServer Storage Repository (SR)
• OVF security features:
  • Encryption
  • Digital signing
• OVF compression
• Snapshot support
• Direct import of VMware OVF content simplifying migration and consumption of VMware content

XenServer-CIM Interface

• Support for XenServer™ 5.5
• Storage profile support
• Networking profile support
• Snapshot classes

The minimum environment to use the tools consists of: Project Kensho OVF Tool Host, a supported virtual machine host, and a Windows SMB share. Project Kensho requires the following services and software to support the components of the Project Kensho OVF Tool.

Prerequisites

Complete the following pre-installation tasks before installing Project Kensho components:

1. Read through this entire document
2. Read through the Project Kensho OVF Tool Readme
3. Setup a Windows file share:
   1. Create a file share from a Windows host
      1. Windows Server 2008 with the File Services Role provides the option of creating SMB or NFS based shares, be sure to select SMB.
      2. Windows Server 2003 and prior create SMB based shares by default.
   2. Obtain a user account and password that has change level access to this share.
4. Project Kensho OVF Tool Host:
   1. Windows XP, Windows Server 2003, or Windows Vista.
   2. Install .NET Framework version 3.5
   3. Install WinRM
5. XenServer™ Host:
   1. XenServer™ 5.0 or 5.5
6. Windows Server 2008 with Hyper-V Host
   1. Add the Hyper-V role

XenServer-CIM Interface Installation

To install the XenServer-CIM Interface on XenServer™, complete the following procedure:

Be Careful The install script creates a hidden ISO Storage Repository and copies two ISOs into it (xenserver-linuxfixup-disk.iso and xenserver-iscsi-target.iso). It also creates a helper VM template called 'iSCSI target' from xenserver-iscsi-target.iso. These are utilized by the Project Kensho OVF Tool. Do not remove, alter or add content to this storage repository.

1. Copy XenServerCIM-Install.tgz to the XenServer™ host to the path of: /tmp
2. From the XenServer™ console, execute the following:
   1. cd /tmp
   2. tar - xvzf XenServer-CIM.tgz
   3. cd /XenServer-CIM
   4. Install the XenServer-CIM and WSMAN providers:
      1. bash ./install.sh
      2. Answer the prompt to set the security level of the interface.

Project Kensho OVF Tool Installation

1. From the computer identified as the Project Kensho OVF Tool computer:
   1. Execute KenshoOVF_x86.msi or KenshoOVF_x64.msi
   2. Follow the prompts

Note The Project Kensho OVF Tool installer must execute via "run as administrator" option on Vista, Windows Server 2008, Windows 7 and Windows Server 2008 R2.

Windows Server 2008 with Hyper-V Configuration

These steps enable WinRM, modify the Windows Firewall rules and set the appropriate authorization to access WinRM remotely with Kensho OVF Tool.

1. At the Hyper-V host login as the administrator
2. Open a command prompt and execute the following commands:
   1. winrm quickconfig
   2. winrm p winrm/config/service @{AllowUnencrypted="true"}
   3. winrm p winrm/config/service/auth @{Basic="true"}
   4. winrm p winrm/config/client @{AllowUnencrypted="true"}
   5. winrm p winrm/config/client/auth @{Basic="true"}

XenServer-CIM Interface Uninstall Process

1. To uninstall the XenServer-CIM and WSMAN providers
   1. bash ./uninstall.sh
      1. If an ISO image is added to the ISO storage repository, answer the prompt to delete the 'XenServer Internal ISO library'
      2. If confirmed, the script deletes the hidden internal ISO storage repository created during install. All ISO images added into this storage repository will be deleted.

Project Kensho OVF Tool Uninstall Process

1. To uninstall Project Kensho OVF Tool:
   1. Open Add / Remove Programs (or Programs)
   2. Select the Project Kensho OVF Tool
   3. Select Remove

This section covers general administration and use of the XenServer CIM interface for XenServer™ and the Project Kensho OVF Tool.

XenServer-CIM Interface

Once installed, the XenServer-CIM interface requires no administration. Documentation is provided within the distribution that further describes using the interface and its options.

Project Kensho OVF Tool

The Project Kensho OVF Tool is the primary utility to create and consume OVF virtual appliances. When starting the utility, an initialization process occurs. This process gathers all of the library and server information from the systems defined by the user. In some scenarios, initialization may take up to 60 seconds or more to collect all data.

Figure 1 - Initializing Indicator

After completing initialization, the main UI appears

Figure 2 - Project Kensho OVF Tool

Adding virtual machine Host(s) and OVF Library Resources:

To begin using the utility, it is necessary to add at least one virtual machine host and an OVF Library. To add a virtual machine host or Library share:

1.   From the menu bar, select File > Add Server. Alternatively, pressing the hotkey combination Alt +A or clicking the Add Server icon on the toolbar invokes the Add Server configuration window.

2.   Select the platform type from the drop down menu:

	For a Library : Enter the server name (or IP address) Enter the share name (without slashes or subfolders) Enter the username and password Click Add .
Figure 3 - Adding a Library Server
	For a virtual machine host: Enter the server name (or IP address) Select the Host server protocol: Unsecure or Secure (HTTP/HTTPS) Enter the username and password Click Add
Figure 4 - Adding a XenServer™ Host

3.  The window will stay open after clicking the Add button. Repeat this process for each hypervisor and or library the Project Kensho OVF Tool will manage. Click the Close button when finished adding all servers.

Note When adding a Hyper V server the account used must be a member of the local Hyper-V host administrators group.

Creating a Virtual Appliance

After configuring a library and virtual machine host(s), the Project Kensho OVF Tool is ready to create a virtual appliance from one or more virtual machines. The virtual appliance will become an OVF package. The virtual appliance is exported from either a XenServer™ or Hyper-V host.

To export a virtual machine as an OVF virtual appliance, follow these easy steps:

1.   Select the Export Tab

Figure 5 - Export Tab

2.   Select the target library share from the Library tree view. This is where the OVF and associated VHD(s) will reside after export.

3.   From the tree view, expand the list of virtual machines under each virtual machine host.

4.   Select a virtual machine with a single click. This will place its qualified name into the Selected vMachine(s) list box. To remove the selection, double click the selection.

Be Aware There is no limit to the number of virtual machines to select for export. The more virtual machines selected, the longer the export will take and require more storage on the Library server. The amount of time to export per virtual machine is dependent on the virtual disk size, type, and network bandwidth between the virtual machine host and the library server.

5.   Click the Export button to begin. The result will be the OVF virtual appliance package containing the virtual machine(s) selected. It is important to enusre that the OVF package is tested before assuming it is good. The next section describes the import process.

Consuming a Virtual Appliance

The Project Kensho OVF Tool can consume any DMTF compliant OVF file that contains virtual machine disk(s) in the VHD or VMDK format. The virtual appliance is imported into either a XenServer™ or Hyper-V host.

To import an OVF virtual appliance, follow these easy steps:

1.   Select the Import Tab.

*Figure 6 - Import Tab

2.   Select the target virtual machine host or hosts from the respective Host type tree view.

3.   From the Kensho Library tree view, select an OVF virtual appliance.

Note OVA packages must be converted to OVF prior to Import. Please see: Converting an OVF package to an OVA for more information.

4.   If a virtual machine to host resource mapping is required - it is noted in the Mapping status field as Mapping: Required.

5.   Click the Mapping wizard button in the Tool bar to map virtual machine to host resources.

6.   Click the Import or Force button to begin the import.

Note The button will display Force if mapping is either incomplete or non-existent.

During a forced import devices are attached in a first found fashion. I.E. if the OVF has a network device defined on the VM an attempt will be made to attach that network to the first virtual network switch listed on the target host.

Advanced Packaging Capabilities

New to the Project Kensho 1.3 OVF Tool is support for a wide range of OVF virtual appliance packaging options. When selecting one or more VMs to export as a virtual appliance, the utility presents the following options:

Figure 7 - Export Options

Each option is unique and may be applied to any virtual appliance export. Selecting a check box enables the feature. Some features, like security options, require user input.

• Create OVA Package
  Selecting this option allows the user to create an OVA package. An OVA package is an archive containing OVF metadata, virtual disks, manifest and certificates in a single file. This feature is useful for scenarios where a single file containing all the necessary virtual machine components is desired. This option produces a file with an .ova extension. If a file inside of the OVF package is greater than 8 GB, the operation to create the OVA will fail.

• Compress OVA Package
  Selecting this option allows the user to compress the entire OVA package. To enable this option, the user must select the Create OVA Package option. This option is useful when the user seeks to reduce the overall file size of the of the OVA package. This option produces a file with the .ova.gz extension.

• Compress OVF Files Individually
  Selecting this option allows the user to compress the individual files within the OVA package. This differs from the option above in that each file within the OVA package is compressed. Selecting this option allows the user to achieve maximum compression of an OVA file. This option produces files within the OVA package with the .gz extension. The OVA package will have the .ova extension.

• Add Manifest
  Selecting this option instructs the Project Kensho OVF Tool to create a manifest file referencing the OVF files and their checksum. This option is useful when a user seeks improved reliability of the content. This option produces a file with the .mf extension.

• Encrypt Attached Files
  Selecting this option allows the user to encrypt the OVF related files. When selecting this option, the user must enter a passphrase. This option is useful when protecting appliance content is required.

• Sign OVF Package
  Selecting this option allows the user to digitally sign the OVF file with a certificate. This option is useful in providing security against unauthorized changes to the OVF file content.

• Include EULA(s)
  Selecting this option allows the user to create a virtual appliance with an End User License Agreement (EULA). This feature is useful when a virtual appliance requires end user agreement to a EULA before the virtual appliance installs on the target hypervisor. To add a EULA follow these directions:

1.   Click the Add EULA button

2.   Browse to the desired text file containing the EULA text.

Note The EULA must be a plain text file and cannot contain any formatting (such as HTML tags) or special characters.

3.   Select the EULA text file.

4.   Click Open

• Export Metadata Only
  Selecting this option allows the user to create an OVF without any virtual disk(s). This is useful when the user needs an OVF without virtual disk information.

Advanced Import Capabilities

New to the Project Kensho 1.3 OVF Tool is support for a range of OVF virtual appliance import options. When selecting one or more OVF virtual appliances to import, the utility presents the following options:

Figure 8 - Import Options

• Verify Digital Signature
  Selecting this option forces the import process to verify the digital signature that was used to sign the OVF during export. If the verification fails, this typically indicates that the OVF has been tampered with.

• Verify Manifest Content
  Selecting this option forces the import process to verify that the content of the manifest file matches what is in the OVF package. If this verification fails, it typically indicates that files are missing.

• Validate OVF Package
  Selecting this option forces the import process to validate the selected OVF file against the DMTF OVF 1.0.0 schema. This is useful to determine the compatibility of an OVF file.

• Import Metadata Only
  Selecting this option imports the metadata only. This is useful if configuration content is all that is needed. The virtual machine content will be created from a template or an existing virtual disk will be attached after import.

• Run Operating System Fixups
  Selecting this option runs automated scripts against the imported VMware based virtual appliance. This is necessary to ensure the VM boots properly. Select this option for Windows or Linux virtual machines imported from VMware sources. Fixup of virtual machines with more than two virtual disks is unsupported.

VM to Host Resource Mapping Wizard

The Project Kensho OVF Tool allows users to map system, storage, and networking resources defined in the OVF virtual appliance to the resources on the virtual machine host(s). This ensures that prior to import, the proper resources are paired and the virtual machine can power on minimizing administrative tasks.

Mapping is performed by selecting items (one or more) in the left column of the Mapping dialog and then selecting a target device in the right

The padlock icon depicts that a mapping of a VM device to Host resource has been set. Individual mappings may be cleared by selecting and clearing the lock icon.

An existing OVF to Host resource mapping may be cleared by clicking the Clear button on the Import tab.

1.   Begin the resource mapping process by Clicking the Mapping button in the Tool bar

2.   The mapping wizard launches and presents the Systems tab (this is the target Host for a VM workload).

Figure 9 - Unmapped VM CPU and memory workload

3.  Select the desired host resource in the right pane

4.  Select a VM resource(s) in the left pane

8Figure 10 - VM CPU and memory workload mapped Host*

5.  Click the Next button to map the Network resources.

*Figure 11 - Mapped VM Network Device to Hypervisor Network Device

6.   Select the desired host resource in the right pane

7.   Select a VM resource(s) in the left pane

8.   Click the Next button to map the Storage resources

Figure 12 - Mapped VM Storage to Hypervisor Storage

9.    Select the desired host resource in the right pane

10.   Select a VM resource(s) in the left pane

11.   Click Done to complete the wizard, save the mapping, and return to the Import screen.

Converting an OVF package to an OVA and vice versa

The Project Kensho OVF Tool facilitates the conversion of any DMTF compliant OVF export to a single OVA file.

To convert an OVF with the Project Kensho OVF Tool:

1.   Select the Import Tab

Figure 13 - OVA Menu

2.   From the Kensho Library, select an OVF.

3.   Right click the OVF and Select 'Convert to OVA'

4.   The reverse process is used to convert an OVA into an OVF.

Note The OVF icon depicts a folder that includes the OVF package configuration and associated file. The OVA icon indicates an OVF package that has been compressed, using tar format, into a single file with the extension .OVA The X icon indicates an OVF package that is not compliant with the DMTF Standards.

Environment Tab

The environment tab is a read-only view of the virtual machine host resources and environment.

Figure 14 - Environment Tab

VMware OVF Support

The Project Kensho OVF Tool facilitates importing VMware derived OVF content directly into a XenServer Storage Repository in the same manner as importing a XenConvert or Project Kensho produced OVF.

It is important to note that not all VMware OVF content is equal. VMware OVF content produced through the latest VMware utilities will result in a higher degree of import success. The following VMware OVF content has been successfully tested:

• vSphere 4
• Virtual Infrastructure 3
• VMware OVF Tool 0.9
• VMware OVF Tool 1.0
• VMware Studio 1.0
• VMware Workstation 6.5.3
• VMware Converter 4.0.x
• VMware Converter 3.0.3

Snapshot Support

The Project Kensho OVF Tool now supports creating virtual appliances from virtual machines with snapshots. Both XenServer 5.5 and Hyper-V support virtual machine snapshots.

When creating an OVF virtual appliance from a virtual machine with a snapshot, the current running state of the virtual machine is what the tool creates as a virtual appliance. This can also be described as the state that is experienced when the virtual machine is powered on.

If a virtual machine contains multiple snapshots, only the current running state of the virtual machine is exported. No snapshot history or detail is exported as part of the virtual appliance

Changes between revision 89 and revision 90: