Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

What the base image contains

Every boot2deb image is the same substrate plus what its layers add. This page is the substrate. It covers what is on a board before any SoC, device, or feature package stacks on top, and why each thing is there.

How the set is built

Three inputs, in order:

  1. Debian’s required + important priority set. This is the base system — a working Debian userland with apt, systemd, bash, less, nano, vim-tiny, procps, fdisk, iputils-ping, and tzdata.
  2. The packages list in base.toml, below.
  3. The layers: arches → socs → boot-methods → devices, then any features the recipe names. Wi-Fi tooling, Mesa, bluez, and the media stack all arrive this way, because they are claims about hardware rather than about Debian.

Two properties of step 1 decide most of step 2. They are worth stating plainly, because they differ from what apt install does on a desktop:

  • Recommends are never installed. Resolution follows Depends only.
  • Priority standard is not part of the base set.

So anything an ordinary Debian install would have reached by either route is absent unless base.toml names it. ca-certificates is the case that shows why this matters. It is priority standard, and nothing Depends on it, since libcurl merely Recommends it. Without an explicit entry an image would ship curl and wget that cannot fetch an https URL.

What base.toml adds

Sizes are installed size on forky/arm64, including each package’s own dependency closure where that closure is the interesting part. They are hand-totalled from the archives’ own Installed-Size figures. boot2deb size is how to re-check one against a build that exists. --by source groups a package with the rest of its source’s output, which is the closure most of these parentheses are describing.

packageswhy
initramfs-tools, dbus, dhcpcd, libpam-systemd, systemd-timesyncd, sudoboot, session, clock, privilege. A board with no RTC gets its time from the network.
openssh-server, openssh-clientRemote access both ways. The server’s Depends already pull openssh-sftp-server, so scp/sftp to a board work without the client. The client is what provides scp, sftp, ssh-keygen, and ssh-copy-id from it. The server is enabled, so a booted board is reachable before anyone has logged in — see The account, sudo, and SSH keys.
ca-certificates, curl, wget, rsyncFetching and moving files, https included.
bind9-dnsutils (~6 MiB with bind9-libs)dig and host, for triaging a board whose network is the thing that is wrong.
unzip, zip, xz-utils, zstdArchives.
pciutils, usbutilsHardware inventory. lsusb earns its place ahead of lspci on these boards: an SBC’s peripherals are far more often on USB than on PCIe.
htop, lsof, psmisc, xxd, file (~10.6 MiB)Looking at a running system, and at bytes. Nearly all of file’s cost is libmagic-mgc, the compiled magic database.
bash-completion, man-db (~9.2 MiB)Shell usability. man-db pulls groff-base, bsdextrautils, and libpipeline1. It buys the ~3.9 MiB of manual pages every other package already puts on the image and that nothing else can read.
locales, keyboard-configuration, console-setup (~44 MiB)What makes a pre-built image reconfigurable with no network. See Locale, timezone, and keyboard.

isc-dhcp-client is excluded. dhcpcd is the DHCP client, and boards whose SoC layer brings NetworkManager exclude dhcpcd in turn.

What is deliberately absent

  • locales-all — 231 MiB installed. The 17 generated locales cost 19.2 MiB instead.
  • A desktop, a display manager, or a browser. Images are headless by default. A desktop is apt install away, and the image ships the locale data one needs to open on something other than English.
  • avahi-daemon / mDNS. It would open a listener on the LAN, which is not a default an appliance image makes for its owner.
  • unattended-upgrades. An image that silently changes itself is not one whose provenance record still describes it.
  • Storage and hardware tooling with no hardware to point at — smartmontools, nvme-cli, mtd-utils. Board-specific tools belong on the board’s layer, as i2c-tools and ir-keytable are.
  • Development toolchains. Nothing on an image builds software. That happens in the builder’s sandbox.
  • uidmap. A boot2deb image does not build boot2deb images as it ships, and this is the package that would be half of making it. doctor on a booted board reports newuidmap was not found on PATH, because the shadow suite’s setuid helpers are a separate package. uidmap is cheap — two packages and 759 KiB over this set — and the other half is not. cargo install needs a host C compiler, and build-essential adds 47 packages and just over 1 GiB. Shipping the cheap half turns two apt install lines into one and leaves the board no more able to build. So the image ships neither, and doctor names what is missing with the command for your distribution.

Adding to it yourself

There is no --package flag, for the same reason there is no build-time locale flag. An image’s contents come from the config its lock was resolved against. A package on the image is therefore a package the config named and the manifest can pin.

The question is which layer the claim belongs to:

  • base.toml takes anything true of every Debian image.
  • The SoC or device layer takes anything true of the hardware.
  • A feature takes anything a recipe opts into.

To add packages without editing the shipped tree at all, put your own layer in an overlay directory and pass --overlay. A same-named layer is deep-merged over the shipped one. See Config model and Overlays.

On a running board it is just Debian: sudo apt install tmux.