Creating a supplemental pack
Supplemental packs can be created containing existing RPMs provided they meet the requirements given below. If standard packages that are not shipped in Citrix Hypervisor are to be included, these must be from the appropriate CentOS distribution that the Citrix Hypervisor dom0 is based upon. In Citrix Hypervisor 8.0, this is CentOS 7.5. Alternatively, components can packaged as RPMs using a custom spec file.
If a pack will only contain drivers, it is normally known as a Citrix Hypervisor Driver Disk. However, the mechanisms used to build and install a driver disk are the same as for any other supplemental pack. One key point is that for drivers, the source code must be provided to the DDK, in order that the drivers be compiled for the correct kernels. For other pack components, no such compilation is necessary.
Syntax of build-update
All supplemental packs are constructed using the /usr/bin/build-update script.
This provides a simple way to provide metadata about the pack, by taking a number of options and arguments.
The significance of each one is discussed in the sections that follow.
Apart from the metadata switches, any further arguments to build-update are taken to be names of the RPMs to be included in the supplemental pack.
Name, vendor, and version information
Basic details concerning the pack authoring organization, name, and version number must be provided. The relevant switches are:
-
--uuid: a universal unique identifier generated by the uuidgen command. -
--label: an identifier that identifies the pack. -
--text: a free text string describing the pack (enclosed by double quote marks). -
--version: the pack version (likely to be of the form 1.2.3).
Declaring Pack dependencies
Supplemental Packs must describe the version of Citrix Hypervisor to which they are compatible. This is done using the --base-requires switch:
--base-requires “product-version=x.x.x”
A brief example
As an illustration of how build-update works, pack authors can create an example pack by placing all constituent RPMs in a directory:
mkdir packages
cd packages
cp /root/rpmbuild/RPMS/x86_64/helloworld-1.0-1.x86_64.rpm .
The pack metadata is then created, using the script.
build-update --uuid 3fbce6cf-5cd2-4d32-9602-e8122c562169 --label example pack --version 1.0.0 \
--description "An Example Pack" --base-requires "product version=8.0.0" \
--key "Example Updates (update) <example@example.com>" --keyfile /root/RPM-GPG-KEY-XS-DDK-TEST \
-o example.iso *.rpm
A CD image is then made from the contents of this directory.
Adding files to Server Status Reports
Citrix Hypervisor provides a convenient mechanism for users to collect a variety of debugging information when opening a support case, known as a Server Status Report in XenCenter, or xen-bugtool on the CLI.
To aid partners in supporting their supplemental packs, it is recommended that pack authors add to the list of files collected as part of these Status Reports, using the method outlined below.
Server Status Reports can include not only files, such as logs, but also the outputs of any normal scripts or commands that are run in the control domain (dom0).
For convenience, the items collected as part of a Report are divided into categories.
For example, the Network Configuration category collects the output of tools such as ifconfig, as well as network configuration files.
Citrix recommends that pack authors create new categories if appropriate, but also consider adding to existing categories.
As an example, partner Acmesoft, who produce software that manages the configuration of a special network card, might want to create a category called Acmesoft, under which various Acmesoft-specific log files are collected. However, they might also want to add (other) files related to networking to the Network Configuration category, as it makes most sense from a user perspective that they be collected as part of this category.
Each category has a level of confidentiality attached to it, which expresses how much personally identifiable information (PII) might be present in the files that are collected as part of that capability. This ensures that users are made aware before they send Status Reports to support teams of what they might be disclosing. There are four levels of confidentiality: no PII, possibly some PII if the file to be collected has been customized, possibly contains some PII, and definitely contains PII.
Extending an existing category
To extend an existing category, create an XML file in /etc/xensource/bugtool/<category>/ directory (where <category> is the category name).
Three elements within an outer <collect> element will be supported:
-
files: a list of one or more files (separated by spaces, hence no spaces are allowed within the file names). -
directory: a directory to be collected, with (optionally) a pattern that will be used to filter objects within. The pattern must be a valid Python regular expression. Thenegateattribute allows the sense of the pattern to be inverted: this attribute is provided for ease of readability purposes, as negation could also be included in the regular expression itself. -
command: a command to be run and its output collected. The optionallabelattribute specifies a name for the output file. If this is not specified, the command name will be used.
For example:
<collect>
<files>file1 file2</files>
<directory pattern=".*\.txt$" negate="false">dir</directory>
<command label="label">cmd</command>
</collect>
<!--NeedCopy-->
Note:
When extending existing categories, any files added must have the same (or lower) confidentiality levels as the category in question.
Existing categories are:
| Category name | Description | PII level | Collected by default? |
|---|---|---|---|
| CVSM | Citrix StorageLink configuration | No | Yes |
| disk-info | Disk information | Maybe | Yes |
| firstboot | First-boot scripts | Yes | Yes |
| hardware-info | Hardware information | Maybe | Yes |
| high-availability | High availability | Maybe | Yes |
| host-crashdump-dumps | Crash dump files | Yes | No |
| host-crashdump-logs | Crash dump logs | No | No |
| kernel-info | Kernel information | Maybe | Yes |
| loopback-devices | Loopback devices | Maybe | Yes |
| multipath | Multipathing configuration | Maybe | Yes |
| network-status | Network scripts | If customized | Yes |
| pam | Authentication module configuration | No | Yes |
| process-list | Process listing | Yes | Yes |
| persistent-stats | Persistent statistics | Maybe | Yes |
| system-logs | System logs | Maybe | Yes |
| system-services | System services | No | Yes |
| tapdisk-logs | Storage subsystem logs | No | No |
| vncterm | VNCTerm crash dumps | Maybe | No |
| wlb | Workload Balancing status | No | Yes |
| XYes1 | X server logs | No | Yes |
| XYes1-auth | X11 authority | No | Yes |
| xapi-subprocess | XenServer daemon subprocesses | No | Yes |
| XenServer-config | XenServer configuration | Maybe | Yes |
| XenServer-domains | XenServer domains list | No | Yes |
| XenServer-databases | XenServer database | Yes | Yes |
| XenServer-install | XenServer installation log files | Maybe | Yes |
| XenServer-logs | XenServer logs | Maybe | Yes |
| xen-info | Hypervisor configuration | Maybe | Yes |
| xha-liveset | High availability liveset | Maybe | Yes |
| yum | RPM package database | If customized | Yes |
A number of other categories exist. These categories are purely for development and test purposes. Do not extend them in your supplemental packs.
Adding new categories
To add a new category, create an XML file with the name /etc/xensource/bugtool/<category>.xml (where <category> is the new category name).
Include a single <capability> element, with the following optional attributes:
-
pii: the degree of confidentiality that is inherent in the files to be collected (personally identifiable information). This must be set to one ofno(no PII),if_customized(PII would only be present if the file has been customized by the user),maybe(PII may be present in this file), oryes(there is a very high likelihood of PII being present). -
min_size: the minimum size (in bytes) of the data collected by this category. -
max_size: the maximum size (in bytes) of the data collected by this category. -
min_time: the minimum time (in seconds) that the commands are expected to take to run to completion. -
max_time: the maximum time (in seconds) that the commands are expected to take to run to completion. -
mime: the MIME type of the data to be collected. This must be one ofapplication/dataortext/plain. -
checked: specifies whether this category is to be collected by default (set totrue) or not (set tofalse). -
hidden: when set totrue, this category will only be collected if explicitly requested on the CLI. It will not be visible in XenCenter.
Note:
If the data to be collected by a capability exceeds the constraints placed upon it (that is, the maximum size of data to be collected is higher than
max_size), then the data is not collected. Themin_sizeandmin_timeattributes are purely for user information: if the amount of data collected, or time taken for its collection, is less than these attributes, the data is collected.
Specify the data to be collected as part of this category by using one or more XML files located in the /etc/xensource/bugtool/<category>/ directory, as described in the previous section.
At present, XenCenter displays any new categories that are added by supplemental packs, but does not provide a mechanism for pack authors to give descriptions of them in the Server Status Report dialogue. Ensure that any new categories have suitably descriptive names.
Automating pack installation at Citrix Hypervisor installation time
If a partner has obtained the necessary agreement from Citrix to distribute Citrix Hypervisor, it is possible to create a modified installation ISO that contains the Citrix Hypervisor installation files, plus one or more supplemental packs. This allows a partner to distribute a single ISO that can seamlessly install Citrix Hypervisor and the supplemental pack(s). There are two steps to this process: the first involves combining the installation ISO with the pack ISO; the second requires an answerfile to be created.
Including an answerfile on the Citrix Hypervisor installation ISO
Answerfiles allow the responses to all the questions posed by the Citrix Hypervisor installer to be specified in an XML file, rather than needing to run the installer in interactive mode.
The Citrix Hypervisor DDK includes a script to add an answerfile to the Citrix Hypervisor main installation ISO, to allow installation to be carried out in an unattended fashion.
The /usr/local/bin/rebuild-iso.sh script can be used within the DDK (though the default root disk size within the DDK is unlikely to be sufficient to perform the necessary ISO re-packing operations, and hence network storage is recommended).
Alternatively, the script, plus /usr/local/bin/rebuild.functions, can be copied to an external machine that has mkisofs installed, and used there.
The rebuild-iso.sh script takes in the Citrix Hypervisor installation ISO, plus the files to be added to it, and outputs a combined ISO. Its syntax is:
rebuild-iso.sh
[--answerfile=<answerfile>]
\[--include=<file>|<directory>]
[--label=<ISOLabel>]
inputFile.iso outputFile.iso
The <answerfile> must be a valid Citrix Hypervisor automated installation file.
Details of the syntax of this file are given in the relevant section of the Citrix Hypervisor Product Documentation.
As part of an answerfile, it is possible to specify scripts that may be run directly after the installation completes.
Whilst such scripts can be on a web server, it is also possible to place them on the ISO, with the answerfile.
The --include switch allows such files to be added to the ISO output by rebuild-iso.sh. Finally, the --label switch controls the volume label of the resulting ISO.
If no label is specified, the label of the input ISO is used.
It is worth noting that whilst an answerfile specifies the answers to
installation questions such as keyboard layout and target disks, it does
not specify which repositories to install from. This is because for an
automated installation, all repositories specified in the
XS-REPOSITORY-LIST file are installed. Therefore, provided that all
supplemental packs that are to be installed are included in the
XS-REPOSITORY-LIST file, they will be installed automatically directly
following the installation of Citrix Hypervisor itself.