XenServer CLI reference

This page is created to provide me with a CLI reference for Citrix XenServer

 

The Basics

 

Basic settings for remote connections with xe.exe:

Each xe.exe command starts with the connection settings for the XenServer (Pool Master), followed by the specific command(s) to be performed.
 

%programfiles%\Citrix\XenCenter>xe.exe -s [xenserver] -u [user] -pw [password] [xe-commands]

 
Which uses the following syntax:

• xenserver: ip-address or name of the XenServer (or Pool Master).
• user: name of account used to connect to the XenServer.
• password: password of the used account.
• xe-commands: the commands to be performed after the connection to the XenServer (Pool Master) is made.

To uniquely identify all objects in a XenServer configuration, each object is given an uuid, a unique identifier to use in all commands, so let’s look at the xe commands, to retrieve the uuid’s for different objects.

 

Informational Commands

Retrieving the required object identifiers

The following commands show you how to retrieve the required unique identifiers for the different XenServer objects that are used for the configurational changes.

* List all XenServers in a Pool:

%programfiles%\Citrix\XenCenter>xe.exe -s [xenserver] -u [user] -pw [password] host-list

 
Gives a list of all XenServers (host) and their uuid.

 

* List all physical interfaces for the specified XenServer:

xe pif-list host-uuid=[uuid-host]

 
Which uses the following syntax:

• uuid-host: unique identifier for the specified XenServer.

 
Gives a list of all physical NICs in the specified XenServer and their uuid.

 

If the XenServer is part of a Pool and the XenServer is NOT specified, all physical interfaces from all XenServers within the Pool are shown. Specify the XenServer to ensure you are retrieving the right uuid for the physical interface (pif).
 

 

* Find the uuid of the VM:

The quicky way to find the uuid of your VM is to run the vm-list command. This does however give you an overview of all VMs, so if you have alot of VMs defined, try to narrow it done with the name-label parameter (which is case sensitive). With the uuid known for the VM, you can easily enable the auto start feature.

[root@<name-xs> ~]# xe vm-list
uuid ( RO)           : [uuid-vm]
     name-label ( RW): [vm-name]
    power-state ( RO): [vm-power]

 
Which returns the following values:

• uuid-vm: A unique identifier for the Virtual Machine.
• vm-name: The name given to the Virtual Machine.
• vm-power: Shows the power state the VM is currently in (running, halted).

 

If you work with alot of VMs in a Pool, the VM list returned can be long and finding the required VM information can take some time. You can get the required uuid for your VM quicker, by adding the name-label=[vm-name] (only use quotes if the name contains spaces) parameter to the command. Keep in mind that the VM name label is case sensitive and no results are shown if the exact name label is not entered.
 

 

* Find the uuid of the Pool:

[root@<name-xs> ~]# xe pool-list
uuid ( RO)                : [uuid-pool]
          name-label ( RW): [pool-name]
    name-description ( RW): [pool-desc]
              master ( RO): [uuid-xs]
          default-SR ( RW): [uuid-sr]

 
Which returns the following values:

• uuid-pool: A unique identifier for the Pool.
• pool-name: The name given to the Pool.
• pool-desc: The description set for the Pool.
• uuid-xs: The unique identifier of the XenServer that currently is the Pool Master.
• uuid-sr: The unique identifier for the default Storage Repository configured for the Pool.

 

Pool commands

 

Enable Auto start functionality

* Enable the auto power on feature at pool level:

[root@<name-xs> ~]# xe pool-param-set uuid=[uuid-pool] other-config:auto_poweron=true

 
Which uses the following additional syntax:

• uuid-pool: A unique identifier for the Pool.

 

VM commands

 

Enable Auto start functionality

* Enable the auto power on feature for the specified VM:

[root@<name-xs> ~]# xe vm-param-set uuid=[uuid-vm] other-config:auto_poweron=true

 
Which uses the following additional syntax:

• uuid-vm: A unique identifier for the Virtual Machine.

 

Network commands

 

Changing speed and duplex-mode of an interface

The following commands are used to change the speed and duplex settings for a NIC.

* Review all settings for the specified physical interface (pif):

xe pif-list uuid=[uuid-pif] params=all

 
Which uses the following additional syntax:

• uuid-pif: unique identifier of the physical NIC in a XenServer.

 

* Setting speed and duplex mode for the specified NIC:

xe pif-param-set uuid=[uuid-pif] other-config:ethtool-autoneg="off" other-config:ethtool-speed="1000" other-config-duplex="full"

 
Which uses the following additional syntax:

• uuid-pif: unique identifier of the physical NIC in a XenServer.

 

In order to set the speed and duplex-mode of the NIC, you need to turn off auto negotiation, so this setting is added to the command as well.
 

 

* Apply the new settings for the specified NIC:

xe pif-unplug uuid=[uuid-pif]
xe pif-plug uuid=[uuid-pif]

 
Which uses the following additional syntax:

• uuid-pif: unique identifier of the physical NIC in a XenServer.

 

You need to unplug and plug the interface in order to activate the new settings. If for some reason you cannot perform these actions, the new settings will not be activated untill the XenServer is rebooted.
 Modifying speed and duplux-mode can also be performed with ethtool, which changes the settings on the fly. The changes made with ethtool are however not persistent and will be discarded after a reboot.

 

Creating a NIC bond

The following commands are used to team (or bond) two NICs into a single interface for network redundancy purposes.

* Create a new pool-wide (virtual) network for use with the bonded NICs:

xe network-create name-label=[network-name]

 
Which uses the following additional syntax:

• network-name: name for the (virtual) network that is newly created.

 

This command returns the uuid of the newly created network. Make sure that you write it down for further reference.
 

 

* Create a new bond for this network:

xe bond-create network-uuid=[uuid-network] pif-uuids=[uuid-pif-1],[uuid-pif-2]

 
Which uses the following additional syntax:

• uuid-network: unique identifier of the network.
• uuid-pif-1: unique identifier of the 1st physical interface that is included in the bond.
• uuid-pif-2: unique identifier of the 2nd physical interface that is included in the bond.

 

This command returns the uuid of the newly created bond. Make sure that you write it down for further reference.
 

 

* Retrieve the unique identifier of the bond:

xe pif-list network-uuid=[uuid-network]

 
Which uses the following additional syntax:

• uuid-network: unique identifier of the network.

 

* Config the bond as an active/passive bond:

xe pif-param-set uuid=[uuid-bond-pif] other-config:bond-mode=active-backup

 
Which uses the following additional syntax:

• uuid-bond-pif: unique identifier of the bond.

 

Storage commands

Enable storage multipathing

Some storage solutions support the use of multipathing. Multipath I/O is a fault-tolerance and performance enhancement technique whereby there is more than one physical path between the XenServer and the Storage device.
Dynamic multipathing support is available for Fibre Channel and iSCSI storage backends. By default, it uses roundrobin mode load balancing, so both routes have active traffic on them during normal operation.

Before attempting to enable multipathing, verify that multiple targets are available on your storage server. For example, an iSCSI storage backend queried for sendtargets on a given portal should return multiple targets.
 

* Check for multipath support (iSCSI):

iscsiadm -m discovery --type sendtargets --portal [ip-address-storage]
102.168.0.161:3260,1 iqn.strawberry:litchie
192.168.0.162:3260,2 iqn.strawberry:litchie

 
Which uses the following additional syntax:

• ip-address-storage: the ip-adress used to connect to the storage.

 

* Retrieve all Physical Block Devices attached to the XenServer:

xe pbd-list host-uuid=[uuid-host]

 
Which uses the following additional syntax:

• uuid-host: unique identifier of the XenServer (host).

 

* Unplug all Physical Block Devices (PBDs):

xe pbd-unplug uuid=[uuid-pbd]

 
Which uses the following additional syntax:

• uuid-pbd: unique identifier of the physical block device (pbd).

 

* Set the multipath parameter on the XenServer:

xe host-param-set other-config:multipathing=true uuid=[uuid-host]

 
Which uses the following additional syntax:

• uuid-host: unique identifier of the XenServer (host).

 

* Set the multipathhandle parameter on the XenServer:

xe host-param-set other-config:multipathhandle=dmp uuid=[uuid-host]

 
Which uses the following additional syntax:

• uuid-host: unique identifier of the XenServer (host).

 

* Replug the PDB:

xe pbd-plug uuid=[uuid-pbd]

 
Which uses the following additional syntax:

• uuid-pbd: unique identifier of the physical block device (pbd).

 

To disable multipathing, first unplug your VBDs, set the host other-config:multipathing parameter to false and then replug your PBDs as described above. Do not modify the otherconfig:multipathhandle parameter as this will be done automatically.