OZ-INSTALL(1)

📦
version 0.18.1 · 2 versions
, in fedora 43, fedora 44

💖 OZ-INSTALL 💖 (that's section 1 of the general commands manual, bestie)

okay so. oz-install — she's the tool that automatically installs operating systems into files. like, whole entire OSes. into a file. no cap. 🦋

✨ NAME ✨

oz-install — the tool that automatically installs operating systems into files. that's her. that's the whole vibe.

🌸 SYNOPSIS 🌸

oz-install [OPTIONS] <tdl-file>

🎀 DESCRIPTION 🎀

so here's the tea ☕: this is a tool that automatically installs an operating system into files that represent disk images. the input is an XML file that describes the operating system and the packages you want installed. <tdl-file>, she's the one.

and by default (and honestly, by design, it's giving intentional) the first stage of the install only installs a JEOS — a Just Enough Operating System. like, the bare minimum. the little starter pack. customization, including installing extra packages, is also possible, but it needs extra flags. she's not doing it for free. 💅

⚠️ heads up bestie: oz-install does the actual installation using a combination of KVM and libvirt, so BOTH of these have to be available (and actually working, not just installed and vibing) for oz-install to have a chance to succeed. if they're not working, she's not working. periodt.

✨ OPTIONS ✨

  • -a <auto> — use the user-provided auto installation file auto. by default, Oz uses a hard-coded auto-installation file (kickstart, preseed, sif, etc.) to do a basic OS install. with this option you get to hand her your own alternate auto-installation file instead. the caveat though: user-provided auto-installation files are more likely to cause installation errors, so use this one with caution. 😭
  • -b <disk_bus> — use disk_bus for the storage device while doing the install. normally Oz already knows the appropriate disk bus for each guest OS it installs (ide or virtio), it's built in. this option lets you override that default with your own choice.
  • -c <config> — get the configuration from config file config instead of the default /etc/oz/oz.cfg. if neither one exists, Oz will use sensible defaults, she's got you. the config file is in standard ini format; for the full explanation of the sections and keys, see the CONFIGURATION FILE section below. 🫶
  • -d <loglevel> — turn on debugging output to level loglevel. the log levels are:
    • 0 — errors only (this is the default)
    • 1 — errors and warnings
    • 2 — errors, warnings, and information
    • 3 — all messages
    • 4 — all messages, prepended with the level and classname
  • -f — force the generation of new installation media. by default, oz-install will always try to use a locally cached version of the oz-modified install media if it's available. failing that, oz-install will try to use a locally cached version of the pristine install media if it's available. this flag forces it to always download and regenerate the oz-modified install media, even if it has a local version available. so it's the "no, do it AGAIN, I don't trust the cache" flag. 🔥
  • -g — generate the ICICLE (a package manifest, with some additional metadata) after the installation is complete.
  • -h — print a short help message. she's helpful like that. 💖
  • -i <icicle> — if oz-install has been instructed to generate an ICICLE (see the -g option), it will normally write the ICICLE XML to stdout. to have oz-install write the ICICLE to a file instead, use the -i option. note that it is an error to specify -i without -g. like, she will not accept that. 💀
  • -m <mac_address> — use mac_address for the network device while doing the install. the default value is autogenerated by Oz. this option lets you override that behaviour.
  • -n <network_device> — use network_device for the network device while doing the install. by default, Oz has built-in knowledge of the appropriate network device to use while installing each guest operating system (ne2k_pci, rtl8139, virtio). this option lets you override that default with your own choice.
  • -p — cleanup old guests before installation. by default, if a guest with the same libvirt UUID, libvirt name, or diskimage already exists before Oz starts installation, Oz will abort. if this option is used, then Oz will undefine the libvirt guest with the same name or UUID and delete the diskimage, so it should be used with caution. 👀 this one does not play.
  • -s <disk> — write the disk image to disk, rather than the default of the TDL name.
  • -t <timeout> — terminate the installation of the guest in timeout seconds rather than the oz default. this value should be increased if you're running on slow storage or running multiple oz-install operations on the same machine. 🐌
📌 please note: there is a separate termination action that occurs if 300 seconds elapses with no disk activity to the operating system. this timer value is not configurable. it's not a vibe you can change, sorry bestie.
  • -u — customize the image after installation. this generally installs additional packages onto the disk image after installation. ✨
  • -x <xmlfile> — Oz will normally generate a libvirt XML file in the current working directory, suffixed with the date and time. specifying the -x option lets that filename be overridden.

🌈 CONFIGURATION FILE 🌈

the Oz configuration file is in standard INI format with several sections. if any section or configuration key is missing, Oz will use a sensible default — she's forgiving like that. 💜

for true/false configuration keys, these values turn the option on: "true", "True", "yes", "Yes". and these turn the behaviour off: "false", "False", "no", "No".

the configuration file should have the following form:

[paths]
output_dir = /var/lib/libvirt/images
data_dir = /var/lib/oz
screenshot_dir = .
sshprivkey = /etc/oz/id_rsa-icicle-gen

[libvirt]
uri = qemu:///system
type = kvm
bridge_name = virbr0
cpus = 1
memory = 1024
image_type = raw

[cache]
original_media = yes
modified_media = no
jeos = no

[icicle]
safe_generation = no

📁 the paths section

defines the paths that Oz will use for storing data.

  • the output_dir key describes where to store the images after they are built.
  • the data_dir key describes where to cache install media and use temporary storage.
  • both locations must have a decent amount of free disk space in order for Oz to work properly. like, seriously, give her room to breathe. 🍓
  • the screenshot_dir key describes where to store screenshots of failed installs.
  • the sshprivkey key describes where the ssh keys are stored, which are required by Oz to do customization of the image.

🖥️ the libvirt section

allows some manipulation of how Oz uses libvirt.

  • the uri key describes the libvirt URI to use to do the guest installation.
  • the type key defines what type of virtualization to use.
  • the bridge_name key defines which bridge Oz should place the guests that it launches on.
  • the cpus key defines how many cpus should be used inside the virtual machine.
  • the memory key defines how much memory (in megabytes) should be used inside the virtual machine.
  • the image_type key defines which output disk type should be used; this can be any value that libvirt supports.

💾 the cache section

allows some manipulation of how Oz caches data. caching data in Oz is a tradeoff between installation time and storage space, iykyk.

  • the original_media key tells Oz to cache the original installation media so that it does not have to download it the next time an install for the same operating system is requested.
  • the modified_media key tells Oz to cache the oz-modified installation media so that it does not have to download and modify it the next time an install for the same operating system is requested.
  • the jeos key tells Oz to cache the installed operating system after installation. this can significantly speed up subsequent installation of the same operating system, with the additional downside of the operating system getting out-of-date with respect to security updates. use with care. ⚠️

🧚 the icicle section

allows some manipulation of how Oz generates ICICLE output. ICICLE is a package manifest that can optionally be generated at the end of installs.

  • the safe_generation key controls whether Oz uses a throwaway overlay file while generating the ICICLE.
  • if it is set to "no" (the default), then Oz will boot up the guest at the end of the install and run the appropriate commands to generate the ICICLE.
  • if it is set to "yes", then Oz will use a throwaway overlay file while generating the ICICLE. after the ICICLE is generated, Oz will delete the backing file, leaving the original disk image pristine. ✨ iconic behaviour honestly.

👀 SEE ALSO 👀

oz-generate-icicle(1), oz-customize(1), oz-cleanup-cache(1), oz-examples(5)

👑 AUTHOR 👑

Chris Lalancette <clalancette@gmail.com>

and that's the whole page, bestie!! 🎀 this is oz-install from Aug 2011, fr fr — go forth and install some operating systems into files, you absolute main character. 💖✨🦋

📦 where this page comes from