Debian ramdisk builder
----------------------

This directory contains an auto-build system for making a minimal Debian
system, suitable for including in a ramdisk.  It is tested and known to
build when run on a Debian system.  It requires that you are running a
system with the apt and dpkg software.  See below for building on Ubuntu.

It currently only creates a very minimal debian system, however it is
intended that additional configuration can be added at both build time
and at runtime for specific use cases (see the Configuration sections, below)

Usage:

    make build-depends          # install needed build packages

    make build/debian.stretch.armhf.cpio  # creates the root filesystem archive

After making sure the needed packages are installed, you just need to
run the full build.  The resulting image can be used to build a ramdisk
install - see the boards directory for various builders

Build time Configuration
------------------------

The various fixups and customisation that are applied to the basic Debian
installation can be seen in the packages.d directory (See the README
in that dir for more details on the layout of that directory).

To customise the system built for differing use cases, it is possible to
add a "config overlay".  This consists of a directory which optionally
extra configuration files to be used during the build.

To activate one or more config overlays, ensure that your environment has
exported a "CONFIGDIRS" variable - this variable is a list of the
directories to search for the overlays.  Configuration will be applied in
the order listed in this variable and the directories will be interpreted
relative to the builder directory - so use fully qualified pathnames to
ensure correctness.  Finally, the normal directory is only searched if it
is included in this list.

E.G:
To enable the normal processing and add one overlay after it:

    export CONFIGDIRS=". /tmp/buildoverlay"
    make build/debian.stretch.armhf.cpio

It is expected that this build system will be embedded in a larger system
and used as a tool - thus the larger build system will set the CONFIGDIRS
variable correctly.

Files that will be taken from the CONFIGDIRS:

debian.$(CONFIG_DEBIAN).multistrap
    This is the main multistrap config file.  If more than one of these files
    exists in the CONFIGDIRS then only the last defined one will be used.
    When replacing this config file with your own, be aware that the list of
    additional packages (from all the packages.txt files) will be simply
    appended to the final multistrap config.
packages.txt
    These files contain a list of additional packages to install in the
    buildroot.  All packages.txt files found in all the CONFIGDIRS will be
    appended to make the complete list of packages to install.  These are
    simply appeneded to the multistrap config file.
packages.d
    The files in these directories are used to apply changes to the installed
    buildroot.  See the README in the main packages.d file for the full list
    of what filed are loaded from here.
    All the package minimisation/fixup/add phases will look in every CONFIGDIR
    to find settings to apply - all matching files all the CONFIGDIRS will be
    applied.

Runtime Configuration
---------------------

During bootup - and before systemd starts - the scripts will scan all found
block devices looking for filesystems with a "/conf.d" directory in their
root and load any configuration found.  This script will not load any kernel
modules, so unless the block driver and filesystem have been statically
compiled, it will not find the filesystem.

These configuration files are simply tar.gz archives or sh scripts. First,
archives are extracted, in alphabetical order to /etc of the ramdisk, so files
in an archive towards the end of the list will overwrite those from an earlier
archive in case of a filename conflict. After all archives are extracted, scripts
are executed in alphabetical order. These steps occur before systemd starts so
systemd will only see the final (highest priority) configurations and after
effects of the scripts are applied.

For example:

    /conf.d/00-tomesh-base.tar.gz
            10-tomesh-wlan-mesh-top-gs07-rt5572.tar.gz
            11-tomesh-wlan-hostap-tplink-tl-wn722n.tar.gz
            50-node-config-save.tar.gz
            90-user-custom-configs.tar.gz
            bootstrap.sh

This allows local communities to customize nodes by distributing archives
of systemd.network configuration files, or any files that are to be read from
/etc. The user simply mounts the fat filesystem like a USB key and drops tar.gz
files into conf.d and can easily back them up across software updates.

If while running, you wish to save the current configuration, the
"config_save" script can be used to save the current /etc directory into an
archive called 50-node-config-save.tar.gz on the first block device found that
has a /conf.d directory.

Building on Ubuntu
------------------

During building, all downloaded Debian packages are verified before use.  This
verification requires the Debian keyring to work.  When using Ubuntu, the
Debian keyring is not installed by default.  The following command will install
the Debian keyring package and allow the verification:

    sudo apt-get install debian-archive-keyring

Note:  Ubuntu 14.04 is shipping a broken version of multistrap, which
will fail with an error message like:

    Global symbol "$forceyes" requires explicit package name at /usr/sbin/multistrap line 989."

The error is present in version 2.2.0ubuntu1 and fixed in 2.2.0ubuntu2.
A workaround for this is to manually edit the line:

    sudo sed -i '989s/$forceyes//' /usr/sbin/multistrap

Applying the following patch will also fix the problem:

--- 1/usr/sbin/multistrap	2014-02-22 15:27:42.000000000 +0800
+++ 2/usr/sbin/multistrap	2014-05-13 13:32:36.000000000 +0800
@@ -986,7 +986,7 @@
 	}
 	# reinstall set
 	foreach my $reinst (sort @reinstall) {
-		system ("$str $env chroot $dir apt-get --reinstall -y $forceyes install $reinst");
+		system ("$str $env chroot $dir apt-get --reinstall -y install $reinst");
 	}
 	&run_native_hooks_end(sort @{$hooks{'N'}}) if (defined $hooks{'N'});
 	return $retval;


TODO
----

A quick list of things that probably need doing:
(sorted vaguely by importance)

* Ensure ssh keys are not saved in image and are regenerated if needed
* Complete the config load and config save scripts
* Add some extra randomness into image
* Load any extra randomness found on boot media
* Check all the available 802.11s flags and use the appropropriate ones
* use a known prefix for tunnel names to allow stable iptables rules and
  coexistance with other tunnel systems
* Write script for generating a basic config file to merge with image
* Use a better default access point name and PSK
* Use a better default root password
* Look for better options for the cjdns package
* look for a IPFS package
* u-boot rules to boot of one or the other of the initramfs images on fallback
* maybe add udev persistent-net-generator.rules - style network interface naming
* config storage - what about SPI flash?