Command-line interface

The xe CLI enables you to script and automate system administration tasks. Use the CLI to integrate Citrix Hypervisor into an existing IT infrastructure.

Getting started with the xe CLI

The xe command line interface is installed by default on all Citrix Hypervisor servers. A remote Windows version is included with XenCenter. A stand-alone remote CLI is also available for Linux.

On your Citrix Hypervisor server

The xe command line interface is installed by default on your server. You can run xe CLI commands in the dom0 console. Access the dom0 console in one of the following ways:

• In XenCenter, go to the Console tab for the server where you want to run the command.
• SSH into the server where you want to run the command.

On Windows

On Windows, the xe.exe command is installed along with XenCenter.

To use the xe.exe command, open a Windows Command Prompt and change directories to the directory where the xe.exe file is located (typically C:\Program Files (x86)\Citrix\XenCenter). If you add the xe.exe installation location to your system path, you can use the command without having to change into the directory.

On Linux

On RPM-based distributions (such as Red Hat), you can install the stand-alone xe command from the RPM named client_install/xapi-xe-BUILD.x86_64.rpm on the main Citrix Hypervisor installation ISO.

To install from the RPM, use the following command:

rpm -ivh xapi-xe-BUILD.x86_64.rpm
<!--NeedCopy-->

You can use parameters at the command line to define the Citrix Hypervisor server, user name, and password to use when running xe commands. However, you also have the option to set this information as an environment variable. For example:

export XE_EXTRA_ARGS="server=<host name>,username=<user name>,password=<password>"
<!--NeedCopy-->

Note:

The remote xe CLI on Linux might hang when attempting to run commands over a secure connection and these commands involve file transfer. If so, you can use the --no-ssl parameter to run the command over an insecure connection to the Citrix Hypervisor server.

Getting help with xe commands

Basic help is available for CLI commands on-host by typing:

xe help command
<!--NeedCopy-->

A list of the most commonly used xe commands is displayed if you type:

xe help
<!--NeedCopy-->

Or a list of all xe commands is displayed if you type:

xe help --all
<!--NeedCopy-->

Basic xe syntax

The basic syntax of all Citrix Hypervisor xe CLI commands is:

xe command-name argument=value argument=value
<!--NeedCopy-->

Each specific command contains its own set of arguments that are of the form argument=value. Some commands have required arguments, and most have some set of optional arguments. Typically a command assumes default values for some of the optional arguments when invoked without them.

If the xe command runs remotely, extra arguments are used to connect and authenticate. These arguments also take the form argument=argument_value.

The server argument is used to specify the host name or IP address. The username and password arguments are used to specify credentials.

A password-file argument can be specified instead of the password directly. In this case, the xe command attempts to read the password from the specified file and uses that password to connect. (Any trailing CRs and LFs at the end of the file are stripped off.) This method is more secure than specifying the password directly at the command line.

The optional port argument can be used to specify the agent port on the remote Citrix Hypervisor server (defaults to 443).

Example: On the local Citrix Hypervisor server:

xe vm-list
<!--NeedCopy-->

Example: On a remote Citrix Hypervisor server:

xe vm-list username=username password=password server=hostname
<!--NeedCopy-->

Shorthand syntax is also available for remote connection arguments:

• -u user name
• -pw password
• -pwf password file
• -p port
• -s server

Example: On a remote Citrix Hypervisor server:

xe vm-list -u myuser -pw mypassword -s hostname
<!--NeedCopy-->

Arguments are also taken from the environment variable XE_EXTRA_ARGS, in the form of comma-separated key/value pairs. For example, to enter commands that are run on a remote Citrix Hypervisor server, first run the following command:

export XE_EXTRA_ARGS="server=jeffbeck,port=443,username=root,password=pass"
<!--NeedCopy-->

After running this command, you no longer have to specify the remote Citrix Hypervisor server parameters in each xe command that you run.

Using the XE_EXTRA_ARGS environment variable also enables tab completion of xe commands when issued against a remote Citrix Hypervisor server, which is disabled by default.

Special characters and syntax

To specify argument/value pairs on the xe command line, write: argument=value

Unless the value includes spaces, do not use quotes. Do not include whitespace between the argument name, the equals sign (=), and the value. Any argument not conforming to this format is ignored.

For values containing spaces, write: argument="value with spaces"

When you use the CLI on your Citrix Hypervisor server, commands have a tab completion feature similar to the feature in the standard Linux bash shell. For example, if you type xe vm-l and then press the TAB key, the rest of the command is displayed. If more than one command begins with vm-l, pressing TAB a second time lists the possibilities. This feature is useful when specifying object UUIDs in commands.

Note:

Tab completion does not normally work when running commands on a remote Citrix Hypervisor server. However, if you set the XE_EXTRA_ARGS variable on the machine where you enter the commands, tab completion is enabled. For more information, see Basic xe syntax.

Command types

The CLI commands can be split in two halves. Low-level commands are concerned with listing and parameter manipulation of API objects. Higher level commands are used to interact 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:

• bond

• console

• host

• host-crashdump

• host-cpu

• network

• patch

• pbd

• pif

• pool

• sm

• sr

• task

• template

• vbd

• vdi

• vif

• vlan

• vm

Not every value of class has the full set of class-param-action commands. Some values of class have a smaller set of commands.

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, a value in parentheses indicates whether parameters are read-write (RW) or read-only (RO). The output of xe vm-param-list on a specified VM might have the following lines:

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

The first parameter, user-version, is writable 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 piece of 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 parameter is a map parameter and is readable and writable. 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 writable.

To filter on a map parameter or set a map parameter, use a colon (:) to separate 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
<!--NeedCopy-->

Low-level parameter 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 commands takes a uuid parameter to specify the particular object. Since these commands are considered low-level commands, they must use the UUID and not the VM name label.

• xe class-param-list uuid=uuid

  Lists all of the parameters and their associated values. Unlike the class-list command, this command lists the values of “expensive” fields.

• xe class-param-get uuid=uuid param-name=parameter param-key=key

  Returns the value of a particular parameter. For a map parameter, specifying the param-key gets the value associated with that key in the map. If param-key is not specified or if the parameter is a set, the command returns a string representation of the set or map.

• xe class-param-set uuid=uuid param=value

  Sets the value of one or more parameters.

• xe class-param-add uuid=uuid param-name=parameter key=value param-key=key

  Adds to either a map or a set parameter. For a map parameter, add key/value pairs by using the key=value syntax. If the parameter is a set, add keys with the param-key=key syntax.

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

• xe class-param-clear uuid=uuid param-name=parameter

  Completely clears a set or a map.

Low-level list commands

The class-list command lists the objects of type class. By default, this type of command lists all objects, printing a subset of the parameters. This behavior can be modified in the following ways:

• It can filter the objects so that it only outputs a subset
• The parameters that are printed can be modified.

To change the parameters that are printed, specify the argument params as a comma-separated list of the required parameters. For example:

xe vm-list params=name-label,other-config
<!--NeedCopy-->

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

xe vm-list params=all
<!--NeedCopy-->

The list command doesn’t show some parameters that are expensive to calculate. These parameters are shown as, for example:

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

To obtain these fields, use either the command class-param-list or class-param-get

To filter the list, the CLI matches parameter values with those values specified on the command-line, only printing objects that match all of the specified constraints. For example:

xe vm-list HVM-boot-policy="BIOS order" power-state=halted
<!--NeedCopy-->

This command lists only those VMs for which both the field power-state has the value halted and the field HVM-boot-policy has the value BIOS order.

You can also filter the list by the value of keys in maps or by the existence of values in a set. The syntax for filtering based on keys in maps is map-name:key=value. The syntax for filtering based on values existing in a set is set-name:contains=value.

When 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 host with three VMs installed gives the three UUIDs of the VMs:

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

Secrets

Citrix Hypervisor provides a secrets mechanism to avoid passwords being stored in plaintext in command-line history or on API objects. XenCenter uses this feature automatically and it can also be used from the xe CLI for any command that requires a password.

Note:

Password secrets cannot be used to authenticate with a Citrix Hypervisor host from a remote instance of the xe CLI.

To create a secret object, run the following command on your Citrix Hypervisor host.

xe secret-create value=my-password
<!--NeedCopy-->

A secret is created and stored on the Citrix Hypervisor host. The command outputs the UUID of the secret object. For example, 99945d96-5890-de2a-3899-8c04ef2521db. Append _secret to the name of the password argument to pass this UUID to any command that requires a password.

Example: On the Citrix Hypervisor host where you created the secret, you can run the following command:

    xe sr-create device-config:location=sr_address device-config:type=cifs device-config:username=cifs_username  \
    device-config:cifspassword_secret=secret_uuid name-label="CIFS ISO SR" type="iso" content-type="iso" shared="true"
<!--NeedCopy-->

Command history

Some xe commands, for example xe vm-migrate or xe pool-enable-external-auth, take secrets like passwords as parameters. These can end up in the shell history and during execution of the command are visible in the process table. It is therefore important to run these commands only in trustworthy environments.

For the bash shell, you can use the HISTCONTROL variable to control which commands are stored in the shell history.

xe command reference

This section groups the commands by the objects that the command addresses. These objects are listed alphabetically.

Appliance commands

Commands for creating and modifying VM appliances (also known as vApps). For more information, see vApps.

Appliance parameters

Appliance commands have the following parameters:

appliance-assert-can-be-recovered

xe appliance-assert-can-be-recovered uuid=appliance-uuid database:vdi-uuid=vdi-uuid
<!--NeedCopy-->

Tests whether storage is available to recover this VM appliance/vApp.

appliance-create

xe appliance-create name-label=name-label [name-description=name-description]
<!--NeedCopy-->

Creates an appliance/vApp. For example:

xe appliance-create name-label=my_appliance
<!--NeedCopy-->

Add VMs to the appliance:

xe vm-param-set uuid=VM-UUID appliance=appliance-uuid
<!--NeedCopy-->

appliance-destroy

xe appliance-destroy uuid=appliance-uuid
<!--NeedCopy-->

Destroys an appliance/vApp. For example:

xe appliance-destroy uuid=appliance-uuid
<!--NeedCopy-->

appliance-recover

xe appliance-recover uuid=appliance-uuid database:vdi-uuid=vdi-uuid [paused=true|false]
<!--NeedCopy-->

Recover a VM appliance/vApp from the database contained in the supplied VDI.

appliance-shutdown

xe appliance-shutdown uuid=appliance-uuid [force=true|false]
<!--NeedCopy-->

Shuts down all VMs in an appliance/vApp. For example:

xe appliance-shutdown uuid=appliance-uuid
<!--NeedCopy-->

appliance-start

xe appliance-start uuid=appliance-uuid [paused=true|false]
<!--NeedCopy-->

Starts an appliance/vApp. For example:

xe appliance-start uuid=appliance-uuid
<!--NeedCopy-->

Audit commands

Audit commands download all of the available records of the RBAC audit file in the pool. If the optional parameter since is present, it downloads only the records from that specific point in time.

audit-log-get parameters

audit-log-get has the following parameters

audit-log-get

xe audit-log-get [since=timestamp] filename=filename
<!--NeedCopy-->

For example, to obtain audit records of the pool since a precise millisecond timestamp, run the following command:

Run the following command:

xe audit-log-get since=2009-09-24T17:56:20.530Z filename=/tmp/auditlog-pool-actions.out
<!--NeedCopy-->

Bonding commands

Commands for working with network bonds, for resilience with physical interface failover. For more information, see Networking.

The bond object is a reference object which glues together master and member PIFs. The master PIF is the bonding interface which must be used as the overall PIF to refer to the bond. The member PIFs are a set of two or more physical interfaces that have been combined into the high-level bonded interface.

Bond parameters

Bonds have the following parameters:

bond-create

xe bond-create network-uuid=network_uuid pif-uuids=pif_uuid_1,pif_uuid_2,...
<!--NeedCopy-->

Create a bonded network interface on the network specified from a list of existing PIF objects. The command fails in any of the following cases:

• If PIFs are in another bond already
• If any member has a VLAN tag set
• If the referenced PIFs are not on the same Citrix Hypervisor server
• If fewer than 2 PIFs are supplied

bond-destroy

xe bond-destroy uuid=bond_uuid
<!--NeedCopy-->

Deletes a bonded interface specified by its UUID from a host.

bond-set-mode

xe bond-set-mode uuid=bond_uuid mode=bond_mode
<!--NeedCopy-->

Change the bond mode.

CD commands

Commands for working with physical CD/DVD drives on Citrix Hypervisor servers.

CD parameters

CDs have the following parameters:

cd-list

xe cd-list [params=param1,param2,...] [parameter=parameter_value]
<!--NeedCopy-->

List the CDs and ISOs (CD image files) on the Citrix Hypervisor server 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. When params is not used, the returned list shows a default subset of all available parameters.

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

Cluster commands

Commands for working with clustered pools.

Clustered pools are resource pools that have the clustering feature enabled. Use these pools with GFS2 SRs. For more information, see Clustered pools

The cluster and cluster-host objects can be listed with the standard object listing commands (xe cluster-list and xe cluster-host-list), and the parameters manipulated with the standard parameter commands. For more information, see Low-level parameter commands. Commands for working with clustered pools.

Cluster parameters

Clusters have the following parameters:

cluster-host-destroy

xe cluster-host-destroy uuid=host_uuid
<!--NeedCopy-->

Destroy a cluster host, effectively leaving the cluster.

cluster-host-disable

xe cluster-host-disable uuid=cluster_uuid
<!--NeedCopy-->

Disable cluster membership for an enabled cluster host.

cluster-host-enable

xe cluster-host-enable uuid=cluster_uuid
<!--NeedCopy-->

Enable cluster membership for a disabled cluster host.

cluster-host-force-destroy

xe cluster-host-force-destroy uuid=cluster_host
<!--NeedCopy-->

Destroy a cluster host object forcefully, effectively leaving the cluster.

cluster-pool-create

xe cluster-pool-create network-uuid=network_uuid [cluster-stack=cluster_stack] [token-timeout=token_timeout] [token-timeout-coefficient=token_timeout_coefficient]
<!--NeedCopy-->

Create pool-wide cluster.

cluster-pool-destroy

xe cluster-pool-destroy cluster-uuid=cluster_uuid
<!--NeedCopy-->

Destroy pool-wide cluster. The pool continues to exist, but it is no longer clustered and can no longer use GFS2 SRs.

cluster-pool-force-destroy

xe cluster-pool-force-destroy cluster-uuid=cluster_uuid
<!--NeedCopy-->

Force destroy pool-wide cluster.

cluster-pool-resync

xe cluster-pool-resync cluster-uuid=cluster_uuid
<!--NeedCopy-->

Resync a cluster across a pool.

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. For more information, see Low-level parameter commands.

Console parameters

Consoles have the following parameters:

console

xe console
<!--NeedCopy-->

Attach to a particular console.

Diagnostic commands

Commands for gathering diagnostic information from Citrix Hypervisor.

diagnostic-compact

xe diagnostic-compact
<!--NeedCopy-->

Perform a major GC collection and heap compaction.

DEPRECATED: diagnostic-db-log

xe diagnostic-db-log
<!--NeedCopy-->

Start logging the database operations. Warning: once started, this cannot be stopped.

diagnostic-db-stats

xe diagnostic-db-stats
<!--NeedCopy-->

Print database statistics.

diagnostic-gc-stats

xe diagnostic-gc-stats
<!--NeedCopy-->

Print GC statistics.

diagnostic-license-status

xe diagnostic-license-status
<!--NeedCopy-->

Help diagnose pool-wide licensing problems.

diagnostic-net-stats

xe diagnostic-net-stats [uri=uri] [method=method] [params=param1,param2...]
<!--NeedCopy-->

Print network statistics.

diagnostic-timing-stats

xe diagnostic-timing-stats
<!--NeedCopy-->

Print timing statistics.

diagnostic-vdi-status

xe diagnostic-vdi-status uuid=vdi_uuid
<!--NeedCopy-->

Query the locking and sharing status of a VDI.

diagnostic-vm-status

xe diagnostic-vm-status uuid=vm_uuid
<!--NeedCopy-->

Query the hosts on which the VM can boot, check the sharing/locking status of all VBDs.

Disaster recovery commands

Commands for recovering VMs after a disaster

drtask-create

xe drtask-create type=type sr-whitelist=sr-white-list device-config=device-config
<!--NeedCopy-->

Creates a disaster recovery task. For example, to connect to an iSCSI SR in preparation for Disaster Recovery:

xe drtask-create type=lvmoiscsi device-config:target=target-ip-address \
    device-config:targetIQN=targetIQN device-config:SCSIid=SCSIid \
    sr-whitelist=sr-uuid-list
<!--NeedCopy-->

Note:

The command sr-whitelist lists SR UUIDs that are allowed. The drtask-create command only introduces and connects to an SR which has one of the allowed UUIDs

drtask-destroy

xe drtask-destroy uuid=dr-task-uuid
<!--NeedCopy-->

Destroys a disaster recovery task and forgets the introduced SR.

vm-assert-can-be-recovered

xe vm-assert-can-be-recovered uuid=vm-uuid database:vdi-uuid=vdi-uuid
<!--NeedCopy-->

Tests whether storage is available to recover this VM.

appliance-assert-can-be-recovered

xe appliance-assert-can-be-recovered uuid=appliance-uuid database:vdi-uuid=vdi-uuid
<!--NeedCopy-->

Checks whether the storage (containing the appliance’s/vAPP disk) is visible.

appliance-recover

xe appliance-recover uuid=appliance-uuid database:vdi-uuid=vdi-uuid [force=true|false]
<!--NeedCopy-->

Recover an appliance/vAPP from the database contained in the supplied VDI.

vm-recover

xe vm-recover uuid=vm-uuid database:vdi-uuid=vdi-uuid [force=true|false]
<!--NeedCopy-->

Recovers a VM from the database contained in the supplied VDI.

sr-enable-database-replication

xe sr-enable-database-replication uuid=sr_uuid
<!--NeedCopy-->

Enables XAPI database replication to the specified (shared) SR.

sr-disable-database-replication

xe sr-disable-database-replication uuid=sr_uuid
<!--NeedCopy-->

Disables XAPI database replication to the specified SR.

Example usage

The example below shows the DR CLI commands in context:

On the primary site, enable database replication:

xe sr-database-replication uuid=sr=uuid
<!--NeedCopy-->

After a disaster, on the secondary site, connect to the SR. The device-config command has the same fields as sr-probe.

xe drtask-create type=lvmoiscsi \
    device-config:target=target ip address \
    device-config:targetIQN=target-iqn \
    device-config:SCSIid=scsi-id \
    sr-whitelist=sr-uuid
<!--NeedCopy-->

Look for database VDIs on the SR:

xe vdi-list sr-uuid=sr-uuid type=Metadata
<!--NeedCopy-->

Query a database VDI for VMs present:

xe vm-list database:vdi-uuid=vdi-uuid
<!--NeedCopy-->

Recover a VM:

xe vm-recover uuid=vm-uuid database:vdi-uuid=vdi-uuid
<!--NeedCopy-->

Destroy the DR task. Any SRs introduced by the DR task and not required by VMs are destroyed:

xe drtask-destroy uuid=drtask-uuid
<!--NeedCopy-->

Event commands

Commands for working with events.

Event classes

Event classes are listed in the following table:

event-wait

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

Blocks other commands from running until an object exists that satisfies the conditions given on the command line. The argument x=y means “wait for field x to take value y” and x=/=y means “wait for field x to take any value other than y.”

Example: wait for a specific VM to be running.

xe event-wait class=vm name-label=myvm power-state=running
<!--NeedCopy-->

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

Example: wait for a specific VM to reboot:

xe event-wait class=vm uuid=$VM start-time=/=$(xe vm-list uuid=$VM params=start-time --minimal)
<!--NeedCopy-->

Blocks other commands until a VM with UUID $VM reboots. The command uses the value of start-time to decide when the VM reboots.

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

GPU commands

Commands for working with physical GPUs, GPU groups, and virtual GPUs.

The GPU objects can be listed with the standard object listing commands: xe pgpu-list, xe gpu-group-list, and xe vgpu-list. The parameters can be manipulated with the standard parameter commands. For more information, see Low-level parameter commands.

Physical GPU parameters

Physical GPUS (pGPUs) have the following parameters:

pgpu-disable-dom0-access

xe pgpu-disable-dom0-access uuid=uuid
<!--NeedCopy-->

Disable PGPU access to dom0.

pgpu-enable-dom0-access

xe pgpu-enable-dom0-access uuid=uuid
<!--NeedCopy-->

Enable PGPU access to dom0.

GPU group parameters

GPU groups have the following parameters:

GPU group operations

Commands for working with GPU Groups

gpu-group-create

xe gpu-group-create name-label=name_for_group [name-description=description]
<!--NeedCopy-->

Creates a new (empty) GPU Group into which pGPUs can be moved.

gpu-group-destroy

xe gpu-group-destroy uuid=uuid_of_group
<!--NeedCopy-->

Destroys the GPU Group; only permitted for empty groups.

gpu-group-get-remaining-capacity

xe gpu-group-get-remaining-capacity uuid=uuid_of_group vgpu-type-uuid=uuid_of_vgpu_type
<!--NeedCopy-->

Returns how many more virtual GPUs of the specified type can be instantiated in this GPU Group.

gpu-group-param-set

xe gpu-group-param-set uuid=uuid_of_group allocation-algorithm=breadth-first|depth-first
<!--NeedCopy-->

Changes the algorithm that the GPU group uses to allocate virtual GPUs to pGPUs.

gpu-group-param-get-uuid

xe gpu-group-param-get-uuid uuid=uuid_of_group param-name=supported-vGPU-types|enabled-vGPU-types
<!--NeedCopy-->

Returns the supported or enabled types for this GPU Group.

Virtual GPU parameters

Virtual GPUs have the following parameters:

Virtual GPU type parameters

Note:

GPU pass-through and virtual GPUs are not compatible with live migration, storage live migration, or VM Suspend unless supported software and graphics cards from GPU vendors are present. VMs without this support cannot be migrated to avoid downtime. For information about NVIDIA vGPU compatibility with live migration, storage live migration, and VM Suspend, see Graphics.

Virtual GPU Types have the following parameters:

Virtual GPU operations

vgpu-create

xe vgpu-create vm-uuid=uuid_of_vm gpu_group_uuid=uuid_of_gpu_group [vgpu-type-uuid=uuid_of_vgpu-type]
<!--NeedCopy-->

Creates a virtual GPU. This command attaches the VM to the specified GPU group and optionally specifies the virtual GPU type. If no virtual GPU type is specified, the ‘pass-through’ type is assumed.

vgpu-destroy

xe vgpu-destroy uuid=uuid_of_vgpu
<!--NeedCopy-->

Destroy the specified virtual GPU.

Disabling VNC for VMs with virtual GPU

xe vm-param-add uuid=uuid_of_vmparam-name=platform vgpu_vnc_enabled=true|false
<!--NeedCopy-->

Using false disables the VNC console for a VM as it passes disablevnc=1 through to the display emulator. By default, VNC is enabled.

Host commands

Commands for interacting with Citrix Hypervisor server.

Citrix Hypervisor servers are the physical servers running Citrix Hypervisor 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 Citrix Hypervisor server objects can be listed with the standard object listing commands: xe host-list, xe host-cpu-list, and xe host-crashdump-list). The parameters can be manipulated with the standard parameter commands. For more information, see Low-level parameter commands.

Host selectors

Several of the commands listed here have a common mechanism for selecting one or more Citrix Hypervisor servers on which to perform the operation. The simplest is by supplying the argument host=uuid_or_name_label. You can also specify Citrix Hypervisor by filtering the full list of hosts on the values of fields. For example, specifying enabled=true selects all Citrix Hypervisor servers whose enabled field is equal to true. Where multiple Citrix Hypervisor servers match and the operation can be performed on multiple Citrix Hypervisor servers, you must specify --multiple to perform the operation. The full list of parameters that can be matched is described at the beginning of this section. You can obtain this list of commands by running the command xe host-list params=all. If no parameters to select Citrix Hypervisor servers are given, the operation is performed on all Citrix Hypervisor servers.

Host parameters

Citrix Hypervisor servers have the following parameters:

Citrix Hypervisor servers contain some other objects that also have parameter lists.

CPUs on Citrix Hypervisor servers have the following parameters:

Crash dumps on Citrix Hypervisor servers have the following parameters:

host-all-editions

xe host-all-editions
<!--NeedCopy-->

Get a list of all available editions

host-apply-edition

xe host-apply-edition [host-uuid=host_uuid] [edition=xenserver_edition="free" "per-socket" "xendesktop"]
<!--NeedCopy-->

Assigns the Citrix Hypervisor license to a host server. When you assign a license, Citrix Hypervisor contacts the License Server and requests the specified type of license. If a license is available, it is then checked out from the license server.

For Citrix Hypervisor for Citrix Virtual Desktops and DaaS editions, use "xendesktop".

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

host-backup

xe host-backup file-name=backup_filename host=host_name
<!--NeedCopy-->

Download a backup of the control domain of the specified Citrix Hypervisor server to the machine that the command is invoked from. Save it there as a file with the name file-name.

Important:

While the xe host-backup command works if run on the local host (that is, without a specific host name specified), do not use it this way. Doing so would fill up the control domain partition with the backup file. Only use the command from a remote off-host machine where you have space to hold the backup file.

host-bugreport-upload

xe host-bugreport-upload [host-selector=host_selector_value...] [url=destination_url http-proxy=http_proxy_name]
<!--NeedCopy-->

Generate a fresh bug report (using xen-bugtool, with all optional files included) and upload to the Support FTP site or some other location.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

Optional parameters are http-proxy: use specified HTTP proxy, and url: upload to this destination URL. If optional parameters are not used, no proxy server is identified and the destination is the default Support FTP site.

host-call-plugin

xe host-call-plugin host-uuid=host_uuid plugin=plugin fn=function [args=args]
<!--NeedCopy-->

Calls the function within the plug-in on the given host with optional arguments.

host-compute-free-memory

xe host-compute-free-memory
<!--NeedCopy-->

Computes the amount of free memory on the host.

host-compute-memory-overhead

xe host-compute-memory-overhead
<!--NeedCopy-->

Computes the virtualization memory overhead of a host.

host-cpu-info

xe host-cpu-info [uuid=uuid]
<!--NeedCopy-->

Lists information about the host’s physical CPUs.

host-crashdump-destroy

xe host-crashdump-destroy uuid=crashdump_uuid
<!--NeedCopy-->

Delete a host crashdump specified by its UUID from the Citrix Hypervisor server.

host-crashdump-upload

xe host-crashdump-upload uuid=crashdump_uuid [url=destination_url] [http-proxy=http_proxy_name]
<!--NeedCopy-->

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

host-declare-dead

xe host-declare-dead uuid=host_uuid
<!--NeedCopy-->

Declare that the host is dead without contacting it explicitly.

Warning:

This call is dangerous and can cause data loss if the host is not actually dead.

host-disable

xe host-disable [host-selector=host_selector_value...]
<!--NeedCopy-->

Disables the specified Citrix Hypervisor servers, which prevents any new VMs from starting on them. This action prepares the Citrix Hypervisor servers to be shut down or rebooted. After that host reboots, if all conditions for enabling are met (for example, storage is available), the host is automatically re-enabled.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors). Optional arguments can be any number of the host parameters listed at the beginning of this section.

host-disable-display

xe host-disable-display uuid=host_uuid
<!--NeedCopy-->

Disable display for the host.

host-disable-local-storage-caching

xe host-disable-local-storage-caching
<!--NeedCopy-->

Disable local storage caching on the specified host.

host-dmesg

xe host-dmesg [host-selector=host_selector_value...]
<!--NeedCopy-->

Get a Xen dmesg (the output of the kernel ring buffer) from specified Citrix Hypervisor servers.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

host-emergency-ha-disable

xe host-emergency-ha-disable  [--force]
<!--NeedCopy-->

Disable HA on the local host. Only to be used to recover a pool with a broken HA setup.

host-emergency-management-reconfigure

xe host-emergency-management-reconfigure interface=uuid_of_management_interface_pif
<!--NeedCopy-->

Reconfigure the management interface of this Citrix Hypervisor server. Use this command only if the Citrix Hypervisor server is in emergency mode. Emergency mode means that the host is a member in a resource pool whose master has disappeared from the network and cannot be contacted after a number of retries.

host-emergency-reset-server-certificate

xe host-emergency-reset-server-certificate
<!--NeedCopy-->

Installs a self-signed certificate on the Citrix Hypervisor server where the command is run.

host-enable

xe host-enable [host-selector=host_selector_value...]
<!--NeedCopy-->

Enables the specified Citrix Hypervisor servers, which allows new VMs to be started on them.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

host-enable-display

xe host-enable-display uuid=host_uuid
<!--NeedCopy-->

Enable display for the host.

host-enable-local-storage-caching

xe host-enable-local-storage-caching  sr-uuid=sr_uuid
<!--NeedCopy-->

Enable local storage caching on the specified host.

host-evacuate

xe host-evacuate [host-selector=host_selector_value...]
<!--NeedCopy-->

Live migrates all running VMs to other suitable hosts on a pool. First, disable the host by using the host-disable command.

If the evacuated host is the pool master, then another host must be selected to be the pool master. To change the pool master with HA disabled, use the pool-designate-new-master command. For more information, see pool-designate-new-master.

With HA enabled, your only option is to shut down the server, which causes HA to elect a new master at random. For more information, see host-shutdown.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

host-forget

xe host-forget uuid=host_uuid
<!--NeedCopy-->

The XAPI agent forgets about the specified Citrix Hypervisor server without contacting it explicitly.

Use the --force parameter to avoid being prompted to confirm that you really want to perform this operation.

Warning:

Do not use this command if HA is enabled on the pool. Disable HA first, then enable it again after you’ve forgotten the host.

This command is useful if the Citrix Hypervisor server to “forget” is dead. However, if the Citrix Hypervisor server is live and part of the pool, use xe pool-eject instead.

host-get-server-certificate

xe host-get-server-certificate
<!--NeedCopy-->

Get the installed server TLS certificate.

host-get-sm-diagnostics

xe host-get-sm-diagnostics uuid=uuid
<!--NeedCopy-->

Display per-host SM diagnostic information.

host-get-system-status

xe host-get-system-status filename=name_for_status_file [entries=comma_separated_list] [output=tar.bz2|zip] [host-selector=host_selector_value...]
<!--NeedCopy-->

Download system status information into the specified file. The optional parameter entries is a comma-separated list of system status entries, taken from the capabilities XML fragment returned by the host-get-system-status-capabilities command. For more information, see host-get-system-status-capabilities. If not specified, all system status information is saved in the file. The parameter output may be tar.bz2 (the default) or zip. If this parameter is not specified, the file is saved in tar.bz2 form.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above).

host-get-system-status-capabilities

xe host-get-system-status-capabilities [host-selector=host_selector_value...]
<!--NeedCopy-->

Get system status capabilities for the specified hosts. The capabilities are returned as an XML fragment that similar to the following example:

<?xml version="1.0" ?>
<system-status-capabilities>
    <capability content-type="text/plain" default-checked="yes" key="xenserver-logs"  \
        max-size="150425200" max-time="-1" min-size="150425200" min-time="-1" \
        pii="maybe"/>
    <capability content-type="text/plain" default-checked="yes" \
        key="xenserver-install" max-size="51200" max-time="-1" min-size="10240" \
        min-time="-1" pii="maybe"/>
    ...
</system-status-capabilities>
<!--NeedCopy-->

Each capability entity can have the following attributes.

• key A unique identifier for the capability.
• content-type Can be either text/plain or application/data. Indicates whether a UI can render the entries for human consumption.
• default-checked Can be either yes or no. Indicates whether a UI selects this entry by default.
• min-size, max-size Indicates an approximate range for the size, in bytes, of this entry. -1 indicates that the size is unimportant.
• min-time, max-time Indicate an approximate range for the time, in seconds, taken to collect this entry. -1 indicates that the time is unimportant.

• pii Personally identifiable information. Indicates whether the entry has information that can identify the system owner or details of their network topology. The attribute can have one of the following values:

  • no: no PII is in these entries
  • yes: PII likely or certainly is in these entries
  • maybe: you might want to audit these entries for PII
  • if_customized if the files are unmodified, then they contain no PII. However, because we encourage editing of these files, PII might have been introduced by such customization. This value is used in particular for the networking scripts in the control domain.

  Passwords are never to be included in any bug report, regardless of any PII declaration.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above).

host-get-thread-diagnostics

xe host-get-thread-diagnostics uuid=uuid
<!--NeedCopy-->

Display per-host thread diagnostic information.

host-get-vms-which-prevent-evacuation

xe host-get-vms-which-prevent-evacuation uuid=uuid
<!--NeedCopy-->

Return a list of VMs which prevent the evacuation of a specific host and display reasons for each one.

host-is-in-emergency-mode

xe host-is-in-emergency-mode
<!--NeedCopy-->

Returns true if the host the CLI is talking to is in emergency mode, false otherwise. This CLI command works directly on pool member servers even with no master server present.

host-license-view

xe host-license-view [host-uuid=host_uuid]
<!--NeedCopy-->

Displays the contents of the Citrix Hypervisor server license.

host-logs-download

xe host-logs-download [file-name=logfile_name] [host-selector=host_selector_value...]
<!--NeedCopy-->

Download a copy of the logs of the specified Citrix Hypervisor servers. The copy is saved by default in a time-stamped file named hostname-yyyy-mm-dd T hh:mm:ssZ.tar.gz. You can specify a different file name using the optional parameter file-name.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

Important:

While the xe host-logs-download command works if run on the local host (that is, without a specific host name specified), do not use it this way. Doing so clutters the control domain partition with the copy of the logs. Only use the command from a remote off-host machine where you have space to hold the copy of the logs.

host-management-disable

xe host-management-disable
<!--NeedCopy-->

Disables the host agent listening on an external management network interface and disconnects all connected API clients (such as the XenCenter). This command operates directly on the Citrix Hypervisor server the CLI is connected to. The command is not forwarded to the pool master when applied to a member Citrix Hypervisor server.

Warning:

Be careful when using this CLI command off-host. After this command is run, you cannot connect to the control domain remotely over the network to re-enable the host agent.

host-management-reconfigure

xe host-management-reconfigure [interface=device] [pif-uuid=uuid]
<!--NeedCopy-->

Reconfigures the Citrix Hypervisor server to use the specified network interface as its management interface, which is the interface that is used to connect to the XenCenter. The command rewrites the MANAGEMENT_INTERFACE key in /etc/xensource-inventory.

If the device name of an interface (which must have an IP address) is specified, the Citrix Hypervisor server immediately rebinds. This command works both in normal and emergency mode.

If the UUID of a PIF object is specified, the Citrix Hypervisor server determines which IP address to rebind to itself. It must not be in emergency mode when this command is run.

Warning:

Be careful when using this CLI command off-host and ensure that you have network connectivity on the new interface. Use xe pif-reconfigure to set one up first. Otherwise, subsequent CLI commands are unable to reach the Citrix Hypervisor server.

host-power-on

xe host-power-on [host=host_uuid]
<!--NeedCopy-->

Turns on power on Citrix Hypervisor servers with the Host Power On function enabled. Before using this command, enable host-set-power-on on the host.

host-reboot

xe host-reboot [host-selector=host_selector_value...]
<!--NeedCopy-->

Reboot the specified Citrix Hypervisor servers. The specified hosts must be disabled first using the xe host-disable command, otherwise a HOST_IN_USE error message is displayed.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

If the specified Citrix Hypervisor servers are members of a pool, the loss of connectivity on shutdown is handled and the pool recovers when the Citrix Hypervisor servers returns. The other members and the master continue to function.

If you shut down the master, the pool is out of action until one of the following actions occurs:

• You make one of the members into the master

• The original master is rebooted and back on line.

  When the master is back online, the members reconnect and synchronize with the master.

host-restore

xe host-restore [file-name=backup_filename] [host-selector=host_selector_value...]
<!--NeedCopy-->

Restore a backup named file-name of the Citrix Hypervisor server control software. The use of the word “restore” here does not mean a full restore in the usual sense, it merely means that the compressed backup file has been uncompressed and unpacked onto the secondary partition. After you’ve done a xe host-restore, you have to boot the Install CD and use its Restore from Backup option.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

host-send-debug-keys

xe host-send-debug-keys  host-uuid=host_uuid keys=keys
<!--NeedCopy-->

Send specified hypervisor debug keys to specified host.

host-server-certificate-install

xe host-server-certificate-install certificate=path_to_certificate_file private-key=path_to_private_key [certificate-chain=path_to_chain_file] [host=host_name | uuid=host_uuid]
<!--NeedCopy-->

Install a TLS certificate on a Citrix Hypervisor server.

host-set-hostname-live

xe host-set-hostname-live host-uuid=uuid_of_host host-name=new_hostname
<!--NeedCopy-->

Change the host name of the Citrix Hypervisor server specified by host-uuid. This command persistently sets both the host name in the control domain database and the actual Linux host name of the Citrix Hypervisor server. The value of host-name is not the same as the value of the name_label field.

host-set-power-on-mode

xe host-set-power-on-mode host=host_uuid power-on-mode={"" | "wake-on-lan" | "DRAC" | "custom"} \
    [ power-on-config:power_on_ip=ip-address power-on-config:power_on_user=user power-on-config:power_on_password_secret=secret-uuid ]
<!--NeedCopy-->

Use to enable the Host Power On function on Citrix Hypervisor hosts that are compatible with remote power solutions. When using the host-set-power-on command, you must specify the type of power management solution on the host (that is, the power-on-mode). Then specify configuration options using the power-on-config argument and its associated key-value pairs.

To use the secrets feature to store your password, specify the key "power_on_password_secret". For more information, see Secrets.

host-shutdown

xe host-shutdown [host-selector=host_selector_value...]
<!--NeedCopy-->

Shut down the specified Citrix Hypervisor servers. The specified Citrix Hypervisor servers must be disabled first using the xe host-disable command, otherwise a HOST_IN_USE error message is displayed.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

If the specified Citrix Hypervisor servers are members of a pool, the loss of connectivity on shutdown is handled and the pool recovers when the Citrix Hypervisor servers returns. The other members and the master continue to function.

If you shut down the master, the pool is out of action until one of the following actions occurs:

• You make one of the members into the master

• The original master is rebooted and back on line.

  When the master is back online, the members reconnect and synchronize with the master.

If HA is enabled for the pool, one of the members is made into a master automatically. If HA is disabled, you must manually designate the desired server as master with the pool-designate-new-master command. For more information, see pool-designate-new-master.

host-sm-dp-destroy

xe host-sm-dp-destroy uuid=uuid dp=dp [allow-leak=true|false]
<!--NeedCopy-->

Attempt to destroy and clean up a storage datapath on a host. If allow-leak=true is provided then it deletes all records of the datapath even if it is not shut down cleanly.

host-sync-data

xe host-sync-data
<!--NeedCopy-->

Synchronize the data stored on the pool master with the named host. This does not include the database data).

host-syslog-reconfigure

xe host-syslog-reconfigure [host-selector=host_selector_value...]
<!--NeedCopy-->

Reconfigure the syslog daemon on the specified Citrix Hypervisor servers. This command applies the configuration information defined in the host logging parameter.

The hosts on which to perform this operation are selected using the standard selection mechanism (see host selectors above). Optional arguments can be any number of the host parameters listed at the beginning of this section.

host-data-source-list

xe host-data-source-list [host-selectors=host selector value...]
<!--NeedCopy-->

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

Select the hosts on which to perform this operation by using the standard selection mechanism (see host selectors). Optional arguments can be any number of the host parameters listed at the beginning of this section. If no parameters to select hosts are given, the operation is performed on all hosts.

Data sources have two parameters – standard and enabled. This command outputs the values of the parameters:

• If a data source has enabled set to true, the metrics are currently being recorded to the performance database.
• If a data source has standard set to true, the metrics are recorded to the performance database by default. The value of enabled is also set to true for this data source.
• If a data source has standard set to false, the metrics are not recorded to the performance database by default. The value of enabled is also set to false for this data source.

To start recording data source metrics to the performance database, run the host-data-source-record command. This command sets enabled to true. To stop, run the host-data-source-forget. This command sets enabled to false.

host-data-source-record

xe host-data-source-record data-source=name_description_of_data_source [host-selectors=host_selector_value...]
<!--NeedCopy-->

Record the specified data source for a host.

This operation writes the information from the data source to the persistent performance metrics database of the specified hosts. For performance reasons, this database is distinct from the normal agent database.

Select the hosts on which to perform this operation by using the standard selection mechanism (see host selectors). Optional arguments can be any number of the host parameters listed at the beginning of this section. If no parameters to select hosts are given, the operation is performed on all hosts.

host-data-source-forget

xe host-data-source-forget data-source=name_description_of_data_source [host-selectors=host_selector_value...]
<!--NeedCopy-->

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

Select the hosts on which to perform this operation by using the standard selection mechanism (see host selectors). Optional arguments can be any number of the host parameters listed at the beginning of this section. If no parameters to select hosts are given, the operation is performed on all hosts.

host-data-source-query

xe host-data-source-query data-source=name_description_of_data_source [host-selectors=host_selector_value...]
<!--NeedCopy-->

Display the specified data source for a host.

Select the hosts on which to perform this operation by using the standard selection mechanism (see host selectors). Optional arguments can be any number of the host parameters listed at the beginning of this section. If no parameters to select hosts are given, the operation is performed on all hosts.

DEPRECATED: Log commands

Commands for working with logs.

DEPRECATED: log-get

xe log-get
<!--NeedCopy-->

Return the log currently stored in the string logger.

DEPRECATED: log-get-keys

xe log-get-keys
<!--NeedCopy-->

List the keys known by the logger.

DEPRECATED: log-reopen

xe log-reopen
<!--NeedCopy-->

Reopen all loggers (use this for rotating files).

DEPRECATED: log-set-output

xe log-set-output output=output [key=key] [level=level]
<!--NeedCopy-->

Set all loggers to the specified output (nil, stderr, string, file:file name, syslog:something).

Message commands

Commands for working with messages. Messages are created to notify users of significant events, and are displayed in XenCenter as alerts.

The message objects can be listed with the standard object listing command (xe message-list), and the parameters manipulated with the standard parameter commands. For more information, see Low-level parameter commands

Message parameters

message-create

xe message-create name=message_name body=message_text [[host-uuid=uuid_of_host] | [sr-uuid=uuid_of_sr] | [vm-uuid=uuid_of_vm] | [pool-uuid=uuid_of_pool]]
<!--NeedCopy-->

Creates a message.

message-destroy

xe message-destroy [uuid=message_uuid]
<!--NeedCopy-->

Destroys an existing message. You can build a script to destroy all messages. For example:

# Dismiss all alerts   \
    IFS=","; for m in $(xe message-list params=uuid --minimal); do  \
    xe message-destroy uuid=$m  \
    done
<!--NeedCopy-->

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. For more information, see Low-level parameter commands

Network parameters

Networks have the following parameters:

network-create

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

Creates a network.

network-destroy

xe network-destroy uuid=network_uuid
<!--NeedCopy-->

Destroys an existing network.

SR-IOV commands

Commands for working with SR-IOV.

The network-sriov objects can be listed with the standard object listing command (xe network-sriov-list), and the parameters manipulated with the standard parameter commands. For more information, see Low-level parameter commands

SR-IOV parameters

SR-IOV has the following parameters:

network-sriov-create

xe network-sriov-create network-uuid=network_uuid pif-uuid=physical_pif_uuid
<!--NeedCopy-->

Creates an SR-IOV network object for a given physical PIF and enables SR-IOV on the physical PIF.

network-sriov-destroy

xe network-sriov-destroy uuid=network_sriov_uuid
<!--NeedCopy-->

Removes a network SR-IOV object and disables SR-IOV on its physical PIF.

Assign an SR-IOV VF

xe vif-create device=device_index mac=vf_mac_address network-uuid=sriov_network vm-uuid=vm_uuid
<!--NeedCopy-->

Assigns a VF from an SR-IOV network to a VM.

SDN Controller commands

Commands for working with the SDN controller.

sdn-controller-forget

xe sdn-controller-introduce [address=address] [protocol=protocol] [tcp-port=tcp_port]
<!--NeedCopy-->

Introduce an SDN controller.

sdn-controller-introduce

xe sdn-controller-forget uuid=uuid
<!--NeedCopy-->

Remove an SDN controller.

Tunnel commands

Commands for working with tunnels.

tunnel-create

xe tunnel-create pif-uuid=pif_uuid network-uuid=network_uuid
<!--NeedCopy-->

Create a new tunnel on a host.

tunnel-destroy

xe tunnel-destroy uuid=uuid
<!--NeedCopy-->

Destroy a tunnel.

Patch commands

Commands for working with patches.

patch-apply

xe patch-apply uuid=patch_uuid host-uuid=host_uuid
<!--NeedCopy-->

Apply the previously uploaded patch to the specified host.

patch-clean

xe patch-clean uuid=uuid
<!--NeedCopy-->

Delete a previously uploaded patch file.

patch-destroy

xe patch-destroy uuid=uuid
<!--NeedCopy-->

Remove an unapplied patch record and files from the server.

patch-pool-apply

xe patch-pool-apply uuid=uuid
<!--NeedCopy-->

Apply the previously uploaded patch to all hosts in the pool.

patch-pool-clean

xe patch-pool-clean uuid=uuid
<!--NeedCopy-->

Delete a previously uploaded patch file on all hosts in the pool.

patch-precheck

xe patch-precheck uuid=uuid host-uuid=host_uuid
<!--NeedCopy-->

Run the prechecks contained within the patch previously uploaded to the specified host.

patch-upload

xe patch-upload file-name=file_name
<!--NeedCopy-->

Upload a patch file to the server.

PBD commands

Commands for working with PBDs (Physical Block Devices). PBDs are the software objects through which the Citrix Hypervisor server 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. For more information, see Low-level parameter commands

PBD parameters

PBDs have the following parameters:

pbd-create

xe pbd-create host-uuid=uuid_of_host sr-uuid=uuid_of_sr [device-config:key=corresponding_value]
<!--NeedCopy-->

Create a PBD on your Citrix Hypervisor server. The read-only device-config parameter can only be set on creation.

To add a mapping from ‘path’ to ‘/tmp’, ensure that the command line contains the argument device-config:path=/tmp

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

pbd-destroy

xe pbd-destroy uuid=uuid_of_pbd
<!--NeedCopy-->

Destroy the specified PBD.

pbd-plug

xe pbd-plug uuid=uuid_of_pbd
<!--NeedCopy-->

Attempts to plug in the PBD to the Citrix Hypervisor server. If this command succeeds, the referenced SR (and the VDIs contained within) becomes visible to the Citrix Hypervisor server.

pbd-unplug

xe pbd-unplug uuid=uuid_of_pbd
<!--NeedCopy-->

Attempt to unplug the PBD from the Citrix Hypervisor server.

PIF commands

Commands for working with PIFs (objects representing the 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. For more information, see Low-level parameter commands

PIF parameters

PIFs have the following parameters:

Note:

Changes made to the other-config fields of a PIF will only take effect after a reboot. Alternately, use the xe pif-unplug and xe pif-plug commands to cause the PIF configuration to be rewritten.

pif-forget

xe pif-forget uuid=uuid_of_pif
<!--NeedCopy-->

Destroy the specified PIF object on a particular host.

pif-introduce

xe pif-introduce host-uuid=host_uuid mac=mac_address_for_pif device=interface_name
<!--NeedCopy-->

Create a PIF object representing a physical interface on the specified Citrix Hypervisor server.

pif-plug

xe pif-plug uuid=uuid_of_pif
<!--NeedCopy-->

Attempt to bring up the specified physical interface.

pif-reconfigure-ip

xe pif-reconfigure-ip uuid=uuid_of_pif [mode=dhcp|mode=static] gateway=network_gateway_address IP=static_ip_for_this_pif netmask=netmask_for_this_pif [DNS=dns_address]
<!--NeedCopy-->

Modify the IP address of the PIF. For static IP configuration, set the mode parameter to static, with the gateway, IP, and netmask parameters set to the appropriate values. To use DHCP, set the mode parameter to DHCP and leave the static parameters undefined.

Note:

Using static IP addresses on physical network interfaces connected to a port on a switch using Spanning Tree Protocol with STP Fast Link turned off (or unsupported) results in a period during which there is no traffic.

pif-reconfigure-ipv6

xe pif-reconfigure-ipv6 uuid=uuid_of_pif mode=mode [gateway=network_gateway_address] [IPv6=static_ip_for_this_pif] [DNS=dns_address]
<!--NeedCopy-->

Reconfigure the IPv6 address settings on a PIF.

pif-scan

xe pif-scan host-uuid=host_uuid
<!--NeedCopy-->

Scan for new physical interfaces on your Citrix Hypervisor server.

pif-set-primary-address-type

xe pif-set-primary-address-type  uuid=uuid primary_address_type=address_type
<!--NeedCopy-->

Change the primary address type used by this PIF.

pif-unplug

xe pif-unplug uuid=uuid_of_pif
<!--NeedCopy-->

Attempt to bring down the specified physical interface.

Pool commands

Commands for working with pools. A pool is an aggregate of one or more Citrix Hypervisor servers. A pool uses one or more shared storage repositories so that the VMs running on one host in the pool can be migrated in near-real time to another host in the pool. This migration happens while the VM is still running, without it needing to be shut down and brought back up. Each Citrix Hypervisor server is really a pool consisting of a single member by default. When your Citrix Hypervisor server is joined to a pool, it is designated as a member, and the pool it has joined becomes the master for the pool.

The singleton pool object can be listed with the standard object listing command (xe pool-list). Its parameters can be manipulated with the standard parameter commands. For more information, see Low-level parameter commands

Pool parameters

Pools have the following parameters:

pool-apply-edition

xe pool-apply-edition edition=edition [uuid=uuid] [license-server-address=address] [license-server-port=port]
<!--NeedCopy-->

Apply an edition across the pool.

pool-certificate-install

xe pool-certificate-install filename=file_name
<!--NeedCopy-->

Install an TLS certificate, pool-wide.

pool-certificate-list

xe pool-certificate-list
<!--NeedCopy-->

List all installed TLS certificates in a pool.

pool-certificate-sync

xe pool-certificate-sync
<!--NeedCopy-->

Sync TLS certificates and certificate revocation lists from pool master to the other pool members.

pool-certificate-uninstall

xe pool-certificate-uninstall name=name
<!--NeedCopy-->

Uninstall a TLS certificate.

pool-crl-install

xe pool-crl-install filename=file_name
<!--NeedCopy-->

Install a TLS certificate revocation list, pool-wide.

pool-crl-list

xe pool-crl-list
<!--NeedCopy-->

List all installed TLS certificate revocation lists.

pool-crl-uninstall

xe pool-crl-uninstall name=name
<!--NeedCopy-->

Uninstall an TLS certificate revocation list.

pool-deconfigure-wlb

xe pool-deconfigure-wlb
<!--NeedCopy-->

Permanently remove the configuration for workload balancing.

pool-designate-new-master

xe pool-designate-new-master host-uuid=uuid_of_new_master
<!--NeedCopy-->

Instruct the specified member Citrix Hypervisor server to become the master of an existing pool. This command performs an orderly handover of the role of master host to another host in the resource pool. This command only works when the current master is online. It is not a replacement for the emergency mode commands listed below.

pool-disable-external-auth

xe pool-disable-external-auth [uuid=uuid] [config=config]
<!--NeedCopy-->

Disables external authentication in all the hosts in a pool.

pool-disable-local-storage-caching

xe pool-disable-local-storage-caching uuid=uuid
<!--NeedCopy-->

Disable local storage caching across the pool.

pool-disable-redo-log

xe pool-disable-redo-log
<!--NeedCopy-->

Disable the redo log if in use, unless HA is enabled.

pool-dump-database

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

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

pool-enable-external-auth

xe pool-enable-external-auth  auth-type=auth_type service-name=service_name [uuid=uuid] [config:=config]
<!--NeedCopy-->

Enables external authentication in all the hosts in a pool. Note that some values of auth-type will require particular config: values.

pool-enable-local-storage-caching

xe pool-enable-local-storage-caching uuid=uuid
<!--NeedCopy-->

Enable local storage caching across the pool.

pool-enable-redo-log

xe pool-enable-redo-log sr-uuid=sr_uuid
<!--NeedCopy-->

Enable the redo log on the given SR if in use, unless HA is enabled.

pool-eject

xe pool-eject host-uuid=uuid_of_host_to_eject
<!--NeedCopy-->

Instruct the specified Citrix Hypervisor server to leave an existing pool.

pool-emergency-reset-master

xe pool-emergency-reset-master master-address=address_of_pool_master
<!--NeedCopy-->

Instruct a pool member server to reset its master server address to the new value and attempt to connect to it. Do not run this command on master servers.

pool-emergency-transition-to-master

xe pool-emergency-transition-to-master
<!--NeedCopy-->

Instruct a member Citrix Hypervisor server to become the pool master. The Citrix Hypervisor server accepts this command only after the host has transitioned to emergency mode. Emergency mode means it is a member of a pool whose master has disappeared from the network and cannot be contacted after some number of retries.

If the host password has been modified since the host joined the pool, this command can cause the password of the host to reset. For more information, see (User commands).

pool-ha-enable

xe pool-ha-enable heartbeat-sr-uuids=uuid_of_heartbeat_sr
<!--NeedCopy-->

Enable high availability on the resource pool, using the specified SR UUID as the central storage heartbeat repository.

pool-ha-disable

xe pool-ha-disable
<!--NeedCopy-->

Disables the high availability feature on the resource pool.

pool-ha-compute-hypothetical-max-host-failures-to-tolerate

Compute the maximum number of host failures to tolerate under the current pool configuration.

pool-ha-compute-max-host-failures-to-tolerate

xe pool-ha-compute-hypothetical-max-host-failures-to-tolerate [vm-uuid=vm_uuid] [restart-priority=restart_priority]
<!--NeedCopy-->

Compute the maximum number of host failures to tolerate with the supplied, proposed protected VMs.

pool-initialize-wlb

xe pool-initialize-wlb wlb_url=url wlb_username=wlb_username wlb_password=wlb_password xenserver_username=username xenserver_password=password
<!--NeedCopy-->

Initialize workload balancing for the current pool with the target Workload Balancing server.

pool-join

xe pool-join master-address=address master-username=username master-password=password
<!--NeedCopy-->

Instruct your Citrix Hypervisor server to join an existing pool.

pool-management-reconfigure

xe pool-management-reconfigure [network-uuid=network-uuid]
<!--NeedCopy-->

Reconfigures the management interface of all the hosts in the pool to use the specified network interface, which is the interface that is used to connect to the XenCenter. The command rewrites the MANAGEMENT_INTERFACE key in /etc/xensource-inventory for all the hosts in the pool.

If the device name of an interface (which must have an IP address) is specified, the Citrix Hypervisor master host immediately rebinds. This command works both in normal and emergency mode.

From the network UUID specified, UUID of the PIF object is identified and mapped to the Citrix Hypervisor server, which determines which IP address to rebind to itself. It must not be in emergency mode when this command is run.

Warning:

Be careful when using this CLI command off-host and ensure that you have network connectivity on the new interface. Use xe pif-reconfigure to set one up first. Otherwise, subsequent CLI commands are unable to reach the Citrix Hypervisor server.

pool-recover-slaves

xe pool-recover-slaves
<!--NeedCopy-->

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

pool-restore-database

xe pool-restore-database file-name=filename_to_restore_from_on_client [dry-run=true|false]
<!--NeedCopy-->

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

There is also a dry run option, which allows you to check that the pool database can be restored without actually perform the operation. By default, dry-run is set to false.

pool-retrieve-wlb-configuration

xe pool-retrieve-wlb-configuration
<!--NeedCopy-->

Retrieves the pool optimization criteria from the Workload Balancing server.

pool-retrieve-wlb-diagnostics

xe pool-retrieve-wlb-diagnostics [filename=file_name]
<!--NeedCopy-->

Retrieves diagnostics from the Workload Balancing server.

pool-retrieve-wlb-recommendations

xe pool-retrieve-wlb-recommendations
<!--NeedCopy-->

Retrieves VM migrate recommendations for the pool from the Workload Balancing server.

pool-retrieve-wlb-report

xe pool-retrieve-wlb-report report=report [filename=file_name]
<!--NeedCopy-->

Retrieves reports from the Workload Balancing server.

pool-secret-rotate

xe pool-secret-rotate
<!--NeedCopy-->

Rotate the pool secret.

The pool secret is a secret shared among the servers in a pool that enables the server to prove its membership to a pool. Users with the Pool Admin role can view this secret when connecting to the server over SSH. Rotate the pool secret if one of these users leaves your organization or loses their Pool Admin role.

pool-send-test-post

xe pool-send-test-post dest-host=destination_host dest-port=destination_port body=post_body
<!--NeedCopy-->

Send the given body to the given host and port, using HTTPS, and print the response. This is used for debugging the TLS layer.

pool-send-wlb-configuration

xe pool-send-wlb-configuration [config:=config]
<!--NeedCopy-->

Sets the pool optimization criteria for the Workload Balancing server.

pool-sync-database

xe pool-sync-database
<!--NeedCopy-->

Force the pool database to be synchronized across all hosts in the resource pool. This command is not necessary in normal operation since the database is regularly automatically replicated. However, the command can be useful for ensuring changes are rapidly replicated after performing a significant set of CLI operations.

igmp-snooping-enabled

xe pool-param-set [uuid=pool-uuid] [igmp-snooping-enabled=true|false]
<!--NeedCopy-->

Enables or disables IGMP snooping on a Citrix Hypervisor pool.

https-only

xe pool-param-set [uuid=pool-uuid] [https-only=true|false]
<!--NeedCopy-->

Enables or disables the blocking of port 80 on the management interface of Citrix Hypervisor hosts.

PVS Accelerator commands

Commands for working with the PVS Accelerator.

pvs-cache-storage-create

xe pvs-cache-storage-create sr-uuid=sr_uuid pvs-site-uuid=pvs_site_uuid size=size
<!--NeedCopy-->

Configure a PVS cache on a given SR for a given host.

pvs-cache-storage-destroy

xe pvs-cache-storage-destroy uuid=uuid
<!--NeedCopy-->

Remove a PVS cache.

pvs-proxy-create

xe pvs-proxy-create pvs-site-uuid=pvs_site_uuid vif-uuid=vif_uuid
<!--NeedCopy-->

Configure a VM/VIF to use a PVS proxy.

pvs-proxy-destroy

xe pvs-proxy-destroy uuid=uuid
<!--NeedCopy-->

Remove (or switch off) a PVS proxy for this VIF/VM.

pvs-server-forget

xe pvs-server-forget uuid=uuid
<!--NeedCopy-->

Forget a PVS server.

pvs-server-introduce

xe pvs-server-introduce addresses=adresses first-port=first_port last-port=last_port pvs-site-uuid=pvs_site_uuid
<!--NeedCopy-->

Introduce new PVS server.

pvs-site-forget

xe pvs-site-forget uuid=uuid
<!--NeedCopy-->

Forget a PVS site.

pvs-site-introduce

xe pvs-site-introduce name-label=name_label [name-description=name_description] [pvs-uuid=pvs_uuid]
<!--NeedCopy-->

Introduce new PVS site.

Storage Manager commands

Commands for controlling Storage Manager plug-ins.

The storage manager objects can be listed with the standard object listing command (xe sm-list). The parameters can be manipulated with the standard parameter commands. For more information, see Low-level parameter commands

SM parameters

SMs have the following parameters:

Snapshot commands

Commands for working with snapshots.

snapshot-clone

xe snapshot-clone new-name-label=name_label [uuid=uuid] [new-name-description=description]
<!--NeedCopy-->

Create a new template by cloning an existing snapshot, using storage-level fast disk clone operation where available.

snapshot-copy

xe snapshot-copy new-name-label=name_label [uuid=uuid] [new-name-description=name_description] [sr-uuid=sr_uuid]
<!--NeedCopy-->

Create a new template by copying 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’ - i.e. not part of a CoW chain.

snapshot-destroy

xe snapshot-destroy  [uuid=uuid] [snapshot-uuid=snapshot_uuid]
<!--NeedCopy-->

Destroy a snapshot. This leaves the storage associated with the snapshot intact. To delete storage too, use snapshot-uninstall.

snapshot-disk-list

xe snapshot-disk-list [uuid=uuid] [snapshot-uuid=snapshot_uuid] [vbd-params=vbd_params] [vdi-params=vdi_params]
<!--NeedCopy-->

List the disks on the selected VM(s).

snapshot-export-to-template

xe snapshot-export-to-template filename=file_name snapshot-uuid=snapshot_uuid  [preserve-power-state=true|false]
<!--NeedCopy-->

Export a snapshot to file name.

snapshot-reset-powerstate

xe snapshot-reset-powerstate [uuid=uuid] [snapshot-uuid=snapshot_uuid] [--force]
<!--NeedCopy-->

Force the VM power state to halted in the management toolstack database only. This command is used to recover a snapshot that is marked as ‘suspended’. This is a potentially dangerous operation: you must ensure that you do not need the memory image anymore. You will not be able to resume your snapshot anymore.

snapshot-revert

xe snapshot-revert [uuid=uuid] [snapshot-uuid=snapshot_uuid]
<!--NeedCopy-->

Revert an existing VM to a previous checkpointed or snapshot state.

snapshot-uninstall

xe snapshot-uninstall [uuid=uuid] [snapshot-uuid=snapshot_uuid] [--force]
<!--NeedCopy-->

Uninstall a snapshot. This operation will destroy those VDIs that are marked RW and connected to this snapshot only. To simply destroy the VM record, use snapshot-destroy.

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. For more information, see Low-level parameter commands

SR parameters

SRs have the following parameters:

sr-create

xe sr-create name-label=name physical-size=size type=type content-type=content_type device-config:config_name=value [host-uuid=host_uuid] [shared=true|false]
<!--NeedCopy-->

Creates an SR on the disk, introduces it into the database, and creates a PBD attaching the SR to the Citrix Hypervisor server. If shared is set to true, a PBD is created for each Citrix Hypervisor server in the pool. If shared is not specified or set to false, a PBD is created only for the Citrix Hypervisor server specified with host-uuid.

The exact device-config parameters differ depending on the device type. For details of these parameters across the different storage back-ends, see Create an SR.

sr-data-source-forget

xe sr-data-source-forget data-source=data_source
<!--NeedCopy-->

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

sr-data-source-list

xe sr-data-source-list
<!--NeedCopy-->

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

sr-data-source-query

xe sr-data-source-query data-source=data_source
<!--NeedCopy-->

Query the last value read from a SR data source.

sr-data-source-record

xe sr-data-source-record  data-source=data_source
<!--NeedCopy-->

Record the specified data source for a SR.

sr-destroy

xe sr-destroy uuid=sr_uuid
<!--NeedCopy-->

Destroys the specified SR on the Citrix Hypervisor server.

sr-enable-database-replication

xe sr-enable-database-replication uuid=sr_uuid
<!--NeedCopy-->

Enables XAPI database replication to the specified (shared) SR.

sr-disable-database-replication

xe sr-disable-database-replication uuid=sr_uuid
<!--NeedCopy-->

Disables XAPI database replication to the specified SR.

sr-forget

xe sr-forget uuid=sr_uuid
<!--NeedCopy-->

The XAPI agent forgets about a specified SR on the Citrix Hypervisor server. When the XAPI agent forgets an SR, the SR is detached and you cannot access VDIs on it, but it remains intact on the source media (the data is not lost).

sr-introduce

xe sr-introduce name-label=name physical-size=physical_size type=type content-type=content_type uuid=sr_uuid
<!--NeedCopy-->

Just places an SR record into the database. Use device-config to specify additional parameters in the form device-config:parameter_key=parameter_value, for example:

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

Note:

This command is never used in normal operation. This advanced operation might be useful when an SR must be reconfigured as shared after it was created or to help recover from various failure scenarios.

sr-probe

xe sr-probe type=type [host-uuid=host_uuid] [device-config:config_name=value]
<!--NeedCopy-->

Performs a scan of the backend, using the provided device-config keys. If the device-config is complete for the SR back-end, this command returns a list of the SRs present on the device, if any. If the device-config parameters are only partial, a back-end-specific scan is performed, returning results that guide you in improving the remaining device-config parameters. The scan results are returned as XML specific to the back end, printed on the CLI.

The exact device-config parameters differ depending on the device type. For details of these parameters across the different storage back-ends, see Storage.

sr-probe-ext

xe sr-probe-ext type=type [host-uuid=host_uuid] [device-config:=config] [sm-config:-sm_config]
<!--NeedCopy-->

Perform a storage probe. The device-config parameters can be specified by for example device-config:devs=/dev/sdb1. Unlike sr-probe, this command returns results in the same human-readable format for every SR type.

sr-scan

xe sr-scan uuid=sr_uuid
<!--NeedCopy-->

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

sr-update

xe sr-update uuid=uuid
<!--NeedCopy-->

Refresh the fields of the SR object in the database.

lvhd-enable-thin-provisioning

xe lvhd-enable-thin-provisioning  sr-uuid=sr_uuid initial-allocation=initial_allocation allocation-quantum=allocation_quantum
<!--NeedCopy-->

Enable thin-provisioning on an LVHD SR.

Subject commands

Commands for working with subjects.

session-subject-identifier-list

xe session-subject-identifier-list
<!--NeedCopy-->

Return a list of all the user subject ids of all externally-authenticated existing sessions.

session-subject-identifier-logout

xe session-subject-identifier-logout subject-identifier=subject_identifier
<!--NeedCopy-->

Log out all externally-authenticated sessions associated to a user subject id.

session-subject-identifier-logout-all

xe session-subject-identifier-logout-all
<!--NeedCopy-->

Log out all externally-authenticated sessions.

subject-add

xe subject-add subject-name=subject_name
<!--NeedCopy-->

Add a subject to the list of subjects that can access the pool.

subject-remove

xe subject-remove subject-uuid=subject_uuid
<!--NeedCopy-->

Remove a subject from the list of subjects that can access the pool.

subject-role-add

xe subject-role-add uuid=uuid [role-name=role_name] [role-uuid=role_uuid]
<!--NeedCopy-->

Add a role to a subject.

subject-role-remove

xe subject-role-remove uuid=uuid [role-name=role_name] [role-uuid=role_uuid]
<!--NeedCopy-->

Remove a role from a subject.

secret-create

xe secret-create value=value
<!--NeedCopy-->

Create a secret.

secret-destroy

xe secret-destroy uuid=uuid
<!--NeedCopy-->

Destroy a secret.

Task commands

Commands for working with long-running asynchronous tasks. These commands are tasks such as starting, stopping, and suspending a virtual machine. The tasks 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. For more information, see Low-level parameter commands

Task parameters

Tasks have the following parameters:

task-cancel

xe task-cancel [uuid=task_uuid]
<!--NeedCopy-->

Direct the specified Task to cancel and return.

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. Citrix Hypervisor ships with a base set of templates, which are generic “raw” VMs that can boot an OS vendor installation CD (for example: RHEL, CentOS, SLES, Windows). You can create VMs, configure them in standard forms for your particular needs, and save a copy of them as templates for future use in VM deployment.

The template objects can be listed with the standard object listing command (xe template-list), and the parameters manipulated with the standard parameter commands. For more information, see Low-level parameter commands

Note:

Templates cannot be directly converted into VMs by setting the is-a-template parameter to false. Setting is-a-template parameter to false is not supported and results in a VM that cannot be started.

VM template parameters

Templates have the following parameters:

• uuid (read only) the unique identifier/object reference for the template
• name-label (read/write) the name of the template
• name-description (read/write) the description string of the template
• user-version (read/write) string for creators of VMs and templates to put version information

• is-a-template (read/write) true if this VM is a template. Template VMs can never be started, they are used only for cloning other VMs. After this value has been set to true, it cannot be reset to false. Template VMs cannot be converted into VMs using this parameter.

  You can convert a VM to a template with:

   xe vm-param-set uuid=<vm uuid> is-a-template=true
   <!--NeedCopy-->
  

• is-control-domain (read only) true if this is a control domain (domain 0 or a driver domain)
• power-state (read only) current power state. The value is always halted for a template
• memory-dynamic-max (read only) dynamic maximum memory in bytes. Currently unused, but if changed the following constraint must be obeyed: memory_static_max >= memory_dynamic_max >= memory_dynamic_min >= memory_static_min.
• memory-dynamic-min (read/write) dynamic minimum memory in bytes. Currently unused, but if changed the same constraints for memory-dynamic-max must be obeyed.
• memory-static-max (read/write) statically set (absolute) maximum memory in bytes. This field is the main value used to determine the amount of memory assigned to a VM.
• memory-static-min (read/write) statically set (absolute) minimum memory in bytes. This field represents the absolute minimum memory, and memory-static-min must be less than memory-static-max. This value is unused in normal operation, but the previous constraint must be obeyed.
• suspend-VDI-uuid (read only) the VDI that a suspend image is stored on (has no meaning for a template)

• VCPUs-params (read/write map parameter) configuration parameters for the selected vCPU policy.

  You can tune a vCPU’s pinning with:

   xe template-param-set uuid=<template_uuid> vCPUs-params:mask=1,2,3
   <!--NeedCopy-->
  

  A VM created from this template 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 template-param-set uuid=<template_uuid> VCPUs-params:weight=512 xe template-param-set uuid=<template_uuid> VCPUs-params:cap=100
   <!--NeedCopy-->
  

  A VM based on this template with a weight of 512 get twice as much CPU as a domain with a weight of 256 on a contended host. Legal weights range from 1 to 65535 and the default is 256.

  The cap optionally fixes the maximum amount of CPU a VM based on this template can consume, even if the Citrix Hypervisor server has idle CPU cycles. The cap is expressed in percentage of one physical CPU: 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, and so on The default, 0, means that there is no upper cap.

• VCPUs-max (read/write) maximum number of vCPUs
• VCPUs-at-startup (read/write) boot number of vCPUs
• actions-after-crash (read/write) action to take when a VM based on this template crashes
• console-uuids (read only set parameter) virtual console devices

• platform (read/write map parameter) platform specific configuration

  To disable the emulation of a parallel port for HVM guests (for example, Windows guests):

   xe vm-param-set uuid=<vm_uuid> platform:parallel=none
   <!--NeedCopy-->
  

  To disable the emulation of a serial port for HVM guests:

   xe vm-param-set uuid=<vm_uuid> platform:hvm_serial=none
   <!--NeedCopy-->
  

  To disable the emulation of a USB controller and a USB tablet device for HVM guests:

   xe vm-param-set uuid=<vm_uuid> platform:usb=false
   xe vm-param-set uuid=<vm_uuid> platform:usb_tablet=false
   <!--NeedCopy-->
  

• allowed-operations (read only set parameter) list of the operations allowed in this state
• current-operations (read only set parameter) list of the operations that are currently in progress on this template
• allowed-VBD-devices (read only set parameter) 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).
• allowed-VIF-devices (read only set parameter) 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).
• HVM-boot-policy (read/write) the boot policy for HVM guests. Either BIOS Order or an empty string.
• HVM-boot-params (read/write map parameter) 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.
• PV-kernel (read/write) path to the kernel
• PV-ramdisk (read/write) path to the initrd
• PV-args (read/write) string of kernel command line arguments
• PV-legacy-args (read/write) string of arguments to make legacy VMs based on this template boot
• PV-bootloader (read/write) name of or path to bootloader
• PV-bootloader-args (read/write) string of miscellaneous arguments for the bootloader
• last-boot-CPU-flags (read only) describes the CPU flags on which a VM based on this template was last booted; not populated for a template
• resident-on (read only) the Citrix Hypervisor server on which a VM based on this template is resident. Appears as not in database for a template
• affinity (read/write) the Citrix Hypervisor server 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
• other-config (read/write map parameter) list of key/value pairs that specify extra configuration parameters for the template
• start-time (read only) timestamp of the date and time that the metrics for a VM based on this template were read, in the form yyyymmddThh:mm:ss z, where z is the single-letter military timezone indicator, for example, Z for UTC(GMT). Set to 1 Jan 1970 Z (beginning of Unix/POSIX epoch) for a template
• install-time (read only) timestamp of the date and time that the metrics for a VM based on this template were read, in the form yyyymmddThh:mm:ss z, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT). Set to 1 Jan 1970 Z (beginning of Unix/POSIX epoch) for a template
• memory-actual (read only) the actual memory being used by a VM based on this template; 0 for a template
• VCPUs-number (read only) the number of virtual CPUs assigned to a VM based on this template; 0 for a template
• VCPUs-Utilization (read only map parameter) list of virtual CPUs and their weight read only map parameter os-version the version of the operating system for a VM based on this template. Appears as not in database for a template
• PV-drivers-version (read only map parameter) the versions of the paravirtualized drivers for a VM based on this template. Appears as not in database for a template
• PV-drivers-detected (read only) flag for latest version of the paravirtualized drivers for a VM based on this template. Appears as not in database for a template
• memory (read only map parameter) memory metrics reported by the agent on a VM based on this template. Appears as not in database for a template
• disks (read only map parameter) disk metrics reported by the agent on a VM based on this template. Appears as not in database for a template
• networks (read only map parameter) network metrics reported by the agent on a VM based on this template. Appears as not in database for a template
• other (read only map parameter) other metrics reported by the agent on a VM based on this template. Appears as not in database for a template
• guest-metrics-last-updated (read only) timestamp when the in-guest agent performed the last write to these fields. In the form yyyymmddThh:mm:ss z, where z is the single-letter military timezone indicator, for example, Z for UTC (GMT)
• actions-after-shutdown (read/write) action to take after the VM has shutdown
• actions-after-reboot (read/write) action to take after the VM has rebooted
• possible-hosts (read only) list of hosts that can potentially host the VM
• HVM-shadow-multiplier (read/write) multiplier applied to the amount of shadow that is made available to the guest
• dom-id (read only) domain ID (if available, -1 otherwise)
• recommendations (read only) XML specification of recommended values and ranges for properties of this VM
• xenstore-data (read/write map parameter) data to be inserted into the xenstore tree (/local/domain/*domid*/vmdata) after the VM is created.
• is-a-snapshot (read only) True if this template is a VM snapshot
• snapshot_of (read only) the UUID of the VM that this template is a snapshot of
• snapshots (read only) the UUIDs of any snapshots that have been taken of this template
• snapshot_time (read only) the timestamp of the most recent VM snapshot taken
• memory-target (read only) the target amount of memory set for this template
• blocked-operations (read/write map parameter) lists the operations that cannot be performed on this template
• last-boot-record (read only) record of the last boot parameters for this template, in XML format
• ha-always-run (read/write) True if an instance of this template is always restarted on another host if there is a failure of the host it is resident on. This parameter is now deprecated. Use the ha-restartpriority parameter instead.
• ha-restart-priority (read only) restart or best-effort read/write blobs binary data store
• live (read only) relevant only to a running VM.

template-export

xe template-export template-uuid=uuid_of_existing_template filename=filename_for_new_template
<!--NeedCopy-->

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

template-uninstall

xe template-uninstall template-uuid=template_uuid [--force]
<!--NeedCopy-->

Uninstall a custom template. This operation will destroy those VDIs that are marked as ‘owned’ by this template.

Update commands

The following section contains Citrix Hypervisor server update commands.

The update objects can be listed with the standard object listing command (xe update-list), and the parameters manipulated with the standard parameter commands. For more information, see Low-level parameter commands

Update parameters

Citrix Hypervisor server updates have the following parameters:

update-upload

xe update-upload file-name=update_filename
<!--NeedCopy-->

Upload a specified update file to the Citrix Hypervisor server. This command prepares an update to be applied. On success, the UUID of the uploaded update is printed. If the update has previously been uploaded, UPDATE_ALREADY_EXISTS error is returned instead and the patch is not uploaded again.

update-precheck

xe update-precheck uuid=update_uuid host-uuid=host_uuid
<!--NeedCopy-->

Run the prechecks contained within the specified update on the specified Citrix Hypervisor server.

update-destroy

xe update-destroy uuid=update_file_uuid
<!--NeedCopy-->

Deletes an update file that has not been applied from the pool. Can be used to delete an update file that cannot be applied to the hosts.

update-apply

xe update-apply host-uuid=host_uuid uuid=update_file_uuid
<!--NeedCopy-->

Apply the specified update file.

update-pool-apply

xe update-pool-apply uuid=update_uuid
<!--NeedCopy-->

Apply the specified update to all Citrix Hypervisor servers in the pool.

update-introduce

xe update-introduce vdi-uuid=vdi_uuid
<!--NeedCopy-->

Introduce update VDI.

update-pool-clean

xe update-pool-clean uuid=uuid
<!--NeedCopy-->

Removes the update’s files from all hosts in the pool.

User commands

user-password-change

xe user-password-change old=old_password new=new_password
<!--NeedCopy-->

Changes the password of the logged-in user. The old password field is not checked because you require supervisor privilege to use this command.

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). The VDI has the information on the physical attributes of the virtual disk (which type of SR, whether the disk is sharable, 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. For more information, see Low-level parameter commands

VBD parameters

VBDs have the following parameters:

vbd-create

xe vbd-create vm-uuid=uuid_of_the_vm device=device_value vdi-uuid=uuid_of_vdi_to_connect_to [bootable=true] [type=Disk|CD] [mode=RW|RO]
<!--NeedCopy-->

Create a VBD on a VM.

The allowable values for the device field are integers 0–15, and the number must be unique for each VM. The current allowable values can be seen in the allowed-VBD-devices parameter on the specified VM. This is seen as userdevice in the vbd parameters.

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 is created for the CD. Mode must be RO for a CD.

vbd-destroy

xe vbd-destroy uuid=uuid_of_vbd
<!--NeedCopy-->

Destroy the specified VBD.

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

vbd-eject

xe vbd-eject uuid=uuid_of_vbd
<!--NeedCopy-->

Remove the media from the drive represented by a VBD. This command only works if the media is of a removable type (a physical CD or an ISO). Otherwise, an error message VBD_NOT_REMOVABLE_MEDIA is returned.

vbd-insert

xe vbd-insert uuid=uuid_of_vbd vdi-uuid=uuid_of_vdi_containing_media
<!--NeedCopy-->

Insert new media into the drive represented by a VBD. This command only works if the media is of a removable type (a physical CD or an ISO). Otherwise, an error message VBD_NOT_REMOVABLE_MEDIA is returned.

vbd-plug

xe vbd-plug uuid=uuid_of_vbd
<!--NeedCopy-->

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

vbd-unplug

xe vbd-unplug uuid=uuid_of_vbd
<!--NeedCopy-->

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

VDI commands

Commands for working with VDIs (Virtual Disk Images).

A VDI is a software object that represents the contents of the virtual disk seen by a VM. This is different to the VBD, which is an 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 sharable, whether the media is read/write or read only, and so on). The VBD has the attributes that 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. For more information, see Low-level parameter commands

VDI parameters

VDIs have the following parameters:

vdi-clone

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

Create a new, writable copy of the specified VDI that can be used directly. It is a variant of vdi-copy that is can expose high-speed image clone facilities where they exist.

Use the optional driver-params map parameter to pass extra vendor-specific configuration information to the back-end storage driver that the VDI is based on. For more information, see the storage vendor driver documentation.

vdi-copy

xe vdi-copy uuid=uuid_of_the_vdi sr-uuid=uuid_of_the_destination_sr
<!--NeedCopy-->

Copy a VDI to a specified SR.

vdi-create

xe vdi-create sr-uuid=uuid_of_sr_to_create_vdi_on name-label=name_for_the_vdi type=system|user|suspend|crashdump virtual-size=size_of_virtual_disk sm-config-\*=storage_specific_configuration_data
<!--NeedCopy-->

Create a VDI.

The virtual-size parameter can be specified in bytes or using the IEC standard suffixes KiB, MiB, GiB, and TiB.

Note:

SR types that support thin provisioning of disks (such as Local VHD and NFS) do not enforce virtual allocation of disks. Take great care when over-allocating virtual disk space on an SR. If an over-allocated SR becomes full, disk space must be made available either on the SR target substrate or by deleting unused VDIs in the SR.

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

vdi-data-destroy

xe vdi-data-destroy uuid=uuid_of_vdi
<!--NeedCopy-->

Destroy the data associated with the specified VDI, but keep the changed block tracking metadata.

Note:

If you use changed block tracking to take incremental backups of the VDI, ensure that you use the vdi-data-destroy command to delete snapshots but keep the metadata. Do not use vdi-destroy on snapshots of VDIs that have changed block tracking enabled.

vdi-destroy

xe vdi-destroy uuid=uuid_of_vdi
<!--NeedCopy-->

Destroy the specified VDI.

Note:

If you use changed block tracking to take incremental backups of the VDI, ensure that you use the vdi-data-destroy command to delete snapshots but keep the metadata. Do not use vdi-destroy on snapshots of VDIs that have changed block tracking enabled.

For Local VHD and NFS SR types, disk space is not immediately released on vdi-destroy, but periodically during a storage repository scan operation. If you must force deleted disk space to be made available, call sr-scan manually.

vdi-disable-cbt

xe vdi-disable-cbt uuid=uuid_of_vdi
<!--NeedCopy-->

Disable changed block tracking for the VDI.

vdi-enable-cbt

xe vdi-enable-cbt uuid=uuid_of_vdi
<!--NeedCopy-->

Enable changed block tracking for the VDI.

Note:

You can enable changed block tracking only on licensed instances of Citrix Hypervisor Premium Edition.

vdi-export

xe vdi-export uuid=uuid_of_vdi filename=filename_to_export_to [format=format] [base=uuid_of_base_vdi] [--progress]
<!--NeedCopy-->

Export a VDI to the specified file name. You can export a VDI in one of the following formats:

• raw
• vhd

The VHD format can be sparse. If there are unallocated blocks within the VDI, these blocks might be omitted from the VHD file, therefore making the VHD file smaller. You can export to VHD format from all supported VHD-based storage types (EXT3/EXT4, NFS).

If you specify the base parameter, this command exports only those blocks that have changed between the exported VDI and the base VDI.

vdi-forget

xe vdi-forget uuid=uuid_of_vdi
<!--NeedCopy-->

Unconditionally removes a VDI record from the database without touching the storage back-end. In normal operation, use vdi-destroy instead.

vdi-import

xe vdi-import uuid=uuid_of_vdi filename=filename_to_import_from [format=format] [--progress]
<!--NeedCopy-->

Import a VDI. You can import a VDI from one of the following formats:

• raw
• vhd

vdi-introduce

xe vdi-introduce uuid=uuid_of_vdi sr-uuid=uuid_of_sr name-label=name_of_new_vdi type=system|user|suspend|crashdump location=device_location_(varies_by_storage_type) [name-description=description_of_vdi] [sharable=yes|no] [read-only=yes|no] [other-config=map_to_store_misc_user_specific_data] [xenstore-data=map_to_of_additional_xenstore_keys] [sm-config=storage_specific_configuration_data]
<!--NeedCopy-->

Create a VDI object representing an existing storage device, without actually modifying or creating any storage. This command is primarily used internally to introduce hot-plugged storage devices automatically.

vdi-list-changed-blocks

xe vdi-list-changed-blocks vdi-from-uuid=first-vdi-uuid vdi-to-uuid=second-vdi-uuid
<!--NeedCopy-->

Compare two VDIs and return the list of blocks that have changed between the two as a base64-encoded string. This command works only for VDIs that have changed block tracking enabled.

For more information, see Changed block tracking.

vdi-pool-migrate

xe vdi-pool-migrate uuid=VDI_uuid sr-uuid=destination-sr-uuid
<!--NeedCopy-->

Migrate a VDI to a specified SR, while the VDI is attached to a running guest. (Storage live migration)

For more information, see Migrate VMs.

vdi-resize

xe vdi-resize uuid=vdi_uuid disk-size=new_size_for_disk
<!--NeedCopy-->

Change the size of the VDI specified by UUID.

vdi-snapshot

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

Produces a read-write version of a VDI that can be used as a reference for backup or template creation purposes or both. Use the snapshot to perform a backup rather than installing and running backup software inside the VM. The VM continues running while external backup software streams the contents of the snapshot to the backup media. Similarly, a snapshot can be used as a “gold image” on which to base a template. A template can be made using any VDIs.

Use the optional driver-params map parameter to pass extra vendor-specific configuration information to the back-end storage driver that the VDI is based on. For more information, see the storage vendor driver documentation.

A clone of a snapshot always produces a writable VDI.

vdi-unlock

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

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

vdi-update

xe vdi-update uuid=uuid
<!--NeedCopy-->

Refresh the fields of the VDI object in the database.

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. For more information, see Low-level parameter commands

VIF parameters

VIFs have the following parameters:

• uuid (read only) the unique identifier/object reference for the VIF
• vm-uuid (read only) the unique identifier/object reference for the VM that this VIF resides on
• vm-name-label (read only) the name of the VM that this VIF resides on
• allowed-operations (read only set parameter) a list of the operations allowed in this state
• current-operations (read only set parameter) a list of the operations that are currently in progress on this VIF
• device (read only) integer label of this VIF, indicating the order in which VIF back-ends were created
• MAC (read only) MAC address of VIF, as exposed to the VM

• MTU (read only) Maximum Transmission Unit of the VIF in bytes.

  This parameter is read-only, but you can override the MTU setting with the mtu key using the other-config map parameter. For example, to reset the MTU on a virtual NIC to use jumbo frames:

   xe vif-param-set \
       uuid=<vif_uuid> \
       other-config:mtu=9000
   <!--NeedCopy-->
  

• currently-attached (read only) true if the device is attached
• qos_algorithm_type (read/write) QoS algorithm to use
• qos_algorithm_params (read/write map parameter) parameters for the chosen QoS algorithm
• qos_supported_algorithms (read only set parameter) supported QoS algorithms for this VIF
• MAC-autogenerated (read only) True if the MAC address of the VIF was automatically generated
• other-config (read/write map parameter) extra configuration key:value pairs
• other-config:ethtoolrx (read/write) set to on to enable receive checksum, off to disable
• other-config:ethtooltx (read/write) set to on to enable transmit checksum, off to disable
• other-config:ethtoolsg (read/write) set to on to enable scatter gather, off to disable
• other-config:ethtooltso (read/write) set to on to enable TCP segmentation offload, off to disable
• other-config:ethtoolufo (read/write) set to on to enable UDP fragment offload, off to disable
• other-config:ethtoolgso (read/write) set to on to enable generic segmentation offload, off to disable
• other-config:promiscuous (read/write) true to a VIF to be promiscuous on the bridge, so that it sees all traffic over the bridge. Useful for running an Intrusion Detection System (IDS) or similar in a VM.
• network-uuid (read only) the unique identifier/object reference of the virtual network to which this VIF is connected
• network-name-label (read only) the descriptive name of the virtual network to which this VIF is connected
• io_read_kbs (read only) average read rate in kB/s for this VIF
• io_write_kbs (read only) average write rate in kB/s for this VIF
• locking_mode (read/write) Affects the VIFs ability to filter traffic to/from a list of MAC and IP addresses. Requires extra parameters.

• locking_mode:default (read/write) Varies according to the default locking mode for the VIF network.

  If the default-locking-mode is set to disabled, Citrix Hypervisor applies a filtering rule so that the VIF cannot send or receive traffic. If the default-lockingmode is set to unlocked, Citrix Hypervisor removes all the filtering rules associated with the VIF. For more information, see Network Commands.

• locking_mode:locked (read/write) Only traffic sent to or sent from the specified MAC and IP addresses is allowed on the VIF. If no IP addresses are specified, no traffic is allowed.
• locking_mode:unlocked (read/write) No filters are applied to any traffic going to or from the VIF.
• locking_mode:disabled (read/write) Citrix Hypervisor applies a filtering rule is applied so that the VIF drops all traffic.

vif-create

xe vif-create vm-uuid=uuid_of_the_vm device=see below network-uuid=uuid_of_network_to_connect_to [mac=mac_address]
<!--NeedCopy-->

Create a VIF on a VM.

Appropriate values for the device field are listed in the parameter allowed-VIF-devices on the specified VM. Before any VIFs exist there, the values allowed are integers from 0-15.

The mac parameter is the standard MAC address in the form aa:bb:cc:dd:ee:ff. If you leave it unspecified, an appropriate random MAC address is created. You can also explicitly set a random MAC address by specifying mac=random.

vif-destroy

xe vif-destroy uuid=uuid_of_vif
<!--NeedCopy-->

Destroy a VIF.

vif-move

xe vif-move uuid=uuid network-uuid=network_uuid
<!--NeedCopy-->

Move the VIF to another network.

vif-plug

xe vif-plug uuid=uuid_of_vif
<!--NeedCopy-->

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

vif-unplug

xe vif-unplug uuid=uuid_of_vif
<!--NeedCopy-->

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

vif-configure-ipv4

Configure IPv4 settings for this virtual interface. Set IPv4 settings as below:

xe vif-configure-ipv4 uuid=uuid_of_vif mode=static address=CIDR_address gateway=gateway_address
<!--NeedCopy-->

For example:

VIF.configure_ipv4(vifObject,"static", " 192.168.1.10/24", " 192.168.1.1")
<!--NeedCopy-->

Clean IPv4 settings as below:

xe vif-configure-ipv4 uuid=uuid_of_vif mode=none
<!--NeedCopy-->

vif-configure-ipv6

Configure IPv6 settings for this virtual interface. Set IPv6 settings as below:

xe vif-configure-ipv6 uuid=uuid_of_vif mode=static address=IP_address gateway=gateway_address
<!--NeedCopy-->

For example:

VIF.configure_ipv6(vifObject,"static", "fd06:7768:b9e5:8b00::5001/64", "fd06:7768:b9e5:8b00::1")
<!--NeedCopy-->

Clean IPv6 settings as below:

xe vif-configure-ipv6 uuid=uuid_of_vif mode=none
<!--NeedCopy-->

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. For more information, see PIF commands. For example, to list VLANs, use xe pif-list.

vlan-create

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

Create a VLAN on your Citrix Hypervisor server.

pool-vlan-create

xe pool-vlan-create pif-uuid=uuid_of_pif vlan=vlan_number network-uuid=uuid_of_network
<!--NeedCopy-->

Create a VLAN on all hosts on a pool, by determining which interface (for example, eth0) the specified network is on (on each host) and creating and plugging a new PIF object one each host accordingly.

vlan-destroy

xe vlan-destroy uuid=uuid_of_pif_mapped_to_vlan
<!--NeedCopy-->

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

VM commands

Commands for controlling VMs and their attributes.

VM selectors

Several of the commands listed here have a common mechanism for selecting one or more VMs on which to perform the operation. The simplest way is by supplying the argument vm=name_or_uuid. An easy way to get the uuid of an actual VM is to, for example, run xe vm-list power-state=running. (Get the full list of fields that can be matched by using the command xe vm-list params=all. ) For example, specifying power-state=halted selects VMs whose power-state parameter is equal to halted. Where multiple VMs are matching, specify the option --multiple to perform the operation. The full list of parameters that can be matched is described at the beginning of this section.

The VM objects can be listed with the standard object listing command (xe vm-list), and the parameters manipulated with the standard parameter commands. For more information, see Low-level parameter commands

VM parameters

VMs have the following parameters:

Note:

All writable VM parameter values can be changed while the VM is running, but new parameters are not applied dynamically and cannot be applied until the VM is rebooted.

• appliance (read/write) the appliance/vApp to which the VM belongs
• uuid (read only) the unique identifier/object reference for the VM
• name-label (read/write) the name of the VM
• name-description (read/write) the description string of the VM
• order (read/write) for vApp startup/shutdown and for startup after HA failover. VMs with an order value of 0 (zero) are started first, then VMs with an order value of 1, and so on.
• version (read only) the number of times this VM has been recovered. If you want to overwrite a new VM with an older version, call vm-recover
• user-version (read/write) string for creators of VMs and templates to put version information

• is-a-template (read/write) False unless this VM is a template. Template VMs can never be started, they are used only for cloning other VMs After this value has been set to true it cannot be reset to false. Template VMs cannot be converted into VMs using this parameter.

  You can convert a VM to a template with:

   xe vm-param-set uuid=<vm uuid> is-a-template=true
   <!--NeedCopy-->
  

• is-control-domain (read only) True if this is a control domain (domain 0 or a driver domain)
• power-state (read only) current power state
• start-delay (read/write) the delay to wait before a call to start up the VM returns in seconds
• shutdown-delay (read/write) the delay to wait before a call to shut down the VM returns in seconds
• memory-dynamic-max (read/write) dynamic maximum in bytes
• memory-dynamic-min (read/write) dynamic minimum in bytes
• memory-static-max (read/write) statically set (absolute) maximum in bytes. If you want to change this value, the VM must be shut down.
• memory-static-min (read/write) statically set (absolute) minimum in bytes. If you want to change this value, the VM must be shut down.
• suspend-VDI-uuid (read only) the VDI that a suspend image is stored on

• VCPUs-params (read/write map parameter) 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
   <!--NeedCopy-->
  

  The selected VM then runs on physical CPUs 1, 2, and 3 only. You can also tune the vCPU priority (xen scheduling) with the cap and weight parameters. For example:

   xe vm-param-set uuid=<vm_uuid> VCPUs-params:weight=512 xe vm-param-set uuid=<vm_uuid> VCPUs-params:cap=100
   <!--NeedCopy-->
  

  A VM with a weight of 512 get twice as much CPU as a domain with a weight of 256 on a contended Citrix Hypervisor server. Legal weights range from 1 to 65535 and the default is 256. The cap optionally fixes the maximum amount of CPU a VM will be able to consume, even if the Citrix Hypervisor server has idle CPU cycles. The cap is expressed in percentage of one physical CPU: 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, and so on The default, 0, means that there is no upper cap.

• VCPUs-max (read/write) maximum number of virtual CPUs.
• VCPUs-at-startup (read/write) boot number of virtual CPUs
• actions-after-crash (read/write) action to take if the VM crashes. For PV guests, valid parameters are:
  • preserve (for analysis only)
  • coredump_and_restart (record a coredump and reboot VM)
  • coredump_and_destroy (record a coredump and leave VM halted)
  • restart (no coredump and restart VM)
  • destroy (no coredump and leave VM halted)
• console-uuids (read only set parameter) virtual console devices

• platform (read/write map parameter) platform-specific configuration

  To disable VDA to switch Windows 10 into Tablet mode:

   xe vm-param-set uuid=<vm_uuid> platform:acpi_laptop_slate=0
   <!--NeedCopy-->
  

  To enable VDA to switch Windows 10 into Tablet mode:

   xe vm-param-set uuid=<vm_uuid> platform:acpi_laptop_slate=1
   <!--NeedCopy-->
  

  To check current state:

   xe vm-param-get uuid=<vm_uuid> param-name=platform param-key=acpi_laptop_slate
   <!--NeedCopy-->
  

• allowed-operations (read only set parameter) list of the operations allowed in this state
• current-operations (read only set parameter) a list of the operations that are currently in progress on the VM
• allowed-VBD-devices (read only set parameter) 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 might not work).
• allowed-VIF-devices (read only set parameter) 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 might not work).
• HVM-boot-policy (read/write) the boot policy for HVM guests. Either BIOS Order or an empty string.
• HVM-boot-params (read/write map parameter) 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.
• HVM-shadow-multiplier (read/write) Floating point value which controls the amount of shadow memory overhead to grant the VM. Defaults to 1.0 (the minimum value), and only change this value if you are an advanced user.
• PV-kernel (read/write) path to the kernel
• PV-ramdisk (read/write) path to the initrd
• PV-args (read/write) string of kernel command line arguments
• PV-legacy-args (read/write) string of arguments to make legacy VMs boot
• PV-bootloader (read/write) name of or path to bootloader
• PV-bootloader-args (read/write) string of miscellaneous arguments for the bootloader
• last-boot-CPU-flags (read only) describes the CPU flags on which the VM was last booted
• resident-on (read only) the Citrix Hypervisor server on which a VM is resident
• affinity (read/write) The Citrix Hypervisor server which the VM has preference for running on. Used by the xe vm-start command to decide where to run the VM

• other-config (read/write map parameter) A list of key/value pairs that specify extra configuration parameters for the VM.

  For example, the other-config key/value pair auto_poweron: true requests to start the VM automatically after any host in the pool boots. You must also set this parameter in your pool’s other-config. These parameters are now deprecated. Use the ha-restart-priority parameter instead.

• start-time (read only) timestamp of the date and time that the metrics for the VM were read. This timestamp is in the form yyyymmddThh:mm:ss z, where z is the single letter military timezone indicator, for example, Z for UTC (GMT)
• install-time (read only) timestamp of the date and time that the metrics for the VM were read. This timestamp is in the form yyyymmddThh:mm:ss z, where z is the single letter military timezone indicator, for example, Z for UTC (GMT)
• memory-actual (read only) the actual memory being used by a VM
• VCPUs-number (read only) the number of virtual CPUs assigned to the VM for a Linux VM. This number can differ from VCPUS-max and can be changed without rebooting the VM using the vm-vcpu-hotplug command. For more information, see vm-vcpu-hotplug. Windows VMs always run with the number of vCPUs set to VCPUsmax and must be rebooted to change this value. Performance drops sharply when you set VCPUs-number to a value greater than the number of physical CPUs on the Citrix Hypervisor server.
• VCPUs-Utilization (read only map parameter) a list of virtual CPUs and their weight
• os-version (read only map parameter) the version of the operating system for the VM
• PV-drivers-version (read only map parameter) the versions of the paravirtualized drivers for the VM
• PV-drivers-detected (read only) flag for latest version of the paravirtualized drivers for the VM
• memory (read only map parameter) memory metrics reported by the agent on the VM
• disks (read only map parameter) disk metrics reported by the agent on the VM
• networks (read only map parameter) network metrics reported by the agent on the VM
• other (read only map parameter) other metrics reported by the agent on the VM
• guest-metrics-lastupdated (read only) timestamp when the in-guest agent performed the last write to these fields. The timestamp is in the form yyyymmddThh:mm:ss z, where z is the single letter military timezone indicator, for example, Z for UTC (GMT)
• actions-after-shutdown (read/write) action to take after the VM has shutdown
• actions-after-reboot (read/write) action to take after the VM has rebooted
• possible-hosts potential hosts of this VM read only
• dom-id (read only) domain ID (if available, -1 otherwise)
• recommendations (read only) XML specification of recommended values and ranges for properties of this VM
• xenstore-data (read/write map parameter) data to be inserted into the xenstore tree (/local/domain/*domid*/vm-data) after the VM is created
• is-a-snapshot (read only) True if this VM is a snapshot
• snapshot_of (read only) the UUID of the VM that this snapshot is of
• snapshots (read only) the UUIDs of all snapshots of this VM
• snapshot_time (read only) the timestamp of the snapshot operation that created this VM snapshot
• memory-target (read only) the target amount of memory set for this VM
• blocked-operations (read/write map parameter) lists the operations that cannot be performed on this VM
• last-boot-record (read only) record of the last boot parameters for this template, in XML format
• ha-always-run (read/write) True if this VM is always restarted on another host if there is a failure of the host it is resident on. This parameter is now deprecated. Use the ha-restart-priority parameter instead.
• ha-restart-priority (read/write) restart or best-effort
• blobs (read only) binary data store
• live (read only) True if the VM is running. False if HA suspects that the VM is not be running.

vm-assert-can-be-recovered

xe vm-assert-can-be-recovered uuid [database] vdi-uuid
<!--NeedCopy-->

Tests whether storage is available to recover this VM.

vm-call-plugin

xe vm-call-plugin vm-uuid=vm_uuid plugin=plugin fn=function [args:key=value]
<!--NeedCopy-->

Calls the function within the plug-in on the given VM with optional arguments (args:key=value). To pass a "value" string with special characters in it (for example new line), an alternative syntax args:key:file=local_file can be used in place, where the content of local_file will be retrieved and assigned to "key" as a whole.

vm-cd-add

xe vm-cd-add cd-name=name_of_new_cd device=integer_value_of_an_available_vbd [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Add a new virtual CD to the selected VM. Select the device parameter from the value of the allowed-VBD-devices parameter of the VM.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-cd-eject

xe vm-cd-eject [vm-selector=vm_selector_value...]
<!--NeedCopy-->

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

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-cd-insert

xe vm-cd-insert cd-name=name_of_cd [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Insert a CD into the virtual CD drive. This command only works if there is exactly one empty CD device attached to the VM. When there are two or more empty CD devices, use the xe vbd-insert command and specify the UUIDs of the VBD and of the VDI to insert.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-cd-list

xe vm-cd-list [vbd-params] [vdi-params] [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Lists CDs attached to the specified VMs.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

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

vm-cd-remove

xe vm-cd-remove cd-name=name_of_cd [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Remove a virtual CD from the specified VMs.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-checkpoint

xe vm-checkpoint new-name-label=name_label [new-name-description=description]
<!--NeedCopy-->

Checkpoint an existing VM, using storage-level fast disk snapshot operation where available.

vm-clone

xe vm-clone new-name-label=name_for_clone [new-name-description=description_for_clone] [vm-selector=vm_selector_value...]
<!--NeedCopy-->

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 or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-compute-maximum-memory

xe vm-compute-maximum-memory total=amount_of_available_physical_ram_in_bytes [approximate=add overhead memory for additional vCPUS? true|false] [vm_selector=vm_selector_value...]
<!--NeedCopy-->

Calculate the maximum amount of static memory which can be allocated to an existing VM, using the total amount of physical RAM as an upper bound. The optional parameter approximate reserves sufficient extra memory in the calculation to account for adding extra vCPUs into the VM later.

For example:

xe vm-compute-maximum-memory vm=testvm total=`xe host-list params=memory-free --minimal`
<!--NeedCopy-->

This command uses the value of the memory-free parameter returned by the xe host-list command to set the maximum memory of the VM named testvm.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-compute-memory-overhead

xe vm-compute-memory-overhead
<!--NeedCopy-->

Computes the virtualization memory overhead of a VM.

vm-copy

xe vm-copy new-name-label=name_for_copy [new-name-description=description_for_copy] [sr-uuid=uuid_of_sr] [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Copy an existing VM, but without using storage-level fast disk clone operation (even if this option is available). The disk images of the copied VM are guaranteed to be full images, that is, not part of a copy-on-write (CoW) chain.

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

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

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-copy-bios-strings

xe vm-copy-bios-strings host-uuid=host_uuid
<!--NeedCopy-->

Copy the BIOS strings of the given host to the VM.

Note:

After you first start a VM, you cannot change its BIOS strings. Ensure that the BIOS strings are correct before starting the VM for the first time.

vm-crashdump-list

xe vm-crashdump-list [vm-selector=vm selector value...]
<!--NeedCopy-->

List crashdumps associated with the specified VMs.

When you use the optional argument params, the value of params is a string containing a list of parameters of this object that you want to display. Alternatively, you can use the keyword all to show all parameters. If params is not used, the returned list shows a default subset of all available parameters.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-data-source-list

xe vm-data-source-list [vm-selector=vm selector value...]
<!--NeedCopy-->

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

Select the VMs on which to perform this operation by using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section. If no parameters to select hosts are given, the operation is performed on all VMs.

Data sources have two parameters – standard and enabled – which you can seen in the output of this command. If a data source has enabled set to true, the metrics are currently being recorded to the performance database. If a data source has standard set to true, the metrics are recorded to the performance database by default (and enabled is also set to true for this data source). If a data source has standard set to false, the metrics are not recorded to the performance database by default (and enabled is also set to false for this data source).

To start recording data source metrics to the performance database, run the vm-data-source-record command. This command sets enabled to true. To stop, run the vm-data-source-forget. This command sets enabled to false.

vm-data-source-record

xe vm-data-source-record data-source=name_description_of_data-source [vm-selector=vm selector value...]
<!--NeedCopy-->

Record the specified data source for a VM.

This operation writes the information from the data source to the persistent performance metrics database of the specified VMs. For performance reasons, this database is distinct from the normal agent database.

Select the VMs on which to perform this operation by using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section. If no parameters to select hosts are given, the operation is performed on all VMs.

vm-data-source-forget

xe vm-data-source-forget data-source=name_description_of_data-source [vm-selector=vm selector value...]
<!--NeedCopy-->

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

Select the VMs on which to perform this operation by using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section. If no parameters to select hosts are given, the operation is performed on all VMs.

vm-data-source-query

xe vm-data-source-query data-source=name_description_of_data-source [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Display the specified data source for a VM.

Select the VMs on which to perform this operation by using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section. If no parameters to select hosts are given, the operation is performed on all VMs.

vm-destroy

xe vm-destroy uuid=uuid_of_vm
<!--NeedCopy-->

Destroy the specified VM. This leaves the storage associated with the VM intact. To delete storage as well, use xe vm-uninstall.

vm-disk-add

xe vm-disk-add disk-size=size_of_disk_to_add device=uuid_of_device [vm-selector=vm_selector_value...]
<!--NeedCopy-->

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

The disk-size parameter can be specified in bytes or using the IEC standard suffixes KiB, MiB, GiB, and TiB.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-disk-list

xe vm-disk-list [vbd-params] [vdi-params] [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Lists disks attached to the specified VMs. The vbd-params and vdi-params parameters control the fields of the respective objects to output. Give the parameters as a comma-separated list, or the special key all for the complete list.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-disk-remove

xe vm-disk-remove device=integer_label_of_disk [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Remove a disk from the specified VMs and destroy it.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-export

xe vm-export filename=export_filename [metadata=true|false] [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Export the specified VMs (including disk images) to a file on the local machine. Specify the file name to export the VM into using the filename parameter. By convention, the file name has a .xva extension.

If the metadata parameter is true, the disks are not exported. Only the VM metadata is written to the output file. Use this parameter when the underlying storage is transferred through other mechanisms, and permits the VM information to be recreated. For more information, see vm-import.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-import

xe vm-import filename=export_filename [metadata=true|false] [preserve=true|false][sr-uuid=destination_sr_uuid]
<!--NeedCopy-->

Import a VM from a previously exported file. If preserve is set to true, the MAC address of the original VM is preserved. The sr-uuid determines the destination SR to import the VM into. If this parameter is not specified, the default SR is used.

If the metadata is true, you can import a previously exported set of metadata without their associated disk blocks. Metadata-only import fails if any VDIs cannot be found (named by SR and VDI.location) unless the --force option is specified, in which case the import proceeds regardless. If disks can be mirrored or moved out-of-band, metadata import/export is a fast way of moving VMs between disjoint pools. For example, as part of a disaster recovery plan.

Note:

Multiple VM imports are performed faster in serial that in parallel.

vm-install

xe vm-install new-name-label=name [template-uuid=uuid_of_desired_template] [template=template_uuid_or_name] [sr-uuid=sr_uuid | sr-name-label=name_of_sr][copy-bios-strings-from=host_uuid]
<!--NeedCopy-->

Install or clone a VM from a template. Specify the template name using either the template-uuid or template argument. Specify an SR using either the sr-uuid or sr-name-label argument. Specify to install BIOS-locked media using the copy-bios-strings-from argument.

Note:

When installing from a template that has existing disks, by default, new disks are created in the same SR as these existing disks. Where the SR supports it, these disks are fast copies. If a different SR is specified on the command line, the new disks are created there. In this case, a fast copy is not possible and the disks are full copies.

When installing from a template that doesn’t have existing disks, any new disks are created in the SR specified, or the pool default SR when an SR is not specified.

vm-is-bios-customized

xe vm-is-bios-customized
<!--NeedCopy-->

Indicates whether the BIOS strings of the VM have been customized.

vm-memory-dynamic-range-set

xe vm-memory-dynamic-range-set min=min max=max
<!--NeedCopy-->

Configure the dynamic memory range of a VM. The dynamic memory range defines soft lower and upper limits for a VM’s memory. It’s possible to change these fields when a VM is running or halted. The dynamic range must fit within the static range.

vm-memory-limits-set

xe vm-memory-limits-set static-min=static_min static-max=static_max dynamic-min=dynamic_min dynamic-max=dynamic_max
<!--NeedCopy-->

Configure the memory limits of a VM.

vm-memory-set

xe vm-memory-set memory=memory
<!--NeedCopy-->

Configure the memory allocation of a VM.

vm-memory-shadow-multiplier-set

xe vm-memory-shadow-multiplier-set [vm-selector=vm_selector_value...] [multiplier=float_memory_multiplier]
<!--NeedCopy-->

Set the shadow memory multiplier for the specified VM.

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

In some specialized application workloads, such as Citrix Virtual Apps, extra shadow memory is required to achieve full performance.

This memory is considered to be an overhead. It is separated from the normal memory calculations for accounting memory to a VM. When this command is invoked, the amount of free host memory decreases according to the multiplier and the HVM_shadow_multiplier field is updated with the value that Xen has assigned to the VM. If there is not enough Citrix Hypervisor server memory free, an error is returned.

The VMs on which to perform this operation are selected using the standard selection mechanism. For more information, see VM selectors.

vm-memory-static-range-set

xe vm-memory-static-range-set min=min max=max
<!--NeedCopy-->

Configure the static memory range of a VM. The static memory range defines hard lower and upper limits for a VM’s memory. It’s possible to change these fields only when a VM is halted. The static range must encompass the dynamic range.

vm-memory-target-set

xe vm-memory-target-set target=target
<!--NeedCopy-->

Set the memory target for a halted or running VM. The given value must be within the range defined by the VM’s memory_static_min and memory_static_max values.

vm-migrate

xe vm-migrate [copy=true|false] [host-uuid=destination_host_uuid] [host=name_or_ uuid_of_destination_host] [force=true|false] [live=true|false] [vm-selector=vm_selector_value...] [remote-master=destination_pool_master_uuid] [remote-username=destination_pool_username] [remote-password=destination_pool_password] [remote-network=destination_pool_network_uuid ][vif:source_vif_uuid=destination_network_uuid] [vdi:vdi_uuid=destination_sr_uuid]
<!--NeedCopy-->

This command migrates the specified VMs between physical hosts. The host parameter can be either the name or the UUID of the Citrix Hypervisor server. For example, to migrate the VM to another host in the pool, where the VM disks are on storage shared by both hosts:

xe vm-migrate uuid=vm_uuid host-uuid=destination_host_uuid
<!--NeedCopy-->

To move VMs between hosts in the same pool that do not share storage (storage live migration):

xe vm-migrate uuid=vm_uuid host-uuid=destination_host_uuid \
    remote-master=192.0.2.35 remote-username=username remote-password=password
<!--NeedCopy-->

For storage live migration, you must provide the host name or IP address, user name, and password for the pool master, even when you are migrating within the same pool.

You can choose the SR where each VDI gets stored:

xe vm-migrate uuid=vm_uuid remote-master=192.0.2.35 remote-username=username remote-password=password host-uuid=destination_host_uuid \
    vdi:vdi_1=destination_sr1_uuid \
    vdi:vdi_2=destination_sr2_uuid \
    vdi:vdi_3=destination_sr3_uuid
<!--NeedCopy-->

Additionally, you can choose which network to attach the VM after migration:

xe vm-migrate uuid=vm_uuid \
    vdi1:vdi_1_uuid=destination_sr1_uuid \
    vdi2:vdi_2_uuid=destination_sr2_uuid \
    vdi3:vdi_3_uuid=destination_sr3_uuid \
    vif:vif_uuid=network_uuid
<!--NeedCopy-->

For cross-pool migration:

xe vm-migrate uuid=vm_uuid remote-master=192.0.2.35 \
    remote-username=username remote-password=password \
    host-uuid=destination_host_uuid  \
    vif:source_vif_uuid=destination_network_uuid \
    vdi:vdi_uuid=destination_sr_uuid
<!--NeedCopy-->

For more information about storage live migration, live migration, and live VDI migration, see Migrate VMs.

By default, the VM is suspended, migrated, and resumed on the other host. The live parameter selects live migration. Live migration keeps the VM running while performing the migration, thus minimizing VM downtime. In some circumstances, such as extremely memory-heavy workloads in the VM, live migration falls back into default mode and suspends the VM for a short time before completing the memory transfer.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-pause

xe vm-pause
<!--NeedCopy-->

Pause a running VM. Note this operation does not free the associated memory (see vm-suspend).

vm-reboot

xe vm-reboot [vm-selector=vm_selector_value...] [force=true]
<!--NeedCopy-->

Reboot the specified VMs.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

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

vm-recover

xe vm-recover vm-uuid [database] [vdi-uuid] [force]
<!--NeedCopy-->

Recovers a VM from the database contained in the supplied VDI.

vm-reset-powerstate

xe vm-reset-powerstate [vm-selector=vm_selector_value...] {force=true}
<!--NeedCopy-->

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

This is an advanced command only to be used when a member host in a pool goes down. You can use this command to force the pool master to reset the power-state of the VMs to be halted. Essentially, this command forces the lock on the VM and its disks so it can be started next on another pool host. This call requires the force flag to be specified, and fails if it is not on the command-line.

vm-resume

xe vm-resume [vm-selector=vm_selector_value...] [force=true|false] [on=host_uuid]
<!--NeedCopy-->

Resume the specified VMs.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

If the VM is on a shared SR in a pool of hosts, use the on argument to specify which pool member to start it on. By default the system determines an appropriate host, which might be any of the members of the pool.

vm-retrieve-wlb-recommendations

xe vm-retrieve-wlb-recommendations
<!--NeedCopy-->

Retrieve the workload balancing recommendations for the selected VM.

vm-shutdown

xe vm-shutdown [vm-selector=vm_selector_value...] [force=true|false]
<!--NeedCopy-->

Shut down the specified VM.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

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

vm-snapshot

xe vm-snapshot new-name-label=name_label [new-name-description+name_description]
<!--NeedCopy-->

Snapshot an existing VM, using storage-level fast disk snapshot operation where available.

vm-start

xe vm-start [vm-selector=vm_selector_value...] [force=true|false] [on=host_uuid] [--multiple]
<!--NeedCopy-->

Start the specified VMs.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

If the VMs are on a shared SR in a pool of hosts, use the on argument to specify which pool member to start the VMs on. By default the system determines an appropriate host, which might be any of the members of the pool.

vm-suspend

xe vm-suspend [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Suspend the specified VM.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-uninstall

xe vm-uninstall [vm-selector=vm_selector_value...] [force=true|false]
<!--NeedCopy-->

Uninstall a VM, destroying its disks (those VDIs that are marked RW and connected to this VM only) in addition to its metadata record. To destroy just the VM metadata, use xe vm-destroy.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

vm-unpause

xe vm-unpause
<!--NeedCopy-->

Unpause a paused VM.

vm-vcpu-hotplug

xe vm-vcpu-hotplug new-vcpus=new_total_vcpu_count [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Dynamically adjust the number of vCPUs available to a running Linux VM. The number of vCPUs is bounded by the parameter VCPUs-max. Windows VMs always run with the number of vCPUs set to VCPUs-max and must be rebooted to change this value.

Use the new-vcpus parameter to define the new total number of vCPUs that you want to have after running this command. Do not use this parameter to pass the number of vCPUs you want to add. For example, if you have two existing vCPUs in your VM and want to add two more vCPUs, specify new-vcpus=4.

The Linux VM or Windows VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

Note:

When running Linux VMs without Citrix VM Tools installed, run the following command on the VM as root to ensure the newly hot plugged vCPUs are used: # for i in /sys/devices/system/cpu/cpu[1-9]*/online; do if [ "$(cat $i)" = 0 ]; then echo 1 > $i; fi; done

vm-vif-list

xe vm-vif-list [vm-selector=vm_selector_value...]
<!--NeedCopy-->

Lists the VIFs from the specified VMs.

The VM or VMs on which this operation is performed are selected using the standard selection mechanism. For more information, see VM selectors. The selectors operate on the VM records when filtering, and not on the VIF values. Optional arguments can be any number of the VM parameters listed at the beginning of this section.

Scheduled snapshots

Commands for controlling VM scheduled snapshots and their attributes.

The vmss objects can be listed with the standard object listing command (xe vmss-list), and the parameters manipulated with the standard parameter commands. For more information, see Low-level parameter commands

vmss-create

xe vmss-create enabled=True/False name-label=name type=type frequency=frequency retained-snapshots=value name-description=description schedule:schedule
<!--NeedCopy-->

Creates a snapshot schedule in the pool.

For example:

xe vmss-create retained-snapshots=9 enabled=true frequency=daily \
    name-description=sample name-label=samplepolicy type=snapshot \
    schedule:hour=10 schedule:min=30
<!--NeedCopy-->

Snapshot schedules have the following parameters:

vmss-destroy

xe vmss-destroy uuid=uuid
<!--NeedCopy-->

Destroys a snapshot schedule in the pool.

USB pass-through

USB pass-through is supported for the following USB versions: 1.1, 2.0, and 3.0.

USB pass-through enable/disable

xe pusb-param-set uuid=pusb_uuid passthrough-enabled=true/false
<!--NeedCopy-->

Enable/disable USB Pass-through.

pusb-scan

xe pusb-scan host-uuid=host_uuid
<!--NeedCopy-->

Scan PUSB and update.

vusb-create

xe vusb-create usb-group-uuid=usb_group_uuid vm-uuid=vm_uuid
<!--NeedCopy-->

Creates a virtual USB in the pool. Start the VM to pass through the USB to the VM.

vusb-unplug

xe vusb-unplug uuid=vusb_uuid
<!--NeedCopy-->

Unplugs USB from VM.

vusb-destroy

xe vusb-destroy uuid=vusb_uuid
<!--NeedCopy-->

Removes the virtual USB list from VM.