OZ-EXAMPLES(1)

📦 version 0.17.0, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 oz-examples 💖

okay bestie, so this is the oz-examples(1) page from the General Commands Manual, and it's genuinely SO useful, you're gonna love it 💅

✨ NAME ✨

oz-examples — example TDL files for Oz. yes that's it, that's the name, slay.

🌸 DESCRIPTION 🌸

okay so first things first: the oz-install(1), oz-customize(1), and oz-generate-icicle(1) man pages are the ones that walk you through the actual command-line usage of the Oz commands. but literally every single one of those commands needs the same required input, and that input is a TDL file — that's a Template Description Language file, iykyk.

a TDL describes:

  • the OS you want to install 👑
  • where to get the media from 📀
  • any extra packages or actions you wanna do on that operating system ✨

and this man page? it's the vibe tour. it walks you through a bunch of TDL examples and tells you exactly what happens when you use them. the TDL is XML, so standard XPath notation is used to describe the various elements of the XML. no cap.

🌈 EXAMPLE 1 - Minimal guest 🌈

so like, imagine we wanna install a minimal Fedora 13 x86_64 operating system from a Fedora 13 DVD ISO located at http://example.org/fedora-13-x86_64.iso

to do this install we first build a TDL XML file, then feed it to oz-install. the TDL file would look like:

<template>
  <name>fedora13_x86_64</name>
    <os>
      <name>Fedora</name>
      <version>13</version>
      <arch>x86_64</arch>
      <install type='iso'>
        <iso>http://example.org/fedora-13-x86_64.iso</iso>
      </install>
    </os>
  <description>My Fedora 13 x86_64 template</description>
</template>

let me break it down for you because the way this works is actually so clean:

  • /template/name is a user-defined name. it can be literally anything you want, but it must be unique among all TDLs you wanna build. no duplicates bestie, pick your fave.
  • /template/os/name is the name of the operating system we want to install, /template/os/version is the version we want, and /template/os/arch is the architecture we want. you can get a full list of supported operating systems by running:
# oz-install -h
  • /template/os/install tells Oz where to get the installation media from. in this example, we set type to 'iso' which means we need an <iso> element in the XML pointing to the ISO install media. (install methods other than ISO are supported, and described in other examples. stay tuned 🦋)
  • /template/description is an optional, human-readable description of the template. it can be anything the user wants, and it's ignored by Oz. so write your little heart out, it doesn't matter 💖

and that's literally all of the input Oz needs. to actually do the installation, save the above to a file (say fedora13.tdl), and then run oz-install:

# oz-install /path/to/fedora13.tdl

running this command will download and prepare the installation media, then run an automated install in a KVM guest. assuming the install succeeds, the minimal operating system will be installed on a file in /var/lib/libvirt/images/fedora13_x86_64.dsk — by default, the output location can be overridden in the configuration file. periodt. 💅

🎀 EXAMPLE 2 - Guest with additional packages 🎀

okay so now imagine we wanna install a Fedora 14 x86_64 operating system from a Fedora 14 DVD ISO located at http://example.org/fedora-14-x86_64.iso

and additionally (yes, extra credit ✨) assume we want to install the postgresql-server package on the operating system. to do this install, we first need to build a TDL XML file and then feed that to oz-install. the TDL file would look like:

<template>
  <name>fedora14_postgres</name>
  <os>
    <name>Fedora</name>
    <version>14</version>
    <arch>x86_64</arch>
    <install type='iso'>
      <iso>http://example.org/fedora-14-x86_64.iso</iso>
    </install>
  </os>
  <description>Fedora 14 x86_64 with postgres</description>
  <packages>
    <package name='postgresql-server'/>
  </packages>
</template>

notice that this is very similar to Example 1, except we specified an additional package to be installed in the /packages/package portion of the TDL. multiple packages can be specified here, and they will all be installed on the operating system. in this example, all packages are downloaded and installed from the default operating system package repositories. running the installation is done the same way as in Example 1, except we have to add a command-line parameter to actually do the customization:

# oz-install -u /path/to/fedora14.tdl

running this command will download and prepare the installation media, then run an automated install in a KVM guest.

assuming the initial install succeeds, Oz will then boot the operating system and run native commands to install the additional packages. and if you're like "bestie why tho" — for more information about why this approach is used, please see the Oz Architecture document at http://github.com/clalancette/oz/wiki/Oz-architecture. 🧚

assuming this final step succeeds, the operating system with the additional packages will be installed on a file in /var/lib/libvirt/images/fedora14_postgres.dsk — by default, the output location can be overridden in the configuration file.

💜 EXAMPLE 3 - Generate a package manifest (ICICLE) after installation 💜

okay so imagine we wanna install a RHEL-5 x86_64 operating system from a RHEL-5 DVD ISO located at http://example.org/rhel-5-x86_64.iso

and additionally assume we want to get a package manifest out of the operating system after the install is done. to do this install, we first need to build a TDL XML file and then feed that to oz-install. the TDL file would look like:

<template>
  <name>rhel5_x86_64</name>
  <os>
    <name>RHEL-5</name>
    <version>U6</version>
    <arch>x86_64</arch>
    <install type='iso'>
      <iso>http://example.org/rhel-5-x86_64.iso</iso>
    </install>
  </os>
  <description>RHEL-5 x86_64</description>
</template>

this is essentially the same as Example 1, except we want to install RHEL-5 instead of Fedora-13. little swap, big energy.

running the installation is done the same was as in Example 1, except we have to add a command-line parameter to generate the manifest at the end:

# oz-install -g /path/to/rhel5.tdl

running this command will download and prepare the installation media, then run an automated install in a KVM guest.

assuming the initial install succeeds, Oz will then boot the operating system and run native commands to query all of the packages in the system. it will then output an XML document (called an ICICLE 🧊) describing the entire manifest.

assuming this step succeeds, the minimal operating system will be install on a file in /var/lib/libvirt/images/rhel5_x86_64.dsk — by default, the output location can be overridden in the configuration file.

🔥 EXAMPLE 4 - Install a package from an alternate repository 🔥

okay so imagine we wanna install a RHEL-6 x86_64 operating system from a RHEL-6 DVD ISO located at http://example.org/rhel-6-x86_64.iso

and additionally assume that we want to install the ccache package from the EPEL-6 repositories on the operating system. to do this install, we first need to build a TDL XML file and then feed that to oz-install. the TDL file would look like:

<template>
  <name>rhel6_ccache</name>
  <os>
    <name>RHEL-6</name>
    <version>1</version>
    <arch>x86_64</arch>
    <install type='iso'>
      <iso>http://example.org/rhel-6-x86_64.iso</iso>
    </install>
  </os>
  <description>RHEL-6 x86_64 with ccache</description>
  <repositories>
    <repository name='epel-6'>
      <url>http://download.fedoraproject.org/pub/epel/6/$basearch</url>
      <signed>yes</signed>
    </repository>
  </repositories>
  <packages>
    <package name='ccache'/>
  </packages>
</template>

notice that this is very similar to Example 2, except we have specified an additional repository from which to download packages. the /repositories/repository section of the TDL specified the URL to the package repository along with whether the packages in the repository are signed. running the installation is done the same way as in Example 2:

# oz-install -u /path/to/rhel6_ccache.tdl

running this command will download and prepare the installation media, then run an automated install in a KVM guest.

assuming the initial install succeeds, Oz will then boot the operating system and run native commands to setup the additional repositories and install the additional packages. for more information about why this approach is used, please see the Oz Architecture document at http://github.com/clalancette/oz/wiki/Oz-architecture. 💅

assuming this final step succeeds, the operating system with the additional packages will be installed on a file in /var/lib/libvirt/images/rhel6_ccache.dsk — by default, the output location can be overridden in the configuration file.

🦋 EXAMPLE 5 - Install a custom file from information in the TDL 🦋

okay so imagine we wanna install a RHEL-6 x86_64 operating system from a RHEL-6 DVD ISO located at http://example.org/rhel-6-x86_64.iso

and additionally assume that we want to write some data to the file /etc/test.out inside the guest. to do this install, we first need to build a TDL XML file and then feed that to oz-install. the TDL file would look like:

<template>
  <name>rhel6_testout</name>
  <os>
    <name>RHEL-6</name>
    <version>1</version>
    <arch>x86_64</arch>
    <install type='iso'>
      <iso>http://example.org/rhel-6-x86_64.iso</iso>
    </install>
  </os>
  <description>RHEL-6 x86_64 with test.out</description>
  <files>
    <file name='/etc/test.out'>THIS=extra_data</file>
  </files>
</template>

multiple files can be specified here, and they will all be installed on the operating system in the specified locations. and the way files can be specified is lowkey flexible — inline in raw text in the TDL, as base64 encoded data in the TDL, or as URLs. 💖 we need to run the installation with customization for this to work:

# oz-install -u /path/to/rhel6_testout.tdl

running this command will download and prepare the installation media, then run an automated install in a KVM guest.

assuming the initial install succeeds, Oz will then boot the operating system and run native commands to upload the files specified in the TDL. for more information about why this approach is used, please see the Oz Architecture document at http://github.com/clalancette/oz/wiki/Oz-architecture. 🫶

assuming this final step succeeds, the operating system with the additional files will be installed on a file in /var/lib/libvirt/images/rhel6_testout.dsk — by default, the output location can be overridden in the configuration file.

🌸 EXAMPLE 6 - Install a custom file from base64-encoded information in the TDL 🌸

Okay bestie, picture this: we want a RHEL-6 x86_64 operating system, and the install media is a RHEL-6 DVD ISO chilling at http://example.org/rhel-6-x86_64.iso. Iconic.

Now additionally, say we wanna write some data into the file /etc/test.out inside the guest. And because that data might be straight-up binary (💀), we're gonna base64 encode it first. To pull off this install we gotta build a TDL XML file and then hand it over to oz-install. The TDL file would look like this, no cap:

<template>
  <name>rhel6_testout</name>
  <os>
    <name>RHEL-6</name>
    <version>1</version>
    <arch>x86_64</arch>
    <install type='iso'>
      <iso>http://example.org/rhel-6-x86_64.iso</iso>
    </install>
  </os>
  <description>RHEL-6 x86_64 with test.out</description>
  <files>
    <file name='/etc/test.out'
type='base64'>VEhJUz1leHRyYV9kYXRhCg==</file>
  </files>
</template>

✨ So here's the tea: you can specify multiple files right there, and every single one of them gets installed onto the operating system at the locations you named. And files can show up in the TDL as inline raw text, as base64 encoded data, or as URLs. Three vibes, one tag. 🫶

We need to run the installation with customization for this to work, though — it's not optional:

# oz-install -u /path/to/rhel6_testout.tdl

Running that command will download and prepare the installation media, then run an automated install in a KVM guest. Yes, it's doing the most, but that's the point. 💅

Assuming the initial install succeeds, Oz will then boot the operating system and run native commands to upload the files specified in the TDL. Curious why it does it this way? Go peek at the Oz Architecture document at http://github.com/clalancette/oz/wiki/Oz-architecture — it explains the whole situation.

Assuming that final step also succeeds, the operating system with the additional files will be installed on a file in /var/lib/libvirt/images/rhel6_testout.dsk (by default — you can override the output location in the configuration file, bestie, it's your world). 🌈

🦋 EXAMPLE 7 - Install a custom file from a URL 🦋

Okay so, almost the same plot: we want a RHEL-6 x86_64 operating system, installed from a RHEL-6 DVD ISO sitting at http://example.org/rhel-6-x86_64.iso. Classic.

And additionally, we want some data written to /etc/test.out inside the guest — except this time we're fetching that data from a URL and uploading it into the guest. To do this install, we first build a TDL XML file and then feed it to oz-install. The TDL file would look like:

<template>
  <name>rhel6_testout</name>
  <os>
    <name>RHEL-6</name>
    <version>1</version>
    <arch>x86_64</arch>
    <install type='iso'>
      <iso>http://example.org/rhel-6-x86_64.iso</iso>
    </install>
  </os>
  <description>RHEL-6 x86_64 with test.out</description>
  <files>
    <file name='/etc/test.out'
type='url'>http://example.org/orig.out</file>
  </files>
</template>

Again — multiple files can be specified here, and they will all be installed on the operating system in the specified locations. Files can be specified inline in raw text in the TDL, as base64 encoded data in the TDL, or as URLs. (Pick your fighter. 🎀)

And again, we need to run the installation with customization for this to work:

# oz-install -u /path/to/rhel6_testout.tdl

Running this command will download and prepare the installation media, then run an automated install in a KVM guest. Main character energy, honestly.

Assuming the initial install succeeds, Oz will then boot the operating system and run native commands to upload the files specified in the TDL. For more information about why this approach is used, please see the Oz Architecture document at http://github.com/clalancette/oz/wiki/Oz-architecture.

Assuming this final step succeeds, the operating system with the additional files will be installed on a file in /var/lib/libvirt/images/rhel6_testout.dsk (by default, the output location can be overridden in the configuration file). ⭐

💖 SEE ALSO 💖

👑 AUTHOR 👑

Chris Lalancette <clalancette@gmail.com> — thank you for your service, king. 🫡

And that's a wrap on oz-examples, bestie! This page is from the oz-examples source, version stamped July 2013, and it's filed under OZ-EXAMPLES(1). Go forth and build all the guests. 🧚💜

📦 where this page comes from