5.3. Command types

Broadly speaking, the CLI commands can be split in two halves: Low-level commands concerned with listing and parameter manipulation of API objects, and higher level commands for interacting with VMs or hosts in a more abstract level. The low-level commands are:

class-list
class-param-get
class-param-set
class-param-list
class-param-add
class-param-remove
class-param-clear

where class is one of:

console
host
host-crashdump
host-cpu
network
patch
pbd
pif
pool
sm
sr
task
template
vbd
vdi
vif
vm

5.3.1. Parameter types

The objects that are addressed with the xe commands have sets of parameters that identify them and define their states.

Most parameters take a single value. For example, the name-label parameter of a VM contains a single string value. In the output from parameter list commands such as xe vm-param-list, such parameters have an indication in parentheses that defines whether they can be read and written to, or are read-only. For example, the output of xe vm-param-list on a specified VM might have the lines

                  user-version ( RW): 1
             is-control-domain ( RO): false

The first parameter, user-version, is writeable and has the value 1. The second, is-control-domain, is read-only and has a value of false.

The two other types of parameters are multi-valued. A set parameter contains a list of values. A map parameter is a set of key/value pairs. As an example, look at the following excerpt of some sample output of the xe vm-param-list on a specified VM:

                      platform (MRW): acpi: true; apic: true; pae: true; nx: false
            allowed-operations (SRO): pause; clean_shutdown; clean_reboot; hard_shutdown; hard_reboot; suspend

The platform parameter has a list of items that represent key/value pairs. The key names are followed by a colon character (:). Each key/value pair is separated from the next by a semicolon character (;). The M preceding the RW indicates that this is a map parameter and is readable and writeable. The allowed-operations parameter has a list that makes up a set of items. The S preceding the RO indicates that this is a set parameter and is readable but not writeable.

In xe commands where you want to filter on a map parameter, or set a map parameter, use the separator : (colon) between the map parameter name and the key/value pair. For example, to set the value of the foo key of the other-config parameter of a VM to baa, the command would be

xe vm-param-set uuid=VM uuid other-config:foo=baa

5.3.2. Low-level param commands

There are several commands for operating on parameters of objects: class-param-get,class-param-set,class-param-add,class-param-remove,class-param-clear and class-param-list. Each of these takes a uuid parameter to specify the particular object.

class-param-list uuid=uuid

Lists all of the parameters and their associated values. Unlike the class-list command, this will list the values of 'expensive' fields.
class-param-get uuid=uuid param-name=parameter [param-key=key]

Returns the value of a particular parameter. If the parameter is a map, specifying the param-key will get the value associated with that key in the map. If param-key is not specified, or if the parameter is a set, it will return a string representation of the set or map.
class-param-set uuid=uuid param=value...

Sets the value of one or more parameters.
class-param-add uuid=uuid param-name=parameter [key=value...] [param-key=key]

Adds to either a map or a set parameter. If the parameter is a map, add key/value pairs using the 'key=value' syntax. If the parameter is a set, add keys with the 'param-key=key' syntax.
class-param-remove uuid=uuid param-name=parameter param-key=key

Removes either a key/value pair from a map, or a key from a set.
class-param-clear uuid=uuid param-name=parameter

Completely clears a set or a map.

5.3.3. Low-level list commands

The class-list command lists the objects of type class. By default it will list all objects, printing a subset of the parameters. This behavior can be modified in two ways: it can filter the objects so that it only outputs a subset, and the parameters that are printed can be modified.

To change the parameters that are printed, the argument params should be specified as a comma-separated list of the required parameters, e.g.:

 xe vm-list params=name-label,other-config

Alternatively, to list all of the parameters, use the syntax:

 xe vm-list params=all

Note that some parameters that are expensive to calculate will not be shown by the list command. These will be shown as e.g.:

  allowed-VBD-devices (SRO): <expensive field>

In order to obtain these fields, use either the command class-param-list or class-param-get

To filter the list, the CLI will match parameter values with those specified on the command-line, only printing object that match all of the specified constraints. e.g.

 xe vm-list HVM-boot-policy="BIOS order" power-state=halted

will only list those VMs for which both the field 'power-state' has the value 'halted', and for which the field 'HVM-boot-policy' has the value 'BIOS order'.

It is also possible to filter the list based on the value of keys in maps, or on the existence of values in a set. The syntax for the first of these is map-name:key=value, and the second is set-name:contains=value

For scripting, a useful technique is passing '--minimal' on the command line, causing xe to print only the first field in a comma-separated list. For example, the command 'xe vm-list --minimal' on a XenServer Host with three VMs installed gives:

a85d6717-7264-d00e-069b-3b1d19d56ad9,aaa3eec5-9499-bcf3-4c03-af10baea96b7,42c044de-df69-4b30-89d9-2c199564581d