5.4. xe command reference

This section provides a reference to the xe commands. They are grouped by objects that the commands address, and listed alphabetically.

5.4.1. CD commands

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

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-utilisation	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 storage is sharable. Always true for CDs.	read only
read-only	Whether the CD is read-only, if false, the device is writeable. 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
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

5.4.1.1. 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 parameters listed at the beginning of this section.

String arguments do not take wildcards.

5.4.2. 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 Section 5.3.2, “Low-level param commands” for details.

Consoles have the following parameters:

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

5.4.3. Event commands

Commands for working with events.

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 (note 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

5.4.3.1. event-wait

event-wait class=class name [param-name=param-value]

Block other commands from executing until an object exists that satisfies the conditions given on the command line.

Example: wait for a specific VM to be running

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

blocks until a VM called myvm is in the power-state "running."

The class name can be any of the classes listed at the beginning of this section, and the parameters can be any of those listed in the CLI command class-param-list.

5.4.4. Host (XenServer Host) commands

Commands for interacting with XenServer Hosts.

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 host-cpu-list, and xe host-crashdump-list), and the parameters manipulated with the standard parameter commands. See Section 5.3.2, “Low-level param commands” for details.

5.4.4.1. 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 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.

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 only
name-description	The description string of the XenServer Host	read only
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	read only
API-version-vendor-implementation	read only map parameter
logging		read only
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
host-metrics-last-updated	Timestamp of the date and time that the metrics for a XenServer Host were read, in the form yyyymmddThh:mm:ssz, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT)	read only
host-metrics-live	true if the host is operational	read only

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

CPUs on XenServer Hosts have the following parameters:

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
utilisation	the current CPU utilization	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

5.4.4.2. host-backup

host-backup file-name=backup filename [host-selector=host-selector value...]

Download a backup of the control domain of the specified XenServer Host to the machine that the command is invoked from, and saving it there as a file with the name file-name.

The host(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

Caution

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 backup file, which would be a bad thing. The command should only be used from a remote off-host machine where you have space to hold the backup file.

5.4.4.3. host-bugreport-upload

host-bugreport-upload [host-selector=host-selector value...] [url=destination_url] [http-proxy=http-proxy-name]

Generate a fresh bug report (via xen-bugtool, with all optional files included) and upload to XenSource Support ftp site or other location.

The host(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

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 XenSource Support ftp site.

5.4.4.4. host-crashdump-destroy

host-crashdump-destroy uuid=crashdump UUID

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

5.4.4.5. host-crashdump-upload

host-crashdump-upload uuid=crashdump UUID [url=destination URL] [http-proxy=HTTP proxy name]

Upload a crashdump to the XenSource Support ftp site or other location. If optional parameters are not used, no proxy server is identified and the destination will be default XenSource Support ftp site. Optional parameters are http-proxy: use specified http proxy, and url: upload to this destination url.

5.4.4.6. host-disable

host-disable [host-selector=host selector value...]

Disables 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 via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

5.4.4.7. 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 via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

5.4.4.8. 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 via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

5.4.4.9. host-forget

host-forget uuid=XenServer Host UUID

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

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.

5.4.4.10. host-license-add

host-license-add license-file=path/license_filename [host-uuid=XenServer Host UUID]

Parses a local license file and adds it to the specified XenServer Host.

5.4.4.11. host-license-view

host-license-view [host-uuid=XenServer Host UUID]

Displays the contents of the XenServer Host license.

5.4.4.12. 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-ddThh: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 via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

Caution

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, which would be a bad thing. The command should only be used from a remote off-host machine where you have space to hold the copy of the logs.

5.4.4.13. 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 via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

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 slave, other slaves 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 slaves will reconnect and synchronize with the master, or until you make one of the slaves into the master.

5.4.4.14. 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 secondary partition to primary partition" option.

The host(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

5.4.4.15. 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 via the standard selection mechanism (see Section 5.4.4.1, “Host selectors”).

5.4.5. Log commands

Commands for working with logs.

5.4.5.1. log-get-keys

log-get-keys

List the keys of all of the logging subsystems.

5.4.5.2. log-reopen

log-reopen

Reopen all loggers. Use this for rotating log files.

5.4.5.3. log-set-output

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, debug logging messages from the storage manager can be sent to a file via 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 or error.

5.4.6. 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 Section 5.3.2, “Low-level param commands” for details.

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 only
name-description	The description text of the network	read only
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	A list of key/value pairs that specify additional configuration parameters for the network.	read/write map parameter

5.4.6.1. network-create

network-create name-label=name for network [name-description=descriptive text]

Creates a new network.

5.4.6.2. network-destroy

network-destroy uuid=network UUID

Destroys an existing network.

5.4.7. Patch commands

Commands for working with XenServer host patches.

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 Section 5.3.2, “Low-level param commands” for details.

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 host to query	read only
name-label	The name of the patch	read only
name-description	The description string of the patch	read only
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

5.4.7.1. patch-apply

patch-apply uuid=patch file UUID

Apply the specified patch file.

5.4.7.2. patch-destroy

patch-destroy uuid=patch file UUID

Delete a specified patch file.

5.4.7.3. patch-upload

patch-upload file-name=patch filename

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

5.4.8. 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 Section 5.3.2, “Low-level param commands” for details.

PBDs have the following parameters:

Parameter Name	Description	Type
uuid	The unique identifier/object reference for the PBD.	read only
host	The XenServer Host on which the PBD is available	read only
sr-uuid	the Storage Repository that the PBD points to	read only
device-config	additional configuration information that is provided to the XenServer Host's SR-backend-driver	read only
currently-attached	Is the SR currently attached on this host? True or False	read only

5.4.8.1. pbd-create

pbd-create host-uuid=UUID of XenServer Host sr-uuid=UUID of SR [device-config-key=corresponding value...]

Note

The syntax device-config-key=value for setting key-value pairs in the device config field will be changed in future versions of XenServer to be consistent with the syntax of the pbd-param-set cli command: device-config:key=value. The current syntax will still be allowed for backward compatibility.

Create a new PBD on a XenServer Host. The read-only device-config parameter can only be set on creation as in the following example:

To add a mapping of 'path' -> '/tmp', the command line should contain the argument device-config-path=/tmp

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

5.4.8.2. pbd-destroy

pbd-destroy uuid=UUID of PBD

Destroy the specified PBD.

5.4.8.3. 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.

5.4.8.4. pbd-unplug

pbd-unplug uuid=UUID of PBD

Attempts to unplug the PBD from the XenServer Host.

5.4.9. PIF commands

Commands for working with PIFs (Physical network interfaces).

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 Section 5.3.2, “Low-level param commands” for details.

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
MTU	Maximum Transmission Unit of the interface in octets	read only
VLAN	VLAN tag for all traffic passing through this interface; -1 indicates no VLAN tag is assigned	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
host-name-label	the name of the XenServer Host to which this PIF is connected	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		read only
vendor-id		read only
vendor-name		read only
device-id		read only
device-name		read only
pif-metrics-last-updated	Timestamp of the date and time that the metrics for this PIF were read, in the form yyyymmddThh:mm:ssz, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT)	read only

5.4.10. Pool commands

Commands for working with pools. A pool is a 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 slave, 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 Section 5.3.2, “Low-level param commands” for details.

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 only
name-description	The description string of the pool	read only
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/object 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

5.4.10.1. pool-eject

pool-eject host-uuid=UUID of XenServer Host to eject

Instruct the specified XenServer Host to leave an existing pool.

5.4.10.2. pool-emergency-reset-master

pool-emergency-reset-master master-address=address of the pool's master XenServer Host

Instruct a slave XenServer Host to reset its master address.

5.4.10.3. pool-emergency-transition-to-master

pool-emergency-transition-to-master

Instruct a slave 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 slave in 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 Section 5.4.15, “User commands”).

5.4.10.4. pool-join

pool-join master-address=address of the pool's master XenServer Host master-username=username for the pool's master XenServer Host master-password=password for the pool's master XenServer Host

Instruct a XenServer Host to join an existing pool.

5.4.10.5. pool-recover-slaves

pool-recover-slaves

Instruct the pool master to try and reset the master address of all slaves currently running in emergency mode. This is typically used after pool-emergency-transition-to-master has been used to set one of the slaves as the new master.

5.4.10.6. 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.

5.4.10.7. pool-restore-database

pool-restore-database file-name=filename to restore from (on client)

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.

5.4.11. 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 Section 5.3.2, “Low-level param commands” for details.

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
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

5.4.12. 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 Section 5.3.2, “Low-level param commands” for details.

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 only
name-description	The description string of the SR	read only
allowed-operations	list of the operations allowed on the SR in this state	read only set parameter
current-operations	A 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
virtual-allocaton	sum of the virtual sizes of all VDIs in this SR, in bytes	read only
physical-utilisation	physical space currently utilized on this SR, in bytes. Note that for sparse disk formats, physical utilisation may be less than virtual allocation	read only
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, if required (for example, ISOs)	read only
shared	true if this SR is capable of being shared between multiple XenServer Hosts; false otherwise
other-config	A list of key/value pairs that specify additional configuration parameters for the SR .	read/write map parameter

5.4.12.1. 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]

Makes 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 device-config parameters differ depending on the device type.

Note

5.4.12.2. sr-destroy

sr-destroy uuid=SR UUID

Destroys the specified SR on the XenServer Host.

5.4.12.3. 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).

5.4.12.4. 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 can be specified by e.g. 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 the fact, or to help recover from various failure scenarios.

5.4.12.5. sr-scan

sr-scan uuid=SR UUID

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

5.4.13. 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 Section 5.3.2, “Low-level param commands” for details.

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
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 completed successfully, 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 set parameter

5.4.13.1. task-cancel

task-cancel [uuid=Task UUID]

Direct the specified Task to cancel and return.

5.4.14. Template commands

Commands for working with VM templates.

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 (Debian Etch and Sarge). With XenServer you can create VMs, configure them in standard forms for your particular needs, and save a copy of it as a Template for future use in 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 Section 5.3.2, “Low-level param commands” for details.

Templates have the following parameters:

Parameter Name	Description	Type
uuid	The unique identifier/object reference for the VM	read only
name-label	The name of the VM	read only
name-description	The description string of the VM	read only
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	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
auto-power-on	true if this VM should be started automatically after host boot	read/write
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	read/write
memory-static-min	statically-set (absolute) minimum in bytes	read/write
suspend-VDI-uuid	The VDI that a suspend image is stored on (has no meaning for a Template)	read/write
VCPUs-params	configuration parameters for the selected VCPU policy. You can tune a VCPU's pinning with xe vm-param-set uuid=<Template UUID> VCPUs-params:mask=1,2,3 A VM created from the selected 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=<Template UUID> VCPUs-params:weight=100 xe vm-param-set uuid=<Template UUID> VCPUs-params:cap=100	read/write map parameter
VCPUs-max	Max number of VCPUs	read/write
VCPUs-at-startup	Boot number of VCPUs	read/write
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	A 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		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 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; 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	A 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:ssz, 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:ssz, 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
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 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-utilisation	A list of virtual CPUs and their weight	read only map parameter
vm-metrics-last-updated	Timestamp of the date and time that the metrics for a VM based on this Template were read, in the form yyyymmddThh:mm:ssz, 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
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
PV-drivers-up-to-date	flag for latest version of the paravirtualized 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
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
other	other metrics reported by the agent on a VM based on this Template; appears as <not in database> for a Template	read only
guest-metrics-last-updated	timestamp when the last write to these fields was performed by the in-guest agent, in the form yyyymmddThh:mm:ssz, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT)	read only

5.4.15. User commands

5.4.15.1. user-password-change

user-password-change old=old_password new=new_password

Changes the logged-in user's password. In a pool, this command only changes the master host's password. This will only make a difference if a slave host is subsequently transitioned to become a master via the pool-emergency-transition-to-master command (see Section 5.4.10.3, “pool-emergency-transition-to-master”), in which case the slave's old password (as recorded in /etc/passwd) will become active.

5.4.16. 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 Section 5.3.2, “Low-level param commands” for details.

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 is device currently attached	read only
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 only
qos_supported_algorithms	supported QoS algorithms for this VBD	read only set parameter
io_read_kbs	average read rate in kB/s for this VBD	read only
io_write_kbs	average write rate in kB/s for this VBD	read only
vbd-metrics-last-updated	Timestamp of the date and time that the metrics for a VM based on this Template were read, in the form yyyymmddThh:mm:ssz, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT)	read only

5.4.16.1. 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]

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.

5.4.16.2. vbd-destroy

vbd-destroy uuid=UUID of VBD

Destroy the specified VBD.

5.4.16.3. 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.

5.4.16.4. 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 removeable type (a physical CD or an ISO); otherwise an error message "VBD_NOT_REMOVABLE_MEDIA" is returned.

5.4.16.5. vbd-plug

vbd-plug uuid=UUID of VBD

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

5.4.16.6. vbd-unplug

vbd-unplug uuid=UUID of VBD

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

5.4.17. 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 Section 5.3.2, “Low-level param commands” for details.

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 only
name-description	The description string of the VDI	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 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 storage backend type, the size may not be respected exactly	read only
physical-utilisation	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 read-only	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

5.4.17.1. vdi-copy

vdi-copy uuid=UUID of the VDI sr-uuid=UUID of the SR to where you want to copy the VDI

Copy a VDI to a specified SR.

5.4.17.2. 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, in bytes

Create a VDI.

Note

SR types that support sparse allocation of disks (i.e. Local VHD and NFS SR types) do not enforce virtual allocation of disks. Users should therefore take great care when over-allocating virtual disk space on an SR. If an over-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.

5.4.17.3. 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 an sr-scan. Users that need to force deleted disk space to be made available should call sr-scan manually.

5.4.17.4. vdi-import

vdi-import uuid=UUID of VDI filename=filename of raw VDI

Import a raw VDI.

5.4.17.5. vdi-resize

vdi-resize uuid=VDI UUID disk-size=new size for disk

Resize the VDI specified by UUID.

5.4.17.6. 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.

5.4.18. 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 Section 5.3.2, “Low-level param commands” for details.

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
MTU	maximum transmission unit of the VIF, in octets	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
other-config	A list of key/value pairs that specify additional configuration parameters for this VIF.	read/write map parameter
network-uuid	The unique identifier/object reference of the virtual network to which this VIF is connected	read only
network-name-label	The unique identifier/object reference 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-metrics-last-updated	Timestamp of the date and time that the metrics for the VIF were read, in the form yyyymmddThh:mm:ssz, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT)	read only

5.4.18.1. vif-create

vif-create vm-uuid=UUID of the VM device=see below vdi-uuid=UUID of the VDI the VBD will connect to [mac=MAC address if VIF] [type=type of VBD: Disk or CD] [mode=mode of VBD: RW or RO]

Create a new VBD 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, a random MAC address will be created. You can also explicitly set a random MAC address by specifying mac=random.

5.4.18.2. vif-destroy

vif-destroy uuid=UUID of VIF

Destroy a VIF.

5.4.18.3. vif-plug

vif-plug uuid=UUID of VIF

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

5.4.18.4. vif-unplug

vif-unplug uuid=UUID of VIF

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

5.4.19. 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 Section 5.4.9, “PIF commands”).

5.4.19.1. vlan-create

vlan-create pif-uuid=UUID of PIF vlan=VLAN tag network-uuid=UUID of network

Create a new VLAN on a XenServer Host.

5.4.19.2. vlan-destroy

vlan-destroy uuid=UUID of PIF mapped to VLAN

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

5.4.20. VM commands

Commands for controlling VMs and their attributes.

5.4.20.1. 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. VMs can also be specified by filtering the full list of VMs on the values of fields. 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. If no parameters to select VMs are given, the operation will be performed on all VMs.

The VMs objects can be listed with the standard object listing command (xe vm-list), and the parameters manipulated with the standard parameter commands. See Section 5.3.2, “Low-level param commands” for details.

VMs have the following parameters:

Parameter Name	Description	Type
uuid	The unique identifier/object reference for the VM	read only
name-label	The name of the VM	read only
name-description	The description string of the VM	read only
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	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
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	read/write
memory-static-min	statically-set (absolute) minimum in bytes	read/write
suspend-VDI-uuid	The VDI that a suspend image is stored on (has no meaning for a Template)	read/write
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=<VM UUID> VCPUs-params:weight=100 xe vm-param-set uuid=<VM UUID> VCPUs-params:cap=100	read/write map parameter
VCPUs-max	Max number of VCPUs	read/write
VCPUs-at-startup	Boot number of VCPUs	read/write
actions-after-crash	action to take if the VM 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	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		read/write
HVM-boot-params		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 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
start-time	Timestamp of the date and time that the metrics for the VM were read, in the form yyyymmddThh:mm:ssz, 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:ssz, 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 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-utilisation	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
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:ssz, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT)	read only

5.4.20.2. 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(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.3. vm-cd-eject

vm-cd-eject [vm-selector=vm selector value...]

Eject a CD from the virtual CD drive. This command will only work if there is one and only one CD attached to the VM. When there are two or more CDs, please use the command xe vbd-eject and specify the UUID of the VBD.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.4. 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, please use the command xe vbd-insert and specify the UUIDs of the VBD and of the VDI to insert.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.5. vm-cd-list

vm-cd-list [vbd-params] [vdi-params] [vm-selector=vm selector value...]

Lists CDs attached to the specified VMs.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

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

5.4.20.6. 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(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.7. 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-name-description arguments.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.8. 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(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.9. vm-crashdump-list

vm-crashdump-list [vm-selector=vm selector value...]

List crashdumps associated with the specified VMs.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.10. vm-create

vm-create name-label=name for VM [name-description=description string for VM]

Create a new VM with default parameters. Despite its suggestive name, this command does not leave you with a running or runnable VM -- it really creates a template. The resultant UUID must be used as the template-uuid argument passed to the vm-install command.

This is an advanced command and should not normally be used to install VMs. Instead, use the pre-defined templates and the vm-install command to instantiate new VMs.

5.4.20.11. 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.

5.4.20.12. 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. The device field should be selected from the value of the allowed-VBD-devices parameter of the VMs.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.13. 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(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.14. 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(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.15. vm-export

vm-export filename=export_filename [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.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.16. vm-import

vm-import filename=export_filename [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 default SR to import the VM into, and is the default SR if not specified.

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 filename-based 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.

5.4.20.17. 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 ]

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.

5.4.20.18. 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]

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(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.19. vm-reboot

vm-reboot [vm-selector=vm selector value...] [force=true]

Reboot the specified VMs.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

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

5.4.20.20. vm-reset-powerstate

vm-reset-powerstate [vm-selector=vm selector value...] {force=true}

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

This is an advanced command only to be used when a slave 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.

5.4.20.21. vm-resume

vm-resume [vm-selector=vm selector value...] [force=true | false] [on=XenServer Host UUID]

Resume the specified VMs.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

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.

5.4.20.22. vm-shutdown

vm-shutdown [vm-selector=vm selector value...] [force=true | false]

Shut down the specified VM.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

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

5.4.20.23. vm-start

vm-start [vm-selector=vm selector value...] [force=true | false] [on=XenServer Host UUID] [--multiple]

Start the specified VMs.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

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.

5.4.20.24. vm-suspend

vm-suspend [vm-selector=vm selector value...]

Suspend the specified VM.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.25. 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(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.26. 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 VM.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”).

5.4.20.27. vm-vif-list

vm-vif-list [vm-selector=vm selector value...]

Lists the VIFs from the specified VMs.

The VM(s) on which this operation should be performed are selected via the standard selection mechanism (see Section 5.4.20.1, “VM selectors”). Note that the selectors operate on the VM records when filtering, and not on the VIF values.