<trclass="field-odd field"><thclass="field-name">Authors:</th><tdclass="field-body">Brian C. Lane <<aclass="reference external"href="mailto:bcl%40redhat.com">bcl<span>@</span>redhat<span>.</span>com</a>></td>
</tr>
</tbody>
</table>
<p>“I am the Lorax. I speak for the trees [and images].”</p>
<p>The <aclass="reference external"href="https://github.com/rhinstaller/lorax">lorax</a> tool is used to create the
<aclass="reference external"href="https://github.com/rhinstaller/anaconda">Anaconda</a> 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.</p>
<divclass="section"id="quickstart">
<h2>Quickstart<aclass="headerlink"href="#quickstart"title="Permalink to this headline">¶</a></h2>
<p>Run this as root to create a boot.iso in <ttclass="docutils literal"><spanclass="pre">./results/</span></tt>:</p>
<p>You can add your own repos with <ttclass="docutils literal"><spanclass="pre">-s</span></tt> and packages with higher NVRs will
override the ones in the distribution repositories.</p>
<p>Under <ttclass="docutils literal"><spanclass="pre">./results/</span></tt> will be the release tree files: .discinfo, .treeinfo, everything that
goes onto the boot.iso, the pxeboot directory, and the boot.iso under <ttclass="docutils literal"><spanclass="pre">./images/</span></tt>.</p>
</div>
<divclass="section"id="how-it-works">
<h2>How it works<aclass="headerlink"href="#how-it-works"title="Permalink to this headline">¶</a></h2>
<p>Lorax uses <aclass="reference external"href="https://github.com/rpm-software-management/dnf">dnf</a> 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.</p>
<p>To drive these processes Lorax uses a custom template system, based on <aclass="reference external"href="http://www.makotemplates.org/">Mako
templates</a> with the addition of custom
commands (documented in <aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner"title="pylorax.ltmpl.LoraxTemplateRunner"><ttclass="xref py py-class docutils literal"><spanclass="pre">pylorax.ltmpl.LoraxTemplateRunner</span></tt></a>). Mako
supports <ttclass="docutils literal"><spanclass="pre">%if/%endif</span></tt> blocks as well as free-form python code inside <ttclass="docutils literal"><spanclass="pre"><%</span>
<spanclass="pre">%></span></tt> tags and variable substitution with <ttclass="docutils literal"><spanclass="pre">${}</span></tt>. The default templates are
shipped with lorax in <ttclass="docutils literal"><spanclass="pre">/usr/share/lorax/templates.d/99-generic/</span></tt> and use the
<h3>runtime-install.tmpl<aclass="headerlink"href="#runtime-install-tmpl"title="Permalink to this headline">¶</a></h3>
<p>The <ttclass="docutils literal"><spanclass="pre">runtime-install.tmpl</span></tt> template lists packages to be installed using the
<ttclass="docutils literal"><spanclass="pre">installpkg</span></tt> command. This template is fairly simple, installing common packages and
architecture specific packages. It must end with the <ttclass="docutils literal"><spanclass="pre">run_pkg_transaction</span></tt>
command which tells dnf to download and install the packages.</p>
</div>
<divclass="section"id="runtime-postinstall-tmpl">
<h3>runtime-postinstall.tmpl<aclass="headerlink"href="#runtime-postinstall-tmpl"title="Permalink to this headline">¶</a></h3>
<p>The <ttclass="docutils literal"><spanclass="pre">runtime-postinstall.tmpl</span></tt> 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:</p>
<ulclass="simple">
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.append"title="pylorax.ltmpl.LoraxTemplateRunner.append"><ttclass="xref py py-func docutils literal"><spanclass="pre">append</span></tt></a> to add text to a file.</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.chmod"title="pylorax.ltmpl.LoraxTemplateRunner.chmod"><ttclass="xref py py-func docutils literal"><spanclass="pre">chmod</span></tt></a> changes the file’s mode.</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.install"title="pylorax.ltmpl.LoraxTemplateRunner.install"><ttclass="xref py py-func docutils literal"><spanclass="pre">install</span></tt></a> to install a file into the installroot.</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.mkdir"title="pylorax.ltmpl.LoraxTemplateRunner.mkdir"><ttclass="xref py py-func docutils literal"><spanclass="pre">mkdir</span></tt></a> makes a new directory.</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.move"title="pylorax.ltmpl.LoraxTemplateRunner.move"><ttclass="xref py py-func docutils literal"><spanclass="pre">move</span></tt></a> to move a file into the installroot</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.replace"title="pylorax.ltmpl.LoraxTemplateRunner.replace"><ttclass="xref py py-func docutils literal"><spanclass="pre">replace</span></tt></a> does text substitution in a file</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.remove"title="pylorax.ltmpl.LoraxTemplateRunner.remove"><ttclass="xref py py-func docutils literal"><spanclass="pre">remove</span></tt></a> deletes a file</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.runcmd"title="pylorax.ltmpl.LoraxTemplateRunner.runcmd"><ttclass="xref py py-func docutils literal"><spanclass="pre">runcmd</span></tt></a> run arbitrary commands.</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.symlink"title="pylorax.ltmpl.LoraxTemplateRunner.symlink"><ttclass="xref py py-func docutils literal"><spanclass="pre">symlink</span></tt></a> creates a symlink</li>
<li><aclass="reference internal"href="pylorax.html#pylorax.ltmpl.LoraxTemplateRunner.systemctl"title="pylorax.ltmpl.LoraxTemplateRunner.systemctl"><ttclass="xref py py-func docutils literal"><spanclass="pre">systemctl</span></tt></a> runs systemctl in the installroot</li>
</ul>
</div>
<divclass="section"id="runtime-cleanup-tmpl">
<h3>runtime-cleanup.tmpl<aclass="headerlink"href="#runtime-cleanup-tmpl"title="Permalink to this headline">¶</a></h3>
<p>The <ttclass="docutils literal"><spanclass="pre">runtime-cleanup.tmpl</span></tt> template is used to remove files that aren’t strictly needed
by the installation environment. In addition to the <ttclass="docutils literal"><spanclass="pre">remove</span></tt> template command it uses:</p>
<h3>The squashfs filesystem<aclass="headerlink"href="#the-squashfs-filesystem"title="Permalink to this headline">¶</a></h3>
<p>After <ttclass="docutils literal"><spanclass="pre">runtime-*.tmpl</span></tt> 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.</p>
</div>
<divclass="section"id="iso-creation">
<h3>iso creation<aclass="headerlink"href="#iso-creation"title="Permalink to this headline">¶</a></h3>
<p>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
<ttclass="docutils literal"><spanclass="pre">/usr/share/lorax/templates.d/99-generic</span></tt> and are named after the arch, like
<ttclass="docutils literal"><spanclass="pre">x86.tmpl</span></tt> and <ttclass="docutils literal"><spanclass="pre">aarch64.tmpl</span></tt>. They handle creation of the tree, copying
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
