Develop for XenServer

Using the XenServer PowerShell module

June 3, 2024

Contributed by:

This article describes how to use the XenServer PowerShell module to manage XenServer resource pools. The article includes an overview of the module cmdlets and their structure, followed by a number of walk-throughs on how to perform certain specialized tasks.

Getting Started

For information about the system requirements for the PowerShell module and how to download and install it, see Getting Started - PowerShell.

XenServer PowerShell module overview

XenServer sessions

The first cmdlet you will need is Connect-XenServer to open a session to a server:

Connect-XenServer -Url https://<servername> -UserName user -Password pwd
<!--NeedCopy-->

It is possible to connect to multiple servers using the same credentials as well as open more than one sessions to the same server. All open sessions can be listed using the cmdlet Get-XenSession. If more than one sessions are to be used, you can set the most frequently used session as the default one as follows:

Connect-XenServer -Server srv -UserName usr -Password pwd -SetDefaultSession
<!--NeedCopy-->

$XenServer_Default_Session = Get-XenSession -Server srv
<!--NeedCopy-->

All XenAPI calls are made in the context of a login session, so all cmdlets accept the parameter -SessionOpaqueRef which allows you to specify which of the open XenServer sessions to use:

Verb-Noun [-SessionOpaqueRef [<String>]]
<!--NeedCopy-->

This parameter is not necessary when only one open session exists or when a default session has been specified.

Once you have finished interacting with a server, it is good practice to log out using the cmdlet Disconnect-XenServer:

Get-XenSession | Disconnect-XenServer
<!--NeedCopy-->

Managing XenAPI objects

The cmdlets fall into the following categories:

1. Class getters

These retrieve a XenAPI object and have names such as Get-XenT, where T is an exposed XenAPI class. The object to get can be specified by -Ref or, for those that have a uuid or name, -Name or -Uuid. If no parameters are specified, all objects of this type are returned. Example:

Get-XenHost -Name "Demo Host"
<!--NeedCopy-->

2. Constructors

These create a new XenAPI object and have names such as New-XenT, where T is an exposed XenAPI class. Example:

$vm = Get-XenVM -Name "Demo VM"
New-XenVBD -VM $vm -VDI $null -Userdevice 3 -Bootable $false -Mode RO `
    -Type CD -Unpluggable $true -Empty $true -OtherConfig @{} `
    -QosAlgorithmType "" -QosAlgorithmParams @{}
<!--NeedCopy-->

3. Class removers

These destroy a XenAPI object and have names such as Remove-XenT, where T is an exposed XenAPI class. To specify the object to remove use the parameter -T, where T is the exposed XenAPI class, or -Ref or, for those objects that have a uuid or name, -UUID or -Name. Example:

Get-XenSR -Name "Demo SR" | Remove-XenSR
<!--NeedCopy-->

4. Property setters

These set a field of a XenAPI object and have names such as Set-XenT, where T is an exposed XenAPI class. To specify the object use the parameter -T, where T is the exposed XenAPI class, or -Ref or, for those objects that have a uuid or name, -UUID or -Name. The field to set can be specified as an accordingly named parameter. Note that more than one fields at a time can be set in a synchronous call. Example:

Get-XenVM -Name "Demo VM" |`
    Set-XenVM -NameLabel "New name" -NameDescription "New description"
<!--NeedCopy-->

5. Property adders

These add an element to a field of a XenAPI object and have names such as Add-XenT, where T is an exposed XenAPI class. To specify the object use the parameter -T, where T is the exposed XenAPI class, or -Ref or, for those objects that have a uuid or name, -UUID or -Name. The field to which the element will be added can be specified as an accordingly named parameter. Note that elements can be added to more than one fields at a time in a synchronous call. Example:

Add-XenHost -Name "Demo Host" -Tags "Tag1"
<!--NeedCopy-->

6. Property removers

These remove an element from a field of a XenAPI object and have names such as Remove-XenTProperty, where T is an exposed XenAPI class. To specify the object use the parameter -T, where T is the exposed XenAPI class, or -Ref or, for those objects that have a uuid or name, -UUID or -Name. The field from which the element will be removed can be specified as an accordingly named parameter. Note that elements can be removed from more than one fields at a time in a synchronous call. Example:

Remove-XenHostProperty -Name "myHost" -Tags "tag1" -OtherConfig "myKey"
<!--NeedCopy-->

7. Property getters

These retrieve the value of a field of a XenAPI object and have names such as Get-XenTProperty, where T is an exposed XenAPI class. To specify the object use the parameters -T, where T is the exposed XenAPI class, or -Ref. To specify the field use the enum parameter -XenProperty. Example:

Get-XenPIFProperty -Ref OpaqueRef:f433bf7b-2b0c-5f53-7018-7d195addb3ca `
    -XenProperty Network
<!--NeedCopy-->

8. Invokers

These invoke operations on XenAPI objects and have names such as Invoke-XenT, where T is an exposed XenAPI class. To specify the object use the parameter -T, where T is the exposed XenAPI class, or -Ref or, for those objects that have a uuid or name, -UUID or -Name. To specify the call to invoke, use the enum parameter -XenAction. Example:

Get-XenPBD -Uuid 1871ac51-ce6b-efc3-7fd0-28bc65aa39ff |`
    Invoke-XenPBD -XenAction Unplug
<!--NeedCopy-->

Most of the XenAPI calls can be run synchronously or asynchronously. To run a cmdlet asynchronously use the parameter -Async where available.

Note that, in the case of the setters, only one field can be set asynchronously at a time, and in the case of the adders and removers, elements can be added or removed asynchronously to only one field at a time.

Also, note that the cmdlets that are not explicit “getters” but return objects, do so only when the standard parameter -PassThru is specified. These cmdlets are Connect-XenServer, the constructors, adders, setters, certain invokers, the property removers, as well as all the asynchronous calls from any category. In the latter case, the cmdlet returns a Task object, the progress of which can be tracked by piping it into the cmdlet Wait-XenTask:

Invoke-XenVM -Name $vm_name -XenAction Start -Async -PassThru |`
    Wait-XenTask -ShowProgress
<!--NeedCopy-->

Wait-XenTask, too, can be used with the -PassThru parameter and, where applicable, it returns the opaque reference of the object that would be returned if the call were run synchronously.

Finally, as many of the cmdlets handle objects of type XenRef<T>, where T is an exposed API class, the cmldet ConvertTo-XenRef can be used to aid conversion between the two. Example:

Get-XenVM -Name "Demo VM" | ConvertTo-XenRef
<!--NeedCopy-->

Complete walk-throughs

How to configure vGPU and GPU pass-through

The following example is a tutorial of a typical vGPU configuration use case using the XenServer PowerShell SDK cmdlets. The example output provided is from a server with both a NVIDIA Grid K1 and K2 card installed.

We start by connecting to the server:

Connect-XenServer -Server server -UserName username -Password password
<!--NeedCopy-->

The first thing we probably want to check is which GPU groups exist (these have been created automatically once the graphics hardware is installed):

PS> Get-XenGPUGroup | select name_label, GPU_types, allocation_algorithm

name_label                                             GPU_types   allocation_algorithm
----------                                             ---------   --------------------
Group of NVIDIA Corporation GK104GL [GRID K2] GPUs   {10de/11bf}            depth_first
Group of NVIDIA Corporation GK107GL [GRID K1] GPUs   {10de/0ff2}          breadth_first
<!--NeedCopy-->

The allocation_algorithm is the placement policy for assigning VMs to GPUs in order to achieve either maximum density by placing as many VMs as possible on the same GPU (depth_first), or maximum performance by placing VMs on as many GPUs as possible (breadth_first). For example, the following command sets the allocation_algorithm to achieve maximum performance:

PS> Get-XenGPUGroup | Set-XenGPUGroup -AllocationAlgorithm breadth_first
PS> Get-XenGPUGroup | select name_label, GPU_types, allocation_algorithm

name_label                                             GPU_types    allocation_algorithm
----------                                             ---------    --------------------
Group of NVIDIA Corporation GK104GL [GRID K2] GPUs   {10de/11bf}           breadth_first
Group of NVIDIA Corporation GK107GL [GRID K1] GPUs   {10de/0ff2}           breadth_first
<!--NeedCopy-->

Now we can list some information about the vGPU types. The vGPU types are pre-sets which can be used to create different kinds of vGPUs.

PS> Get-XenVGPUType | ft vendor_name, model_name, framebuffer_size, max_heads, `
    max_resolution_x, max_resolution_y

vendor_name           model_name   framebuffer_size    max_heads   max_resolution_x   max_resolution_y
-----------           ----------   ----------------    ---------   ----------------   ----------------
NVIDIA Corporation    GRID K100           268435456            2               1920               1200
NVIDIA Corporation    GRID K140Q         1006632960            2               2560               1600
NVIDIA Corporation    GRID K240Q         1006632960            2               2560               1600
NVIDIA Corporation    GRID K260Q         2013265920            4               2560               1600
NVIDIA Corporation    GRID K200           268435456            2               1920               1200
                      passthrough                 0            0                  0                  0
<!--NeedCopy-->

The vGPU type passthrough is supported for all PCI display devices, and can be used to create pass-through vGPUs.

We can see for which PCI display devices a vGPU type is supported as follows:

PS> Get-XenVGPUType | Where {$_.model_name -eq "GRID K100"} |`
    Get-XenVGPUTypeProperty -XenProperty SupportedOnPGPUs |`
    Get-XenPGPU | Get-XenPCI -Ref {$_.PCI} | select device_name, pci_id

device_name          pci_id
-----------          ------
GK107GL [GRID K1]    0000:0a:00.0
GK107GL [GRID K1]    0000:07:00.0
GK107GL [GRID K1]    0000:08:00.0
GK107GL [GRID K1]    0000:09:00.0
<!--NeedCopy-->

A vGPU type will show up as supported or enabled in a GPU group if it is supported or enabled respectively on at least one of the pGPUs in the group. We can query the GPU groups to find out which vGPU types are supported or enabled. For example:

PS> Get-XenGPUGroup | Where {$_.name_label -match "GRID K2"} |`
    Get-XenGPUGroupProperty -XenProperty EnabledVGPUTypes |`
    Get-XenVGPUType | select model_name

model_name
----------
GRID K200
passthrough
GRID K260Q
GRID K240Q
<!--NeedCopy-->

We may want to disallow a certain vGPU type on a pGPU. For example, the following commands disable and then re-enable the vGPU type Grid K240Q:

PS> $vgpuType = Get-XenVgpuType | where {$_.model_name -eq "GRID K240Q"}
PS> $vgpuType | Get-XenVGPUTypeProperty -XenProperty EnabledOnPGPUs |`
    Get-XenPGPU | select uuid

uuid
----
a913a90d-0be9-aea3-862f-3fbfe1823a3f
8a0d1316-0f09-1ee9-f95b-c778c759ee40

PS> Remove-XenPGPUProperty -Uuid a913a90d-0be9-aea3-862f-3fbfe1823a3f `
    -EnabledVGPUTypes $vgputype.opaque_ref

PS> $vgpuType | Get-XenVGPUTypeProperty -XenProperty EnabledOnPGPUs |get-xenpgpu | select uuid

uuid
----
8a0d1316-0f09-1ee9-f95b-c778c759ee40

PS> Add-XenPGPU -Uuid a913a90d-0be9-aea3-862f-3fbfe1823a3f -EnabledVGPUTypes $vgputype.opaque_ref
PS> $vgpuType | Get-XenVGPUTypeProperty -XenProperty EnabledOnPGPUs |get-xenpgpu | select uuid

uuid
----
a913a90d-0be9-aea3-862f-3fbfe1823a3f
8a0d1316-0f09-1ee9-f95b-c778c759ee40
<!--NeedCopy-->

We may want to find out how many vGPUs of a certain type can be started on the pGPUs in a group, in addition to the vGPUs which are already running:

PS> $gpuGroups = Get-XenGPUGroup
PS> Get-XenVGPUtype | % {Get-XenGPUGroupProperty $gpuGroups[0] -XenProperty RemainingCapacity -VgpuType $_}

0
0
8
4
16
2
<!--NeedCopy-->

Now suppose we want to assign a vGPU of type Grid K260Q to a VM which has no vGPU yet. This can be done as follows:

PS> $vm = Get-XenVm -Name "w7-test"
PS> $vgpuTypes = Get-XenVGPUtype
PS> Get-XenVMProperty -VM $vm -XenProperty VGPUs
PS>
PS> New-XenVGPU -VM $vm -GPUGroup $gpuGroups[0] -Device 0 -Type $vgpuTypes[3] -PassThru

uuid               : f1122947-3b11-3fd3-0630-779701b37265
VM                 : XenAPI.XenRef`1[XenAPI.VM]
GPU_group          : XenAPI.XenRef`1[XenAPI.GPU_group]
device             : 0
currently_attached : False
other_config       : {}
type               : XenAPI.XenRef`1[XenAPI.VGPU_type]
resident_on        : XenAPI.XenRef`1[XenAPI.PGPU]
opaque_ref         : OpaqueRef:15b2d1a9-8944-2f28-53df-6b8274d4d6fb
Changed            : True
<!--NeedCopy-->

At this stage we can boot the VM, install the in-guest NVIDIA drivers, and enable RDP. Then we may want to disable the VNC console as this has a significant performance overhead. To do this we need to shut down the VM, set the flag vgpu_vnc_enabled to false and then boot the VM.

PS> Invoke-XenVM -VM $vm -XenAction Shutdown –Async –PassThru | Wait-XenTask –ShowProgress

PS> $p = Get-XenVMProperty -VM $vm -XenProperty Platform
PS> $p["vgpu_vnc_enabled"]="false"
PS> Set-XenVM -VM $vm -Platform $p
PS> Invoke-XenVM -VM $vm -XenAction Start –Async –PassThru | Wait-XenTask –ShowProgress
<!--NeedCopy-->

Start VM

Before finishing we should remember to disconnect from the server:

Get-XenSession | Disconnect-XenServer
<!--NeedCopy-->

How to copy or live migrate a VM across pools

The following tutorial shows how to use the XenServer PS module to migrate a running VM or copy a halted VM from a pool or standalone server, hereafter referred to as the source server, to a different pool or standalone server, hereafter referred to as the destination server.

This example also displays how to work with multiple sessions and use implicitly the global variable $XenServer_Default_Session.

We’re starting by connecting to the source server. The session created with the source server will be more frequently used, so it makes sense to set it as the default session:

Connect-XenServer -Url $sourceServerUrl -UserName $sourceServerUsername -Password $sourceServerPwd -SetDefaultSession
<!--NeedCopy-->

Let’s select the VM we are going to copy or live migrate from the source pool:

$theVM = Get-XenVM -Name $nameOfSourceVmToCopy
<!--NeedCopy-->

Note that in the above call we did not need to specify the -Session parameter since we have set the source session as the default one.

Then we need to connect to the destination pool and obtain its coordinator. Note that we will need to specify the -Session parameter in all calls made to the destination pool since this session is not the default one.

$destSession = Connect-XenServer -Url $destServerUrl -UserName $destServerUsername -Password $destServerPwd -PassThru

$destCoordinator = Get-XenPool -Session $destSession.opaque_ref | `
    select -ExpandProperty master | `
    Get-XenHost -Session $destSession.opaque_ref
<!--NeedCopy-->

The coordinator of the destination pool has to be prepared to receive the VM that will be live migrated or copied. For this, we will also need to obtain the details of the network on the destination pool through which migration traffic will be received.

$destTransferNetwork = Get-XenNetwork -Name $destTransferNetworkName -Session $destSession.opaque_ref

$destMap = Invoke-XenHost -XenAction MigrateReceive -XenHost $destCoordinator -Network $destTransferNetwork -Session $destSession.opaque_ref -options @null -PassThru
<!--NeedCopy-->

The next step is to map the VM’s VIFs to networks on the destination pool. Let’s consider a case where the destination pool has as many networks as the VIFs on the VM we want to live migrate or copy, so we can create a one-to-one mapping of VIFs to networks as follows:

$targetNetworkRefs = Get-XenNetwork -SessionOpaqueRef $destSession.opaque_ref | ConvertTo-XenRef

$vmVifRefs = $theVM.VIFs | Get-XenVIF | ConvertTo-XenRef

$vifmap = @{}

for ($i = 0; $i -lt $vmVifRefs.Count; $i++) {
    $vifmap[$vmVifRefs[$i]] = $targetNetworkRefs[$i]
}
<!--NeedCopy-->

Similarly, we proceed to map the VM’s disks to storage repositories on the destination pool. Let’s consider a simple case where we want to place all VM disks on the same storage repository with name $destSrName.

$targetSrRef = Get-XenSR -name $destSrName -SessionOpaqueRef $destSession.opaque_ref | ConvertTo-XenRef

$vdiRefs = $theVM.VBDs | Get-XenVBD | `
    where { $_.type -eq [XenAPI.vbd_type]::Disk} | `
    select -ExpandProperty VDI

$vdimap = @{}

foreach ($vdiRef in $vdiRefs) {
    $vdimap[$vdiRef] = $targetSrRef
}
<!--NeedCopy-->

Now we are ready to live migrate or copy the VM to the destination pool. Both operations are performed using the same cmdlet. However, we need to specify different options in each case. The call is run on the source pool session. Due to the long duration of the operation, it is recommended to run it asynchronously.

To live migrate a running VM:

$theTask = Invoke-XenVM -VM $theVM -XenAction MigrateSend -Live $true `
    -Dest $destMap -VifMap $vifmap -VdiMap $vdimap `
    -Options @{} -Verbose -Async -PassThru
<!--NeedCopy-->

Or, to copy a halted VM:

$theTask = Invoke-XenVM -VM $theVM -XenAction MigrateSend -Live $false `
    -Dest $destMap -VifMap $vifmap -VdiMap $vdimap `
    -Options @{"copy"="true"} -Verbose -Async -PassThru
<!--NeedCopy-->

In either case, we can monitor the task progress:

Wait-XenTask -Task $theTask -ShowProgress
<!--NeedCopy-->

Once the task is finished, we can query it to obtain the new VM on the destination pool:

$theTask = Get-XenTask -uuid $theTask.uuid

if ($theTask.status -eq [XenAPI.task_status_type]::success) {
    $doc = [xml]$theTask.result
    $newVmRef = $doc.value
    Get-XenVM -Ref $newVmRef -SessionOpaqueRef $destSession.opaque_ref
}
else {
    Write-Host "Operation failed: " $theTask.error_info
}
<!--NeedCopy-->

Finally, we need to disconnect from the source and the destination pools:

Get-XenSession | Disconnect-XenServer
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Using the XenServer PowerShell module

June 3, 2024

Contributed by:

June 3, 2024

Contributed by:

Using the XenServer PowerShell module

Getting Started

XenServer PowerShell module overview

XenServer sessions

Managing XenAPI objects

1. Class getters

2. Constructors

3. Class removers

4. Property setters

5. Property adders

6. Property removers

7. Property getters

8. Invokers

Complete walk-throughs

How to configure vGPU and GPU pass-through

How to copy or live migrate a VM across pools

In this article