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
yyyymmdd–hhmmss–ABC, 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”
Excellent post; I just got what i wanted from this post ;
Thank you.
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?
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?