Class XenClient

This class provides a simple light-weight XenServer or XCP-ng API that connects to the XenServer host operating system via SSH and executes commands using the xe XenServer client tool.

Inheritance

object

XenClient

Implements

IXenClient

Namespace: Neon.XenServer

Assembly: Neon.XenServer.dll

Syntax

public sealed class XenClient : IXenClient

Remarks

Ideally, we'd use the XenServer .NET API but at this time (Jan 2018), the API is not compatible with .NET Core which cluster neon-cli requires because it needs to run on Windows, OSX, and perhaps some day within the Ubuntu based tool container.

The workaround is to simnply connect to the XenServer host via SSH and perform commands using the xe command line tool installed with XenServer. We're going to take advantage of the SSH.NET package to handle the SSH connection and command execution.

XenServer template operations are implemented by the Template property, storage repository operations by Storage and virtual machine operations by Machine.

Constructors

XenClient(string, string, string, string, string)

Constructor. Note that you should dispose the instance when you're finished with it.

Declaration

public XenClient(string addressOrFQDN, string username, string password, string name = null, string logFolder = null)

Parameters

Type	Name	Description
string	addressOrFQDN	The target XenServer IP address or FQDN.
string	username	The user name.
string	password	The password.
string	name	Optionally specifies the XenServer name.
string	logFolder	The folder where log files are to be written, otherwise null or empty to disable logging.

Fields

LocalStorageName

Identifies the local storage repository.

Declaration

public const string LocalStorageName = "Local storage"

Field Value

Type	Description
string

Properties

Address

Returns the address or FQDN of the remote XenServer.

Declaration

public string Address { get; }

Property Value

Type	Description
string

LogWriter

Returns the client's log writer or null.

Declaration

public TextWriter LogWriter { get; }

Property Value

Type	Description
TextWriter

Machine

Implements the XenServer virtual machine operations.

Declaration

public XenClient.MachineOperations Machine { get; }

Property Value

Type	Description
XenClient.MachineOperations

Name

Returns the XenServer name as passed to the constructor.

Declaration

public string Name { get; }

Property Value

Type	Description
string

Storage

Implements the XenServer storage repository operations.

Declaration

public XenClient.StorageOperations Storage { get; }

Property Value

Type	Description
XenClient.StorageOperations

Template

Implements the XenServer virtual machine template operations.

Declaration

public XenClient.TemplateOperations Template { get; }

Property Value

Type	Description
XenClient.TemplateOperations

Methods

Connect()

Establishes an SSH connection to the assocated XenServer.

Declaration

public LinuxSshProxy Connect()

Returns

Type	Description
LinuxSshProxy	The connected LinuxSshProxy.

CreateTempIso(string, string)

Used for temporarily uploading an ISO disk to a XenServer such that it can be mounted to a VM, typically for one-time initialization purposes. NEONKUBE uses this as a very simple poor man's alternative to cloud-init for initializing a VM on first boot.

Declaration

public XenTempIso CreateTempIso(string isoPath, string srName = null)

Parameters

Type	Name	Description
string	isoPath	Path to the source ISO file on the local workstation.
string	srName	Optionally specifies the storage repository name. neon-UUID with a generated UUID will be used by default.

Returns

Type	Description
XenTempIso	A XenTempIso with information about the new storage repository and its contents.

Remarks

During cluster setup on virtualization platforms like XenServer and Hyper-V, NEONKUBE need to configure new VMs with IP addresses, hostnames, etc. Traditionally, we've relied on being able to SSH into the VM to perform all of these actions, but this relied on being VM being able to obtain an IP address via DHCP and for setup to be able to discover the assigned address.

The dependency on DHCP is somewhat problematic, because it's conceivable that this may not be available for more controlled environments. We looked into using Linux cloud-init for this, but that requires additional local infrastructure for non-cloud deployments and was also a bit more complex than what we had time for.

Instead of cloud-init, we provisioned our XenServer and Hyper-V node templates with a neon-init service that runs before the network service to determine whether a DVD (ISO) is inserted into the VM and runs the neon-init.sh script there one time, if it exists. This script will initialize the node's IP address and could also be used for other configuration as well, like setting user credentials.

note

In theory, we could have used the same technique for mounting a cloud-init data source via this ISO, but we decided not to go there, at least for now (we couldn't get that working).

note

NEONKUBE doesn't use this technique for true cloud deployments (AWS, Azure, Google,...) because we can configure VM networking directly via the cloud APIs.

The XenServer requires the temporary ISO implementation to be a bit odd. We want these temporary ISOs to be created directly on the XenServer host machine so users won't have to configure any additional infrastructure as well as to simplify cluster setup. We'll be creating a local ISO storage repository from a folder on the host. Any files to be added to the repository must exist when the repository is created and it is not possible to add, modify, or remove files from a repository after its been created.

note

XenServer hosts have only 4GB of free space at the root Linux level, so you must take care not to create large ISOs or to allow these to accumulate.

This method uploads the ISO file isoPath from the local workstation to the XenServer host, creating a new folder named with a UUID. Then a new storage repository will be created from this folder and a XenTempIso will be returned holding details about the new storage repository and its contents. The setup code will use this to insert the ISO into a VM.

Once the setup code is done with the ISO, it will eject it from the VM and call RemoveTempIso(XenTempIso) to remove the storage repository.

Dispose()

Releases any resources associated with the instance.

Declaration

public void Dispose()

GetHostInfo()

Returns information about the connected XenServer host machine.

Declaration

public XenHostInfo GetHostInfo()

Returns

Type	Description
XenHostInfo	The XenHostInfo.

Invoke(string, params string[])

Invokes a low-level XE-CLI command on the remote XenServer host that returns text.

Declaration

public ExecuteResponse Invoke(string command, params string[] args)

Parameters

Type	Name	Description
string	command	The XE-CLI command.
string[]	args	The optional arguments formatted as name=value.

Returns

Type	Description
ExecuteResponse	The command response.

InvokeItems(string, params string[])

Invokes a low-level XE-CLI command on the remote XenServer host that returns a list of items.

Declaration

public XenResponse InvokeItems(string command, params string[] args)

Parameters

Type	Name	Description
string	command	The XE-CLI command.
string[]	args	The optional arguments formatted as name=value.

Returns

Type	Description
XenResponse	The command XenResponse.

ParseValues(string)

Parses xe client properties formatted like name1:value1; name2: value2;... into a dictionary, making it easy to retrieve specific values.

Declaration

public static Dictionary<string, string> ParseValues(string property)

Parameters

Type	Name	Description
string	property	The property string.

Returns

Type	Description
Dictionary<string, string>	The case-insensitive dictionary.

RemoveTempIso(XenTempIso)

Removes a temporary ISO disk along with its PBD and storage repository.

Declaration

public void RemoveTempIso(XenTempIso tempIso)

Parameters

Type	Name	Description
XenTempIso	tempIso	The ISO disk information returned by CreateTempIso(string, string).

Remarks

CreateTempIso(string, string) for more information.

SafeInvoke(string, params string[])

Invokes a low-level XE-CLI command on the remote XenServer host that returns text, throwing an exception on failure.

Declaration

public ExecuteResponse SafeInvoke(string command, params string[] args)

Parameters

Type	Name	Description
string	command	The XE-CLI command.
string[]	args	The optional arguments formatted as name=value.

Returns

Type	Description
ExecuteResponse	The command response.

Exceptions

Type	Condition
XenException	Thrown if the operation failed.

SafeInvokeItems(string, params string[])

Invokes a low-level XE-CLI command on the remote XenServer host that returns a list of items, throwing an exception on failure.

Declaration

public XenResponse SafeInvokeItems(string command, params string[] args)

Parameters

Type	Name	Description
string	command	The XE-CLI command.
string[]	args	The optional arguments formatted as name=value.

Returns

Type	Description
XenResponse	The command XenResponse.

Exceptions

Type	Condition
XenException	Thrown if the operation failed.

WipeHost(bool, Func<XenTemplate, bool>)

Wipes the connected XenServer host by terminating and shutting down all virtual machines by default and optionally, selected virtual machine templates.

note

**WARNING:** This is dangerous and should only be used when you are **VERY** sure that important workloads are not being hosted on the XenServer. We generally use this for integration testing where XenServer hosts are dedicated exclusively for specific test runners.

Declaration

public void WipeHost(bool deleteVMs = true, Func<XenTemplate, bool> templateSelector = null)

Parameters

Type	Name	Description
bool	deleteVMs	Optionally disable virtual machine removal by passing false.
Func<XenTemplate, bool>	templateSelector	Optionally specifies a selector that chooses which templates are removed.

Implements

IXenClient