raffaellod / tinytium

1. Introduction
---------------

Tinytium is an initramfs generator based on Gentoo’s Portage. It features a
small set of custom utilities, while relying on BusyBox for most of its
features, which are:

•  Command-line-configurable recovery mode, which allows either local login or
   remote (SSH) access. When recovery mode is entered, a minimalist init
   system is able to set up a network connection (using DHCP if configured to
   do so) and starts an SSH daemon; syslogd is also available;

•  Support for resuming an hibernated system, automatically detecting and
   loading an hibernated image;

•  Support for UUID= and LABEL= methods for specifying partitions/volumes.



1.1. Name
---------

Tinytium is a portmanteau of “tiny” and “initium” (Latin for “beginning”),
respectively its goal and its purpose (as in “beginning of the boot process”).


2. Usage
--------

Tinytium is to be launched by executing the /build program; this will populate
the folder from which it’s executed with the generated contents for the
initramfs.

The build program is designed to be launched by kernel-gen (part of
kernel-tools), and it expects these environment variables to be set:

   CROSS_COMPILE
      Cross-compiling toolchain prefix.
   PORTAGE_ARCH
      Target architecture, using Portage’s naming convention.

When executed, Tinytium customizes and builds every necessary package, using
Portage’s standard emerge program; the packages thus built are kept in a
cache, located in /var/cache, so that regenerating the initramfs after
rebuilding a kernel won’t also cause all the packages to be rebuilt.

The easiest way to ensure your initramfs is rebuilt whenever you recompile
your kernel is to symlink the Tinyium source folder from /usr/src/initramfs.
Multiple kernel versions can be built using the same Tinytium installation;
this is achieved by keeping separate caches.


3. Contents of the generated initramfs
--------------------------------------

Owing to Tinytium’s minimalistic approach, very few packages are inserted in
the initramfs:

•  sys-apps/busybox
   Provides every basic Linux command as well as many and not-so-basic ones,
   including a shell.

•  net-misc/dropbear
   Provides a minimal SSH client and server; used to provide remote access for
   a recovery console.

•  app-editors/nano
   Easy-to-use text editor.

•  sys-fs/e2fsprogs
   Advanced ext2/3/4 diagnostic programs.

These packages are customized (beyond what USE flags allow) to reduce the
resulting size of the initramfs.


3.1. BusyBox customization
--------------------------

Tinytium supports customizing the configuration that will be used to build
BusyBox, by leveraging the USE=savedconfig feature support in
sys-apps/busybox. On the first execution, the saved configuration file will be
pulled in from the host system, which means that the resulting BusyBox
configuration will be a superset of the host system’s.

Due to BusyBox being a core component of a Tinytium-generated initramfs,
several customizations are applied on-the-fly when building the initramfs that
may override the user’s saved configuration:

•  Commands (applets) needed by the minimalistic init system of the initramfs
   generated by Tinytium (see § 5.1. Rescue shell) - e.g. awk(1);
•  Features required to make the initramfs work - e.g. the ash shell.

Tinytium will make all necessary changes to BusyBox’s configuration, and will
store the resulting saved configuration in the cache (see § 2.1. Usage).


3.2. Dependencies
-----------------

The build program will recursively pull into the initramfs any and all run-
time dependencies of the packages that make up the initramfs. This means that
there’s no need for statically-linked executables; all binaries will link to
the shared libraries built by Tinytium or these available on the host system,
and all binaries will be seamlessly bundled together in the resulting
initramfs.


4. Configuring the boot loader
------------------------------

After the initramfs has been generated by Tinytium’s build program and
packaged by kernel-gen, the boot loader should be configured to load the
initramfs for the kernel.


4.1. Loading the initramfs
--------------------------

The syntax varies from one boot loader to another, but generally, all that’s
needed is a statement specifying the absolute path to the initramfs compressed
archive.


4.2. Configuring the Tinytium-generated initramfs
-------------------------------------------------

Tinytium’s behavior can be customized dynamically via arguments specified on
the kernel’s command line.

Supported arguments (* denotes default):

•  noresume
   Don’t check for a hibernated memory image; the system will always be
   booted.

•  quiet
   Suppress most output from the kernel.

•  resume=...
   Specifies the device from which resuming from hibernation should be
   attempted. Supports UUID= and LABEL= syntax.

•  ro*
   The /init program will mount the root file system as read-only. Opposite of
   “rw”.

•  root=...
   Specifies the device containing the root file system. Supports UUID= and
   LABEL= syntax.

•  rootflags=...
   Additional flags that will be passed to the mount(8) program when mounting
   the root file system.

•  rootfstype=...
   Allows to override the file system type detection for the root file system.

•  rw
   The /init program will mount the root file system as read/write. Opposite
   of “ro”.

•  tym:break={cmdline,devs-coldplug,devs-modprobe,devs-wait,resume,mount,
   pre-init,init},...
   Breaks into rescue mode when one the specified boot stages is reached.

   TODO: document the boot stages.

•  tym:errors={panic*,shell,ssh}
   Specifies the recovery action to be taken in case of errors occurring
   during the execution of the /init program:
   •  “panic” will do just that - panic the kernel, resulting in either a halt
      or a reboot;
   •  “shell” will cause Tinytium to break into a shell with root access and
      no authentication;
   •  “ssh” will attempt to start the network interfaces as per any “tym:net”
      arguments, after which a SSH daemon will be started; upon connection, a
      remote client will be presented the same shell launched by the “shell”
      value.

•  tym:logvt=[n]
   Specifies the virtual terminal to which kernel logging should be directed,
   in case errors cause breaking into a shell;

•  tym:net.eth0=dhcp
•  tym:net.eth1=192.168.1.10/24,gw=192.168.1.1
   Network configuration. When breaking into a shell, settings like these will
   allow for networking support, which is of course necessary to support
   remote rescue shells.


5. Running the generated initramfs
----------------------------------

The Tinytium-generated initramfs is normally executed without user
intervention. However, if anything goes wrong during any of the operations
that are required to make the root file system available, Tinytium’s /init
program will break into the configured rescue shell (see § 5.1. Rescue shell).

Here’s a break-down of the execution of Tinytium’s /init program:

1. Mount the kernel-maintained devtmpfs, then start BusyBox’s mdev to process
   all hot- and cold-plugs. This is done in order to make available both the
   root file system and a possible hibernation image; Tinytium relies on
   kernel-gen to add all necessary modules into the initramfs.

2. If a hibernation image is detected, or the specified one (see § 4.2.
   Configuring the Tinytium-generated initramfs) becomes available, Tinytium
   will attempt to resume the system from hibernation.

3. When the root file system becomes available, Tinytium will mount it once,
   to retrieve the fstab(5) file and immediately remount it with the mount
   flags therein specified.

4. Switch to executing the real init program.


5.1. Rescue shell
-----------------

The rescue shell is BusyBox’s ash applet, which is launched after a few core
daemons are started by Tinytium’s minimalistic init system.

•  dropbear: SSH server;
•  net: network interfaces setup; the initial configuration is based on the
   parameters provided on the kernel command line (see § 4.2. Configuring the
   Tinytium-generated initramfs), but can be customized by editing
   /etc/svc/net in the live in-memory initramfs;
•  syslogd: system logger that redirects the kernel log to a different virtual
   terminal, configurable via kernel command line (see § 4.2. Configuring the
   Tinytium-generated initramfs).

After these services are started, the (possibly remote, if connected via SSH)
user is presented with BusyBox’s ash. Exiting ash (via Ctrl+D or exit command)
will typically result in the faulty operation to be retried if the break was
caused by an error, of it will cause the execution of /init to be resumed if
the interruption was due to request via kernel command line argument tym:break
(see § 4.2. Configuring the Tinytium-generated initramfs).




------------------------------------------------------------------------------
Copyright 2012-2015, 2017 Raffaello D. Di Napoli

This file is part of Tinytium.

Tinytium is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

Tinytium is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
Tinytium. If not, see <http://www.gnu.org/licenses/>.