From b099b3075461dd591b8175648edb0bc59f32632b Mon Sep 17 00:00:00 2001 From: "Brian C. Lane" Date: Tue, 2 Feb 2016 17:41:15 -0800 Subject: [PATCH] Add documentation for the lorax command and templates --- docs/lorax.rst | 121 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 119 insertions(+), 2 deletions(-) diff --git a/docs/lorax.rst b/docs/lorax.rst index c43be130..b62b54b0 100644 --- a/docs/lorax.rst +++ b/docs/lorax.rst @@ -1,6 +1,123 @@ -lorax +Lorax ===== -The lorax script executes the templates and create the boot.iso +:Authors: + Brian C. Lane + +"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. +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 :class:`pylorax.ltmpl.LoraxTemplateRunner`). Mako +supports ``%if/%endif`` blocks as well as free-form python code inside ``<% +%>`` tags and variable substitution with ``${}``. The templates are shipped +with lorax in /usr/share/lorax/ 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: + +* :func:`append ` to add text to a file. +* :func:`chmod ` changes the file's mode. +* :func:`gconfset ` runs gconfset. +* :func:`install ` to install a file into the installroot. +* :func:`mkdir ` makes a new directory. +* :func:`move ` to move a file into the installroot +* :func:`replace ` does text substitution in a file +* :func:`remove ` deletes a file +* :func:`runcmd ` run arbitrary commands. +* :func:`symlink ` creates a symlink +* :func:`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: + +* :func:`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. +* :func:`removefrom ` + Removes some files from a package. A file glob can be used, or the --allbut option to + remove everything except a select few. +* :func:`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/`` 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 +:func:`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 +