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]
             [--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]] [-V]
             OUTPUTDIR

Positional arguments:

outputdir

Output directory

Options:

`-p, --product`	product name
`-v, --version`	version identifier
`-r, --release`	release information
`-s=[], --source=[]`
	source repository (may be listed multiple times)
`--repo=[]`	source dnf repository file
`-m=[], --mirrorlist=[]`
	mirrorlist repository (may be listed multiple times)
`-t, --variant`	variant name
`-b=your distribution provided bug reporting tool, --bugurl=your distribution provided bug reporting tool`
	bug reporting URL for the product
`--isfinal=False`
	Undocumented
`-c=/etc/lorax/lorax.conf, --config=/etc/lorax/lorax.conf`
	config file
`--proxy`	repo proxy url:port
`-i=[], --installpkgs=[]`
	package glob to install before runtime-install.tmpl runs. (may be listed multiple times)
`--buildarch`	build architecture
`--volid`	volume id
`--macboot=True`	Undocumented
`--nomacboot=True`
	Undocumented
`--noupgrade=True`
	Undocumented
`--logfile=./lorax.log`
	Path to logfile
`--tmp=/var/tmp`	Top level temporary directory
`--cachedir`	DNF cache directory. Default is a temporary dir.
`--workdir`	Work directory, overrides –tmp. Default is a temporary dir under /var/tmp
`--force=False`	Run even when the destination directory exists
`--add-template=[]`
	Additional template for runtime image
`--add-template-var=[]`
	Set variable for runtime image template
`--add-arch-template=[]`
	Additional template for architecture-specific image
`--add-arch-template-var=[]`
	Set variable for architecture-specific image
`--noverify=True`
	Do not verify the install root
`--sharedir`	Directory containing all the templates. Overrides config file sharedir
`--enablerepo=[]`
	Names of repos to enable
`--disablerepo=[]`
	Names of repos to disable
`-V`	show program’s version number and exit

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/.

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.
gconfset runs gconfset.
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

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 mkisofs 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.