Working With UUID’s

Every object in a XenServer (XS) environment – whether it is a physical interface (PIF) or a virtual interface (VIF), a physical hard disk drive (PBD) or a virtual hard disk drive (VHD),  a physical host or a virtual machine (VM), or even a pool of XenServer hosts – has a Universally-unique Identifier (UUID) assigned to it.

A UUID is a 16-octet (128-bit) number. In its canonical form, a UUID is represented by 32 lowercase hexadecimal digits, displayed in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 alphanumeric characters and four hyphens). For example:

123e4567-e89b-12d3-a456-426655440000

…The number of possible UUID’s is 1632, which is 2128 or about 3.4 × 1038.

Working with XS from the command-line interface (CLI) involves a lot of iterating through the UUID’s in a XS environment- i.e., Looking up one value in order to find another and using that other value to find another and so on – so working efficiently and effectively with UUID’s is an important skill when managing XS from the CLI. This tutorial will demonstrate how to make working with UUID’s easier.

The /etc/xensource-inventory File

The /etc/xensource-inventory file contains a lot of useful information. Fortunately for XS administrators the creators of XAPI formatted the information in this file as a list of shell variables and their respective values:


Legend: GET | SEE | USE

[root@xs-1 ~]# cat /etc/xensource-inventory
BUILD_NUMBER=’90233c’
PLATFORM_VERSION=’1.9.0′
DOM0_VCPUS=’1′
INSTALLATION_UUID=’13ea7f70-953d-48c8-9507-b48510a284a6′
LINUX_KABI_VERSION=’3.10.0+2′
MANAGEMENT_ADDRESS_TYPE=’IPv4′
PRODUCT_VERSION_TEXT_SHORT=’6.5′
BRAND_CONSOLE=’XenCenter’
PRIMARY_DISK=’/dev/disk/by-id/scsi-SATA_VBOX_HARDDISK_VB7c4f9765-54da6762′
PRODUCT_BRAND=’XenServer’
INSTALLATION_DATE=’2016-10-31 18:22:27.885636′
PLATFORM_NAME=’XCP’
COMPANY_NAME_SHORT=’Citrix’
PRODUCT_VERSION_TEXT=’6.5′
BACKUP_PARTITION=’/dev/disk/by-id/scsi-SATA_VBOX_HARDDISK_VB7c4f9765-54da6762-part2′
PRODUCT_VERSION=’6.5.0′
XEN_VERSION=’4.4.1′
KERNEL_VERSION=’3.10.41′
MANAGEMENT_INTERFACE=’xenbr0′
DOM0_MEM=’752′
COMPANY_NAME=’Citrix Systems, Inc.’
PRODUCT_NAME=’xenenterprise’
CONTROL_DOMAIN_UUID=’a2c48646-3130-436d-a6fe-4c4a7ed16ea0′


One name/value pair in the list is especially important if your XS host is configured as part of a resource pool: $INSTALLATION_UUID.

Often, when XS administrators interrogate XAPI they’ll need to tell XAPI which host in the pool they’re interested in. (If no host-UUID is given, XAPI will interpret the scope of the inquiry to be the entire pool.) e.g., The command `/xe pif-list` will return a list of all of the physical interfaces on all of the hosts in the resource pool:


Legend: GET | SEE | USE

[root@xs-1 ~]# xe host-list
uuid ( RO) : 13ea7f70-953d-48c8-9507-b48510a284a6
name-label ( RW): xs-1
name-description ( RW): Default install of XenServer

uuid ( RO) : af660edb-f4eb-4ba4-940b-00dc9d081d79
name-label ( RW): xs-2
name-description ( RW): Default install of XenServer

[root@xs-1 ~]# xe pif-list | grep device
device ( RO): eth3
device ( RO): eth0
device ( RO): eth1
device ( RO): eth2
device ( RO): eth1
device ( RO): eth0
device ( RO): eth2
device ( RO): eth3

[root@xs-1 ~]# xe pif-list | grep device | wc -l
8


To narrow the results to the list of interfaces attached to the local host, include the host-uuid command-line option and the UUID of the local host (i.e., contained in the $INSTALLATION_UUID the Bash global variable):


Legend: GET | SEE | USE

[root@xs-1 ~]# grep INSTALLATION_UUID /etc/xensource-inventory
INSTALLATION_UUID=’13ea7f70-953d-48c8-9507-b48510a284a6′

[root@xs-1 ~]# source /etc/xensource-inventory

[root@xs-1 ~]# echo $INSTALLATION_UUID
13ea7f70-953d-48c8-9507-b48510a284a6

[root@xs-1 ~]# xe host-list
uuid ( RO) : 13ea7f70-953d-48c8-9507-b48510a284a6
name-label ( RW): xs-1
name-description ( RW): Default install of XenServer

uuid ( RO) : af660edb-f4eb-4ba4-940b-00dc9d081d79
name-label ( RW): xs-2
name-description ( RW): Default install of XenServer

[root@xs-1 ~]# xe pif-list host-uuid=$INSTALLATION_UUID | grep device | wc -l
4


To narrow the results to the list of interfaces attached to the other host, include the /host-uuid command-line option and the UUID of the other host using a bit of shell magic (explained in the section “Creating Environment Variables On-the-fly“, below):


Legend: GET | SEE | USE

[root@xs-1 ~]# xe host-list
uuid ( RO) : 13ea7f70-953d-48c8-9507-b48510a284a6
name-label ( RW): xs-1
name-description ( RW): Default install of XenServer

uuid ( RO) : af660edb-f4eb-4ba4-940b-00dc9d081d79
name-label ( RW): xs-2
name-description ( RW): Default install of XenServer

[root@xs-1 ~]# OTHER_HOST_UUID=$(xe host-list name-label=xs-2 | awk ‘/uuid/ { print $5 }’)

[root@xs-1 ~]# echo $OTHER_HOST_UUID
af660edb-f4eb-4ba4-940b-00dc9d081d79

[root@xs-1 ~]# xe pif-list host-uuid=$OTHER_HOST_UUID | grep device | wc -l
4


To make the name/value pairs contained in the /etc/xensource-inventory configuration file available from the CLI as global environment variables every time the administrator logs in, add this line to the end of the Bash global configuration file: /etc/bashrc:

source /etc/xensource-inventory

Bash Autocompletion

The XS control domain (i.e., Dom0) is created using CentOS Enterprise Linux. The default shell for the XS Administrator account (i.e., root) is Bash – the Bourne Again SHell. Bash is a highly-extensible and very powerful shell that includes many features that help administrators to work efficiently and effectively from the command-line.
One of the most powerful features of the Bash shell is autocompletion:

The programmable completion feature in Bash permits typing a partial command, then pressing the Tab key to auto-complete the command sequence.

The creators of XAPI have extended the autocompletion feature of Bash to maximum effect with context-sensitive autocompletion. The awareness of context means that, when pressing the Tab key…

  • If the cursor follows directly after the `xe` command: Bash returns a complete list of all of the XAPI commands available to the administrator.
  • If the cursor follows some portion of a XAPI command: Bash returns a list of all of the XAPI commands that match the portion of the command that’s already been typed.
  • If the cursor follows a complete XAPI command: Bash returns a complete list of all of the command-line options that may be utilized with the specific XAPI command.
  • If the cursor follows some portion of a command-line option: Bash either completes the option or returns a list of options that match the portion of the option that’s already been typed.
  • If the cursor follows a complete command-line option: Bash suggests a list of relevant UUID’s to be used.


[root@xs-1 ~]# xe help
Usage: xe [-s server] [-pw passwd] [-p port] [-u user] [-pwf password-file]
[command specific arguments]

To get help on a specific command: xe help
To get a full listing of commands: xe help –all

Common command list
——————-
cd-list, diagnostic-vm-status, network-list, snapshot-clone
snapshot-copy, snapshot-disk-list, snapshot-export-to-template
snapshot-reset-powerstate, snapshot-revert, snapshot-uninstall, sr-list
template-export, template-uninstall, vm-cd-add, vm-cd-eject
vm-cd-insert, vm-cd-list, vm-cd-remove, vm-checkpoint, vm-clone
vm-compute-maximum-memory, vm-copy, vm-disk-add, vm-disk-list
vm-disk-remove, vm-export, vm-import, vm-install, vm-list, vm-migrate
vm-pause, vm-reboot, vm-reset-powerstate, vm-resume, vm-shutdown
vm-snapshot, vm-snapshot-with-quiesce, vm-start, vm-suspend
vm-uninstall, vm-unpause, vm-vif-list


In this example, notice how Bash autocompletion suggests the UUID’s of the two members in the resource pool:


Legend: GET | SEE | USE

[root@xs-1 ~]# xe host-list
uuid ( RO) : 13ea7f70-953d-48c8-9507-b48510a284a6
name-label ( RW): xs-1
name-description ( RW): Default install of XenServer

uuid ( RO) : af660edb-f4eb-4ba4-940b-00dc9d081d79
name-label ( RW): xs-2
name-description ( RW): Default install of XenServer

[root@xs-1 ~]# xe pif-list host-uuid=Tab
13ea7f70-953d-48c8-9507-b48510a284a6 af660edb-f4eb-4ba4-940b-00dc9d081d79


(To use either of the two host-UUID’s offered by Bash, begin entering either UUID and press the Tab key to allow Bash to automatically complete the UUID.)

By providing fine-grained context-sensitivity, Bash autocompletion allows XS administrators to work efficiently and effectively from the command-line with relatively little detailed knowledge of XAPI’s command syntax.

Creating Environment Variables On-the-fly

Many XAPI commands return a UUID upon successful completion. Using some simple shell scripting the UUID that XAPI returns can be captured as a shell variable and re-used later in the process. e.g.,


Legend: GET | SEE | USE

[root@xs-1 ~]# unzip -d /tmp /tmp/XS65ESP1.zip
Archive: /tmp/XS65ESP1.zip
inflating: /tmp/XS65ESP1.xsupdate
inflating: /tmp/XS65ESP1-src-pkgs.tar.bz2

[root@xs-1 ~]# xe patch-upload file-name=/tmp/XS65ESP1.xsupdate
7f2e4a3a-4098-4a71-84ff-b0ba919723c7

[root@xs-1 ~]# xe patch-apply host-uuid=$INSTALLATION_UUID uuid=7f2e4a3a-4098-4a71-84ff-b0ba919723c7


The value returned by the `/xe patch-upload` command could have been stored as a custom variable and re-used like this:


Legend: GET | SEE | USE

[root@xs-1 ~]# unzip -d /tmp /tmp/XS65ESP1.zip
Archive: /tmp/XS65ESP1.zip
inflating: /tmp/XS65ESP1.xsupdate
inflating: /tmp/XS65ESP1-src-pkgs.tar.bz2

[root@xs-1 ~]# PATCH_UUID=$(xe patch-upload file-name=/tmp/XS65ESP1.xsupdate)

[root@xs-1 ~]# echo $PATCH_UUID
7f2e4a3a-4098-4a71-84ff-b0ba919723c7

[root@xs-1 ~]# xe patch-apply host-uuid=$INSTALLATION_UUID uuid=$PATCH_UUID


By storing the value returned by the `xe` command, entire series of XAPI commands can be daisy-chained together to form larger, more complex commands – all the while, reducing they number of keystrokes and eliminating typos!

Summary

By using the features of the Bash shell XS administrators can effectively and efficiently manage XS from the command-line.