Using the XenServer PowerShell module
This article describes how to use the XenServer PowerShell module to manage XenServer resource pools, starting with an overview of the module cmdlets and their structure.
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-->
or
$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
The following sections include a number of walk-throughs on how to perform certain specialized tasks.