SDM Overview

Relevant source files

• CHANGELOG.md
• Docs/Index.md
• README.md
• sdm

Purpose and Scope

This document provides a comprehensive overview of sdm (Raspberry Pi SSD/SD Card Image Manager), a command-line tool for customizing and deploying Raspberry Pi operating system images. It covers the system's purpose, high-level architecture, core execution model, and primary subsystems.

For installation procedures, see Installation and Setup. For practical examples, see Quick Start and Usage Examples. For detailed terminology definitions, see Core Concepts and Terminology. For in-depth architectural details, see System Architecture Overview.

Sources: sdm1-28 README.md1-149

What is sdm?

sdm is a management tool that automates the customization and deployment of Raspberry Pi disk images. It enables users to create consistent, ready-to-deploy SSDs and SD Cards with all desired software packages, configurations, and customizations pre-installed. The system operates on IMG files, physical devices, or directory trees, supporting reproducible builds across multiple Raspberry Pi systems.

The tool addresses several key use cases:

• Building multiple identical Raspberry Pi systems from a common base image
• Creating "golden master" images with all personal customizations pre-configured
• Distributing ready-to-use disk images without exposing sensitive host system data
• Performing system maintenance tasks on already-burned devices

Sources: sdm1-28 README.md4-23

Core Architecture Components

The system is organized into five primary layers:

Layer	Components	Purpose
Entry Points	sdm, ezsdm, install-sdm	Command-line interface and installation
Core Engine	sdm-cparse, sdm-cmdsubs, sdm-readparams	Command routing, function library, configuration
Phase Execution	sdm-phase0, sdm-phase1, sdm-spawn, sdm-firstboot	Four-phase lifecycle implementation
Extensions	Plugins, Custom Scripts	Modular functionality extensions
Specialized Systems	Encryption, Networking	Complex domain-specific subsystems

Sources: sdm369-370 sdm350

The Four-Phase Execution Model

sdm implements a signature four-phase lifecycle that separates customization operations based on execution context. This architecture enables cross-architecture image customization and handles operations that require different system states.

Phase Execution Contexts

Phase	Script	Execution Context	Primary Operations
0	sdm-phase0	Host with IMG mounted at $SDMPT	File operations, asset copying
1	sdm-phase1	Inside container (nspawn/chroot)	Package installation, system configuration
2	sdm-cmdsubs (burn functions)	Host with device access	Device writing, partition management
3	sdm-firstboot	Target system first boot	Hardware-dependent configuration

Sources: sdm17-28 sdm858-994

Phase Separation Rationale

The four-phase model addresses several technical requirements:

1. Cross-Architecture Support: Phase 1 executes inside systemd-nspawn or chroot with QEMU user-mode emulation, enabling 32-bit host systems to customize 64-bit images and vice versa.

2. Hardware Dependency Isolation: Operations requiring actual hardware (SSH key generation with hardware entropy, time synchronization) execute in Phase 3 when the target device boots.

3. File System Access Control: Phase 0 operates with direct file system access for efficient bulk file operations, while Phase 1 operates in a sandboxed environment for package installation.

4. Device-Specific Customization: Phase 2 applies per-device customizations (unique hostnames, disk IDs) to copies of the same base image.

Sources: sdm987-994 sdm752-776

Key Subsystems and Code Entities

Configuration Management

The cparams file stores system configuration and is read/written through sdm-readparams:

Configuration variables defined on the command line are written to /etc/sdm/cparams during Phase 0 by the writeconfig function at sdm133 Subsequent phases and plugins read this configuration using sdm-readparams.

Sources: sdm133 sdm979-980

Virtualization and Container Execution

The sdm-spawn script provides an abstraction layer over systemd-nspawn and chroot:

Function	Purpose	Switch
sdm_spawn	Execute command in container	--chroot forces chroot mode
initvirt	Initialize virtualization environment	Detects architecture mismatches
Cross-architecture	QEMU user-mode emulation	Automatic when needed

The system detects when the host architecture differs from the IMG architecture and automatically configures QEMU user-mode emulation. The --chroot switch sdm417 forces use of chroot instead of systemd-nspawn for compatibility with certain host operating systems.

Sources: sdm302 sdm417 sdm1001

Plugin System Architecture

Plugins are discovered from multiple sources:

• Built-in plugins in /usr/local/sdm/plugins/ (copied at sdm115-119)
• Local user plugins in /usr/local/sdm/local-plugins/ (copied at sdm120-124)
• Plugin list files specified with @filename syntax

Each plugin executes in three phases: phase 0 (host context), phase 1 (container context), and post-install (container context after all phase 1 operations complete).

Sources: sdm136-178 sdm452 sdm638-673

Primary Command Operations

The main sdm script implements several primary commands:

Command	Implementation	Purpose
--customize	sdm421 sdm886-994	Customize an IMG file through Phases 0 and 1
--burn	sdm412-413 sdm753-776	Write IMG to physical device via sdm-cmdsubs
--burnfile	sdm414-415	Create a ready-to-burn IMG file
--explore	sdm432 sdm882-885	Interactive nspawn shell into IMG
--mount	sdm444 sdm796-820	Mount IMG and drop to bash shell
--shrink	sdm466 sdm780-786	Reduce IMG file size
--extend	sdm433 sdm824-832	Increase IMG file size

Command Flow Example: Customize

Sources: sdm886-994 sdm97-134

File System Organization

The system maintains a consistent directory structure within customized images:

Directory	Purpose	Created By
/etc/sdm/	Configuration and control files	sdm102
/etc/sdm/assets/	Plugin asset storage	sdm102
/etc/sdm/0piboot/	FirstBoot startup scripts	sdm102
/etc/sdm/xpiboot/	Early FirstBoot scripts	sdm102
/etc/sdm/zzpiboot/	Late FirstBoot scripts	sdm102
/etc/sdm/history	Operation audit log	sdm103
/etc/sdm/cparams	Configuration parameters	sdm133
/usr/local/sdm/	sdm program files	sdm106 configurable via --sdmdir sdm349
/usr/local/sdm/plugins/	Built-in plugins	sdm114
/usr/local/sdm/local-plugins/	User plugins	sdm114

Sources: sdm97-134

Variable Naming Conventions

Key variables used throughout the codebase:

Variable	Purpose	Scope
$SDMPT	Mount point for IMG file	Exported environment variable
$src	Source directory for sdm files on host	sdm369
$sdmdir	Target directory for sdm in IMG	sdm349 default /usr/local/sdm
$dimg	Path to IMG file or device	sdm296 sdm480
$dimgdevname	Type: "IMG", "Device", or "Directory"	sdm297
$plugins	List of plugins to execute	sdm336
$version	sdm version string	sdm270

Sources: sdm270 sdm296-297 sdm336 sdm349 sdm369

Logging and Audit Trail

All operations are logged to multiple destinations:

1. Console output: Real-time feedback to user
2. /etc/sdm/history: Complete audit trail within the IMG sdm103
3. /etc/sdm/apt.log: APT operation details
4. System journal: FirstBoot operations logged via logtoboth and bootlog functions

The logtoboth function outputs to both the console and the history file, providing comprehensive traceability. The --redact switch sdm455 can redact sensitive information (passwords) from history files.

Sources: sdm103 sdm455

Integration with Host System

sdm integrates with the host system through several mechanisms:

• Package Dependencies: Requires binfmt-support, qemu-user-static, systemd-container, parted, gdisk, rsync, keyboard-configuration, uuid README.md41
• Loop Device Management: Dynamically allocates loop devices for IMG mounting
• QEMU User Emulation: Automatically configured for cross-architecture operations
• Privilege Requirements: Requires root privileges for disk operations; automatically re-runs with sudo if needed sdm528-533

Sources: sdm528-533 README.md38-41