py-pi-bake 0.0.4__py3-none-any.whl

pi_bake/__init__.py

@@ -0,0 +1,49 @@
+"""pi-bake — generate flashable, headless Raspberry Pi images.
+
+Bake `(board, os, version, hostname, ssh_pubkey, [wifi])` into a
+single `.img.gz` operator dd's to an SD card. Boot the Pi → it
+joins the network → operator can SSH in. No keyboard, no monitor,
+no `setup-alpine`.
+
+Public API (also surfaced via the `pi-bake` CLI):
+
+    from pi_bake import NodeConfig, build, list_boards, list_oses
+    out = build(
+        board="pi-zero-2-w",
+        os_name="alpine",
+        version="3.21",
+        node=NodeConfig(
+            hostname="pi-radio-1",
+            ssh_pubkey="ssh-ed25519 AAAA...",
+            wifi_ssid="totaldns-lab",
+            wifi_psk="secret",
+        ),
+        out_path="~/sdcards/pi-radio-1.img.gz",
+    )
+
+Designed to be agnostic of any specific downstream — totaldns,
+home-server projects, anything that wants a flash-and-boot Pi.
+"""
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from pi_bake.boards import Board, BOARDS, list_boards
+from pi_bake.config import NodeConfig
+from pi_bake.oses import OSImage, OSES, list_oses, resolve_image
+from pi_bake.bake import build, supports
+
+try:
+    # Distribution name on PyPI is `py-pi-bake`; importlib.metadata
+    # reads it from the installed dist-info, which setuptools_scm
+    # populated from the git tag at build time.
+    __version__ = _pkg_version("py-pi-bake")
+except PackageNotFoundError:
+    # Running from a checkout without `pip install -e .` — fine for
+    # one-off tests, just don't claim a real version.
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "Board", "BOARDS", "list_boards",
+    "OSImage", "OSES", "list_oses", "resolve_image",
+    "NodeConfig",
+    "build", "supports",
+]

pi_bake/alpine.py

@@ -0,0 +1,375 @@
+"""Alpine RPi image baker — no-root, mtools-based.
+
+Alpine RPi ships as a tarball you extract onto a FAT32 partition.
+On boot, an apkovl tarball (per-host state overlay) is restored
+into the live filesystem; that's where `/etc/hostname`,
+`/etc/ssh/sshd_config`, etc. come from on subsequent boots.
+
+To produce a single flashable `.img.gz`:
+  1. Create an empty FAT32 image of fixed size with `mformat`.
+  2. Extract the upstream Alpine RPi tarball.
+  3. `mcopy` the extracted tree into the image.
+  4. Generate a per-node apkovl.tar.gz (etc/, root/, runlevels).
+  5. `mcopy` the apkovl in.
+  6. gzip → final `.img.gz`.
+
+No `losetup`, no root. Requires `mtools` + `dosfstools` on PATH.
+
+Sizing: ~400 MB image is enough for the standard Alpine RPi
+tarball (~150 MB extracted) + apkovl + future apk-cache headroom.
+Operator-overridable via `image_size_mb`.
+"""
+from __future__ import annotations
+
+import gzip
+import io
+import logging
+import os
+import shutil
+import stat
+import subprocess
+import tarfile
+import tempfile
+from pathlib import Path
+
+from pi_bake.config import NodeConfig
+from pi_bake.download import fetch
+
+LOG = logging.getLogger("pi_bake.alpine")
+
+DEFAULT_IMAGE_SIZE_MB = 400
+
+
+def bake(
+    *, url: str, node: NodeConfig, out_path: Path,
+    image_size_mb: int = DEFAULT_IMAGE_SIZE_MB,
+) -> Path:
+    """Build an Alpine RPi `.img.gz` for `node`. Returns out_path.
+
+    Steps the operator might want to inspect: each one logs at INFO.
+    """
+    _require_tools("mformat", "mcopy", "mmd")
+
+    out_path = Path(out_path).expanduser().resolve()
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    tarball = fetch(url)
+
+    with tempfile.TemporaryDirectory(prefix="pi-bake-alpine-") as td:
+        td = Path(td)
+        # 1. Empty FAT32 image.
+        img = td / "image.img"
+        LOG.info("creating %d MB FAT32 image at %s", image_size_mb, img)
+        _create_fat32_image(img, image_size_mb)
+
+        # 2. Extract the upstream tarball into a tree we can mcopy.
+        extracted = td / "extracted"
+        extracted.mkdir()
+        LOG.info("extracting %s", tarball.name)
+        with tarfile.open(tarball, "r:*") as tf:
+            # `filter="data"` is Python 3.12+ and applies path-traversal
+            # sanitization. Pre-3.12 lacks the kwarg; the official Alpine
+            # tarball is trusted upstream content so the older permissive
+            # behavior is fine. Try the safer call first, fall back.
+            try:
+                tf.extractall(extracted, filter="data")
+            except TypeError:
+                tf.extractall(extracted)
+
+        # 3. Pour the tree into the FAT32 image.
+        LOG.info("mcopy: tarball → image")
+        for child in sorted(extracted.iterdir()):
+            _mcopy_into(img, child, "/")
+
+        # 4. Per-node apkovl.tar.gz.
+        apkovl_path = td / f"{node.hostname}.apkovl.tar.gz"
+        LOG.info("generating apkovl: %s", apkovl_path.name)
+        _write_apkovl(apkovl_path, node)
+        _mcopy_into(img, apkovl_path, "/")
+
+        # 5. gzip → out_path.
+        LOG.info("compressing → %s", out_path)
+        with open(img, "rb") as src, gzip.open(out_path, "wb", compresslevel=6) as dst:
+            shutil.copyfileobj(src, dst, length=1 << 20)
+
+    LOG.info("DONE: %s (%d MB)", out_path, out_path.stat().st_size >> 20)
+    return out_path
+
+
+# --------------------------------------------------------------------------- #
+# FAT32 image helpers (mtools)                                                 #
+# --------------------------------------------------------------------------- #
+
+def _create_fat32_image(path: Path, size_mb: int) -> None:
+    """Create an empty FAT32 image at `path` of exactly `size_mb`
+    megabytes. Uses `truncate` + `mformat` (no root)."""
+    size_bytes = size_mb * 1024 * 1024
+    with open(path, "wb") as f:
+        f.truncate(size_bytes)
+    # -i for image file, -F for FAT32, -v for volume label.
+    subprocess.run(
+        ["mformat", "-i", str(path), "-F", "-v", "PI-BAKE", "::"],
+        check=True, capture_output=True, text=True,
+    )
+
+
+def _mcopy_into(img: Path, src: Path, dest: str = "/") -> None:
+    """`mcopy -s -i <img> <src> ::<dest>`.
+
+    `dest` is the path inside the FAT image — normalized to start with
+    `/`, then prefixed with `::` to form mtools' "image-root-relative"
+    syntax. `::/` puts files at the FAT root; `::/apkovl/` inside an
+    apkovl subdir, etc. Recursive (`-s`) handles directories.
+    """
+    if not dest.startswith("/"):
+        dest = "/" + dest
+    target = f"::{dest}"
+    cmd = ["mcopy", "-Q", "-s", "-i", str(img), str(src), target]
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    if r.returncode != 0:
+        raise RuntimeError(
+            f"mcopy failed: {' '.join(cmd)}\n--- stderr ---\n{r.stderr}"
+        )
+
+
+# --------------------------------------------------------------------------- #
+# apkovl generation                                                            #
+# --------------------------------------------------------------------------- #
+
+def _write_apkovl(out: Path, node: NodeConfig) -> None:
+    """Build an Alpine apkovl.tar.gz for `node`.
+
+    Strategy: rely on Alpine RPi's diskless init, which on first boot
+    runs `apk add --root $sysroot --no-network` reading packages from
+    the overlay's `/etc/apk/world` and pulling apks from the local
+    `/media/mmcblk0/apks/` cache that ships in the tarball. So as long
+    as everything we want is in the stock cache, no network is needed
+    to come up with sshd + DHCP + NTP wired up. No first-boot script,
+    no over-the-network apk fetch dance — the package set just IS at
+    the end of the first boot.
+
+    Stock Alpine RPi tarball (verified) ships: openssh-server,
+    openssh-server-common-openrc, dhcpcd, dhcpcd-openrc, chrony,
+    chrony-openrc, wpa_supplicant, wpa_supplicant-openrc, iw,
+    ifupdown-ng-wifi, ca-certificates-bundle. NOT shipped: avahi,
+    dbus, linux-firmware-brcm, linux-firmware-intel — those need
+    a bake-time fetch (future v0.2 work, see ROADMAP.md).
+
+    DHCP choice: dhcpcd, not busybox udhcpc. udhcpc 1.37 + Alpine 3.21
+    + Pi 5's macb driver hangs with "address family not supported".
+    dhcpcd is more reliable across kernels and is what setup-alpine
+    selects by default in recent releases.
+
+    Files we lay down (paths relative to /):
+      etc/hostname                    — node.hostname
+      etc/hosts                       — localhost + hostname entry
+      etc/timezone                    — node.timezone
+      etc/ssh/sshd_config             — root-by-key only, no passwords
+      root/.ssh/authorized_keys       — node.all_pubkeys
+      etc/network/interfaces          — lo only (+ eth0 static path)
+      etc/apk/world                   — packages init will install
+      etc/apk/repositories            — local cache + upstream main/community
+      etc/runlevels/default/sshd      — symlink, started at boot
+      etc/runlevels/default/dhcpcd    — symlink (skipped on static-IP)
+      etc/runlevels/default/chronyd   — symlink
+      etc/runlevels/default/networking — symlink (brings up lo + static eth0)
+      etc/wpa_supplicant/wpa_supplicant.conf + runlevel — only when wifi
+    """
+    members: list[tuple[str, bytes, int, bool]] = []
+    # (path, content, mode, is_symlink)
+
+    # The whole reason the rest of this works. Alpine RPi's /init,
+    # when it finds an apkovl, SKIPS the "add default boot services"
+    # block (rc_add modloop sysinit, rc_add modules boot, …) UNLESS
+    # this marker file is present. Without modloop in sysinit, the
+    # squashfs of kernel modules never mounts on /lib/modules, so
+    # af_packet, ipv6, almost every needed network driver is absent
+    # — and every DHCP client fails with "Address family not
+    # supported by protocol" (seen on Pi 5 with both busybox udhcpc
+    # and dhcpcd 10.x). The init script deletes this marker after
+    # consuming it, so it's truly one-shot.
+    members.append(("etc/.default_boot_services", b"", 0o644, False))
+
+    # lbu (Alpine "local backup") writes a fresh apkovl onto the FAT
+    # so the operator's post-boot changes survive reboot. Without
+    # LBU_MEDIA set, `lbu commit` and even `lbu status` just print
+    # usage. mmcblk0 is the SD card's FAT partition, mounted at
+    # /media/mmcblk0 by Alpine RPi init.
+    members.append((
+        "etc/lbu/lbu.conf",
+        b'LBU_MEDIA="mmcblk0"\n',
+        0o644, False,
+    ))
+
+    members.append(("etc/hostname", f"{node.hostname}\n".encode(), 0o644, False))
+    members.append((
+        "etc/hosts",
+        (
+            "127.0.0.1 localhost\n"
+            f"127.0.1.1 {node.hostname}\n"
+            "::1 localhost ip6-localhost ip6-loopback\n"
+            "ff02::1 ip6-allnodes\nff02::2 ip6-allrouters\n"
+        ).encode(),
+        0o644, False,
+    ))
+    members.append(("etc/timezone", f"{node.timezone}\n".encode(), 0o644, False))
+
+    # sshd_config: enable, no passwords, root login by key.
+    # Alpine's openssh is built WITHOUT PAM — `UsePAM yes` makes sshd
+    # refuse to start ("Bad configuration option: UsePAM"). Don't add
+    # it back unless you also switch to a PAM-enabled openssh build.
+    # `ChallengeResponseAuthentication` was renamed to
+    # `KbdInteractiveAuthentication` in openssh 8.7; 9.9 still parses
+    # it but it's redundant when PasswordAuthentication=no.
+    sshd_cfg = (
+        "PermitRootLogin prohibit-password\n"
+        "PasswordAuthentication no\n"
+        "KbdInteractiveAuthentication no\n"
+        "PrintMotd no\n"
+        "AcceptEnv LANG LC_*\n"
+        "Subsystem sftp /usr/lib/ssh/sftp-server\n"
+    )
+    members.append(("etc/ssh/sshd_config", sshd_cfg.encode(), 0o600, False))
+
+    members.append(("root/.ssh/authorized_keys",
+                    node.authorized_keys_text().encode(), 0o600, False))
+
+    # /etc/network/interfaces — lo is always managed by `networking`.
+    # For DHCP nodes, eth0 + wlan0 are NOT listed here: dhcpcd runs as
+    # a daemon and watches all interfaces, so listing them under
+    # `networking` would race with dhcpcd. For static-IP nodes, eth0
+    # IS listed (and dhcpcd is dropped from the runlevel entirely —
+    # see further down).
+    interfaces = "auto lo\niface lo inet loopback\n"
+    if node.has_static_ip:
+        interfaces += (
+            f"\nauto eth0\n"
+            f"iface eth0 inet static\n"
+            f"    address {node.static_address_only}\n"
+            f"    netmask {node.static_netmask}\n"
+            f"    gateway {node.gateway_ipv4}\n"
+        )
+    members.append(("etc/network/interfaces", interfaces.encode(), 0o644, False))
+
+    # /etc/resolv.conf for static-IP nodes (DHCP fills this via dhcpcd
+    # but static doesn't). Default to Cloudflare + Google — operator
+    # can replace post-boot if they want their own resolver.
+    if node.has_static_ip:
+        members.append((
+            "etc/resolv.conf",
+            b"nameserver 1.1.1.1\nnameserver 8.8.8.8\n",
+            0o644, False,
+        ))
+
+    # /etc/apk/repositories — local FAT cache first (init's `--no-network`
+    # path resolves from here), then upstream so post-boot `apk add`
+    # works for anything not in the cache. Track the matching version
+    # to avoid mixed-release ABI surprises.
+    members.append((
+        "etc/apk/repositories",
+        (
+            "/media/mmcblk0/apks\n"
+            "http://dl-cdn.alpinelinux.org/alpine/v3.21/main\n"
+            "http://dl-cdn.alpinelinux.org/alpine/v3.21/community\n"
+        ).encode(),
+        0o644, False,
+    ))
+
+    # /etc/apk/world — the package set Alpine init installs on first
+    # boot from the local /media/mmcblk0/apks cache. All listed
+    # packages MUST exist in the stock RPi tarball; anything else
+    # would need bake-time fetch (deferred — see module docstring).
+    world_pkgs = [
+        "alpine-base",
+        "openssh-server",
+        "openssh-server-common-openrc",
+        # openssh-server alone has no sftp-server binary, so modern
+        # scp (openssh 9.0+ defaults to SFTP protocol) fails with
+        # "subsystem request failed". pyinfra also leans on SFTP for
+        # file pushes. Ships in stock RPi tarball — free to include.
+        "openssh-sftp-server",
+        "chrony",
+        "chrony-openrc",
+    ]
+    if not node.has_static_ip:
+        world_pkgs += ["dhcpcd", "dhcpcd-openrc"]
+    if node.has_wifi:
+        world_pkgs += [
+            "wpa_supplicant",
+            "wpa_supplicant-openrc",
+            "iw",
+            "ifupdown-ng-wifi",
+        ]
+    members.append((
+        "etc/apk/world",
+        ("\n".join(world_pkgs) + "\n").encode(),
+        0o644, False,
+    ))
+
+    if node.has_wifi:
+        members.append((
+            "etc/wpa_supplicant/wpa_supplicant.conf",
+            node.wpa_supplicant_conf().encode(),
+            0o600, False,
+        ))
+        # Tell wpa_supplicant-openrc which interface to drive. Without
+        # this it boots in no-interface mode and never associates.
+        members.append((
+            "etc/conf.d/wpa_supplicant",
+            b'wpa_supplicant_args="-iwlan0"\n',
+            0o644, False,
+        ))
+
+    # /etc/runlevels/default/* — symlinks into /etc/init.d/ enable
+    # services at boot. The target init scripts don't exist yet when
+    # the apkovl is extracted; they appear when init's `apk add`
+    # installs the corresponding `*-openrc` packages from world (a few
+    # lines below). By the time the `default` runlevel actually starts,
+    # both symlink and target exist.
+    runlevel_svcs = ["networking", "sshd", "chronyd"]
+    if not node.has_static_ip:
+        runlevel_svcs.append("dhcpcd")
+    if node.has_wifi:
+        runlevel_svcs.append("wpa_supplicant")
+    for svc in runlevel_svcs:
+        members.append((
+            f"etc/runlevels/default/{svc}",
+            f"/etc/init.d/{svc}".encode(),
+            0o777, True,
+        ))
+
+    # Pack as tar.gz.
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        for path, content, mode, is_symlink in members:
+            ti = tarfile.TarInfo(name=path)
+            if is_symlink:
+                ti.type = tarfile.SYMTYPE
+                ti.linkname = content.decode()
+                ti.size = 0
+            else:
+                ti.size = len(content)
+            ti.mode = mode
+            ti.uid = 0
+            ti.gid = 0
+            ti.mtime = 0
+            if is_symlink:
+                tf.addfile(ti)
+            else:
+                tf.addfile(ti, io.BytesIO(content))
+
+    out.write_bytes(buf.getvalue())
+
+
+# --------------------------------------------------------------------------- #
+# Helpers                                                                      #
+# --------------------------------------------------------------------------- #
+
+def _require_tools(*names: str) -> None:
+    missing = [n for n in names if shutil.which(n) is None]
+    if missing:
+        raise RuntimeError(
+            f"missing required tool(s) on PATH: {missing}. "
+            f"On Fedora: sudo dnf install mtools dosfstools. "
+            f"On Debian/Ubuntu: sudo apt install mtools dosfstools."
+        )

pi_bake/bake.py

@@ -0,0 +1,74 @@
+"""Top-level bake dispatcher.
+
+Routes `(board, os)` to the right backend module + verifies the
+combo is on the supported edge list before going anywhere near
+the network. The CLI calls this; the Python API also exports it
+via `pi_bake.build()`.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from pi_bake.boards import get_board
+from pi_bake.config import NodeConfig
+from pi_bake.oses import get_os, resolve_image
+
+LOG = logging.getLogger("pi_bake.bake")
+
+
+def supports(board: str, os_name: str) -> bool:
+    """True iff `os_name` is supported on `board` per the catalog."""
+    try:
+        b = get_board(board)
+        o = get_os(os_name)
+    except KeyError:
+        return False
+    return b.name in o.supports_boards
+
+
+def build(
+    *, board: str, os_name: str, version: str | None,
+    node: NodeConfig, out_path: str | Path,
+    image_size_mb: int | None = None,
+) -> Path:
+    """Build an `.img.gz` for `(board, os, version, node)`.
+
+    `version=None` → use the OS's latest known-good.
+    `image_size_mb=None` → backend's default.
+
+    Raises:
+      - KeyError on unknown board/os.
+      - ValueError if the (board, os) combo isn't supported.
+      - NotImplementedError for backends not in v0.1.
+    """
+    b = get_board(board)
+    o = get_os(os_name)
+    if b.name not in o.supports_boards:
+        raise ValueError(
+            f"{o.pretty} ({o.name}) doesn't support {b.pretty} ({b.name}). "
+            f"Supported boards for {o.name}: {sorted(o.supports_boards)}"
+        )
+
+    o, resolved_version, url = resolve_image(o.name, version, b.arch)
+
+    LOG.info(
+        "baking %s on %s using %s %s (url=%s)",
+        node.hostname, b.name, o.name, resolved_version, url,
+    )
+
+    backend = o.bake_backend
+    if backend == "alpine":
+        from pi_bake import alpine
+        kwargs = {"url": url, "node": node, "out_path": Path(out_path)}
+        if image_size_mb is not None:
+            kwargs["image_size_mb"] = image_size_mb
+        return alpine.bake(**kwargs)
+    elif backend == "raspbian":
+        from pi_bake import raspbian
+        return raspbian.bake(
+            url=url, node=node, out_path=Path(out_path),
+            image_size_mb=image_size_mb or 0,
+        )
+    else:
+        raise RuntimeError(f"unknown bake backend {backend!r} in OS catalog")

pi_bake/boards.py

@@ -0,0 +1,77 @@
+"""Raspberry Pi board catalog.
+
+One `Board` per officially-supported model. Keep this list short +
+honest — a board belongs here when at least one OS we know how to
+bake images for ACTUALLY runs on it. "Supported" lives on the
+(board, os) edges in `oses.py`, not on the board itself.
+
+`arch` matches what the upstream OS image archives use, so the
+download URL templates can interpolate it directly.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Board:
+    name: str          # short slug, e.g. "pi-5"
+    pretty: str        # human label, e.g. "Raspberry Pi 5"
+    arch: str          # "aarch64" | "armhf" — what the OS image label uses
+    notes: str = ""    # quirks worth flagging to the operator
+
+    def __str__(self) -> str:
+        return f"{self.name} — {self.pretty} ({self.arch})"
+
+
+# Order: most-current first. CLI `list-boards` renders in this order.
+BOARDS: tuple[Board, ...] = (
+    Board(
+        "pi-5", "Raspberry Pi 5", "aarch64",
+        notes="64-bit only. Alpine 3.21+ has experimental support; "
+              "Raspberry Pi OS Lite (Debian Bookworm) is the safe default.",
+    ),
+    Board(
+        "pi-4", "Raspberry Pi 4 Model B", "aarch64",
+        notes="64-bit recommended; 32-bit still works for the ≤2 GB models.",
+    ),
+    Board(
+        "pi-zero-2-w", "Raspberry Pi Zero 2 W", "aarch64",
+        notes="Quad-core Cortex-A53; the snappy small WiFi-only Pi. "
+              "Alpine aarch64 is the typical choice for IoT / station roles.",
+    ),
+    Board(
+        "pi-3", "Raspberry Pi 3 Model B+", "aarch64",
+        notes="Mostly legacy; Pi 4 / Pi 5 are the buy-it-today choices.",
+    ),
+    Board(
+        "pi-zero-w", "Raspberry Pi Zero W (original)", "armhf",
+        notes="32-bit ARMv6 ONLY. Alpine `armhf` image. Pi Zero 2 W is the "
+              "successor for new deployments.",
+    ),
+)
+
+_BY_NAME: dict[str, Board] = {b.name: b for b in BOARDS}
+
+
+def list_boards() -> list[Board]:
+    """Return every supported board, in display order."""
+    return list(BOARDS)
+
+
+def get_board(name: str) -> Board:
+    """Look up a board by slug. Raises KeyError on miss.
+
+    Aliases: `pi5` / `pi-5` / `rpi5` all resolve to `pi-5`.
+    """
+    norm = name.strip().lower().replace("rpi", "pi").replace(" ", "-")
+    # Common shorthand: "pi5" → "pi-5".
+    if norm not in _BY_NAME and "-" not in norm and norm.startswith("pi"):
+        try_dashed = f"pi-{norm[2:]}"
+        if try_dashed in _BY_NAME:
+            return _BY_NAME[try_dashed]
+    if norm in _BY_NAME:
+        return _BY_NAME[norm]
+    raise KeyError(
+        f"unknown board {name!r}; known: {sorted(_BY_NAME)}"
+    )