Skip to content

Operating Details

Jump to bottom
Benn edited this page Nov 8, 2022 · 2 revisions

sdm operates on the SD Card image in distinct phases:

  • Phase 0: Operating in the logical context of your physical RasPiOS system, copying files into the RasPiOS IMG file. sdm takes care of Phase 0 for you. The Phase 0 script sdm-phase0 performs the Phase 0 copying. It will also optionally call a Custom Phase script provided by you to perform customized personal steps. See https://github.com/gitbls/sdm/wiki/Custom-Phase-Script for details.

  • Phase 1: Operating inside the IMG file and in the context of that system (via systemd-nspawn). When operating in this context, all changes made only affect the SD Card IMG, not the physical RasPiOS system on which sdm is running

    Most, but not all commands can be used in Phase 1. For instance, most systemctl commands don't work because systemd is not running in the nspawn'ed image. Importantly, however, systemctl disable and systemctl enable do work.

    Other functions you might want to do in Phase 1 include: add new users, set or change passwords, install packages, etc. In other words, you can do almost everything you want to configure a system for repeated SD card burns.

    Once sdm has started the nspawn container, it will automatically run /usr/local/sdm/sdm-phase1 to perform Phase 1 customization. As with Phase 0, your optional Custom Phase Script will be called. After Phase 1 completes, sdm will provide a command prompt inside the container unless you specified --batch, in which case sdm will exit the container. NOTE: When sdm provides a command prompt, either with Phase 1 customization or with --mount, the terminal colors are changed (if your terminal supports it) to remind you that the IMG is mounted. See https://github.com/gitbls/sdm/wiki/Terminal-Colors.

  • Post-Install: The post-install phase runs after Phase 1. In the post-install phase, custom phase scripts and plugins can count on all packages being installed, so that packages can be configured, etc.

  • Phase 3: Write the SD Card. Using the sdm --burn command, the IMG is written to the new physical SD card using dd, and the new system name is written to the SD card. This enables a single IMG file to be the source for as many Pi systems as you'd like. Of course, you can burn the SD Card using a different tool if you'd prefer, although you'll need to set the hostname with another mechanism.

  • Phase 4: Boot the newly-created SD card on a Pi. When the new system boots the first time, the systemd service sdm-firstboot.service sets WiFi Country, and any device-specific settings you've enabled (see below), and then disables itself so it doesn't run on subsequent system boots.

Once the IMG is completed (Phase 0, Phase 1, and post-install), Phase 3 and Phase 4 can be repeated as often as needed to create fresh bootable devices for one or more of your Pi fleet, configured exactly as you want them to be.

Clone this wiki locally