Citrix XenServer xe Command Reference

Citrix XenServer xe command reference

This section provides a reference to the xe commands. They are grouped by objects that the commands

address, and listed alphabetically.

Bonding commands

Commands for working with network bonds, for resilience with physical interface failover. See the section

called “Creating NIC bonds on a standalone host” for details.

The bond object is a reference object which glues together master and member PIFs. The master PIF is

the bonding interface which must be used as the overall PIF to refer to the bond. The member PIFs are a

set of 2 or more physical interfaces which have been combined into the high-level bonded interface.

Bond parameters

Bonds have the following parameters:

Parameter Name Description Type

uuid unique identifier/object reference for the

bond

read only

master UUID for the master bond PIF read only

members set of UUIDs for the underlying bonded

PIFs

read only set parameter

bond-create

bond-create network-uuid=<network_uuid> pif-uuids=<pif_uuid_1,pif_uuid_2,…>

Create a bonded network interface on the network specified from a list of existing PIF objects. The command

will fail if PIFs are in another bond already, if any member has a VLAN tag set, if the referenced PIFs are

not on the same XenServer host, or if fewer than 2 PIFs are supplied.

bond-destroy

host-bond-destroy uuid=<bond_uuid>

Delete a bonded interface specified by its UUID from the XenServer host.

 

CD commands

Commands for working with physical CD/DVD drives on XenServer hosts.

CD parameters

CDs have the following parameters:

Parameter Name Description Type

uuid unique identifier/object reference for the

CD

read only

name-label Name for the CD read/write

name-description Description text for the CD read/write

allowed-operations A list of the operations that can be

performed on this CD

read only set parameter

current-operations A list of the operations that are currently

in progress on this CD

read only set parameter

sr-uuid The unique identifier/object reference for

the SR this CD is part of

read only

sr-name-label The name for the SR this CD is part of read only

vbd-uuids A list of the unique identifiers for the

VBDs on VMs that connect to this CD

read only set parameter

crashdump-uuids Not used on CDs since crashdumps

cannot be written to them

read only set parameter

virtual-size Size of the CD as it appears to VMs (in

bytes)

read only

physical-Utilization amount of physical space that the CD

image is currently taking up on the SR (in

bytes)

read only

type Set to User for CDs read only

sharable Whether or not the CD drive is sharable.

Default is false.

read only

read-only Whether the CD is read-only, if false, the

device is writable. Always true for CDs.

read only

storage-lock true if this disk is locked at the storage

level

read only

parent Reference to the parent disk, if this CD is

part of a chain

read only

149

Parameter Name Description Type

missing true if SR scan operation reported this

CD as not present on disk

read only

other-config A list of key/value pairs that specify

additional configuration parameters for

the CD

read/write map parameter

location The path on which the device is mounted read only

managed true if the device is managed read only

xenstore-data Data to be inserted into the xenstore tree read only map parameter

sm-config names and descriptions of storage

manager device config keys

read only map parameter

is-a-snapshot True if this template is a CD snapshot read only

snapshot_of The UUID of the CD that this template is

a snapshot of

read only

snapshots The UUID(s) of any snapshots that have

been taken of this CD

read only

snapshot_time The timestamp of the snapshot operation read only

cd-list

cd-list [params=<param1,param2,…>] [parameter=<parameter_value>…]

List the CDs and ISOs (CD image files) on the XenServer host or pool, filtering on the optional argument

params.

If the optional argument params is used, the value of params is a string containing a list of parameters of

this object that you want to display. Alternatively, you can use the keyword all to show all parameters. If

params is not used, the returned list shows a default subset of all available parameters.

Optional arguments can be any number of the CD parameters listed at the beginning of this section.

Console commands

Commands for working with consoles.

The console objects can be listed with the standard object listing command (xe console-list), and the

parameters manipulated with the standard parameter commands. See the section called “Low-level param

commands” for details.

Console parameters

Consoles have the following parameters:

150

Parameter Name Description Type

uuid The unique identifier/object reference for

the console

read only

vm-uuid The unique identifier/object reference of

the VM this console is open on

read only

vm-name-label The name of the VM this console is open

on

read only

protocol Protocol this console uses. Possible

values are vt100: VT100 terminal, rfb:

Remote FrameBuffer protocol (as used in

VNC), or rdp: Remote Desktop Protocol

read only

location URI for the console service read only

other-config A list of key/value pairs that specify

additional configuration parameters for

the console.

read/write map parameter

Event commands

Commands for working with events.

Event classes

Event classes are listed in the following table:

Class name Description

pool A pool of physical hosts

vm A Virtual Machine

host A physical host

network A virtual network

vif A virtual network interface

pif A physical network interface (separate VLANs are represented as several PIFs)

sr A storage repository

vdi A virtual disk image

vbd A virtual block device

pbd The physical block devices through which hosts access SRs

event-wait

event-wait class=<class_name> [<param-name>=<param_value>] [<param-name>=/=<param_value>]

151

Blocks other commands from executing until an object exists that satisfies the conditions given on the

command line. x=y means "wait for field x to take value y", and x=/=y means "wait for field x to take any

value other than y".

Example: wait for a specific VM to be running

xe event-wait class=vm name-label=myvm power-state=running

Blocks other commands until a VM called myvm is in the power-state "running."

Example: wait for a specific VM to reboot:

xe event-wait class=vm uuid=$VM start-time=/=$(xe vm-list uuid=$VM params=start-time –minimal)

Blocks other commands until a VM with UUID $VM reboots (i.e. has a different start-time value).

The cl
ass name can be any of the Event classes listed at the beginning of this section, and the parameters

can be any of those listed in the CLI command class-param-list.

Host (XenServer host) commands

Commands for interacting with XenServer host.

XenServer hosts are the physical servers running XenServer software. They have VMs running on them

under the control of a special privileged Virtual Machine, known as the control domain or domain 0.

The XenServer host objects can be listed with the standard object listing command (xe host-list, xe hostcpu-

list, and xe host-crashdump-list), and the parameters manipulated with the standard parameter

commands. See the section called “Low-level param commands” for details.

Host selectors

Several of the commands listed here have a common mechanism for selecting one or more

XenServer hosts on which to perform the operation. The simplest is by supplying the argument

host=<uuid_or_name_label>. XenServer hosts can also be specified by filtering the full list of hosts on

the values of fields. For example, specifying enabled=true will select all XenServer hosts whose enabled

field is equal to true. Where multiple XenServer hosts are matching, and the operation can be performed

on multiple XenServer hosts, the option –multiple must be specified to perform the operation. The full

list of parameters that can be matched is described at the beginning of this section, and can be obtained

by running the command xe host-list params=all. If no parameters to select XenServer hosts are given,

the operation will be performed on all XenServer hosts.

Host parameters

XenServer hosts have the following parameters:

Parameter Name Description Type

uuid The unique identifier/object

reference for the XenServer

host

read only

name-label The name of the XenServer

host

read/write

name-description The description string of the

XenServer host

read only

152

Parameter Name Description Type

enabled false if disabled which

prevents any new VMs from

starting on them, which

prepares the XenServer hosts

to be shut down or rebooted;

true if the host is currently

enabled

read only

API-version-major major version number read only

API-version-minor minor version number read only

API-version-vendor identification of API vendor read only

API-version-vendor-implementation details of vendor

implementation

read only map parameter

logging logging configuration read/write map parameter

suspend-image-sr-uuid the unique identifier/object

reference for the SR where

suspended images are put

read/write

crash-dump-sr-uuid the unique identifier/object

reference for the SR where

crash dumps are put

read/write

software-version list of versioning parameters

and their values

read only map parameter

capabilities list of Xen versions that the

XenServer host can run

read only set parameter

other-config A list of key/value pairs

that specify additional

configuration parameters for

the XenServer host

read/write map parameter

hostname XenServer host hostname read only

address XenServer host IP address read only

supported-bootloaders list of bootloaders that the

XenServer host supports, for

example, pygrub, eliloader

read only set parameter

memory-total total amount of physical RAM

on the XenServer host, in

bytes

read only

memory-free total amount of physical

RAM remaining that can be

allocated to VMs, in bytes

read only

153

Parameter Name Description Type

host-metrics-live true if the host is operational read only

logging The syslog_destination

key can be set to the

hostname of a remote

listening syslog service.

read/write map parameter

allowed-operations lists the operations allowed in

this state. This list is advisory

only and the server state may

have changed by the time this

field is read by a client.

read only set parameter

current-operations lists the operations currently

in process. This list is

advisory only and the server

state may have changed by

the time this field is read by a

client

read only set parameter

patches Set of host patches read only set parameter

blobs Binary data store read only

memory-free-computed A conservative estimate of

the maximum amount of

memory free on a host

read only

ha-statefiles The UUID(s) of all HA

statefiles

read only

ha-network-peers The UUIDs of all hosts that

could host the VMs on this

host in case of failure

read only

external-auth-type Type of external

authentication, for example,

Active Directory.

read only

external-auth-service-name The name of the external

authentication service

read only

external-auth-configuration Configuration information for

the external authentication

service.

read only map parameter

XenServer hosts contain some other objects that also have parameter lists.

CPUs on XenServer hosts have the following parameters:

154

Parameter Name Description Type

uuid The unique identifier/object reference for

the CPU

read only

number the number of the physical CPU core

within the XenServer host

read only

vendor the vendor string for the CPU name, for

example, "GenuineIntel"

read only

speed The CPU clock speed, in Hz read only

modelname the vendor string for the CPU model,

for example, "Intel(R) Xeon(TM) CPU

3.00GHz"

read only

stepping the CPU revision number read only

flags the flags of the physical CPU (a decoded

version of the features field)

read only

Utilization the current CPU utilization read only

host-uuid the UUID if the host the CPU is in read only

model the model number of the physical CPU read only

family the physical CPU family number read only

Crash dumps on XenServer hosts have the following parameters:

Parameter Name Description Type

uuid The unique identifier/object reference for

the crashdump

read only

host XenServer host the crashdump

corresponds to

read only

timestamp Timestamp of the date and time that

the crashdump occurred, in the form

yyyymmddhhmmssABC, where ABC is

the timezone indicator, for example, GMT

read only

size size of the crashdump, in bytes read only

host-backup

host-backup file-name=<backup_filename> host=<host_name>

Download a backup of the control domain of the specified XenServer host to the machine that the command

is invoked from, and save it there as a file with the name file-name.

While the xe host-backup command will work if executed on the local host (that is, without a specific

hostname specified), do not use it this way. Doing so would fill up the control domain partition with the

155

backup file. The command should only be used from a remote off-host machine where you have space to

hold the backup file.

host-bugreport
-upload

host-bugreport-upload [<host-selector>=<host_selector_value>…] [url=<destination_url>]

[http-proxy=<http_proxy_name>]

Generate a fresh bug report (using xen-bugtool, with all optional files included) and upload to the Citrix

Support ftp site or some other location.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

Optional parameters are http-proxy: use specified http proxy, and url: upload to this destination URL. If

optional parameters are not used, no proxy server is identified and the destination will be the default Citrix

Support ftp site.

host-crashdump-destroy

host-crashdump-destroy uuid=<crashdump_uuid>

Delete a host crashdump specified by its UUID from the XenServer host.

host-crashdump-upload

host-crashdump-upload uuid=<crashdump_uuid>

[url=<destination_url>]

[http-proxy=<http_proxy_name>]

Upload a crashdump to the Citrix Support ftp site or other location. If optional parameters are not used, no

proxy server is identified and the destination will be the default Citrix Support ftp site. Optional parameters

are http-proxy: use specified http proxy, and url: upload to this destination URL.

host-disable

host-disable [<host-selector>=<host_selector_value>…]

Disables the specified XenServer hosts, which prevents any new VMs from starting on them. This prepares

the XenServer hosts to be shut down or rebooted.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

host-dmesg

host-dmesg [<host-selector>=<host_selector_value>…]

Get a Xen dmesg (the output of the kernel ring buffer) from specified XenServer hosts.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

host-emergency-management-reconfigure

host-emergency-management-reconfigure interface=<uuid_of_management_interface_pif>

156

Reconfigure the management interface of this XenServer host. Use this command only if the XenServer

host is in emergency mode, meaning that it is a member in a resource pool whose master has disappeared

from the network and could not be contacted for some number of retries.

host-enable

host-enable [<host-selector>=<host_selector_value>…]

Enables the specified XenServer hosts, which allows new VMs to be started on them.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

host-evacuate

host-evacuate [<host-selector>=<host_selector_value>…]

Live migrates all running VMs to other suitable hosts on a pool. The host must first be disabled using the

host-disable command.

If the evacuated host is the pool master, then another host must be selected to be the pool master. To change

the pool master with HA disabled, you need to use the pool-designate-new-master command. See the

section called “pool-designate-new-master” for details. With HA enabled, your only option is to shut down

the server, which will cause HA to elect a new master at random. See the section called “host-shutdown”.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

host-forget

host-forget uuid=<XenServer_host_UUID>

The xapi agent forgets about the specified XenServer host without contacting it explicitly.

Use the –force parameter to avoid being prompted to confirm that you really want to perform this

operation.

Warning:

Don’t use this command if HA is enabled on the pool. Disable HA first, then enable it again after you’ve

forgotten the host.

Tip:

This command is useful if the XenServer host to "forget" is dead; however, if the XenServer host is live and

part of the pool, you should use xe pool-eject instead.

host-get-system-status

host-get-system-status filename=<name_for_status_file>

[entries=<comma_separated_list>] [output=<tar.bz2 | zip>] [<host-selector>=<host_selector_value>…]

Download system status information into the specified file. The optional parameter entries is a commaseparated

list of system status entries, taken from the capabilities XML fragment returned by the hostget-

system-status-capabilities command. See the section called “host-get-system-status-capabilities” for

157

details. If not specified, all system status information is saved in the file. The parameter output may be

tar.bz2 (the default) or zip; if this parameter is not specified, the file is saved in tar.bz2 form.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above).

host-get-system-status-capabilities

host-get-system-status-capabilities [<host-selector>=<host_selector_value>…]

Get system status capabilities for the specified host(s). The capabilities are returned as an XML fragment

that looks something like this:

<?xml version="1.0" ?> <system-status-capabilities>

<capability content-type="text/plain" default-checked="yes" key="xenserver-logs"

max-size="150425200" max-time="-1" min-size="150425200" min-time="-1"

pii="maybe"/>

<capability content-type="text/plain" default-checked="yes"

key="xenserver-install" max-size="51200" max-time="-1" min-size="10240"

min-time="-1" pii="maybe"/>

</system-status-capabilities>

Each capability entity has a number of attributes.

Attribute Description

key A unique identifier for the capability.

content-type Can be either text/plain or application/data. Indicates whether a

UI can render the entries for human consumption.

default-checked Can be either yes or no. Indicates whether a UI should select

this entry by default.

min-size, max-size Indicates an approximate range for the size, in bytes, of this

entry. -1 indicates that the size is unimportant.

min-time, max-time Indicate an approximate range for the time, in seconds, taken

to collect this entry. -1 indicates the time is unimportant.

pii Personally identifiable information. Indicates whether the entry

would have information that would identi
fy the system owner, or

details of their network topology. This is one of:

no: no PII will be in these entries

yes: PII will likely or certainly be in these entries

maybe: you might wish to audit these entries for PII

if_customized if the files are unmodified, then they will

contain no PII, but since we encourage editing of these files,

PII may have been introduced by such customization. This

is used in particular for the networking scripts in the control

domain.

Passwords are never to be included in any bug report,

regardless of any PII declaration.

158

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above).

host-is-in-emergency-mode

host-is-in-emergency-mode

Returns true if the host the CLI is talking to is currently in emergency mode, false otherwise. This CLI

command works directly on slave hosts even with no master host present.

host-apply-edition

host-apply-edition [host-uuid=<XenServer_host_UUID>]

[edition=xenserver_edition=<"free"><"advanced"><"enterprise"><"platinum"><"enterprise-xd">]

Assigns a XenServer license to a host server. When you assign a license, XenServer contacts the Citrix

License Server and requests the specified type of license. If a license is available, it is then checked out

from the license server.

For Citrix XenServer for XenDesktop editions, use <"enterprise-xd">.

For initial licensing configuration, see also license-server-address and license-server-port.

license-server-address

license-server-address [license-server-address=license_server_address hostuuid=

XenServer<_host_UUID>]

For XenServer Advanced Edition and higher, use to specify either a license server name or IP address.

Run on the pool master before initial use. Specifies the name of the license server the pool is to use. Assigns

a XenServer license to a host server. Optionally use with the license-server-port command. You only need

to set the license server address once and the information is retained until you change it.

license-server-port

license-server-port [license-server-port=license_server_port host-uuid=XenServer<_host_UUID>]

For XenServer Advanced Edition and higher, specifies the port the host is to use to communicate with the

Citrix License Server. The default port is 27000, which is the port the license server uses by default for

communications with Citrix products. If you changed the port on the Citrix License Server, specify the new

port number using this command. Otherwise, you do not need to run this command. For more information

about changing port numbers due to conflicts, see the licensing topics in Citrix eDocs.

host-license-add

host-license-add [license-file=<path/license_filename>] [host-uuid=<XenServer_host_UUID>]

For XenServer (free edition), use to parses a local license file and adds it to the specified XenServer host.

Note:

This command only applies to free XenServer. XenServer 5.6 Advanced edition and higher use the hostapply-

edition, license-server-address and license-server-port commands. For these editions licensing has

changed. They now use the licensing model described in the Citrix XenServer 5.6 Installation Guide.

159

host-license-view

host-license-view [host-uuid=<XenServer_host_UUID>]

For XenServer (free edition), displays the contents of the XenServer host license.

Note:

This command only applies to free XenServer. XenServer 5.6 Advanced edition and higher use the hostapply-

edition, license-server-address and license-server-port commands. For these editions licensing has

changed. They now use the licensing model described in the Citrix XenServer 5.6 Installation Guide.

host-logs-download

host-logs-download [file-name=<logfile_name>] [<host-selector>=<host_selector_value>…]

Download a copy of the logs of the specified XenServer hosts. The copy is saved by default in a timestamped

file named hostname-yyyy-mm-dd T hh:mm:ssZ.tar.gz. You can specify a different

filename using the optional parameter file-name.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

While the xe host-logs-download command will work if executed on the local host (that is, without a specific

hostname specified), do not use it this way. Doing so will clutter the control domain partition with the copy

of the logs. The command should only be used from a remote off-host machine where you have space to

hold the copy of the logs.

host-management-disable

host-management-disable

Disables the host agent listening on an external management network interface and disconnects all

connected API clients (such as the XenCenter). Operates directly on the XenServer host the CLI is

connected to, and is not forwarded to the pool master if applied to a member XenServer host.

Warning:

Be extremely careful when using this CLI command off-host, since once it is run it will not be possible to

connect to the control domain remotely over the network to re-enable it.

host-management-reconfigure

host-management-reconfigure [interface=<device> ] | [pif-uuid=<uuid> ]

Reconfigures the XenServer host to use the specified network interface as its management interface,

which is the interface that is used to connect to the XenCenter. The command rewrites the

MANAGEMENT_INTERFACE key in /etc/xensource-inventory.

If the device name of an interface (which must have an IP address) is specified, the XenServer host will

immediately rebind. This works both in normal and emergency mode.

If the UUID of a PIF object is specified, the XenServer host determines which IP address to rebind to itself.

It must not be in emergency mode when this command is executed.

Warning:

160

Be careful when using this CLI command off-host and ensure that you have network connectivity on the

new interface. Use xe pif-reconfigure to set one up first. Otherwise, subsequent CLI commands will reach

the XenServer host.

host-power-on

host-power-on [host=<host_uuid> ]

Turns on power on XenServer hosts with Host Power On functionality enabled. Before using this command,

host-set-power-on must be enabled on the host.

host-set-power-on

host-set-power-on {host=<host uuid> {power-on-mode=<""> <"wake-on-lan"> <"iLO"> <"DRAC">

<"custom"> } | [power-on-config=<"power_on_ip"><"power_on_user"><"power_on_password_secret">] }

Use to enable Host Power On functionality on XenServer hosts that are compatible with remote power

solutions. Workload Balancing requires Host Power On functionality is enabled for it to turn off underused

hosts in Maximum Density mode. When using the host-set-power-on command, you must specify the

type of power management solution on the host (that is, the <power-on-mode>). Then specify configuration

options using the <power-on-config> argument and its associated key-value pairs. To use the secrets feature

to store your password, specify the key "power_on_password_secret".

host-reboot

host-reboot [<host-selector>=<host_selector_value>…]

Reboot the specified XenServer hosts. The specified XenServer hosts must be disabled first using the xe

host-disable command, otherwise a HOST_IN_USE error message is displayed.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

If the specified XenServer hosts are members of a pool, the loss of connectivity on shutdown will be handled

and the pool will recover when the XenServer hosts returns. If you shut down a pool member, other members

and the master will continue to function. If you shut down the master, the pool will be out of action until the

master is rebooted and back on line (at which point the members will reconnect and synchronize with the

master) or until you make one of the members into the master.

host-restore

host-restore [file-name=<backup_filename>] [<host-selector>=<host_selector_value>…]

Restore a backup named file-name of the XenServer host control software. Note that the use of the

word "restore" here does not mean a full restore in the usual sense, it merely means that the compressed

backup file has been uncompressed and unpacked onto the secondary partition. After you’ve done a xe

host-restore, you have to boot the Install CD and use its Restore from Backup option.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

host-set-hostname-live

host-set-hostname host-uuid=<uuid_of_host> hostname=<new_hostname>

161

Change the hostname of the XenServer host specified by host-uuid. This command persistently sets

both the hostname in the control domain database and the actual Linux hostname of the XenServer host.

Note that hostname is not the same as the value of the name_label field.

host-shutdown

host-shutdown [<host-selector>=<host_selector_value>…]

Shut down the specified XenServer hosts. The specified XenServer hosts must be disabled first using the

xe host-disable command, otherwise a HOST_IN_USE error message is displayed.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

If the specified XenServer hosts are members of a pool, the loss of connectivity on shutdown will be handled

and the pool will recover when the XenServer hosts returns. If you shut down a pool member, other members

and the master will continue to function. If you shut down the master, the pool will be out of action until

the master is rebooted and back on line, at which point the members will reconnect and synchronize with

the master, or until one of the members is made into the master. If HA is enabled for the pool, one of the

members will be made into a master automatically. If HA is disabled, you must manually designate the

desired server as master with the pool-designate-new-master command. See the section called “pooldesignate-

new-master”.

host-syslog-reconfigure

host-syslog-reconfigure [<host-selector>=<host_selector_value>…]

Reconfigure the syslog daemon on the specified XenServer hosts. This command applies the configuration

information defined in the host logging parameter.

The host(s) on which this operation should be performed are selected using the standard selection

mechanism (see host selectors above). Optional arguments can be any number of the host selectors listed

at the beginning of this section.

Log commands

Commands for working with logs.

log-get-keys

log-get-keys

List the keys of all of the logging subsystems.

log-reopen

log-reopen

Reopen all loggers. Use this command for rotating log files.

log-set-output

log-set-output output=nil | stderr | file:<filename> | syslog:<sysloglocation> [key=<key>] [level= debug

| info | warning | error]

162

Set the output of the specified logger. Log messages are filtered by the subsystem in which they originated

and the log level of the message. For example, send debug logging messages from the storage manager

to a file by running the following command:

xe log-set-output key=sm level=debug output=<file:/tmp/sm.log>

The optional parameter key specifies the particular logging subsystem. If this parameter is not set, it will

default to all logging subsystems.

The optional parameter level specifies the logging level. Valid values are:

• debug

• info

• warning

• error

Message commands

Commands for working with messages. Messages are created to notify users of significant events, and are

displayed in XenCenter as system alerts.

Message parameters

Parameter Name Description Type

uuid The unique identifier/object reference for

the message

read only

name The unique name of the message read only

priority The message priority. Higher numbers

indicate greater priority

read only

class The message class, for example VM. read only

obj-uuid The uuid of the affected object. read only

timestamp The time that the message was

generated.

read only

body The message content. read only

message-create

message-create name=<message_name> body=<message_text> [[host-uuid=<uuid_of_host>] | [sruuid=<

uuid_of_sr>] | [vm-uuid=<uuid_of_vm>] | [pool-uuid=<uuid_of_pool>]]

Creates a new message.

message-list

message-list

Lists all messages, or messages that match the specified standard selectable parameters.

163

Network commands

Commands for working with networks.

The network objects can be listed with the standard object listing command (xe network-list), and the

parameters manipulated with the standard parameter commands. See the section called “Low-level param

commands” for details.

Network parameters

Networks have the following parameters:

Parameter Name Description Type

uuid The unique identifier/object reference for

the network

read only

name-label The name of the network read write

name-description The description text of the network read write

VIF-uuids A list of unique identifiers of the VIFs

(virtual network interfaces) that are

attached from VMs to this network

read only set parameter

PIF-uuids A list of unique identifiers of the PIFs

(physical network interfaces) that are

attached from XenServer hosts to this

network

read only set parameter

bridge name of the bridge corresponding to this

network on the local XenServer host

read only

other-config:staticroutes

comma-separated list of

<subnet>/<netmask>/<gateway>

formatted entries specifying the

gateway address through which to

route subnets. For example, setting

other-config:static-routes to

172.16.0.0/15/192.168.0.3,172.18.0.0/16/192.168.0.4

causes traffic on 172.16.0.0/15 to be

routed over 192.168.0.3 and traffic

on 172.18.0.0/16 to be routed over

192.168.0.4.

read write

other-config:ethtoolautoneg

set to no to disable autonegotiation of

the physical interface or bridge. Default is

yes.

read write

other-config:ethtool-rx set to on to enable receive checksum,

off to disable

read write

other-config:ethtool-tx set to on to enable transmit checksum,

off to disable

read write

164

Parameter Name Description Type

other-config:ethtool-sg set to on to enable scatter gather, off to

disable

read write

other-config:ethtool-tso set to on to enable tcp segmentation

offload, off to disable

read write

other-config:ethtool-ufo set to on to enable UDP fragment

offload, off to disable

read write

other-config:ethtool-gso set to on to enable generic segmentation

offload, off to disable

read write

blobs Binary data store read only

network-create

network-create name-label=<name_for_network> [name-description=<descriptive_text>]

Creates a new network.

network-destroy

network-destroy uuid=<network_uuid>

Destroys an existing network.

Patch (update) commands

Commands for working with XenServer host patches (updates). These are for the standard non-OEM

editions of XenServer for commands relating to updating the OEM edition of XenServer, see the section

called “Update commands” for details.

The patch objects can be listed with the standard object listing command (xe patch-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

Patch parameters

Patches have the following parameters:

Parameter Name Description Type

uuid The unique identifier/object reference for

the patch

read only

host-uuid The unique identifier for the XenServer

host to query

read only

name-label The name of the patch read only

name-description The description string of the patch read only

165

Parameter Name Description Type

applied Whether or not the patch has been

applied; true or false

read only

size Whether or not the patch has been

applied; true or false

read only

patch-apply

patch-apply uuid=<patch_file_uuid>

Apply the specified patch file.

patch-clean

patch-clean uuid=<patch_file_uuid>

Delete the specified patch file from the XenServer host.

patch-pool-apply

patch-pool-apply uuid=<patch_uuid>

Apply the specified patch to all XenServer hosts in the pool.

patch-precheck

patch-precheck uuid=<patch_uuid> host-uuid=<host_uuid>

Run the prechecks contained within the specified patch on the specified XenServer host.

patch-upload

patch-upload file-name=<patch_filename>

Upload a specified patch file to the XenServer host. This prepares a patch to be applied. On

success, the UUID of the uploaded patch is printed out. If the patch has previously been uploaded, a

PATCH_ALREADY_EXISTS error is returned instead and the patch is not uploaded again.

PBD commands

Commands for working with PBDs (Physical Block Devices). These are the software objects through which

the XenServer host accesses storage repositories (SRs).

The PBD objects can be listed with the standard object listing command (xe pbd-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

PBD parameters

PBDs have the following parameters:

Parameter Name Description Type

uuid The unique identifier/object reference for

the PBD.

read only

166

Parameter Name Description Type

sr-uuid the storage repository that the PBD

points to

read only

device-config additional configuration information that

is provided to the SR-backend-driver of a

host

read only map parameter

currently-attached True if the SR is currently attached on

this host, False otherwise

read only

host-uuid UUID of the physical machine on which

the PBD is available

read only

host The host field is deprecated. Use

host_uuid instead.

read only

other-config Additional configuration information. read/write map parameter

pbd-create

pbd-create host-uuid=<uuid_of_host>

sr-uuid=<uuid_of_sr>

[device-config:key=<corresponding_value>…]

Create a new PBD on a XenServer host. The read-only device-config parameter can only be set on

creation.

To add a mapping of ‘path’ -> ‘/tmp’, the command line should contain the argument deviceconfig:

path=/tmp

For a full list of supported device-config key/value pairs on each SR type see Storage.

pbd-destroy

pbd-destroy uuid=<uuid_of_pbd>

Destroy the specified PBD.

pbd-plug

pbd-plug uuid=<uuid_of_pbd>

Attempts to plug in the PBD to the XenServer host. If this succeeds, the referenced SR (and the VDIs

contained within) should then become visible to the XenServer host.

pbd-unplug

pbd-unplug uuid=<uuid_of_pbd>

Attempt to unplug the PBD from the XenServer host.

PIF commands

Commands for working with PIFs (objects representing the physical network interfaces).

167

The PIF objects can be listed with the standard object listing command (xe pif-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

PIF parameters

PIFs have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object reference for

the PIF

read only

device machine-readable name of the interface

(for example, eth0)

read only

MAC the MAC address of the PIF read only

other-config Additional PIF configuration name:value

pairs.

read/write map parameter

physical if true, the PIF points to an actual

physical network interface

read only

currently-attached is the PIF currently attached on this host?

true or false

read only

MTU Maximum Transmission Unit of the PIF in

bytes.

read only

VLAN VLAN tag for all traffic passing through

this interface; -1 indicates no VLAN tag< /p>

is assigned

read only

bond-master-of the UUID of the bond this PIF is the

master of (if any)

read only

bond-slave-of the UUID of the bond this PIF is the slave

of (if any)

read only

management is this PIF designated to be a

management interface for the control

domain

read only

network-uuid the unique identifier/object reference of

the virtual network to which this PIF is

connected

read only

network-name-label the name of the of the virtual network to

which this PIF is connected

read only

host-uuid the unique identifier/object reference of

the XenServer host to which this PIF is

connected

read only

168

Parameter Name Description Type

host-name-label the name of the XenServer host to which

this PIF is connected

read only

IP-configuration-mode type of network address configuration

used; DHCP or static

read only

IP IP address of the PIF, defined here if IPconfiguration-

mode is static; undefined if

DHCP

read only

netmask Netmask of the PIF, defined here if IPconfiguration-

mode is static; undefined if

supplied by DHCP

read only

gateway Gateway address of the PIF, defined

here if IP-configuration-mode is static;

undefined if supplied by DHCP

read only

DNS DNS address of the PIF, defined here if

IP-configuration-mode is static; undefined

if supplied by DHCP

read only

io_read_kbs average read rate in kB/s for the device read only

io_write_kbs average write rate in kB/s for the device read only

carrier link state for this device read only

vendor-id the ID assigned to NIC’s vendor read only

vendor-name the NIC vendor’s name read only

device-id the ID assigned by the vendor to this NIC

model

read only

device-name the name assigned by the vendor to this

NIC model

read only

speed data transfer rate of the NIC read only

duplex duplexing mode of the NIC; full or half read only

pci-bus-path PCI bus path address read only

other-config:ethtoolspeed

sets the speed of connection in Mbps read write

other-config:ethtoolautoneg

set to no to disable autonegotiation of

the physical interface or bridge. Default is

yes.

read write

other-config:ethtoolduplex

Sets duplexing capability of the PIF,

either full or half.

read write

169

Parameter Name Description Type

other-config:ethtool-rx set to on to enable receive checksum,

off to disable

read write

other-config:ethtool-tx set to on to enable transmit checksum,

off to disable

read write

other-config:ethtool-sg set to on to enable scatter gather, off to

disable

read write

other-config:ethtool-tso set to on to enable tcp segmentation

offload, off to disable

read write

other-config:ethtool-ufo set to on to enable udp fragment offload,

off to disable

read write

other-config:ethtool-gso set to on to enable generic segmentation

offload, off to disable

read write

other-config:domain comma-separated list used to set the

DNS search path

read write

other-config:bondmiimon

interval between link liveness checks, in

milliseconds

read write

other-config:bonddowndelay

number of milliseconds to wait after link

is lost before really considering the link to

have gone. This allows for transient link

loss

read write

other-config:bondupdelay

number of milliseconds to wait after the

link comes up before really considering it

up. Allows for links flapping up. Default is

31s to allow for time for switches to begin

forwarding traffic.

read write

disallow-unplug True if this PIF is a dedicated storage

NIC, false otherwise

read/write

Note:

Changes made to the other-config fields of a PIF will only take effect after a reboot. Alternately, use

the xe pif-unplug and xe pif-plug commands to cause the PIF configuration to be rewritten.

pif-forget

pif-forget uuid=<uuid_of_pif>

Destroy the specified PIF object on a particular host.

pif-introduce

pif-introduce host-uuid=<UUID of XenServer host> mac=<mac_address_for_pif> device=<machinereadable

name of the interface (for example, eth0)>

Create a new PIF object representing a physical interface on the specified XenServer host.

170

pif-plug

pif-plug uuid=<uuid_of_pif>

Attempt to bring up the specified physical interface.

pif-reconfigure-ip

pif-reconfigure-ip uuid=<uuid_of_pif> [ mode=<dhcp> | mode=<static> ]

gateway=<network_gateway_address> IP=<static_ip_for_this_pif>

netmask=<netmask_for_this_pif> [DNS=<dns_address>]

Modify the IP address of the PIF. For static IP configuration, set the mode parameter to static, with

the gateway, IP, and netmask parameters set to the appropriate values. To use DHCP, set the mode

parameter to DHCP and leave the static parameters undefined.

Note:

Using static IP addresses on physical network interfaces connected to a port on a switch using Spanning Tree

Protocol with STP Fast Link turned off (or unsupported) results in a period during which there is no traffic.

pif-scan

pif-scan host-uuid=<UUID of XenServer host>

Scan for new physical interfaces on a XenServer host.

pif-unplug

pif-unplug uuid=<uuid_of_pif>

Attempt to bring down the specified physical interface.

Pool commands

Commands for working with pools. A pool is an aggregate of one or more XenServer hosts. A pool uses

one or more shared storage repositories so that the VMs running on one XenServer host in the pool can

be migrated in near-real time (while still running, without needing to be shut down and brought back up)

to another XenServer host in the pool. Each XenServer host is really a pool consisting of a single member

by default. When a XenServer host is joined to a pool, it is designated as a member, and the pool it has

joined becomes the master for the pool.

The singleton pool object can be listed with the standard object listing command (xe pool-list), and its

parameters manipulated with the standard parameter commands. See the section called “Low-level param

commands” for details.

Pool parameters

Pools have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object

reference for the pool

read only

name-label the name of the pool read/write

name-description the description string of the

pool

read/write

171

Parameter Name Description Type

master the unique identifier/object

reference of XenServer host

designated as the pool’s

master

read only

default-SR the unique identifier/object

reference of the default SR

for the pool

read/write

crash-dump-SR the unique identifier/object

reference of the SR where

any crash dumps for pool

members are saved

read/write

suspend-image-SR the unique identifier/obje
ct

reference of the SR where

suspended VMs on pool

members are saved

read/write

other-config a list of key/value pairs

that specify additional

configuration parameters for

the pool

read/write map parameter

supported-sr-types SR types that can be used by

this pool

read only

ha-enabled True if HA is enabled for the

pool, false otherwise

read only

ha-configuration reserved for future use. read only

ha-statefiles lists the UUIDs of the

VDIs being used by HA to

determine storage health

read only

ha-host-failures-to-tolerate the number of host failures

to tolerate before sending a

system alert

read/write

ha-plan-exists-for the number of hosts failures

that can actually be handled,

according to the calculations

of the HA algorithm

read only

ha-allow-overcommit True if the pool is allowed

to be overcommitted, False

otherwise

read/write

ha-overcommitted True if the pool is currently

overcommitted

read only

172

Parameter Name Description Type

blobs binary data store read only

wlb-url Path to the WLB server read only

wlb-username Name of the user of the WLB

service

read only

wlb-enabled True is WLB is enabled read/write

wlb-verify-cert True if there is a certificate to

verify

read/write

pool-designate-new-master

pool-designate-new-master host-uuid=<UUID of member XenServer host to become new master>

Instruct the specified member XenServer host to become the master of an existing pool. This performs an

orderly hand over of the role of master host to another host in the resource pool. This command only works

when the current master is online, and is not a replacement for the emergency mode commands listed below.

pool-dump-database

pool-dump-database file-name=<filename_to_dump_database_into_(on_client)>

Download a copy of the entire pool database and dump it into a file on the client.

pool-eject

pool-eject host-uuid=<UUID of XenServer host to eject>

Instruct the specified XenServer host to leave an existing pool.

pool-emergency-reset-master

pool-emergency-reset-master master-address=<address of the pool’s master XenServer host>

Instruct a slave member XenServer host to reset its master address to the new value and attempt to connect

to it. This command should not be run on master hosts.

pool-emergency-transition-to-master

pool-emergency-transition-to-master

Instruct a member XenServer host to become the pool master. This command is only accepted by the

XenServer host if it has transitioned to emergency mode, meaning it is a member of a pool whose master

has disappeared from the network and could not be contacted for some number of retries.

Note that this command may cause the password of the host to reset if it has been modified since joining

the pool (see the section called “User commands”).

pool-ha-enable

pool-ha-enable heartbeat-sr-uuids=<SR_UUID_of_the_Heartbeat_SR>

Enable High Availability on the resource pool, using the specified SR UUID as the central storage heartbeat

repository.

173

pool-ha-disable

pool-ha-disable

Disables the High Availability functionality on the resource pool.

pool-join

pool-join master-address=<address> master-username=<username> master-password=<password>

Instruct a XenServer host to join an existing pool.

pool-recover-slaves

pool-recover-slaves

Instruct the pool master to try and reset the master address of all members currently running in emergency

mode. This is typically used after pool-emergency-transition-to-master has been used to set one of the

members as the new master.

pool-restore-database

pool-restore-database file-name=<filename_to_restore_from_(on_client)> [dry-run=<true | false>]

Upload a database backup (created with pool-dump-database) to a pool. On receiving the upload, the

master will restart itself with the new database.

There is also a dry run option, which allows you to check that the pool database can be restored without

actually perform the operation. By default, dry-run is set to false.

pool-sync-database

pool-sync-database

Force the pool database to be synchronized across all hosts in the resource pool. This is not necessary

in normal operation since the database is regularly automatically replicated, but can be useful for ensuring

changes are rapidly replicated after performing a significant set of CLI operations.

Storage Manager commands

Commands for controlling Storage Manager plugins.

The storage manager objects can be listed with the standard object listing command (xe sm-list), and the

parameters manipulated with the standard parameter commands. See the section called “Low-level param

commands” for details.

SM parameters

SMs have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object reference for

the SM plugin

read only

name-label the name of the SM plugin read only

name-description the description string of the SM plugin read only

type the SR type that this plugin connects to read only

174

Parameter Name Description Type

vendor name of the vendor who created this

plugin

read only

copyright copyright statement for this SM plugin read only

required-api-version minimum SM API version required on the

XenServer host

read only

configuration names and descriptions of device

configuration keys

read only

capabilities capabilities of the SM plugin read only

driver-filename the filename of the SR driver. read only

SR commands

Commands for controlling SRs (storage repositories).

The SR objects can be listed with the standard object listing command (xe sr-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

SR parameters

SRs have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object reference for

the SR

read only

name-label the name of the SR read/write

name-description the description string of the SR read/write

allowed-operations list of the operations allowed on the SR in

this state

read only set parameter

current-operations list of the operations that are currently in

progress on this SR

read only set parameter

VDIs unique identifier/object reference for the

virtual disks in this SR

read only set parameter

PBDs unique identifier/object reference for the

PBDs attached to this SR

read only set parameter

physical-Utilization physical space currently utilized on this

SR, in bytes. Note that for sparse disk

formats, physical utilization may be less

than virtual allocation

read only

175

Parameter Name Description Type

physical-size total physical size of the SR, in bytes read only

type type of the SR, used to specify the SR

backend driver to use

read only

content-type
the type of the SR’s content. Used to

distinguish ISO libraries from other SRs.

For storage repositories that store a

library of ISOs, the content-type

must be set to iso. In other cases, Citrix

recommends that this be set either to

empty, or the string user.

read only

shared True if this SR is capable of being

shared between multiple XenServer

hosts; False otherwise

read/write

other-config list of key/value pairs that specify

additional configuration parameters for

the SR .

read/write map parameter

host The storage repository host name read only

virtual-allocation sum of virtual-size values of all VDIs in

this storage repository (in bytes)

read only

sm-config SM dependent data read only map parameter

blobs binary data store read only

sr-create

sr-create name-label=<name> physical-size=<size> type=<type>

content-type=<content_type> device-config:<config_name>=<value>

[host-uuid=<XenServer host UUID>] [shared=<true | false>]

Creates an SR on the disk, introduces it into the database, and creates a PBD attaching the SR to a

XenServer host. If shared is set to true, a PBD is created for each XenServer host in the pool; if shared

is not specified or set to false, a PBD is created only for the XenServer host specified with host-uuid.

The exact device-config parameters differ depending on the device type. See Storage for details of

these parameters across the different storage backends.

sr-destroy

sr-destroy uuid=<sr_uuid>

Destroys the specified SR on the XenServer host.

sr-forget

sr-forget uuid=<sr_uuid>

The xapi agent forgets about a specified SR on the XenServer host, meaning that the SR is detached and

you cannot access VDIs on it, but it remains intact on the source media (the data is not lost).

176

sr-introduce

sr-introduce name-label=<name>

physical-size=<physical_size>

type=<type>

content-type=<content_type>

uuid=<sr_uuid>

Just places an SR record into the database. The device-config parameters are specified by deviceconfig:<

parameter_key>=<parameter_value>, for example:

xe sr-introduce device-config:<device>=</dev/sdb1>

Note:

This command is never used in normal operation. It is an advanced operation which might be useful if an SR

needs to be reconfigured as shared after it was created, or to help recover from various failure scenarios.

sr-probe

sr-probe type=<type> [host-uuid=<uuid_of_host>] [device-config:<config_name>=<value>]

Performs a backend-specific scan, using the provided device-config keys. If the device-config is

complete for the SR backend, then this will return a list of the SRs present on the device, if any. If the

device-config parameters are only partial, then a backend-specific scan will be performed, returning

results that will guide you in improving the remaining device-config parameters. The scan results are

returned as backend-specific XML, printed out on the CLI.

The exact device-config parameters differ depending on the device type. See Storage for details of

these parameters across the different storage backends.

sr-scan

sr-scan uuid=<sr_uuid>

Force an SR scan, syncing the xapi database with VDIs present in the underlying storage substrate.

Task commands

Commands for working with long-running asynchronous tasks. These are tasks such as starting, stopping,

and suspending a Virtual Machine, which are typically made up of a set of other atomic subtasks that together

accomplish the requested operation.

The task objects can be listed with the standard object listing command (xe task-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

Task parameters

Tasks have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object reference for

the Task

read only

name-label the name of the Task read only

177

Parameter Name Description Type

name-description the description string of the Task read only

resident-on the unique identifier/object reference of

the host on which the task is running

read only

status current status of the Task read only

progress if the Task is still pending, this field

contains the estimated percentage

complete, from 0. to 1. If the Task

has completed, successfully or

unsuccessfully, this should be 1.

read only

type if the Task has successfully completed,

this parameter contains the type of the

encoded result – that is, the name of the

class whose reference is in the result

field; otherwise, this parameter’s value is

undefined

read only

result if the Task has completed successfully,

this field contains the result value, either

Void or an object reference; otherwise,

this parameter’s value is undefined

read only

error_info if the Task has failed, this parameter

contains the set of associated error

strings; otherwise, this parameter’s value

is undefined

read only

allowed_operations list of the operations allowed in this state read only

created time the task has been created read only

finished time task finished (i.e. succeeded or

failed). If task-status is pending, then the

value of this field has no meaning

read only

subtask_of contains the UUID of the tasks this task is

a sub-task of

read only

subtasks contains the UUID(s) of all the subtasks

of this task

read only

task-cancel

task-cancel [uuid=<task_uuid>]

Direct the specified Task to cancel and return.

Template commands

Commands for working with VM templates.

178

Templates are essentially VMs with the is-a-template parameter set to true. A template is a "gold

image" that contains all the various configuration settings to instantiate a specific VM. XenServer ships

with a base set of templates, which range from generic "raw" VMs that can boot an OS vendor installation

CD (RHEL, CentOS, SLES, Windows) to complete pre-configured OS instances (the "Demo Linux VM"

template). With XenServer you can create VMs, configure them in standard forms for your particular needs,

and save a copy of them as templates for future use in VM deployment.

The template objects can be listed with the standard object listing command (xe template-list), and the

parameters manipulated with the standard parameter commands. See the section called “Low-level param

commands” for details.

Template parameters

Templates have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object

reference for the template

read only

name-label the name of the template read/write

name-description the description string of the

template

read/write

user-version string for creators of VMs

and templates to put version

information

read/write

is-a-template true if this is a template.

Template VMs can never be

started, they are used only for

cloning other VMs

Note that setting is-atemplate

using the CLI is not

supported.

read/write

is-control-domain true if this is a control domain

(domain 0 or a driver domain)

read only

power-state current power state; always

halted for a template

read only

power-state current power state; always

halted for a template

read only

memory-dynamic-max dynamic maximum memory

in bytes. Currently unused,

but if changed the following

constraint must be obeyed:

memory_static_max >=

memory_dynamic_max >=

memory_dynamic_min >=

memory_static_min.

read/write

179

Parameter Name Description Type

memory-dynamic-min dynamic minimum memory in

bytes. Currently unused, but if

changed the same constraints

for memory-dynamic-max

must be obeyed.

read/write

memory-static-max statically-set (absolute)

maximum memory in bytes.

This is the main value used

to determine the amount of

memory assigned to a VM.

read/write

memory-static-min statically-set (absolute)

minimum memory in bytes.

This represents the absolute

minimum memory, and

memory-static-min

must be less than memorystatic-

max. This value is

currently unused in normal

operation, but the previous

constraint must be obeyed.

read/write

suspend-VDI-uuid the VDI that a suspend image

is stored on (has no meaning

for a template)

read only

180

Parameter Name Description Type

VCPUs-params configuration parameters for

the selected VCPU policy.

You can tune a VCPU’s

pinning with

xe vm-param-set

uuid=<vm_uuid>

VCPUs-params:mask=1,2,3

A VM created from this

template will then run on

physical CPUs 1, 2, and 3

only.

You can also tune the VCPU

priority (xen scheduling)

with the cap and weight

parameters; for example

xe vm-param-set

uuid=<vm_uuid>

VCPUs-params:weight=512

xe vm-param-set

uuid=<vm_uuid>

VCPUs-params:cap=100

A VM based on this template

with a weight of 512 will get

twice as much CPU as a

domain with a weight of 256

on a contended XenServer

host. Legal weights range

from 1 to 65535 and the

default is 256.

The cap optionally fixes the

maximum amount of CPU a

VM based on this template

will be able to consume, even

if the XenServer host has

idle CPU cycles. The cap is

expressed in percentage of

one physical CPU: 100 is 1

physical CPU, 50 is half a

CPU, 400 is 4 CPUs, etc. The

default, 0, means there is no

upper cap.

read/write map parameter

VCPUs-max maximum number of VCPUs read/write

VCPUs-at-startup boot number of VCPUs read/write

181

Parameter Name Description Type

actions-after-crash action to take if a VM based

on this template crashes

read/write

console-uuids virtual console devices read only set parameter

platform platform-specific configuration read/write map parameter

allowed-operations list of the operations allowed

in this state

read only set parameter

current-operations list of the operations that are

currently in progress on this

template

read only set parameter

allowed-VBD-devices list of VBD identifiers

available for use, represented

by integers of the range 0-15.

This list is informational only,

and other devices may be

used (but may not work).

read only set parameter

allowed-VIF-devices list of VIF identifiers available

for use, represented by

integers of the range 0-15.

This list is informational only,

and other devices may be

used (but may not work).

read only set parameter

HVM-boot-policy the boot policy for HVM

guests. Either BIOS Order

or an empty string.

read/write

HVM-boot-params the order key controls

the HVM guest boot order,

represented as a string where

each character is a boot

method: d for the CD/DVD,

c for the root disk, and n

for network PXE boot. The

default is dc.

read/write map parameter

PV-kernel path to the kernel read/write

PV-ramdisk path to the initrd read/write

PV-args string of kernel command line

arguments

read/write

PV-legacy-args string of arguments to make

legacy VMs based on this

template boot

read/write

182

Parameter Name Description Type

PV-bootloader name of or path to bootloader read/write

PV-bootloader-args string of miscellaneous

arguments for the bootloader

read/write

last-boot-CPU-flags describes the CPU flags on

which a VM based on this

template was last booted; not

populated for a template

read only

resident-on the XenServer host on which

a VM based on this template

is currently resident; appears

as <not in database> for

a template

read only

affinity a XenServer host which a

VM based on this template

has preference for running

on; used by the xe vm-start

command to decide where to

run the VM

read/write

other-config list of key/value pairs

that specify additional

configuration parameters for

the template

read/write map parameter

start-time timestamp of the date and

time that the metrics for a

VM based on this template

were read, in the form

yyyymmddThh:mm:ss z,

where z is the single-letter

military timezone indicator,

for example, Z for UTC

(GMT); set to 1 Jan 1970 Z

(beginning of Unix/POSIX

epoch) for a template

read only

install-time timestamp of the date and

time that the metrics for a

VM based on this template

were read, in the form

yyyymmddThh:mm:ss z,

where z is the single-letter

military timezone indicator,

for example, Z for UTC

(GMT); set to 1 Jan 1970 Z

(beginning of Unix/POSIX

epoch) for a template

read only

183

Parameter Name Description Type

memory-actual the actual memory being

used by a VM based on this

template; 0 for a template

read only

VCPUs-number the number of virtual CPUs

assigned to a VM based on

this template; 0 for a template

read only

VCPUs-Utilization list of virtual CPUs and their

weight

read only map parameter

os-version the version of the operating

system for a VM based on

this template; appears as

<not in database> for a

template

read only map parameter

PV-drivers-version the versions of the

paravirtualized drivers for a

VM based on this template;

appears as <not in

database> for a template

read only map parameter

PV-drivers-up-to-date flag for latest version of the

par
avirtualized drivers for a

VM based on this template;

appears as <not in

database> for a template

read only

memory memory metrics reported by

the agent on a VM based

on this template; appears as

<not in database> for a

template

read only map parameter

disks disk metrics reported by the

agent on a VM based on

this template; appears as

<not in database> for a

template

read only map parameter

networks network metrics reported by

the agent on a VM based

on this template; appears as

<not in database> for a

template

read only map parameter

other other metrics reported by

the agent on a VM based

on this template; appears as

<not in database> for a

template

read only map parameter

184

Parameter Name Description Type

guest-metrics-last-updated timestamp when the last write

to these fields was performed

by the in-guest agent, in the

form yyyymmddThh:mm:ss

z, where z is the single-letter

military timezone indicator, for

example, Z for UTC (GMT)

read only

actions-after-shutdown action to take after the VM

has shutdown

read/write

actions-after-reboot action to take after the VM

has rebooted

read/write

possible-hosts list of hosts that could

potentially host the VM

read only

HVM-shadow-multiplier multiplier applied to the

amount of shadow that will be

made available to the guest

read/write

dom-id domain ID (if available, -1

otherwise)

read only

recommendations XML specification of

recommended values and

ranges for properties of this

VM

read only

xenstore-data data to be inserted into the

xenstore tree (/local/domain/

<domid>/vm-data) after the

VM is created.

read/write map parameter

is-a-snapshot True if this template is a VM

snapshot

read only

snapshot_of the UUID of the VM that this

template is a snapshot of

read only

snapshots the UUID(s) of any snapshots

that have been taken of this

template

read only

snapshot_time the timestamp of the most

recent VM snapshot taken

read only

memory-target the target amount of memory

set for this template

read only

185

Parameter Name Description Type

blocked-operations lists the operations that

cannot be performed on this

template

read/write map parameter

last-boot-record record of the last boot

parameters for this template,

in XML format

read only

ha-always-run True if an instance of this

template will always restarted

on another host in case of the

failure of the host it is resident

on

read/write

ha-restart-priority 1, 2, 3 or best effort. 1 is the

highest restart priority

read/write

blobs binary data store read only

live only relevant to a running VM. read only

template-export

template-export template-uuid=<uuid_of_existing_template> filename=<filename_for_new_template>

Exports a copy of a specified template to a file with the specified new filename.

Update commands

Commands for working with updates to the OEM edition of XenServer. For commands relating to updating

the standard non-OEM editions of XenServer, see the section called “Patch (update) commands” for details.

update-upload

update-upload file-name=<name_of_upload_file>

Streams a new software image to a OEM edition XenServer host. You must then restart the host for this

to take effect.

User commands

user-password-change

user-password-change old=<old_password> new=<new_password>

Changes the password of the logged-in user. The old password field is not checked because you require

supervisor privilege to make this call.

186

VBD commands

Commands for working with VBDs (Virtual Block Devices).

A VBD is a software object that connects a VM to the VDI, which represents the contents of the virtual disk.

The VBD has the attributes which tie the VDI to the VM (is it bootable, its read/write metrics, and so on),

while the VDI has the information on the physical attributes of the virtual disk (which type of SR, whether

the disk is shareable, whether the media is read/write or read only, and so on).

The VBD objects can be listed with the standard object listing command (xe vbd-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

VBD parameters

VBDs have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object

reference for the VBD

read only

vm-uuid the unique identifier/object

reference for the VM this VBD

is attached to

read only

vm-name-label the name of the VM this VBD

is attached to

read only

vdi-uuid the unique identifier/object

reference for the VDI this

VBD is mapped to

read only

vdi-name-label the name of the VDI this VBD

is mapped to

read only

empty if true, this represents an

empty drive

read only

device the device seen by the guest,

for example hda1

read only

userdevice user-friendly device name read/write

bootable true if this VBD is bootable read/write

mode the mode the VBD should be

mounted with

read/write

type how the VBD appears to the

VM, for example disk or CD

read/write

currently-attached True if the VBD is currently

attached on this host, false

otherwise

read only

187

Parameter Name Description Type

storage-lock True if a storage-level lock

was acquired

read only

status-code error/success code

associated with the last attach

operation

read only

status-detail error/success information

associated with the last attach

operation status

read only

qos_algorithm_type the QoS algorithm to use read/write

qos_algorithm_params parameters for the chosen

QoS algorithm

read/write map parameter

qos_supported_algorithms supported QoS algorithms for

this VBD

read only set parameter

io_read_kbs average read rate in kB per

second for this VBD

read only

io_write_kbs average write rate in kB per

second for this VBD

read only

allowed-operations list of the operations allowed

in this state. This list is

advisory only and the server

state may have changed by

the time this field is read by a

client.

read only set parameter

current-operations links each of the running

tasks using this object

(by reference) to a

current_operation enum

which describes the nature of

the task.

read only set parameter

unpluggable true if this VBD will support

hot-unplug

read/write

attachable True if the device can be

attached

read only

other-config additional configuration read/write map parameter

vbd-create

vbd-create vm-uuid=<uuid_of_the_vm> device=<device_value>

vdi-uuid
=<uuid_of_the_vdi_the_vbd_will_connect_to> [bootable=true] [type=<Disk | CD>] [mode=<RW |

RO>]

188

Create a new VBD on a VM.

Appropriate values for the device field are listed in the parameter allowed-VBD-devices on the

specified VM. Before any VBDs exist there, the allowable values are integers from 0-15.

If the type is Disk, vdi-uuid is required. Mode can be RO or RW for a Disk.

If the type is CD, vdi-uuid is optional; if no VDI is specified, an empty VBD will be created for the CD.

Mode must be RO for a CD.

vbd-destroy

vbd-destroy uuid=<uuid_of_vbd>

Destroy the specified VBD.

If the VBD has its other-config:owner parameter set to true, the associated VDI will also be destroyed.

vbd-eject

vbd-eject uuid=<uuid_of_vbd>

Remove the media from the drive represented by a VBD. This command only works if the media is of a

removable type (a physical CD or an ISO); otherwise an error message VBD_NOT_REMOVABLE_MEDIA is

returned.

vbd-insert

vbd-insert uuid=<uuid_of_vbd> vdi-uuid=<uuid_of_vdi_containing_media>

Insert new media into the drive represented by a VBD. This command only works if the media is of a

removable type (a physical CD or an ISO); otherwise an error message VBD_NOT_REMOVABLE_MEDIA is

returned.

vbd-plug

vbd-plug uuid=<uuid_of_vbd>

Attempt to attach the VBD while the VM is in the running state.

vbd-unplug

vbd-unplug uuid=<uuid_of_vbd>

Attempts to detach the VBD from the VM while it is in the running state.

VDI commands

Commands for working with VDIs (Virtual Disk Images).

A VDI is a software object that represents the contents of the virtual disk seen by a VM, as opposed to the

VBD, which is a connector object that ties a VM to the VDI. The VDI has the information on the physical

attributes of the virtual disk (which type of SR, whether the disk is shareable, whether the media is read/

write or read only, and so on), while the VBD has the attributes which tie the VDI to the VM (is it bootable,

its read/write metrics, and so on).

The VDI objects can be listed with the standard object listing command (xe vdi-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

189

VDI parameters

VDIs have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object reference for

the VDI

read only

name-label the name of the VDI read/write

name-description the description string of the VDI read/write

allowed-operations a list of the operations allowed in this

state

read only set parameter

current-operations a list of the operations that are currently

in progress on this VDI

read only set parameter

sr-uuid SR in which the VDI resides read only

vbd-uuids a list of VBDs that refer to this VDI read only set parameter

crashdump-uuids list of crash dumps that refer to this VDI read only set parameter

virtual-size size of disk as presented to the VM,

in bytes. Note that, depending on the

storage backend type, the size may not

be respected exactly

read only

physical-Utilization amount of physical space that the VDI is

currently taking up on the SR, in bytes

read only

type type of VDI, for example, System or User read only

sharable true if this VDI may be shared read only

read-only true if this VDI can only be mounted readonly

read only

storage-lock true if this VDI is locked at the storage

level

read only

parent references the parent VDI, if this VDI is

part of a chain

read only

missing true if SR scan operation reported this

VDI as not present

read only

other-config additional configuration information for

this VDI

read/write map parameter

sr-name-label name of the containing storage repository read only

location location information read only

190

Parameter Name Description Type

managed true if the VDI is managed read only

xenstore-data data to be inserted into the xenstore

tree (/local/domain/0/backend/

vbd/<domid>/<device-id>/smdata)

after the VDI is attached. This is

generally set by the SM backends on

vdi_attach.

read only map parameter

sm-config SM dependent data read only map parameter

is-a-snapshot true if this VDI is a VM storage snapshot read only

snapshot_of the UUID of the storage this VDI is a

snapshot of

read only

snapshots the UUID(s) of all snapshots of this VDI read only

snapshot_time the timestamp of the snapshot operation

that created this VDI

read only

vdi-clone

vdi-clone uuid=<uuid_of_the_vdi> [driver-params:<key=value>]

Create a new, writable copy of the specified VDI that can be used directly. It is a variant of vdi-copy that is

capable of exposing high-speed image clone facilities where they exist.

The optional driver-params map parameter can be used for passing extra vendor-specific configuration

information to the back end storage driver that the VDI is based on. See the storage vendor driver

documentation for details.

vdi-copy

vdi-copy uuid=<uuid_of_the_vdi> sr-uuid=<uuid_of_the_destination_sr>

Copy a VDI to a specified SR.

vdi-create

vdi-create sr-uuid=<uuid_of_the_sr_where_you_want_to_create_the_vdi>

name-label=<name_for_the_vdi>

type=<system | user | suspend | crashdump>

virtual-size=<size_of_virtual_disk>

sm-config-*=<storage_specific_configuration_data>

Create a VDI.

The virtual-size parameter can be specified in bytes or using the IEC standard suffixes KiB (210 bytes),

MiB (220 bytes), GiB (230 bytes), and TiB (240 bytes).

Note:

SR types that support sparse allocation of disks (such as Local VHD and NFS) do not enforce virtual allocation

of disks. Users should therefore take great care when over-allocating virtual disk space on an SR. If an over191

allocated SR does become full, disk space must be made available either on the SR target substrate or by

deleting unused VDIs in the SR.

Note:

Some SR types might round up the virtual-size value to make it divisible by a configured block size.

vdi-destroy

vdi-destroy uuid=<uuid_of_vdi>

Destroy the specified VDI.

Note:

In the case of Local VHD and NFS SR types, disk space is not immediately released on vdi-destroy, but

periodically during a storage repository scan operation. Users that need to force deleted disk space to be

made available should call sr-scan manually.

vdi-forget

vdi-forget uuid=<uuid_of_vdi>

Unconditionally removes a VDI record from the database without touching the storage backend. In normal

operation, you should be using vdi-destroy instead.

vdi-import

vdi-import uuid=<uuid_of_vdi> filename=<filename_of_raw_vdi>

Import a raw VDI.

vdi-introduce

vdi-int
roduce uuid=<uuid_of_vdi>

sr-uuid=<uuid_of_sr_to_import_into>

name-label=<name_of_the_new_vdi>

type=<system | user | suspend | crashdump>

location=<device_location_(varies_by_storage_type)>

[name-description=<description_of_vdi>]

[sharable=<yes | no>]

[read-only=<yes | no>]

[other-config=<map_to_store_misc_user_specific_data>]

[xenstore-data=<map_to_of_additional_xenstore_keys>]

[sm-config<storage_specific_configuration_data>]

Create a VDI object representing an existing storage device, without actually modifying or creating any

storage. This command is primarily used internally to automatically introduce hot-plugged storage devices.

vdi-resize

vdi-resize uuid=<vdi_uuid> disk-size=<new_size_for_disk>

Resize the VDI specified by UUID.

vdi-snapshot

vdi-snapshot uuid=<uuid_of_the_vdi> [driver-params=<params>]

192

Produces a read-write version of a VDI that can be used as a reference for backup and/or template creation

purposes. You can perform a backup from a snapshot rather than installing and running backup software

inside the VM. The VM can continue running while external backup software streams the contents of the

snapshot to the backup media. Similarly, a snapshot can be used as a "gold image" on which to base a

template. A template can be made using any VDIs.

The optional driver-params map parameter can be used for passing extra vendor-specific configuration

information to the back end storage driver that the VDI is based on. See the storage vendor driver

documentation for details.

A clone of a snapshot should always produce a writable VDI.

vdi-unlock

vdi-unlock uuid=<uuid_of_vdi_to_unlock> [force=true]

Attempts to unlock the specified VDIs. If force=true is passed to the command, it will force the unlocking

operation.

VIF commands

Commands for working with VIFs (Virtual network interfaces).

The VIF objects can be listed with the standard object listing command (xe vif-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

VIF parameters

VIFs have the following parameters:

Parameter Name Description Type

uuid the unique identifier/object

reference for the VIF

read only

vm-uuid the unique identifier/object

reference for the VM that this

VIF resides on

read only

vm-name-label the name of the VM that this

VIF resides on

read only

allowed-operations a list of the operations

allowed in this state

read only set parameter

current-operations a list of the operations that

are currently in progress on

this VIF

read only set parameter

device integer label of this VIF,

indicating the order in which

VIF backends were created

read only

MAC MAC address of VIF, as

exposed to the VM

read only

193

Parameter Name Description Type

MTU Maximum Transmission

Unit of the VIF in bytes. This

parameter is read-only, but

you can override the MTU

setting with the mtu key

using the other-config map

parameter. For example, to

reset the MTU on a virtual

NIC to use jumbo frames:

xe vif-param-set

uuid=<vif_uuid>

other-config:mtu=9000

read only

currently-attached true if the device is currently

attached

read only

qos_algorithm_type QoS algorithm to use read/write

qos_algorithm_params parameters for the chosen

QoS algorithm

read/write map parameter

qos_supported_algorithms supported QoS algorithms for

this VIF

read only set parameter

MAC-autogenerated True if the MAC address of

the VIF was automatically

generated

read only

other-config Additional configuration

key:value pairs

read/write map parameter

other-config:ethtool-rx set to on to enable receive

checksum, off to disable

read write

other-config:ethtool-tx set to on to enable transmit

checksum, off to disable

read write

other-config:ethtool-sg set to on to enable scatter

gather, off to disable

read write

other-config:ethtool-tso set to on to enable tcp

segmentation offload, off to

disable

read write

other-config:ethtool-ufo set to on to enable udp

fragment offload, off to

disable

read write

other-config:ethtool-gso set to on to enable generic

segmentation offload, off to

disable

read write

194

Parameter Name Description Type

other-config:promiscuous true to a VIF to be

promiscuous on the bridge,

so that it sees all traffic over

the bridge. Useful for running

an Intrusion Detection System

(IDS) or similar in a VM.

read write

network-uuid the unique identifier/object

reference of the virtual

network to which this VIF is

connected

read only

network-name-label the descriptive name of the

virtual network to which this

VIF is connected

read only

io_read_kbs average read rate in kB/s for

this VIF

read only

io_write_kbs average write rate in kB/s for

this VIF

read only

vif-create

vif-create vm-uuid=<uuid_of_the_vm> device=<see below>

network-uuid=<uuid_of_the_network_the_vif_will_connect_to> [mac=<mac_address>]

Create a new VIF on a VM.

Appropriate values for the device field are listed in the parameter allowed-VIF-devices on the

specified VM. Before any VIFs exist there, the allowable values are integers from 0-15.

The mac parameter is the standard MAC address in the form aa:bb:cc:dd:ee:ff. If you leave it

unspecified, an appropriate random MAC address will be created. You can also explicitly set a random MAC

address by specifying mac=random.

vif-destroy

vif-destroy uuid=<uuid_of_vif>

Destroy a VIF.

vif-plug

vif-plug uuid=<uuid_of_vif>

Attempt to attach the VIF while the VM is in the running state.

vif-unplug

vif-unplug uuid=<uuid_of_vif>

195

Attempts to detach the VIF from the VM while it is running.

VLAN commands

Commands for working with VLANs (virtual networks). To list and edit virtual interfaces, refer to the PIF

commands, which have a VLAN parameter to signal that they have an associated virtual network (see the

section called “PIF commands”). For example, to list VLANs you need to use xe pif-list.

vlan-create

vlan-create pif-uuid=<uuid_of_pif> vlan=<vlan_number> network-uuid=<uuid_of_network>

Create a new VLAN on a XenServer host.

pool-vlan-create

vlan-create pif-uuid=<uuid_of_pif> vlan=<vlan_number> network-uuid=<uuid_of_network>

Create a new VLAN on all hosts on a pool, by determining which interface (for example, eth0) the specified

network is on (on each host) and creating and plugging a new PIF object one each host a
ccordingly.

vlan-destroy

vlan-destroy uuid=<uuid_of_pif_mapped_to_vlan>

Destroy a VLAN. Requires the UUID of the PIF that represents the VLAN.

VM commands

Commands for controlling VMs and their attributes.

VM selectors

Several of the commands listed here have a common mechanism for selecting one or more VMs on which

to perform the operation. The simplest way is by supplying the argument vm=<name_or_uuid>. An easy

way to get the uuid of an actual VM is to, for example, execute xe vm-list power-state=running. (The full

list of fields that can be matched can be obtained by the command xe vm-list params-all. ) For example,

specifying power-state=halted will select all VMs whose power-state parameter is equal to halted.

Where multiple VMs are matching, the option –multiple must be specified to perform the operation. The

full list of parameters that can be matched is described at the beginning of this section, and can be obtained

by the command xe vm-list params=all.

The VM objects can be listed with the standard object listing command (xe vm-list), and the parameters

manipulated with the standard parameter commands. See the section called “Low-level param commands”

for details.

VM parameters

VMs have the following parameters:

196

Note:

All writable VM parameter values can be changed while the VM is running, but the new parameters are not

applied dynamically and will not be applied until the VM is rebooted.

Parameter Name Description Type

uuid the unique identifier/object

reference for the VM

read only

name-label the name of the VM read/write

name-description the description string of the

VM

read/write

user-version string for creators of VMs

and templates to put version

information

read/write

is-a-template False unless this is a

template; template VMs can

never be started, they are

used only for cloning other

VMs

Note that setting is-atemplate

using the CLI is

not supported.

read/write

is-control-domain True if this is a control

domain (domain 0 or a driver

domain)

read only

power-state current power state read only

memory-dynamic-max dynamic maximum in bytes read/write

memory-dynamic-min dynamic minimum in bytes read/write

memory-static-max statically-set (absolute)

maximum in bytes.

If you want to change this

value, the VM must be shut

down.

read/write

memory-static-min statically-set (absolute)

minimum in bytes. If you want

to change this value, the VM

must be shut down.

read/write

suspend-VDI-uuid the VDI that a suspend image

is stored on

read only

197

Parameter Name Description Type

VCPUs-params configuration parameters for

the selected VCPU policy.

You can tune a VCPU’s

pinning with

xe vm-param-set

uuid=<vm_uuid>

VCPUs-params:mask=1,2,3

The selected VM will then run

on physical CPUs 1, 2, and 3

only.

You can also tune the VCPU

priority (xen scheduling)

with the cap and weight

parameters; for example

xe vm-param-set

uuid=<template_uuid>

VCPUs-params:weight=512

xe vm-param-set

uuid=<template UUID>

VCPUs-params:cap=100

A VM with a weight of 512 will

get twice as much CPU as a

domain with a weight of 256

on a contended XenServer

host. Legal weights range

from 1 to 65535 and the

default is 256.

The cap optionally fixes the

maximum amount of CPU a

VM will be able to consume,

even if the XenServer host

has idle CPU cycles. The cap

is expressed in percentage

of one physical CPU: 100 is

1 physical CPU, 50 is half a

CPU, 400 is 4 CPUs, etc. The

default, 0, means there is no

upper cap.

read/write map parameter

VCPUs-max maximum number of virtual

CPUs.

read/write

VCPUs-at-startup boot number of virtual CPUs read/write

198

Parameter Name Description Type

actions-after-crash action to take if the VM

crashes. For PV guests,

valid parameters are:

preserve (for analysis only),

coredump_and_restart

(record a coredump

and reboot VM),

coredump_and_destroy

(record a coredump and

leave VM halted), restart (no

coredump and restart VM),

and destroy (no coredump

and leave VM halted).

read/write

console-uuids virtual console devices read only set parameter

platform platform-specific configuration read/write map parameter

allowed-operations list of the operations allowed

in this state

read only set parameter

current-operations a list of the operations that

are currently in progress on

the VM

read only set parameter

allowed-VBD-devices list of VBD identifiers

available for use, represented

by integers of the range 0-15.

This list is informational only,

and other devices may be

used (but may not work).

read only set parameter

allowed-VIF-devices list of VIF identifiers available

for use, represented by

integers of the range 0-15.

This list is informational only,

and other devices may be

used (but may not work).

read only set parameter

HVM-boot-policy the boot policy for HVM

guests. Either BIOS Order

or an empty string.

read/write

HVM-boot-params the order key controls

the HVM guest boot order,

represented as a string where

each character is a boot

method: d for the CD/DVD,

c for the root disk, and n

for network PXE boot. The

default is dc.

read/write map parameter

199

Parameter Name Description Type

HVM-shadow-multiplier Floating point value which

controls the amount of

shadow memory overhead

to grant the VM. Defaults to

1.0 (the minimum value),

and should only be changed

by advanced users.

read/write

PV-kernel path to the kernel read/write

PV-ramdisk path to the initrd read/write

PV-args string of kernel command line

arguments

read/write

PV-legacy-args string of arguments to make

legacy VMs boot

read/write

PV-bootloader name of or path to bootloader read/write

PV-bootloader-args string of miscellaneous

arguments for the bootloader

read/write

last-boot-CPU-flags describes the CPU flags on

which the VM was last booted

read only

resident-on the XenServer host on which

a VM is currently resident

read only

affinity a XenServer host which

the VM has preference for

running on; used by the xe

vm-start command to decide

where to run the VM

read/write

other-config A list of key/value pairs

that specify additional

configuration parameters for

the VM

For example, a VM will be

started automatically after

host boot if the other-config

parameter includes the key/

value pair auto_poweron: true

read/write map parameter

200

Parameter Name Description Type

start-time timestamp of the date a
nd

time that the metrics for the

VM were read, in the form

yyyymmddThh:mm:ss z,

where z is the single-letter

military timezone indicator, for

example, Z for UTC (GMT)

read only

install-time timestamp of the date and

time that the metrics for the

VM were read, in the form

yyyymmddThh:mm:ss z,

where z is the single-letter

military timezone indicator, for

example, Z for UTC (GMT)

read only

memory-actual the actual memory being

used by a VM

read only

VCPUs-number the number of virtual CPUs

assigned to the VM

For a paravirtualized Linux

VM, this number can differ

from VCPUS-max and can be

changed without rebooting

the VM using the vm-vcpuhotplug

command. See the

section called “vm-vcpuhotplug”.

Windows VMs

always run with the number

of vCPUs set to VCPUs-max

and must be rebooted to

change this value.

Note that performance

will drop sharply if you set

VCPUs-number to a value

greater than the number

of physical CPUs on the

XenServer host.

read only

VCPUs-Utilization a list of virtual CPUs and their

weight

read only map parameter

os-version the version of the operating

system for the VM

read only map parameter

PV-drivers-version the versions of the

paravirtualized drivers for the

VM

read only map parameter

201

Parameter Name Description Type

PV-drivers-up-to-date flag for latest version of the

paravirtualized drivers for the

VM

read only

memory memory metrics reported by

the agent on the VM

read only map parameter

disks disk metrics reported by the

agent on the VM

read only map parameter

networks network metrics reported by

the agent on the VM

read only map parameter

other other metrics reported by the

agent on the VM

read only map parameter

guest-metrics-last-updated timestamp when the last write

to these fields was performed

by the in-guest agent, in the

form yyyymmddThh:mm:ss

z, where z is the single-letter

military timezone indicator, for

example, Z for UTC (GMT)

read only

actions-after-shutdown action to take after the VM

has shutdown

read/write

actions-after-reboot action to take after the VM

has rebooted

read/write

possible-hosts potential hosts of this VM read only

dom-id domain ID (if available, -1

otherwise)

read only

recommendations XML specification of

recommended values and

ranges for properties of this

VM

read only

xenstore-data data to be inserted into the

xenstore tree (/local/

domain/<domid>/vmdata)

after the VM is created

read/write map parameter

is-a-snapshot True if this VM is a snapshot read only

snapshot_of the UUID of the VM this is a

snapshot of

read only

snapshots the UUID(s) of all snapshots

of this VM

read only

202

Parameter Name Description Type

snapshot_time the timestamp of the

snapshot operation that

created this VM snapshot

read only

memory-target the target amount of memory

set for this VM

read only

blocked-operations lists the operations that

cannot be performed on this

VM

read/write map parameter

last-boot-record record of the last boot

parameters for this template,

in XML format

read only

ha-always-run True if this VM will always

restarted on another host in

case of the failure of the host

it is resident on

read/write

ha-restart-priority 1, 2, 3 or best effort. 1 is the

highest restart priority

read/write

blobs binary data store read only

live True if the VM is running,

false if HA suspects that the

VM may not be running.

read only

vm-cd-add

vm-cd-add cd-name=<name_of_new_cd> device=<integer_value_of_an_available_vbd>

[<vm-selector>=<vm_selector_value>…]

Add a new virtual CD to the selected VM. The device parameter should be selected from the value of the

allowed-VBD-devices parameter of the VM.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-cd-eject

vm-cd-eject [<vm-selector>=<vm_selector_value>…]

Eject a CD from the virtual CD drive. This command only works if there is one and only one CD attached to

the VM. When there are two or more CDs, use the command xe vbd-eject and specify the UUID of the VBD.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

203

vm-cd-insert

vm-cd-insert cd-name=<name_of_cd> [<vm-selector>=<vm_selector_value>…]

Insert a CD into the virtual CD drive. This command will only work if there is one and only one empty CD

device attached to the VM. When there are two or more empty CD devices, use the xe vbd-insert command

and specify the UUIDs of the VBD and of the VDI to insert.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-cd-list

vm-cd-list [vbd-params] [vdi-params] [<vm-selector>=<vm_selector_value>…]

Lists CDs attached to the specified VMs.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

You can also select which VBD and VDI parameters to list.

vm-cd-remove

vm-cd-remove cd-name=<name_of_cd> [<vm-selector>=<vm_selector_value>…]

Remove a virtual CD from the specified VMs.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-clone

vm-clone new-name-label=<name_for_clone>

[new-name-description=<description_for_clone>] [<vm-selector>=<vm_selector_value>…]

Clone an existing VM, using storage-level fast disk clone operation where available. Specify the name

and the optional description for the resulting cloned VM using the new-name-label and new-namedescription

arguments.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-compute-maximum-memory

vm-compute-maximum-memory total=<amount_of_available_physical_ram_in_byt
es
>

[approximate=<add overhead memory for additional vCPUS? true | false>]

[<vm_selector>=<vm_selector_value>…]

Calculate the maximum amount of static memory which can be allocated to an existing VM, using the total

amount of physical RAM as an upper bound. The optional parameter approximate reserves sufficient

extra memory in the calculation to account for adding extra vCPUs into the VM at a later date.

204

For example:

xe vm-compute-maximum-memory vm=testvm total=`xe host-list params=memory-free –minimal`

This command uses the value of the memory-free parameter returned by the xe host-list command to

set the maximum memory of the VM named testvm.

The VM or VMs on which this operation will be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-copy

vm-copy new-name-label=<name_for_copy> [new-name-description=<description_for_copy>]

[sr-uuid=<uuid_of_sr>] [<vm-selector>=<vm_selector_value>…]

Copy an existing VM, but without using storage-level fast disk clone operation (even if this is available).

The disk images of the copied VM are guaranteed to be "full images" – that is, not part of a copy-on-write

(CoW) chain.

Specify the name and the optional description for the resulting copied VM using the new-name-label and

new-name-description arguments.

Specify the destination SR for the resulting copied VM using the sr-uuid. If this parameter is not specified,

the destination is the same SR that the original VM is in.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-crashdump-list

vm-crashdump-list [<vm-selector>=<vm selector value>…]

List crashdumps associated with the specified VMs.

If the optional argument params is used, the value of params is a string containing a list of parameters of

this object that you want to display. Alternatively, you can use the keyword all to show all parameters. If

params is not used, the returned list shows a default subset of all available parameters.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-data-source-forget

vm-data-source-forget data-source=<name_description_of_data-source> [<vm-selector>=<vm

selector value>…]

Stop recording the specified data source for a VM, and forget all of the recorded data.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-data-source-list

vm-data-source-list [<vm-selector>=<vm selector value>…]

205

List the data sources that can be recorded for a VM.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-data-source-query

vm-data-source-query data-source=<name_description_of_data-source> [<vm-selector>=<vm

selector value>…]

Display the specified data source for a VM.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-data-source-record

vm-data-source-record data-source=<name_description_of_data-source> [<vm-selector>=<vm

selector value>…]

Record the specified data source for a VM.

This will write the information from the data source to the VM’s persistent performance metrics database.

This database is distinct from the normal agent database for performance reasons.

Data sources have the true/false parameters standard and enabled, which can be seen in the output of

the vm-data-source-list command. If enabled=true, the data source metrics are currently being recorded

to the performance database; if enabled=false they are not. Data sources with standard=true have

enabled=true and have their metrics recorded to the performance database by default. Data sources

which have standard=false have enabled=false by default. The vm-data-source-record command

sets enabled=false.

Once enabled, you can stop recording the metrics of the data source by running the vm-data-source-forget

command.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-destroy

vm-destroy uuid=<uuid_of_vm>

Destroy the specified VM. This leaves the storage associated with the VM intact. To delete storage as well,

use xe vm-uninstall.

vm-disk-add

vm-disk-add disk-size=<size_of_disk_to_add> device=<uuid_of_device>

[<vm-selector>=<vm_selector_value>…]

Add a new disk to the specified VMs. Select the device parameter from the value of the allowed-VBDdevices

parameter of the VMs.

206

The disk-size parameter can be specified in bytes or using the IEC standard suffixes KiB (210 bytes),

MiB (220 bytes), GiB (230 bytes), and TiB (240 bytes).

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-disk-list

vm-disk-list [vbd-params] [vdi-params] [<vm-selector>=<vm_selector_value>…]

Lists disks attached to the specified VMs. The vbd-params and vdi-params parameters control the fields

of the respective objects to output and should be given as a comma-separated list, or the special key all

for the complete list.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-disk-remove

vm-disk-remove device=<integer_label_of_disk> [<vm-selector>=<vm_selector_value>…]

Remove a disk from the specified VMs and destroy it.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-export

vm-expo
rt filename=<export_filename>

[metadata=<true | false>]

[<vm-selector>=<vm_selector_value>…]

Export the specified VMs (including disk images) to a file on the local machine. Specify the filename to export

the VM into using the filename parameter. By convention, the filename should have a .xva extension.

If the metadata parameter is true, then the disks are not exported, and only the VM metadata is written

to the output file. This is intended to be used when the underlying storage is transferred through other

mechanisms, and permits the VM information to be recreated (see the section called “vm-import”).

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-import

vm-import filename=<export_filename>

[metadata=<true | false>]

[preserve=<true | false>]

[sr-uuid=<destination_sr_uuid>]

Import a VM from a previously-exported file. If preserve is set to true, the MAC address of the original

VM will be preserved. The sr-uuid determines the destination SR to import the VM into, and is the default

SR if not specified.

207

The filename parameter can also point to an XVA-format VM, which is the legacy export format from

XenServer 3.2 and is used by some third-party vendors to provide virtual appliances. This format uses a

directory to store the VM data, so set filename to the root directory of the XVA export and not an actual

file. Subsequent exports of the imported legacy guest will automatically be upgraded to the new filenamebased

format, which stores much more data about the configuration of the VM.

Note:

The older directory-based XVA format does not fully preserve all the VM attributes. In particular, imported

VMs will not have any virtual network interfaces attached by default. If networking is required, create one

using vif-create and vif-plug.

If the metadata is true, then a previously exported set of metadata can be imported without their

associated disk blocks. Metadata-only import will fail if any VDIs cannot be found (named by SR and

VDI.location) unless the –force option is specified, in which case the import will proceed regardless.

If disks can be mirrored or moved out-of-band then metadata import/export represents a fast way of moving

VMs between disjoint pools (e.g. as part of a disaster recovery plan).

Note:

Multiple VM imports will be performed faster in serial that in parallel.

vm-install

vm-install new-name-label=<name>

[ template-uuid=<uuid_of_desired_template> | [template=<uuid_or_name_of_desired_template>]]

[ sr-uuid=<sr_uuid> | sr-name-label=<name_of_sr> ]

[ copy-bios-strings-from=<uuid of host> ]

Install a VM from a template. Specify the template name using either the template-uuid or template

argument. Specify an SR other than the default SR using either the sr-uuid or sr-name-label argument.

Specify to install BIOS-locked media using the copy-bios-strings-from argument.

vm-memory-shadow-multiplier-set

vm-memory-shadow-multiplier-set [<vm-selector>=<vm_selector_value>…]

[multiplier=<float_memory_multiplier>]

Set the shadow memory multiplier for the specified VM.

This is an advanced option which modifies the amount of shadow memory assigned to a hardware-assisted

VM. In some specialized application workloads, such as Citrix XenApp, extra shadow memory is required

to achieve full performance.

This memory is considered to be an overhead. It is separated from the normal memory calculations for

accounting memory to a VM. When this command is invoked, the amount of free XenServer host memory

will decrease according to the multiplier, and the HVM_shadow_multiplier field will be updated with the

actual value which Xen has assigned to the VM. If there is not enough XenServer host memory free, then

an error will be returned.

The VMs on which this operation should be performed are selected using the standard selection mechanism

(see VM selectors for more information).

vm-migrate

vm-migrate [[host-uuid=<destination XenServer host UUID> ] | [host=<name or UUID of destination

XenServer host> ]] [<vm-selector>=<vm_selector_value>…] [live=<true | false>]

208

Migrate the specified VMs between physical hosts. The host parameter can be either the name or the

UUID of the XenServer host.

By default, the VM will be suspended, migrated, and resumed on the other host. The live parameter

activates XenMotion and keeps the VM running while performing the migration, thus minimizing VM

downtime to less than a second. In some circumstances such as extremely memory-heavy workloads in

the VM, XenMotion automatically falls back into the default mode and suspends the VM for a brief period

of time before completing the memory transfer.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-reboot

vm-reboot [<vm-selector>=<vm_selector_value>…] [force=<true>]

Reboot the specified VMs.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

Use the force argument to cause an ungraceful shutdown, akin to pulling the plug on a physical server.

vm-reset-powerstate

vm-reset-powerstate [<vm-selector>=<vm_selector_value>…] {force=true}

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

This is an advanced command only to be used when a member host in a pool goes down. You can use this

command to force the pool master to reset the power-state of the VMs to be halted. Essentially this forces

the lock on the VM and its disks so it can be subsequently started on another pool host. This call requires

the force flag to be specified, and fails if it is not on the command-line.

vm-resume

vm-resume [<vm-selector>=<vm_selector_value>…] [force=<true | false>] [on=<XenServer host UUID>]

Resume the specified VMs.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

If the VM is on a shared SR in a pool of hosts, use the on argument to specify which host in the pool

on which to start it. By default the system will determine an appropriate host, which might be any of the

members of the pool.

vm-shutdown< /b>

vm-shutdown [<vm-selector>=<vm_selector_value>…] [force=<true | false>]

209

Shut down the specified VM.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

Use the force argument to cause an ungraceful shutdown, similar to pulling the plug on a physical server.

vm-start

vm-start [<vm-selector>=<vm_selector_value>…] [force=<true | false>] [on=<XenServer host UUID>] [–

multiple]

Start the specified VMs.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

If the VMs are on a shared SR in a pool of hosts, use the on argument to specify which host in the pool

on which to start the VMs. By default the system will determine an appropriate host, which might be any

of the members of the pool.

vm-suspend

vm-suspend [<vm-selector>=<vm_selector_value>…]

Suspend the specified VM.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-uninstall

vm-uninstall [<vm-selector>=<vm_selector_value>…] [force=<true | false>]

Uninstall a VM, destroying its disks (those VDIs that are marked RW and connected to this VM only) as well

as its metadata record. To simply destroy the VM metadata, use xe vm-destroy.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Optional arguments can be any number of the VM parameters listed at the

beginning of this section.

vm-vcpu-hotplug

vm-vcpu-hotplug new-vcpus=<new_vcpu_count> [<vm-selector>=<vm_selector_value>…]

Dynamically adjust the number of VCPUs available to a running paravirtual Linux VM within the number

bounded by the parameter VCPUs-max. Windows VMs always run with the number of VCPUs set to VCPUsmax

and must be rebooted to change this value.

The paravirtualized Linux VM or VMs on which this operation should be performed are selected using

the standard selection mechanism (see VM selectors). Optional arguments can be any number of the VM

parameters listed at the beginning of this section.

210

vm-vif-list

vm-vif-list [<vm-selector>=<vm_selector_value>…]

Lists the VIFs from the specified VMs.

The VM or VMs on which this operation should be performed are selected using the standard selection

mechanism (see VM selectors). Note that the selectors operate on the VM records when filtering, and not

on the VIF values. Optional arguments can be any number of the VM parameters listed at the beginning

of this section.

Workload Balancing commands

Commands for controlling the Workload Balancing feature.

pool-initialize-wlb

pool-initialize-wlb wlb_url=<wlb_server_address>

wlb_username=<wlb_server_username>

wlb_password=<wlb_server_password>

xenserver_username=<pool_master_username>

xenserver_password=<pool_master_password>

Starts the Workload Balancing service on a pool.

Note:

Initializing a pool requires running two commands. After executing the pool-initialize-wlb command,

execute xe pool-param-set wlb-enabled=true uuid=<pool-uuid>[].

pool-param-set other-config

Use the pool-param-set other-config command to specify the timeout when communicating with the WLB

server. All requests are serialized, and the timeout covers the time from a request being queued to its

response being completed. In other words, slow calls cause subsequent ones to be slow. Defaults to 30

seconds if unspecified or if the setting cannot be parsed.

xe pool-param-set other-config:wlb_timeout=<0.01>

uuid=<315688af-5741-cc4d-9046-3b9cea716f69>

host-retrieve-wlb-evacuate-recommendations

host-retrieve-wlb-evacuate-recommendations uuid=<host_uuid>

Returns the evacuation recommendations for a host, and a reference to the UUID of the recommendations

object.

vm-retrieve-wlb-recommendations

Returns the workload balancing recommendations for the selected VM. The simplest way to select the VM

on which the operation is to be performed is by supplying the argument vm=<name_or_uuid>. VMs can

also be specified by filtering the full list of VMs on the values of fields. For example, specifying powerstate=

halted selects all VMs whose power-state is halted. Where multiple VMs are matching, specify

the option –multiple to perform the operation. The full list of fields that can be matched can be obtained

by the command xe vm-list params=all. If no parameters to select VMs are given, the operation will be

performed on all VMs.

211

pool-certificate-list

XenServer’s Workload Balancing component lets you use certificates to secure communication between

XenServer pools and the Workload Balancing server. You can either use the default certificate, which is

created automatically during Workload Balancing installation, or you can specify a certificate you have

already created.

To use your own certificate, the certificate must be in X.509 format. If you want to import the certificate into

XenServer’s certificate store, during Workload Balancing installation you must specify for WLB to use an

existing certificate and export it. Currently, you must do this installing WLB with the Msiexec commands.

However, following installation you need to export the certificate again. When you export the certificate

from Workload Balancing, Workload Balancing exports it in Base64 encoded format. You must convert the

exported certificate into a Privacy Enhanced Mail (PEM) file or a .crt format by exporting it from Windows

using Windows certificate management features so that XenServer can import it.

Note:

To convert the exported certificate into a PEM (.pem) file, copy it to your XenServer pool master and run

the following commands:

openssl enc -base64 -in <exported_cert_name.crt> -out <certificate.pem>

After converting the certificate into .pem or .crt, you must load the certificate onto servers across the pool

by doing the following:

1. List any existing certificates on the pool (using xe pool-certificate-list).

2. Install the certificate you specified during WLB installation (using pool-certificate-install).

3. Synchronize the certificate on all hosts in the pool (using pool-certificate-sync).

4. (Optional.) Instruct XenServer to require a certificate before connecting (using pool-certificate-sync).

pool-certificate-list

Lists all installed SSL certificates.

pool-certificate-install

pool-certificate-install filename=<certificatefilename>

Run this command on the pool to install the certifi
cate you specified during WLB installation on the pool

master. Before installing the certificate on the master, it must be exported in either .pem or .crt format. If you

are exporting the certificate using Windows certificate management features, select the Base 64 encoded

X.509 format.

Typically, when you installed WLB, you may have named the certificate something like wlbcert.cer. Simply

renaming the file wlbcert.crt is not sufficient. You must export the certificate so the file formats is converted

into a format XenServer is expecting to receive.

pool-certificate-sync

pool-certificate-install

Run this command on the pool, after running the pool-certificate-install command, to make sure the

certificate and certificate revocation lists are synchronized from the pool master to all slaves on the pool.

212

pool-param-set

pool-param-set wlb-verify-cert=<true> uuid=<uuid_of_pool>

Run this command on the pool, after running the pool-certificate-sync command, to make XenServer always

verify the certificate when communicating with the Workload Balancing server.

Tip:

Pressing the Tab key automatically populates the UUID of the pool.

pool-deconfigure-wlb

Permanently deletes all workload balancing configuration.

pool-retrieve-wlb-configuration

Prints all workload balancing configuration to standard out.

pool-retrieve-wlb-recommendations

Prints all workload balancing recommendations to standard out.

pool-retrieve-wlb-report

Gets a WLB report of the specified type and saves it to the specified file. The available reports are:

• pool_health

• pool_audit_history poolid

• pool_optimization_history

• host_health_history

• optimization_performance_history

• pool_health_history

• vm_movement_history

• vm_performance_history

Example usage for each report type is shown below. The utcoffset parameter specifies the number of

hours ahead or behind of UTC for your time zone. The start parameter and end parameters specify the

number of hours to report about. For example specifying start=-3 and end=0 will cause WLB to report

on the last 3 hour of activity.

xe pool-retrieve-wlb-report report=pool_health

poolid=<51e411f1-62f4-e462-f1ed-97c626703cae>

utcoffset=<-5>

start=<-3>

end=<0>

filename=</pool_health.txt>

xe pool-retrieve-wlb-report report=host_health_history

hostid=<e26685cd-1789-4f90-8e47-a4fd0509b4a4>

utcoffset=<-5>

start=<-3>

end=<0>

filename=</host_health_history.txt>

213

xe pool-retrieve-wlb-report report=optimization_performance_history

poolid=<51e411f1-62f4-e462-f1ed-97c626703cae>

utcoffset=<-5>

start=<-3>

end=<0>

filename=</optimization_performance_history.txt>

xe pool-retrieve-wlb-report report=pool_health_history

poolid=<51e411f1-62f4-e462-f1ed-97c626703cae>

utcoffset=<-5>

start=<-3>

end=<0>

<filename=/pool_health_history.txt>

xe pool-retrieve-wlb-report report=vm_movement_history

poolid=<51e411f1-62f4-e462-f1ed-97c626703cae>

utcoffset=<-5>

start=<-5>

end=<0>

filename=</vm_movement_history.txt>

xe pool-retrieve-wlb-report report=vm_performance_history

hostid=<e26685cd-1789-4f90-8e47-a4fd0509b4a4>

utcoffset=<-5>

start=<-3>

end=<0>

<filename=/vm_performance_history.txt>

pool-send-wlb-configuration

Modifies Workload Balancing configuration settings, including thresholds, WLB power-management

settings, and weightings. It is not mandatory to configure all settings with the command. You can configure

only some parameters, but not all, if desired.

Before using the pool-send-wlb-configuration command, learn about the default values on your system by

running pool-retrieve-wlb-configuration.

When you run the pool-retrieve-wlb-configuration command, additional parameters appear that are not

documented in this section. Citrix does not recommend editing these parameters.

pool-send-wlb-configuration

[ config:HostMemoryThresholdCritical=<HostCpuThresholdCritical=value>

config:HostMemoryThresholdHigh=<HostMemoryThresholdHigh=value>config:HostPifReadThresholdCritical=<HostPifReadThresholdCritical=config:HostPifReadThresholdHigh=<HostPifReadThresholdHigh=value>

config:set_host_configuration=<true | false> …]

Use the pool-send-wlb-configuration command with the arguments <ParticipatesInPowerManagement>

and <set_host_configuration> to configure Workload Balancing’s Host Power Management feature.

xe pool-send-wlb-configuration

config:<host_21_>

ParticipatesInPowerManagement=<true>

<

p>config:set_host_configuration=<true>

0 thoughts on “Citrix XenServer xe Command Reference

  1. I’m curious to find out what blog system you happen to be working with? I’m
    having some minor security issues with my latest website and I would like to find something more safeguarded.

    Do you have any solutions?

  2. I was curious if you ever considered changing the structure of your
    blog? Its very well written; I love what youve got to say.
    But maybe you could a little more in the way of content
    so people could connect with it better. Youve got an awful lot of text for only having 1 or two pictures.
    Maybe you could space it out better?

Leave a Reply

Your email address will not be published. Required fields are marked *