Lorax¶
- Authors
Brian C. Lane <bcl@redhat.com>
"I am the Lorax. I speak for the trees [and images]."
The lorax tool is used to create the Anaconda installer boot.iso as well as the basic release tree, and .treeinfo metadata file. Its dependencies are fairly light-weight because it needs to be able to run in a mock chroot environment. It is best to run lorax from the same release as is being targeted 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.
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]
[--dracut-arg DRACUT_ARGS] [-V]
OUTPUTDIR
Positional Arguments¶
- OUTPUTDIR
Output directory
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
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
Default: True
- --nomacboot
Default: True
- --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
Use a plain squashfs filesystem for the runtime.
Default: False
dracut arguments¶
- --dracut-arg
Argument to pass to dracut when rebuilding the initramfs. Pass this once for each argument. NOTE: this overrides the default. (default: )
Quickstart¶
Run this as root to create a boot.iso in ./results/
:
dnf install lorax
setenforce 0
lorax -p Fedora -v 23 -r 23 \
-s http://dl.fedoraproject.org/pub/fedora/linux/releases/23/Everything/x86_64/os/ \
-s http://dl.fedoraproject.org/pub/fedora/linux/updates/23/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/
will be the release tree files: .discinfo, .treeinfo, everything that
goes onto the boot.iso, the pxeboot directory, and the boot.iso under ./images/
.
Running inside of mock¶
If you are using lorax with mock v1.3.4 or later you will need to pass
--old-chroot
to mock. Mock now defaults 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¶
Lorax uses dnf to install packages into a temporary directory, sets up configuration files, it 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.
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.
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.
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 installrootreplace
does text substitution in a fileremove
deletes a fileruncmd
run arbitrary commands.symlink
creates a symlinksystemctl
runs systemctl in the installroot
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
The squashfs filesystem¶
After runtime-*.tmpl
templates have finished their work lorax creates an
empty ext4 filesystem, copies the remaining files to it, and makes a squashfs
filesystem of it. This file is the / of the boot.iso's installer environment
and is what is in the LiveOS/squashfs.img file on the iso.
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
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.