← Back to Layer Index

rpi-microboot-base

distribution v1.0.0

Microboot filesystem base plus tooling hooks to pack a minimal filesystem into a single directory suitable for post-processing to create bootable media.

Additional Documentation

This layer builds a minimal, bootable filesystem packed as a compressed initramfs. It is intended to be built on by downstream layers.

Build model

Unlike conventional layers, this layer bootstraps with variant: extract meaning that packages are unpacked into the chroot but never configured. No maintainer scripts run, so files that might otherwise be expected to exist may not. This 'donor' chroot serves as a 'parts bin' rather than the final target destination. Nothing in it ships in the final image unless something copies it out.

Important

Because the variant is extract, mmdebstrap only runs setup and extract hooks. A downstream/consumer layer that integrates with it must do so from a setup or extract hook.

Four directories matter, all beneath the chroot passed to every hook as $1:

Path Contents

$1

The donor chroot. Unpacked packages only, curated out.

$1/staging

The microboot filesystem as it is being assembled. Overlay content, busybox applet links, account files, etc.

$1/initramfs-root

What actually becomes the initramfs. Staging is synced here, then dracut-install adds binaries, libraries and modules from the donor chroot.

$1/bootfs

The boot filesystem contents, eg kernel, DTBs, firmware, config.txt, cmdline.txt and the packed initramfs.

Integration points

Boot files

config.txt and cmdline.txt are written as defaults. To replace either, copy your own into $1/bootfs from a standalone hook:

#!/bin/bash
set -euo pipefail
cp "$LAYER_DOTD/config.txt" "$1/bootfs/config.txt"

Initramfs content

Two lists drive what is curated out of the donor chroot using dracut-install which pulls in dependencies automatically. Both lists swept across the build plan, so any layer extends them by shipping fragments in its own companion directory:

<stem>.d/initramfs.list.<initsys>

Files and directories to install.

<stem>.d/modules.list

Kernel modules to install.

Fragments are appended to the base lists, which are held by IGconf_u_initramfs_list and IGconf_u_modules_list. Comments and blank lines are ignored.

For content that is not a file to curate, write directly into $1/staging or $1/initramfs-root.

Console and credentials

The console policy is a variable naming both a device and an authentication mode for the console exposed by the system.

usb-login and usb-autologin are schemes that only apply to /dev/ttyGS0, the gadget serial port. This may be useful for an image reached over a USB cable rather than a UART. This layer does not build a USB gadget: something else must create one with a CDC-ACM function.

The non-root account exists so that a service need not run as uid 0.

Warning

The busybox initramfs verifies passwords using busybox’s own crypt implementation. The pre-built Debian busybox does not support yescrypt. Generate a hashed password using bin/genpasswd <chroot>/staging, which detects this correctly.

Services

IGconf_u_services selects which of the layer’s own services start. none starts none. A service left out stays in the image, switched off.

Supported service names map to underlying units via a service-policy list which is particular to the init system.

Services from other layers are not governed by this mechanism.

Relationships

Depends on:

device-base device-user-credentials

Provides: debian-base

Configuration Variables

Declares (prefix: u):

Variable Description Default Validation Policy
IGconf_u_initsys The init system of choice for the initramfs busybox Must be one of: busybox, systemd force
IGconf_u_console Console policy for the microboot base filesystem. 'none' runs no getty, leaving no interactive console. 'login' runs a getty with a login prompt. 'autologin' runs a getty that execs a root shell without authenticating. Both login types run on the first serial console the kernel reports. 'usb-' forms are equivalent policies on /dev/ttyGS0 (gadget serial port) for an image attached over USB (needs a gadget with CDC-ACM support). none Must be one of: none, login, autologin, usb-login, usb-autologin immediate
IGconf_u_services Which of this layer's own boot services start. Services shipped by other layers are not governed here. network Comma-separated subset of: none, network immediate
IGconf_u_initramfs_list Path to a file listing files/directories to include in the microboot initramfs from the donor chroot. Resolved via dracut-install, pulling in shared library dependencies automatically. List only what you want. Not transitive dependencies. ${DOTD}/initramfs.list.${IGconf_u_initsys} Path to an existing non-empty regular file immediate
IGconf_u_modules_list Path to a file listing kernel modules to include in the microboot initramfs from the donor chroot. Resolved via dracut-install. List only what you actually want. Not transitive dependencies. ${DOTD}/modules.list Path to an existing non-empty regular file immediate
IGconf_u_init_overlay Filesystem overlay used to seed the microboot initramfs. ${DOTD}/init/${IGconf_u_initsys}/overlay Path to an existing directory immediate
IGconf_u_service_policy Applies init service policy to staging ${DOTD}/init/${IGconf_u_initsys}/service-policy Path to an existing non-empty regular file immediate
IGconf_u_dracut_install_opts Extra command-line flags passed to every dracut-install invocation. See man(8) dracut. -v String value (may be empty) immediate
IGconf_u_dracut_install_env Extra environment variables applied to every dracut-install invocation, as a space-separated KEY=value list (eg "DRACUT_LDD=/some/other/ldd DRACUT_NO_XATTR=1"). See man(8) dracut. <empty> String value (may be empty) immediate

mmdebstrap

Suite

Variant

Installs package set:

Architectures

Packages

Installs:

Mirrors

dpkgopts

aptopts

Hooks

Phase Hooks
extract extract05-console-policy, extract06-service-policy, extract10-sync-staging, extract15-collect-lists, extract20-dracut-install, extract99-pack-initramfs

Attributes

File: rpi/microboot/base.yaml

Type: static