Skip to content

Oz template description language

Jump to bottom Edit New page
Xing Zhang edited this page Oct 26, 2017 · 6 revisions

Template Description Language

This page describes Template Description Language (TDL) and the structure of a TDL document. This page also provides examples of TDL files for use with Aeolus Conductor.

TDL Definition

TDL is an XML-based language for creating image templates. TDL files define aspects of a virtual machine image including operating system, installation settings, packages, and files. An Aeolus user imports TDL files into Conductor. Aeolus (specially Imagefactory and Oz) interprets these TDL files and builds them into images, which can be pushed into cloud providers.

Required TDL elements

The following is an example of a basic Fedora 15 image using 64-bit architecture:

<template version="1.0">
  <name>Fedora_15-x86_64</name>
  <os>
    <name>Fedora</name>
    <version>15</version>
    <arch>x86_64</arch>
    <install type='...'>
      ...
    </install>
    <rootpw>p@55w0rd!</rootpw>
  </os>
</template>

The elements specified in this template are required for all TDL files.

template

The template element acts as a base container for your template. It requires a version attribute to define the TDL language version.

name

The name element is a user-defined indentifier for your template.

os

The os element acts as a container for your operating system information. It requires several sub-elements: name, version, arch, install and rootpw.

The name and version elements define the operating system for the image. The name refers to the name of the operating system while the version refers to the operating system’s version. In our example, the operating system is Fedora 15:

<template version="1.0">
  ...
  <os>
    <name>Fedora</name>
    <version>15</version>
    ...
  </os>
<template>

The arch element specifies the architecture of the virtual CPU. Values include either i386 (32-bit) or x86_64 (64-bit).

The install element is a reference to the installation media. This element contains a type attribute, which defines one of two options for installation media: url or iso.

* If the type attribute is set to url, Aeolus uses a repository url that contains the operating system:

<install type='url'>
  <url>http://www.example.com/fedora/releases/15/x86_64/os/</url>
</install>
</pre>
* If the @type@ attribute is set to @iso@, Aeolus uses an @iso@ location that contains the operating system:
<pre>
<install type='iso'>
  <iso>http://www.example.com/isos/fedora_15-x86_64.iso</iso>
</install>

The rootpw element defines the root user’s password for your system.

Optional TDL elements

The following outlines optional elements in a TDL file:

description

<template version="1.0">
  <name>Fedora_15-x86_64</name>
  <description>Fedora 15 64-bit Image</description> 
<template>

The description element specifies a user-defined description of the image.

repositories

<template version="1.0">
  ...
  <repositories>
    <repository name='signed-custom-repo'>
      <url>http://custom-package-site.redhat.com/repos/unsigned_custom_repo/</url>
      <signed>True</signed>
    </repository>
    <repository name='unsigned-custom-repo'>
      <url>http://custom-rpackage-site2.redhat.com/repos/signed_custom_repo/</url>
      <signed>False</signed>
      <persisted>False</persisted>
    </repository>
  </repositories>
  ...
<template>

The repositories element contains a set of repository elements. Each repository element lists an additional repository for package installation.

A repository element requires a name attribute and a url element pointing to the repository location.

The signed element indicates the GPG signature-checking status for the repository as Boolean value. If true, Aeolus enables GPG signature checking. If false or not included, Aeolus disables GPG signature checking.

The persisted element indicates whether Aeolus keeps the repository definition on the image. If true or not included, Aeolus includes the repository definition. If false, the repository is only available during customization and does not appear on the completed image.

packages

<template version="1.0">
  ...
  <packages>
    <package name='samba'/>
    <package name='samba-client'/>
    <package name='samba-custom-package'>
      <repository>signed-custom-repo</repository>
    </package>
  </packages>
  ...
<template>

The packages element contains a set of package elements. Each package element defines an additional package to install using the name attribute.

Use the repository sub-element to define a specific repository that contains the package. Ensure to define this repository in the repositories section.

files

<template version="1.0">
  ...
  <files>
    <file name='/etc/hosts'>
127.0.0.1     localhost
::1           localhost
15.125.64.1   www.example1.com
15.125.64.2   www.example2.com
    </file>
    <file name='/tmp/binary_file' type='base64'>
VGhpcyBpcyBhbiBlbmNvZGVkIGZpbGUK
    </file>
  </files>
  ...
</template>

The files element contains a set of file elements. Each file element defines an file to create on the image.

Each file element contains a name, which indicates the location and filename on the image, and a type, which equals either raw (raw text) or base64 (Base64-encoded).

A TDL file defines the file as data within the file element. In the example above, the /etc/hosts file contains a list of customised IP hostnames.

commands/precommands

<template version="1.0">
  ...
  <commands>
    <command name="test">
echo "15.125.64.3   www.example3.com" >> /etc/hosts
    </command>
  </commands>
  ...
</template>

The commands element contains a set of command elements. Each command element runs a command post-installation of an image. The name attribute acts as an identifier for the command.

Or you can use the precommands element instead of commands, if you want to run your command before install package.

In the example above, the command appends the /etc/host with an additional IP hostname.

Element Reference Table

Read the full specification for TDL here .

A command run on an image post-installation
**Element** **Description** **Attributes** **Parents** **Children** **Required**
arch CPU architecture of the image Either `i386` or `x86_64` os Yes
cacert The certificate authority for SSL repository Yes, if `sslverify` is true
clientcert The client certificate for SSL repository Yes, if `sslverify` is true
clientkey The client key for SSL repository Yes, if `sslverify` is true
commandname=“command-name” commands
commands Container for `command` elements template command
description A user-defined description for the image template
file Defines a file to save to the image in a specific location. name=“/location/filename” files
files Container for `file` elements template file
install The installation media. Requires a `type`. type=“url&\#124;iso” os url, iso Yes
iso Location of installation media ISO file. install Yes, either `url` or `iso`
kernelparam Kernel parameters to change how the installation boots. os
key The serial key for Windows installation os Yes, if a Windows-based machine
md5sum The MD5 checksum to verify an ISO install
name (os) Defines the operating system name. Examples of choices include Fedora, RHEL6, RHEL5, Windows. os Yes
name (template) The image template’s name. template Yes
os Container for operating system information template name (os), version, arch, install, rootpw, key Yes
package Defines a package to install to the image. name=“package-name” packages repository (package)
packages Container for `package` elements template package
persisted A Boolean value indicating whether to store the repository information on the image. The default is `true`. repository
repositories Container for `repository` elements. template repository (repositories)
repository (package) Defines a target repository that contains a specific package. package
precommands Container for `command` elements template command
repository (repositories) Defines a repository that contains additional packages for installation. name=“repo-name” repositories url, signed, persisted, sslverify, cacert, clientcert, clientkey
rootpw The root password for the image. os Yes
sha1sum The SHA1 checksum to verify an ISO install
sha256sum The SHA256 checksum to verify an ISO install
signed A Boolean value to indicate whether to perform GPG signature checks. The default is `false`. repository
sslverify A Boolean value to indicate whether to use SSL for accessing the repository. The default is `false`. repository
template Base container for all TDL elements. version=“1.0” name, description, os, repositories, packages, files, commands Yes
url Location of installation media. install Yes, either `url` or `iso`
version The operating system version. os Yes

Examples

The following sections list a few examples of TDL files. Find more examples here .

Basic Image

<template>
  <name>Fedora_15</name>
  <description>Fedora 15</description>
  <os>
    <name>Fedora</name>
    <version>15</version>
    <arch>x86_64</arch>
    <install type='url'>
      <url>http://download.fedoraproject.org/pub/fedora/linux/releases/15/Fedora/x86_64/os/</url>
    </install>
  </os>
</template>

This is a basic TDL file that creates a Fedora 15 64-bit image using the main Fedora RPMs.

Image with Repositories and Packages

<template>
  <name>Fedora_15-Audrey</name>
  <description>Fedora 15 with Audrey Agent</description>
  <os>
    <name>Fedora</name>
    <version>15</version>
    <arch>x86_64</arch>
    <install type='url'>
      <url>http://download.fedoraproject.org/pub/fedora/linux/releases/15/Fedora/x86_64/os/</url>
    </install>
  </os>
  <repositories>
    <repository name='aeolusrepo'>
      <url>http://repos.fedorapeople.org/repos/aeolus/conductor/latest-release/fedora-15/x86_64/</url>
      <signed>False</signed>
    </repository>
  </repositories>
  <packages>
    <package name='aeolus-audrey-agent'/>
  </packages>
</template>

This is a TDL file that creates an Audrey-enabled Fedora 15 64-bit image. Note the additional repository (aeolusrepo) and package (aeolus-audrey-agent) will install Audrey Agent to your image.

Image with ISO Installation

<template>
  <name>opensuse.11.3</name>
  <description>OpenSUSE 11.3</description>
  <os>
    <name>OpenSUSE</name>
    <version>11.3</version>
    <arch>x86_64</arch>
    <install type='iso'>
      <iso>http://download.opensuse.org/distribution/11.3/iso/openSUSE-11.3-DVD-x86_64.iso</iso>
    </install>
  </os>
</template>

This is a TDL file for an OpenSUSE 11.3 image with installation from an ISO.

References

Add a custom footer
Add a custom sidebar
Clone this wiki locally