C.3. Installation media repository format

The repository format described here should be used by installation sources and driver disks.

C.3.1. Presence of installation media repositories

Given a path, the presence of a XenSource installation media repository is determined by checking for the existence of valid XS-REPOSITORY and XS-PACKAGES files. From a given base, that base is checked, along with the packages, packages.main, packages.linux, and packages.site subdirectories. Thus, a typical installation point will have the following format:

  xs-installation
  +-- packages.main
  |   +-- XS-REPOSITORY
  |   +-- XS-PACKAGES
  |   +-- ...
  +-- packages.linux
  |   +-- XS-REPOSITORY
  |   +-- XS-PACKAGES
  |   +-- ...
  +-- packages.site
  |   +-- XS-REPOSITORY
  |   +-- XS-PACKAGES
  |   +-- ...

A typical driver disk will have the following layout:

  xs-driver-disk
  +-- XS-REPOSITORY
  +-- XS-PACKAGES

In the first example, given a path to xs-installation, the XenServer installer will detect the presence of three repositories. In the second example, xs-driver-disk, a single repository will be detected.

C.3.2. Installation media repository metadata

The XS-REPOSITORY file is used to describe a XenSource-format installation media repository. It has four fields, separated by newlines:

repository id
repository name
intended target product
intended target version

Repository IDs should be alphanumeric strings that provide a machine identifier for the repository. They should be unique within a target product and version. Best practice is to use the form

vendor:repository

XenSource repositories start with xs (for example, xs:main), custom repositories should be custom:my-repo, and third-party add-ons should be identified as such by using an appropriate vendor string. This will help avoid name clashes.

Repository names are presented to the user, so should be a string that identifies the repository in a sensible manner so the user can confirm that they wish to install from it.

The intended target product will be XenServer; version 4.0.1-build.

C.3.3. Package metadata

The XS-PACKAGES file describes the packages in a repository, one line per package. Fields are separated by spaces.

There are three types of package:

tbz2 packages are bzipped tarballs that get extracted onto the root filesystem
driver packages are kernel modules that get loaded by the installer at runtime as well as being installed into the filesystem
firmware packages are made available during the installation so that they may be loaded by udev in addition to getting installed into the target filesystem.

Firmware loading support is currently limited; this will be addressed in a future release.

The first three fields are mandatory: package name, package size, and package checksum (md5). The fourth field is the package type, either tbz2, driver, or firmware. Which type is used dictates the contents of the subsequent fields.

If the type is tbz2, the subsequent fields are required or optional, source filename, and destination (usually just /).

Example:

docs 37750 2ba1783d84d10c71f07469252c555427 tbz2 required docs.tar.bz2 /

If the type is driver, the subsequent fields are source filename and destination (${KERNEL_VERSION} will be substituted with the Xen-kernel version.)

Example:

firmware_example 77001 3452c04dfcc237cde11c63d43e97a303 driver \
firmware_example.ko \
/lib/modules/${KERNEL_VERSION}/extra/firmware_example.ko

If the type is firmware, the subsequent field is destination filename (no path is necessary - it is automatically prefixed with /lib/firmware/).

Example:

firmware 12 6f5902ac237024bdd0c176cb93063dc4 firmware sample_firware.bin

Note

The backslashes at the ends of lines in the examples in this section denote continuation of lines; do not actually include them in a XS-PACKAGES file.

C.3.4. Example files

C.3.4.1. XS-REPOSITORY

xs:main
Base Pack and extra driver
XenServer
3.2.0-1934

C.3.4.2. XS-PACKAGES

storage-manager 59831 b66672f0aa681bd2b498e3d902f17c04 tbz2 required \
storage-manager.tar.bz2 /
docs 37750 2ba1783d84d10c71f07469252c555427 tbz2 required docs.tar.bz2 /
xgts-main 1133 59dda9c318f4205167350b7ed993b5cd tbz2 required \
xgts-main.tar.bz2 /
pvdrivers-win 524477 37ea0c145f5b0d7a2740ecb69d21ed52 tbz2 required \
pvdrivers-win.tar.bz2 /
dom0fs 169875708 c1a86d705915eda16cca84cccffaca9f tbz2 required \
dom0fs.tar.bz2 /

C.3.5. Notes on best practice

If a driver disk is used, any tbz2 packages on it will also be installed to the target. However, a copy of the repository will be taken so that the drivers can be loaded at runtime; this copy is placed into memory. Therefore, if you are constructing a driver disk that also includes user-space tools, and if these result in a large repository, it is better to split it up into two repositories and require that people use the packages.site mechanism to install your add-ons. Alternatively, provide a post-install script to install them after the fact.