OZ-EXAMPLES(5)

📦 version 0.18.1, in fedora 43, fedora 44

OZ-EXAMPLES(5) 💖

okay bestie, this is the File Formats Manual page for oz-examples, and it's literally the cheat sheet for all the TDL files you're gonna feed to Oz. pull up a chair 🫶

✨ NAME ✨

oz-examples — example TDL files for Oz, no cap 💅

🌸 DESCRIPTION 🌸

so the oz-install(1), oz-customize(1), and oz-generate-icicle(1) man pages already explain the command-line usage of the Oz commands, right? but every single one of those commands needs a TDL file as input. TDL = Template Description Language, and it's the thing that describes:

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

this man page walks through a bunch of TDL examples and explains what happens when you actually use them. and because TDL is XML, we use standard XPath notation to talk about the different XML elements. iykyk 🧚

💜 EXAMPLE 1 - Minimal guest 💜

okay so imagine we want to install a minimal Fedora 13 x86_64 operating system from a Fedora 13 DVD ISO sitting 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 looks like this:

<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's break it down, shall we? 🎀

  • /template/name — this is a user-defined name. it can literally be anything you want, BUT it has to be unique among all the TDLs you wanna build. no duplicates bestie.
  • /template/os/name — the name of the operating system we want to install.
  • /template/os/version — the version we want.
  • /template/os/arch — the architecture we want.

want the full list of supported operating systems? just run:

# 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. (other install methods besides ISO are supported, and they get described in the other examples, don't worry 💖)

/template/description is an optional, human-readable description of the template. it can be anything you want, and Oz just straight up ignores it 🙈

and that's all the input Oz needs. to actually do the install, save the above to a file (say fedora13.tdl), 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 lands on a file at /var/lib/libvirt/images/fedora13_x86_64.dsk (by default — the output location can be overridden in the configuration file). slay 🔥

🌈 EXAMPLE 2 - Guest with additional packages 🌈

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

AND we also 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 looks 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 this is like, so similar to Example 1, except we specified an additional package to be installed in the /packages/package portion of the TDL. multiple packages can go here, and they'll 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 works the same way as Example 1, except we gotta 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. curious why this approach is used? go check out 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 lands on a file at /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 want a RHEL-5 x86_64 operating system from a RHEL-5 DVD ISO at http://example.org/rhel-5-x86_64.iso

AND 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 looks 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 basically Example 1 again, except we want RHEL-5 instead of Fedora-13. periodt 💅

running the installation is done the same way as in Example 1, except we gotta 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'll then output an XML document (called an ICICLE) describing the entire manifest. iconic ✨

assuming this step succeeds, the minimal operating system will be installed on a file at /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 want a RHEL-6 x86_64 operating system from a RHEL-6 DVD ISO at http://example.org/rhel-6-x86_64.iso

AND 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 looks 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 this is very similar to Example 2, except we've specified an additional repository to download packages from. the /repositories/repository section of the TDL specifies 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 set up the additional repositories and install the additional packages. wanna know why this approach is used? go read 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 lands on a file at /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 want a RHEL-6 x86_64 operating system from a RHEL-6 DVD ISO at http://example.org/rhel-6-x86_64.iso

AND 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 looks 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 go here, and they'll 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 🔗

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. wanna know why this approach is used? check out 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 lands on a file at /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 so picture this: we wanna install a RHEL-6 x86_64 operating system, and the DVD ISO lives at http://example.org/rhel-6-x86_64.iso ✨

and ALSO (yes there's more, we're multitasking, main character energy 💅) we wanna write some data to the file /etc/test.out inside the guest. and because that data might be straight-up binary (spooky, unpredictable, not text-safe 😭), the move is to base64 encode it first. no cap.

so to pull this install off, we first 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' type='base64'>VEhJUz1leHRyYV9kYXRhCg==</file>
  </files>
</template>

multiple files can be specified here, and they will all be installed on the operating system in the specified locations. literally all of them, it's giving assembly line 🌸

and here's the tea on how you can specify files — three whole flavors:

  • inline in raw text in the TDL
  • as base64 encoded data in the TDL
  • as URLs

and to make any of this work, we NEED to run the installation with customization:

# 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. iconic behaviour, 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. and if you're sitting there like "bestie whyyy this approach though" — valid question, and the answer lives in the Oz Architecture document at http://github.com/clalancette/oz/wiki/Oz-architecture 📚

and 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 7 - Install a custom file from a URL 🦋

bestie we're back and it's basically the same vibe but with a glow-up ✨

assume we want to 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, we want to write some data to the file /etc/test.out inside the guest — but THIS time we wanna fetch that data from a URL and upload it into the guest. remote data, walking in like it owns the place 💅

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' type='url'>http://example.org/orig.out</file>
  </files>
</template>

same deal as before, multiple files can be specified here, and they will all be installed on the operating system in the specified locations. and the three ways to specify files stay exactly the same:

  • inline in raw text in the TDL
  • as base64 encoded data in the TDL
  • as URLs

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. yes it's the same sentence, no we're not sorry, it's just what happens 😌

assuming the initial install succeeds, Oz will then boot the operating system and run native commands to upload the files specified in the TDL. and for more info on 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 💖

go read these next, they're the whole friend group, iykyk:

👑 AUTHOR 👑

this masterpiece was brought to you by Chris Lalancette <clalancette@gmail.com> — give them their flowers fr fr 🌸

and that's a wrap on OZ-EXAMPLES(5) bestie 🎀 this page is oz-examples, dated July 2013, and it's filed under OZ-EXAMPLES(5). go forth and build your guests, you absolute legend 💅✨🦋
📦 where this page comes from