<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<title>Structure of a larch live system</title>
<!-- (en) Add your meta data here -->
<link href="css/larchdocs.css" rel="stylesheet" type="text/css"/>
<!--[if lte IE 7]>
<link href="css/yaml/core/iehacks.css" rel="stylesheet" type="text/css" />
<![endif]-->
</head>
<body>
<!-- skip link navigation -->
<ul id="skiplinks">
<li><a class="skip" href="#col1">Skip to main content (Press Enter).</a></li>
</ul>
<div class="page_margins">
<div class="page">
<div id="top"><div id="tm"></div></div>
<!-- begin: #col1 -->
<div id="col1" role="main">
<div id="col1_content">
<div id="header" role="banner">
<h1><span><em>live Arch Linux</em> builder</span></h1>
</div>
<!-- begin: #col3 navigation column -->
<div id="col3" role="complementary">
<div id="col3_content">
<img class="indent2" alt="larch logo" src="css/screen/larch150x.png" width="150" height="150" />
<div class="vlist">
<ul>
<li><a href="index.html"><h6>Table Of Contents</h6></a></li>
<li><a href="larch_ssh.html"><h6>Next:</h6>
<div class="indent1">ssh access</div></a></li>
<li><a href="profiles.html"><h6>Previous:</h6>
<div class="indent1">Profiles</div></a></li>
</ul>
</div>
</div>
</div>
<!-- end: #col3 -->
<div class="larchdocs">
<h2 id="pagetitle" level="1">Structure of a <em>larch live</em> system</h2>
<p>The vast majority of the code that runs in a <em>live</em> system
is exactly the same as in a normal system running from hard disk.
The main differences arise through the <em>live</em> system being based on
a read-only root file-system, so various adjustments are necessary to
make the areas that must be writeable appear to be so. I say 'appear to be'
because the bulk of the underlying system is generally (as is the case in a
<em>larch</em> system) stored in a <em>squashfs</em> archive, which is not
writeable. This is overcome to some extent by using <em>aufs</em> to add
a writeable overlay.
</p>
<h3><a name="Squashfs_and_Unionfs"></a>squashfs and aufs</h3>
<p>In <em>larch</em>, as in many other <em>live</em> systems, the
ability to (apparently) write to a read-only file-system is provided by
<em>aufs</em> (originally derived from <em>unionfs</em>).
The file-system is also compressed, using <em>squashfs</em>, so as to fit
more data onto the storage device. A custom <em>Arch Linux</em> installation
(you can choose which packages are installed) is compressed into a
<em>squashfs</em> file-system in the file <strong>system.sqf</strong>,
which is placed in the '/larch' directory of the boot device.
</p>
<p>For use in a <em>live</em> system a few changes must be made to some files
in the installation. In <em>larch</em> this is usually not done directly,
the installed system is left in a 'clean' state. Instead of that, an additional
<em>aufs</em> layer is created containing all the modified files (in a writeable
system also changes made by the user will be placed in this layer). You can
include (pretty well) any customisations you like in this overlay, giving you
a great deal of freedom in designing your <em>live</em> system.
</p>
<p>When the <em>live</em> system boots an <em>aufs</em> file-system is set up
with the base system as its lowest layer (branch). The modification layer - either
the 'mods.sqf' file or the medium itself (if writeable) - is
placed above this. If the modification layer is not writeable (either inherently
or because of a boot option) a further, writeable, layer in <em>tmpfs</em>
(a memory based file-system) is added above this. The <em>aufs</em> file-system
is then used as the root file-system for the <em>live</em> system (compare with
a normal linux system where the root file-system would be a hard-disk partition).
</p>
<h3><a name="bundles"></a><em>'Bundles'</em></h3>
<p>An additional possibility inherent in <em>aufs</em> is that of including
additional code or data 'packages' - which I here call 'bundles', to distinguish
them from the normal packages managed by pacman - by adding them as further
layers (branches). This is also supported in <em>larch</em>. It is a completely
optional feature, supported in the <em>initramfs</em> code, by the 'larch' hook
(see the man-pages or the <em>Arch wiki</em> for more details on
<em>mkinitcpio</em> and <em>Arch initramfs</em> support). Bundles are simply
overlays over the root file system (like software packages) which should
be compressed into <em>squashfs</em> archives with names ending in '.sqb'.
They should be placed in the medium's '/larch/bundles' directory and during
the boot process they will be added to the <em>aufs</em> file-system in
alphabetical order directly above the base system layer.
</p>
<h3><a name="initramfs"></a><em>initramfs</em> and <em>mkinitcpio</em></h3>
<p>It is, in general, not possible to boot directly into a <em>live</em>
system.
Some form of 'initrd' or 'initramfs' is required, in order to find the boot
device and prepare the root file-system for running.
Many modern <em>GNU/Linux</em> systems use initrd/initramfs (the former
being now deprecated) as a matter of course, for loading the necessary kernel
modules, and <em>Arch Linux</em> is no exception, a modular initramfs system
(<em>mkinitcpio</em>) being the standard way to boot <em>Arch Linux</em>,
and <em>larch</em> also takes advantage of it, although some additions need
to be made to boot <em>live</em> systems.
</p>
<p><em>larch</em> adds its own 'hook' (code plug-in) to the
<em>Arch Linux mkinitcpio</em> system (the 'larch' hook is supplied in the
'larch-live' package). It performs several steps, the first of which is to
find the live medium.
</p>
<p>Note that the live medium is not necessarily the same as the
boot device (which could be a boot-cd required for booting from another
device unsupported by the machine's BIOS). The medium can be detected / selected
on the basis of a UUID, a partition label, or a partition device node
('/dev/sdb1', etc.). Alternatively, all available devices can be searched
for the file '/larch/larchboot'. Once the device has been found a simple
validity check is made by testing for the existence of '/larch/system.sqf'.
</p>
<p>An <em>aufs</em> file-system is set up and the <em>squashfs</em> archive
'system.sqf' is added as the base layer. If there are 'bundles' in the
'/larch/bundles' directory these are layered on top of the base (as
<em>aufs</em> branches).
</p>
<p>Then the modifications overlay is added (as a further <em>aufs</em>
branch), and if the overlay is read-only then another layer is added on
top of it, a writeable in-memory file-system (<em>tmpfs</em>).
</p>
<p>A few more tweaks are made to prepare the file-system for the boot
proper (see the code of the larch hook in '/lib/initcpio/hooks/larch'
for the details) and this <em>aufs</em> file-system is then used as the
root file-system for the further boot process, after leaving the
<em>initramfs</em>.
</p>
<p>In order to generate the special <em>initramfs</em> a customised
'/etc/mkinitcpio.conf' - '/etc/mkinitcpio.conf.larch' - is used, also
supplied in the 'larch-live' package (though it can be replaced by a
customised version in the profile's overlay directory - the
gui has a button for this).
</p>
<p>There is also a customized <em>mkinitcpio</em> preset,
'/etc/mkinitcpio.d/larch.preset', which is used to replace the standard
preset belonging to the kernel, so that subsequent kernel updates (etc.)
will regenerate a correct <em>initramfs</em> for the <em>larch</em> system.
If you want to revert to the normal <em>Arch Linux mkinitcpio</em> behaviour
(for example, if you are installing the system) you will need to replace
the preset by the original, which gets saved with '.larchsave' appended.
</p>
<h3><a name="rc_files"></a>/etc/rc.sysinit and /etc/rc.shutdown</h3>
<p>The initial boot script and the shutdown script must be customized for use
in a <em>larch live</em> environment. This is achieved by using hooks in the
standard /etc/rc.sysinit and /etc/rc.shutdown scripts. The file
'etc/rc.d/functions.d/larch-hooks', in the 'larch-live' package, defines these.
During startup the main tweaks are to the content of /etc/mtab and /etc/fstab.
During shutdown we probably want to disable writing to the hardware clock,
and if running from CD/DVD we will want to eject the device just before
shutting down.
</p>
<h3><a name="fstab"></a>/etc/fstab</h3>
<p>If the file '/etc/fstab.larch' exists this will be used as a persistent
'/etc/fstab', being copied there during the boot process (in the 'larch'
hook in the <em>initramfs</em> system). Otherwise a very minimal '/etc/fstab'
will be generated at each boot. It includes entries for any existing swap
partitions, but these are commented out unless the 'swap' boot parameter
is specified (the default <em>larch</em> behaviour is to mount nothing
automatically).
</p>
<p>The 'x10d_fstab' script in the 'larch-live' package allows the very basic
/etc/fstab generated by the <em>initramfs</em> system ('larch' hook) to be
extended automatically, but '/etc/fstab' will only be changed if
'/etc/fstab.larch' doesn't exist.
This script adds entries for the partitions it detects, and also mount points
in '/mnt' for them. The entries are such that the partitions are not mounted
automatically.
</p>
</div>
<div class="topref"><a href="#top">Top</a></div>
</div>
<!-- begin: #footer -->
<div id="footer">
<div id="footer-content" role="contentinfo">© 2010 Michael Towers<br />
Page layout assisted by <a href="http://www.yaml.de/">YAML</a> and
<a href="http://www.kuwata-lab.com/tenjin/">pyTenjin</a>
</div>
</div>
<!-- end: #footer -->
</div>
<!-- end: #col1 -->
<div id="bottom"><div id="bl"><div id="bm"></div></div></div>
</div>
</div>
<!-- full skiplink functionality in webkit browsers -->
<script src="css/yaml/core/js/webkit-focusfix.js" type="text/javascript"></script>
</body>
</html>