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.