LORAX(1)

📦
version 44.7 · 3 versions
, in fedora 43, fedora 44

✨ LORAX(1) ✨

okay bestie, sit down, hydrate, and let me tell you about lorax 💖 this is the manual page for the lorax tool, section 1, and it's genuinely iconic.

NAME

lorax — Lorax Documentation

Authors: Brian C. Lane <bcl@redhat.com>

"I am the Lorax. I speak for the trees [and images]." 🌳💅

The lorax tool is what you use to create the Anaconda installer boot.iso, plus the basic release tree, plus the .treeinfo metadata file. Its dependencies are fairly light-weight on purpose, because it needs to be able to run in a mock chroot environment. And here's the tea: it is best to run lorax from the same release as the thing you're targeting, because the templates may have release-specific logic in them. eg. use the rawhide version to build the boot.iso for rawhide, along with the rawhide repositories. no cap. 🦋

LORAX CMDLINE ARGUMENTS ✨

Create the Anaconda boot.iso 🎀

usage: lorax [-h] -p PRODUCT -v VERSION -r RELEASE [-s REPOSITORY] [--repo REPOSITORY] [-m REPOSITORY]
             [-t VARIANT] [-b URL] [--isfinal] [-c CONFIGFILE] [--proxy HOST] [-i PACKAGE] [-e PACKAGE]
             [--buildarch ARCH] [--volid VOLID] [--macboot] [--nomacboot] [--noupgrade]
             [--logfile LOGFILE] [--tmp TMP] [--cachedir CACHEDIR] [--workdir WORKDIR] [--force]
             [--add-template ADD_TEMPLATES] [--add-template-var ADD_TEMPLATE_VARS]
             [--add-arch-template ADD_ARCH_TEMPLATES] [--add-arch-template-var ADD_ARCH_TEMPLATE_VARS]
             [--noverify] [--sharedir SHAREDIR] [--enablerepo [repo]] [--disablerepo [repo]]
             [--rootfs-size ROOTFS_SIZE] [--noverifyssl] [--dnfplugin DNFPLUGINS] [--squashfs-only]
             [--skip-branding] [--rootfs-type ROOTFSTYPE] [--dracut-conf DRACUT_CONF]
             [--dracut-arg DRACUT_ARGS] [-V]
             OUTPUTDIR

Positional Arguments

  • OUTPUTDIR — the output directory 📁 (yes she's required, she's the moment)

Named Arguments

  • -V — show program's version number and exit 👑

required arguments

  • -p, --product — product name
  • -v, --version — version identifier
  • -r, --release — release information
  • -s, --source — source repository (may be listed multiple times)

Default: []

  • --repo REPOSITORY — source dnf repository file

Default: []

Named Arguments

  • -m, --mirrorlist — mirrorlist repository (may be listed multiple times)

Default: []

  • -t, --variant — variant name

Default: ""

  • -b, --bugurl — bug reporting URL for the product

Default: "your distribution provided bug reporting tool"

  • --isfinal

Default: False

  • -c, --config — config file

Default: "/etc/lorax/lorax.conf"

  • --proxy — repo proxy url:port
  • -i, --installpkgs — package glob to install before runtime-install.tmpl runs. (may be listed multiple times)

Default: []

  • -e, --excludepkgs — package glob to remove before runtime-install.tmpl runs. (may be listed multiple times)

Default: []

  • --buildarch — build architecture
  • --volid — volume id
  • --macboot — make the iso bootable on UEFI based Mac systems

Default: True

  • --nomacboot — do not create a Mac bootable iso

Default: False

  • --noupgrade

Default: True

  • --logfile — path to logfile

Default: ./lorax.log

  • --tmp — top level temporary directory

Default: "/var/tmp/lorax"

  • --cachedir — DNF cache directory. Default is a temporary dir.
  • --workdir — work directory, overrides --tmp. Default is a temporary dir under /var/tmp/lorax
  • --force — run even when the destination directory exists

Default: False

  • --add-template — additional template for runtime image

Default: []

  • --add-template-var — set variable for runtime image template

Default: []

  • --add-arch-template — additional template for architecture-specific image

Default: []

  • --add-arch-template-var — set variable for architecture-specific image

Default: []

  • --noverify — do not verify the install root

Default: True

  • --sharedir — directory containing all the templates. Overrides config file sharedir
  • --enablerepo — names of repos to enable

Default: []

  • --disablerepo — names of repos to disable

Default: []

  • --rootfs-size — size of root filesystem in GiB. Defaults to 2.

Default: 2

  • --noverifyssl — do not verify SSL certificates

Default: False

  • --dnfplugin — enable a DNF plugin by name/glob, or * to enable all of them.

Default: []

  • --squashfs-only — ignored, provided for backward compatibility. 🫠

Default: False

  • --skip-branding — disable automatic branding package selection. Use --installpkgs to add custom branding.

Default: False

  • --rootfs-type — type of rootfs: squashfs,squashfs-ext4,erofs,erofs-ext4

Default: "squashfs"

dracut arguments: (default: )

  • --dracut-conf — path to a dracut.conf file to use instead of the default arguments. See the dracut.conf(5) manpage.
  • --dracut-arg — argument to pass to dracut when rebuilding the initramfs. Pass this once for each argument. NOTE: this overrides the defaults. 😭

QUICKSTART 🚀

Run this as root to create a boot.iso in ./results/:

dnf install lorax
setenforce 0
lorax -p Fedora -v 38 -r 38 \
-s http://dl.fedoraproject.org/pub/fedora/linux/releases/38/Everything/x86_64/os/ \
-s http://dl.fedoraproject.org/pub/fedora/linux/updates/38/Everything/x86_64/ \
./results/
setenforce 1

You can add your own repos with -s, and packages with higher NVRs will override the ones in the distribution repositories. 💅

Under ./results/ you'll find the release tree files: .discinfo, .treeinfo, literally everything that goes onto the boot.iso, the pxeboot directory, and the boot.iso under ./results/images/. 🎀

BRANDING 🎨

By default lorax will search for the first package that provides system-release that doesn't start with generic-, and it will install it. Then it selects a corresponding logo package by taking the first part of the system-release package name and appending -logos to it. eg. fedora-release and fedora-logos. ✨

Variants

If a variant is passed to lorax it will select a system-release package that ends with the variant name. eg. passing --variant workstation will select the fedora-release-workstation package if it exists. It selects a logo package the same way it does for non-variants. eg. fedora-logos. 🌸

If there is no package ending with the variant name, it will fall back to using the first non-generic package providing system-release. 🦋

Custom Branding

If --skip-branding is passed to lorax it will skip selecting the system-release and logos packages, and leave it up to the user to pass any branding related packages to lorax using --installpkgs. When using skip-branding you must make sure that you provide all of the expected files, otherwise Anaconda may not work as expected. See the contents of fedora-release and fedora-logos for examples of what to include. 👑

Note that this does not prevent something else in the dependency tree from causing these packages to be included. Using --excludepkgs may help if they are unexpectedly included. ⚠️

RUNNING INSIDE OF MOCK 📦

As of mock version 2.0 you no longer need to pass --old-chroot. You will, however, need to pass --enable-network so that the mock container can download packages. 🫶

Older versions of mock, between 1.3.4 and 2.0, will need to pass --old-chroot to mock. These versions of mock default to using systemd-nspawn which cannot create the needed loop device nodes. Passing --old-chroot will use the old system where /dev/loop* is setup for you. 💀

🔧 HOW IT WORKS 🔧

okay bestie, here's the whole ✨journey✨ of how a lorax build actually goes down, step by step, no cap:

Lorax uses dnf to install packages into a temporary directory, sets up configuration files, then removes unneeded files to save space, and creates a squashfs filesystem of the files. The iso is then built using a generic initramfs and the kernel from the selected repositories. literally the whole pipeline, chef's kiss 👨🍳💋

To drive these processes Lorax uses a custom template system, based on Mako templates with the addition of custom commands (documented in pylorax.ltmpl.LoraxTemplateRunner). Mako supports %if/%endif blocks as well as free-form python code inside <% %> tags and variable substitution with ${}. The default templates are shipped with lorax in /usr/share/lorax/templates.d/99-generic/ and use the .tmpl extension. templating girlies, this one's for you 💅

🎀 runtime-install.tmpl 🎀

The runtime-install.tmpl template lists packages to be installed using the installpkg command. This template is fairly simple, installing common packages and architecture specific packages. It must end with the run_pkg_transaction command which tells dnf to download and install the packages. like it's not optional bestie, that's the whole point 🔥

🎀 runtime-postinstall.tmpl 🎀

The runtime-postinstall.tmpl template is where the system configuration happens. The installer environment is similar to a normal running system, but needs some special handling. Configuration files are setup, systemd is told to start the anaconda.target instead of a default system target, and a number of unneeded services are disabled, some of which can interfere with the installation. A number of template commands are used here:

  • append to add text to a file.
  • chmod changes the file's mode.
  • install to install a file into the installroot.
  • mkdir makes a new directory.
  • move to move a file into the installroot
  • replace does text substitution in a file
  • remove deletes a file
  • runcmd run arbitrary commands.
  • symlink creates a symlink
  • systemctl runs systemctl in the installroot

so many little commands, each one doing its own tiny slay 💜

🎀 runtime-cleanup.tmpl 🎀

The runtime-cleanup.tmpl template is used to remove files that aren't strictly needed by the installation environment. In addition to the remove template command it uses:

  • removepkg remove all of a specific package's contents. A package may be pulled in as a dependency, but not really used. eg. sound support.
  • removefrom Removes some files from a package. A file glob can be used, or the --allbut option to remove everything except a select few.
  • removekmod Removes kernel modules

decluttering era 🧹✨

🎀 The install.img root filesystem 🎀

NOTE: 🚨 The erofs options are still experimental. They require dracut-103 or later in order for the iso to boot, and the kernel erofs driver must support the compression type selected. For more information see the erofs website.

After runtime-*.tmpl templates have finished their work lorax creates the root filesystem in the install.img file. The anaconda-dracut and dracut-live dracut modules detect the type of rootfs and mounts it for booting. There are currently four possible formats for this file:

  • Plain squashfs filesystem (DEFAULT) — This can be mounted directly and is simply a squashfs compressed root filesystem. It is created by default, when --squashfs-only, or --rootfs-type squashfs are passed to lorax.
  • squashfs compressed ext4 filesystem — This creates a LiveOS/rootfs.img ext4 filesystem of the root filesystem and then compresses that with squashfs. This is selected when passing --rootfs-type squashfs-ext4 to lorax.
  • Plain erofs filesystem — This can be mounted directly and is an erofs filesystem compressed using the lzma compression algorithm. This is created when passing --rootfs-type erofs to lorax.
  • erofs compressed ext4 filesystem — This is like the squashfs-ext4 option except that it uses erofs. It is selected when passing --rootfs-type erofs-ext4 to lorax.

When using erofs the current default is to use lzma compression. You can use the [compression.erofs] section of the lorax configuration file to pass a different compression type and arguments to the mkfs.erofs program. For example to use lz4 with extra options create a lorax.conf file with:

[compression.erofs]
type = lz4
args = -E dedupe,all-fragments -C 65536

And run the build with:

lorax -c ./lorax.conf --rootfs-type erofs ...

see? four whole formats, pick your fighter 🥊✨

🎀 iso creation 🎀

The iso creation is handled by another set of templates. The one used depends on the architecture that the iso is being created for. They are also stored in /usr/share/lorax/templates.d/99-generic and are named after the arch, like x86.tmpl and aarch64.tmpl. They handle creation of the tree, copying configuration template files, configuration variable substitution, treeinfo metadata (via the treeinfo template command). Kernel and initrd are copied from the installroot to their final locations and then xorrisofs is run to create the boot.iso 🌈

and boom, you got yourself an iso. main character energy fr fr 👑

🦋 CUSTOM TEMPLATES 🦋

The default set of templates and configuration files from the lorax-generic-templates package are shipped in the /usr/share/lorax/templates.d/99-generic/ directory. You can make a copy of them and place them into another directory under templates.d and they will be used instead if their sort order is below all other directories. This allows multiple packages to ship lorax templates without conflict. You can (and probably should) select the specific template directory by passing --sharedir to lorax.

lowkey do pass --sharedir bestie, it's giving "i know exactly which templates i want" 🫶

💖 AUTHOR 💖

Weldr Team

2024, Red Hat, Inc.

and that's a wrap on the whole page, bestie 🎀 you just read version 41.3 from Aug 12, 2024 (the LORAX(1) page) and honestly? iconic. go build something cute. periodt 💅✨🦋

📦 where this page comes from