Download full document:

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 XenServer are to be included, these should be from the appropriate CentOS distribution that the XenServer dom0 is based upon. In XenServer 7.3, this is CentOS 7.2. Alternatively, components can packaged as RPMs using a custom spec file.

If a pack will only contain drivers, it is normally known as a XenServer 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 should describe the version of XenServer 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=7.3.0" \
--key "Example Updates (update) <example@example.com>" --keyfile /root/RPM-GPG-KEY-XS-DDK-TEST \
-o example.iso *.rpm

A CD image should then be made from the contents of this directory.

Adding files to Server Status Reports

XenServer 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 wish to create a category called Acmesoft, under which various Acmesoft-specific log files are collected. However, they might also wish 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, an XML file should be created 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. The negate attribute 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 executed and its output collected. The optional label attribute 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>

Note

When extending existing categories, any files added should 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 are purely for development and test purposes, and should therefore not be extended by supplemental packs.

Adding new categories

To add a new category, an XML file should be created with the name /etc/xensource/bugtool/<category>.xml (where <category> is the new category name). It should contain 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 of no (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), or yes (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 of application/data or text/plain.

  • checked: specifies whether this category is to be collected by default (set to true) or not (set to false).

  • hidden: when set to true, 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. The min_size and min_time attributes 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.

The data to be collected as part of this category should be specified by 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. Pack authors should therefore ensure that any new categories have suitably descriptive names.

Automating pack installation at XenServer installation time

If a partner has obtained the necessary agreement from Citrix to distribute XenServer, it is possible to create a modified installation ISO that contains the XenServer installation files, plus one or more supplemental packs. This allows a partner to distribute a single ISO that can seamlessly install XenServer 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 XenServer installation ISO

Answerfiles allow the responses to all the questions posed by the XenServer installer to be specified in an XML file, rather than needing to run the installer in interactive mode. The XenServer DDK includes a script to add an answerfile to the XenServer 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 XenServer 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 XenServer automated installation file. Details of the syntax of this file are given in the relevant section of the XenServer Installation Guide. 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 what the volume label of the resulting ISO should be. 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 XenServer itself.