XenSource
Skip navigation links
Overview Expand Overview
Products Expand Products
Solutions Expand Solutions
Support Services Expand Support Services
Partners Expand Partners
About Us Expand About Us
How to Buy

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 NameDescriptionType
uuidunique identifier/object reference for the CDread only
name-labelName for the CDread/write
name-descriptionDescription text for the CDread/write
allowed-operationsA list of the operations that can be performed on this CDread only set parameter
current-operationsA list of the operations that are currently in progress on this CDread only set parameter
sr-uuidThe unique identifier/object reference for the SR this CD is part ofread only
sr-name-labelThe name for the SR this CD is part ofread only
vbd-uuidsA list of the unique identifiers for the VBDs on VMs that connect to this CDread only set parameter
crashdump-uuidsNot used on CDs since crashdumps cannot be written to themread only set parameter
virtual-sizeSize of the CD as it appears to VMs (in bytes)read only
physical-utilisationamount of physical space that the CD image is currently taking up on the SR (in bytes)read only
typeSet to User for CDsread only
sharableWhether or not the storage is sharable. Always true for CDs.read only
read-onlyWhether the CD is read-only, if false, the device is writeable. Always true for CDs.read only
storage-locktrue if this disk is locked at the storage levelread only
parentReference to the parent disk, if this CD is part of a chainread only
missingtrue if SR scan operation reported this CD as not present on diskread only
other-configA list of key/value pairs that specify additional configuration parameters for the CDread/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 NameDescriptionType
uuidThe unique identifier/object reference for the consoleread only
vm-uuidThe unique identifier/object reference of the VM this console is open onread only
vm-name-labelThe name of the VM this console is open onread only
protocolProtocol this console uses. Possible values are vt100: VT100 terminal, rfb:Remote FrameBuffer protocol (as used in VNC), or rdp: Remote Desktop Protocolread only
locationURI for the console serviceread only
other-configA 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 nameDescription
poolA pool of physical hosts
vmA Virtual Machine
hostA physical host
networkA virtual network
vifA virtual network interface
pifA physical network interface (note separate VLANs are represented as several PIFs)
srA storage repository
vdiA virtual disk image
vbdA virtual block device
pbdThe 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 NameDescriptionType
uuidThe unique identifier/object reference for the XenServer Hostread only
name-labelThe name of the XenServer Hostread only
name-descriptionThe description string of the XenServer Hostread only
enabledfalse 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 enabledread only
API-version-majormajor version numberread only
API-version-minorminor version numberread only
API-version-vendorread only 
API-version-vendor-implementationread only map parameter 
logging read only
suspend-image-sr-uuidthe unique identifier/object reference for the SR where suspended images are putread/write
crash-dump-sr-uuidthe unique identifier/object reference for the SR where crash dumps are putread/write
software-versionlist of versioning parameters and their valuesread only map parameter
capabilitieslist of Xen versions that the XenServer Host can runread only set parameter
other-configA list of key/value pairs that specify additional configuration parameters for the XenServer Hostread/write map parameter
hostnameXenServer Host hostnameread only
addressXenServer Host IP addressread only
supported-bootloaderslist of bootloaders that the XenServer Host supports, for example, pygrub, eliloaderread only set parameter
memory-totaltotal amount of physical RAM on the XenServer Host, in bytesread only
memory-freetotal amount of physical RAM remaining that can be allocated to VMs, in bytesread only
host-metrics-last-updatedTimestamp 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-livetrue if the host is operationalread only

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

CPUs on XenServer Hosts have the following parameters:

Parameter NameDescriptionType
uuidThe unique identifier/object reference for the CPUread only
numberthe number of the physical CPU core within the XenServer Hostread only
vendorthe vendor string for the CPU name, for example, "GenuineIntel"read only
speedThe CPU clock speed, in Hzread only
modelnamethe vendor string for the CPU model, for example, "Intel(R) Xeon(TM) CPU 3.00GHz"read only
steppingthe CPU revision numberread only
flagsthe flags of the physical CPU (a decoded version of the features field)read only
utilisationthe current CPU utilizationread only

Crash dumps on XenServer Hosts have the following parameters:

Parameter NameDescriptionType
uuidThe unique identifier/object reference for the crashdumpread only
hostXenServer Host the crashdump corresponds toread only
timestampTimestamp of the date and time that the crashdump occurred, in the form yyyymmdd-hhmmss-ABC, where ABC is the timezone indicator, for example, GMTread only
sizesize of the crashdump, in bytesread 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”).

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

log-set-output output=nil | stderr | file:filename | syslog:sysloglocation [key=key] [level= debug | info | warning | error]

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 NameDescriptionType
uuidThe unique identifier/object reference for the networkread only
name-labelThe name of the networkread only
name-descriptionThe description text of the networkread only
VIF-uuidsA list of unique identifiers of the VIFs (virtual network interfaces) that are attached from VMs to this networkread only set parameter
PIF-uuidsA list of unique identifiers of the PIFs (physical network interfaces) that are attached from XenServer Hosts to this networkread only set parameter
bridgename of the bridge corresponding to this network on the local XenServer Hostread only
other-configA 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 NameDescriptionType
uuidThe unique identifier/object reference for the patchread only
host-uuidThe unique identifier for the XenServer Host host to queryread only
name-labelThe name of the patchread only
name-descriptionThe description string of the patchread only
appliedWhether or not the patch has been applied; true or falseread only
sizeWhether or not the patch has been applied; true or falseread 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 NameDescriptionType
uuidThe unique identifier/object reference for the PBD.read only
hostThe XenServer Host on which the PBD is availableread only
sr-uuidthe Storage Repository that the PBD points toread only
device-configadditional configuration information that is provided to the XenServer Host's SR-backend-driverread only
currently-attachedIs the SR currently attached on this host? True or Falseread 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 NameDescriptionType
uuidThe unique identifier/object reference for the PIFread only
devicemachine-readable name of the interface (for example, eth0)read only
MACthe MAC address of the PIFread only
MTUMaximum Transmission Unit of the interface in octetsread only
VLANVLAN tag for all traffic passing through this interface; -1 indicates no VLAN tag is assignedread only
network-uuidthe unique identifier/object reference of the virtual network to which this PIF is connectedread only
network-name-labelthe name of the of the virtual network to which this PIF is connectedread only
host-uuidthe unique identifier/object reference of the XenServer Host to which this PIF is connectedread only
host-name-labelthe name of the XenServer Host to which this PIF is connectedread only
io_read_kbsaverage read rate in kB/s for the deviceread only
io_write_kbsaverage write rate in kB/s for the deviceread only
carrier read only
vendor-id read only
vendor-name read only
device-id read only
device-name read only
pif-metrics-last-updatedTimestamp 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 NameDescriptionType
uuidthe unique identifier/object reference for the poolread only
name-labelThe name of the poolread only
name-descriptionThe description string of the poolread only
masterthe unique identifier/object reference of XenServer Host designated as the pool's masterread only
default-SRthe unique identifier/object reference of the default SR for the poolread/write
crash-dump-SRthe unique identifier/object reference of the SR where any crash dumps for pool members are savedread/write
suspend-image-SRthe unique identifier/object reference of the SR where suspended VMs on pool members are savedread/write
other-configA list of key/value pairs that specify additional configuration parameters for the poolread/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 NameDescriptionType
uuidThe unique identifier/object reference for the SM pluginread only
name-labelThe name of the SM pluginread only
name-descriptionThe description string of the SM pluginread only
typeThe SR type that this plugin connects toread only
vendorName of the vendor who created this pluginread only
copyrightcopyright statement for this SM pluginread only
required-api-versionMinimum SM API version required on the XenServer Hostread only
configurationnames and descriptions of device configuration keysread 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 NameDescriptionType
uuidThe unique identifier/object reference for the SRread only
name-labelThe name of the SRread only
name-descriptionThe description string of the SRread only
allowed-operationslist of the operations allowed on the SR in this stateread only set parameter
current-operationsA list of the operations that are currently in progress on this SRread only set parameter
VDIsunique identifier/object reference for the virtual disks in this SRread only set parameter
PBDsunique identifier/object reference for the PBDs attached to this SRread only set parameter
virtual-allocatonsum of the virtual sizes of all VDIs in this SR, in bytesread only
physical-utilisationphysical space currently utilized on this SR, in bytes. Note that for sparse disk formats, physical utilisation may be less than virtual allocationread only
physical-sizetotal physical size of the SR, in bytesread only
typetype of the SR, used to specify the SR backend driver to useread only
content-typethe type of the SR’s content, if required (for example, ISOs)read only
sharedtrue if this SR is capable of being shared between multiple XenServer Hosts; false otherwise 
other-configA 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

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.

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 NameDescriptionType
uuidThe unique identifier/object reference for the Taskread only
name-labelThe name of the Taskread only
name-descriptionThe description string of the Taskread only
resident-onThe unique identifier/object reference of the host on which the task is runningread only
statuscurrent status of the Taskread only
progressif 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
typeif 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 undefinedread only
resultif the Task has completed successfully, this field contains the result value, either Void or an object reference; otherwise, this parameter's value is undefinedread only
error_infoif the Task has failed, this parameter contains the set of associated error strings; otherwise, this parameter's value is undefinedread only
allowed_operationslist of the operations allowed in this stateread 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 NameDescriptionType
uuidThe unique identifier/object reference for the VMread only
name-labelThe name of the VMread only
name-descriptionThe description string of the VMread only
user-versionstring for creators of VMs and templates to put version informationread/write
is-a-templatetrue if this is a template. Template VMs can never be started, they are used only for cloning other VMsread/write
is-control-domaintrue if this is a control domain (domain 0 or a driver domain)read only
power-stateCurrent power state; always halted for a Templateread only
auto-power-ontrue if this VM should be started automatically after host bootread/write
memory-dynamic-maxdynamic maximum in bytesread/write
memory-dynamic-mindynamic minimum in bytesread/write
memory-static-maxstatically-set (absolute) maximum in bytesread/write
memory-static-minstatically-set (absolute) minimum in bytesread/write
suspend-VDI-uuidThe VDI that a suspend image is stored on (has no meaning for a Template)read/write
VCPUs-paramsconfiguration 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-maxMax number of VCPUsread/write
VCPUs-at-startupBoot number of VCPUsread/write
actions-after-crashaction to take if a VM based on this Template crashesread/write
console-uuidsvirtual console devicesread only set parameter
platformplatform-specific configurationread/write map parameter
allowed-operationslist of the operations allowed in this stateread only set parameter
current-operationsA list of the operations that are currently in progress on this Templateread only set parameter
allowed-VBD-deviceslist 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-deviceslist 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-paramsThe 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-kernelpath to the kernelread/write
PV-ramdiskpath to the initrdread/write
PV-argsstring of kernel command line argumentsread/write
PV-legacy-argsstring of arguments to make legacy VMs bootread/write
PV-bootloadername of or path to bootloaderread/write
PV-bootloader-argsstring of miscellaneous arguments for the bootloaderread/write
last-boot-CPU-flagsdescribes the CPU flags on which the VM was last booted; not populated for a Templateread only
resident-onthe XenServer Host on which a VM based on this template is currently resident; appears as <not in database> for a Templateread only
affinitya 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 VMread/write
other-configA list of key/value pairs that specify additional configuration parameters for the Templateread/write map parameter
start-timeTimestamp 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 Templateread only
install-timeTimestamp 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 Templateread only
memory-actualThe actual memory being used by a VM based on this Template; 0 for a Templateread only
VCPUs-numberThe 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-utilisationA list of virtual CPUs and their weightread only map parameter
vm-metrics-last-updatedTimestamp 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 Templateread only
os-versionthe version of the operating system for a VM based on this Template; appears as <not in database> for a Templateread only map parameter
PV-drivers-versionthe versions of the paravirtualized drivers for a VM based on this Template; appears as <not in database> for a Templateread only
PV-drivers-up-to-dateflag for latest version of the paravirtualized drivers for a VM based on this Template; appears as <not in database> for a Templateread only
memorymemory metrics reported by the agent on a VM based on this Template; appears as <not in database> for a Templateread only
disksdisk metrics reported by the agent on a VM based on this Template; appears as <not in database> for a Templateread only map parameter
networksnetwork metrics reported by the agent on a VM based on this Template; appears as <not in database> for a Templateread only
otherother metrics reported by the agent on a VM based on this Template; appears as <not in database> for a Templateread only
guest-metrics-last-updatedtimestamp 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 NameDescriptionType
uuidThe unique identifier/object reference for the VBDread only
vm-uuidThe unique identifier/object reference for the VM this VBD is attached toread only
vm-name-labelThe name of the VM this VBD is attached toread only
vdi-uuidThe unique identifier/object reference for the VDI this VBD is mapped toread only
vdi-name-labelThe name of the VDI this VBD is mapped toread only
emptyif true, this represents an empty driveread only
devicethe device seen by the guest, for example hda1read only
userdeviceuser-friendly device nameread/write
bootabletrue if this VBD is bootableread/write
modethe mode the VBD should be mounted withread/write
typehow the VBD appears to the VM, for example disk or CDread/write
currently-attachedtrue if the is device currently attachedread only
storage-locktrue if a storage-level lock was acquiredread only
status-codeerror/success code associated with the last attach operationread only
status-detailerror/success information associated with the last attach operation statusread only
qos_algorithm_typethe QoS algorithm to useread/write
qos_algorithm_paramsparameters for the chosen QoS algorithmread only
qos_supported_algorithmssupported QoS algorithms for this VBDread only set parameter
io_read_kbsaverage read rate in kB/s for this VBDread only
io_write_kbsaverage write rate in kB/s for this VBDread only
vbd-metrics-last-updatedTimestamp 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 NameDescriptionType
uuidThe unique identifier/object reference for the VDIread only
name-labelThe name of the VDIread only
name-descriptionThe description string of the VDIread only
allowed-operationsa list of the operations allowed in this stateread only set parameter
current-operationsa list of the operations that are currently in progress on this VDIread only set parameter
sr-uuidSR in which the VDI residesread only
vbd-uuidsa list of VBDs that refer to this VDIread only set parameter
crashdump-uuidslist of crash dumps that refer to this VDIread only set parameter
virtual-sizesize of disk as presented to the VM, in bytes. Note that, depending on storage backend type, the size may not be respected exactlyread only
physical-utilisationamount of physical space that the VDI is currently taking up on the SR, in bytesread only
typetype of VDI, for example, System or Userread only
sharabletrue if this VDI may be sharedread only
read-onlytrue if this VDI can only be mounted read-onlyread only
storage-locktrue if this VDI is locked at the storage levelread only
parentReferences the parent VDI, if this VDI is part of a chainread only
missingtrue if SR scan operation reported this VDI as not presentread only
other-configadditional configuration information for this VDIread/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 NameDescriptionType
uuidThe unique identifier/object reference for the VIFread only
vm-uuidThe unique identifier/object reference for the VM that this VIF resides onread only
vm-name-labelThe name of the VM that this VIF resides onread only
allowed-operationsa list of the operations allowed in this stateread only set parameter
current-operationsa list of the operations that are currently in progress on this VIFread only set parameter
deviceinteger label of this VIF, indicating the order in which VIF backends were createdread only
MACMAC address of VIF, as exposed to the VMread only
MTUmaximum transmission unit of the VIF, in octetsread only
currently-attachedtrue if the device is currently attachedread only
qos_algorithm_typeQoS algorithm to useread/write
qos_algorithm_paramsparameters for the chosen QoS algorithmread/write map parameter
qos_supported_algorithmssupported QoS algorithms for this VIFread only set parameter
other-configA list of key/value pairs that specify additional configuration parameters for this VIF.read/write map parameter
network-uuidThe unique identifier/object reference of the virtual network to which this VIF is connectedread only
network-name-labelThe unique identifier/object reference of the virtual network to which this VIF is connectedread only
io_read_kbsaverage read rate in kB/s for this VIFread only
io_write_kbsaverage write rate in kB/s for this VIFread only
vif-metrics-last-updatedTimestamp 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 NameDescriptionType
uuidThe unique identifier/object reference for the VMread only
name-labelThe name of the VMread only
name-descriptionThe description string of the VMread only
user-versionstring for creators of VMs and templates to put version informationread/write
is-a-templatefalse unless this is a template; Template VMs can never be started, they are used only for cloning other VMsread/write
is-control-domaintrue if this is a control domain (domain 0 or a driver domain)read only
power-stateCurrent power state; always halted for a Templateread only
memory-dynamic-maxdynamic maximum in bytesread/write
memory-dynamic-mindynamic minimum in bytesread/write
memory-static-maxstatically-set (absolute) maximum in bytesread/write
memory-static-minstatically-set (absolute) minimum in bytesread/write
suspend-VDI-uuidThe VDI that a suspend image is stored on (has no meaning for a Template)read/write
VCPUs-paramsconfiguration 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-maxMax number of VCPUsread/write
VCPUs-at-startupBoot number of VCPUsread/write
actions-after-crashaction to take if the VM crashesread/write
console-uuidsvirtual console devicesread only set parameter
platformplatform-specific configurationread/write map parameter
allowed-operationslist of the operations allowed in this stateread only set parameter
current-operationsA list of the operations that are currently in progress on the VMread only set parameter
allowed-VBD-deviceslist 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-deviceslist 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-kernelpath to the kernelread/write
PV-ramdiskpath to the initrdread/write
PV-argsstring of kernel command line argumentsread/write
PV-legacy-argsstring of arguments to make legacy VMs bootread/write
PV-bootloadername of or path to bootloaderread/write
PV-bootloader-argsstring of miscellaneous arguments for the bootloaderread/write
last-boot-CPU-flagsdescribes the CPU flags on which the VM was last bootedread only
resident-onthe XenServer Host on which a VM is currently residentread only
affinitya XenServer Host which the VM has preference for running on; used by the xe vm-start command to decide where to run the VMread/write
other-configA 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-timeTimestamp 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-timeTimestamp 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-actualThe actual memory being used by a VMread only
VCPUs-numberThe 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-utilisationA list of virtual CPUs and their weightread only map parameter
os-versionthe version of the operating system for the VMread only map parameter
PV-drivers-versionthe versions of the paravirtualized drivers for the VMread only
PV-drivers-up-to-dateflag for latest version of the paravirtualized drivers for the VMread only
memorymemory metrics reported by the agent on the VMread only map parameter
disksdisk metrics reported by the agent on the VMread only map parameter
networksnetwork metrics reported by the agent on the VMread only map parameter
otherother metrics reported by the agent on the VMread only map parameter
guest-metrics-last-updatedtimestamp 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.

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