Packed Base Image

SwiftOS boots a small kernel and mounts the rest of the root filesystem from a deterministic, read-only packed image. That image is build/base.img. It holds the base /bin programs, default /etc files, static web content, package trust roots, sample packages, and model bundles used by the checked-in product profiles.

The current base image format is signed SWOSBASE version 3. Older unsigned version 2 packed images still exist for package payload overlays, but the root base image must be signed v3 and is refused by the kernel if its metadata signature is invalid.

Use this document with:

• Installation Guide for boot profiles.
• Update And Rollback Guide and Update Store for checked A/B base-image updates.
• Application Cookbook for staging native programs.
• Package Guide for package payloads and package-store images that layer beside the base image.
• AI Hosting Guide for model bundles staged under /models.

User Model

The base image is the immutable system root:

Changes made inside /bin, /etc, /www, /models, or /packages in a running guest do not persist because those paths are read-only. To make a change durable, rebuild build/base.img, provide a package payload, or use a future persistent storage profile when one exists.

Choose A Base Image Workflow

Start from the durable content you need to change. The running guest is the verification target, but the source of truth is always a host-side input.

Example static-content change:

printf 'hello from SwiftOS\n' > base/www/index.html
make base-image
./tests/httpd_test.sh

Build And Boot

Build the normal signed base image:

make base-image

Build the kernel, DTB, and base image together:

make build base-image build/virt.dtb

Boot the direct QEMU profile:

make run

Boot the UEFI/GPT profile:

make disk base-image
make disk-run

The base image is a separate virtio-blk disk in both the direct and UEFI QEMU profiles. A manual direct boot uses:

qemu-system-aarch64 -M virt -cpu cortex-a72 -m 256M -nographic \
  -global virtio-mmio.force-legacy=false \
  -device loader,file=build/virt.dtb,addr=0x4FF00000,force-raw=on \
  -drive file=build/base.img,format=raw,if=none,id=swosbase,readonly=on \
  -device virtio-blk-device,drive=swosbase \
  -kernel build/kernel.elf

Expected boot evidence includes:

vfs: base image signature verified (ed25519)
M11c: read-only base mounted from disk

Build Inputs

make base-image creates a temporary staging tree at build/base-root, then packs it into build/base.img with build/basepack.

Do not edit build/base-root by hand. It is generated output and is removed on the next make base-image.

Signed Format v3

All integer fields are little-endian. Paths are UTF-8 paths relative to / without a leading slash. Directories and regular files are the only entry kinds.

Header layout:

0   u8[8]  magic          "SWOSBASE"
8   u32    version        3 for the signed root base image
12  u32    header_size    64
16  u32    entry_size     72
20  u32    entry_count
24  u64    entries_offset
32  u64    strings_offset
40  u64    strings_size
48  u64    data_offset    strings_offset + strings_size + 64-byte signature
56  u64    data_size

Entry layout:

0   u32    path_offset    offset into the string table
4   u32    path_length    path byte length, excluding the NUL terminator
8   u32    kind           1 directory, 2 regular file
12  u32    flags          currently 0
16  u64    data_offset    offset into the payload data section
24  u64    data_size
32  u32    mode           directories and /bin files are usually 0755; other files 0644
36  u32    owner          current base image owner principal is 1 (root)
40  u8[32] content_hash   SHA-256 of file data; all zero for directories

The signed metadata region is:

header | entries | string table

The 64-byte Ed25519 signature is stored immediately after the string table. File payload bytes follow the signature. The signature authenticates filesystem metadata, names, modes, owners, and per-file content hashes. File data is checked against the stored SHA-256 hash lazily on first open, so metadata tampering prevents the image from mounting and payload tampering rejects the affected file while the rest of the guest keeps running.

Unsigned SWOSBASE v2 images use 40-byte entries and have no signature or per-file hash. The kernel accepts v2 only for package payload overlays that have already been validated by the package or package-store path; it does not accept v2 as the root base image.

Inspect The Image

Build and run the host parser:

make base-image
/usr/bin/swiftc tests/base_image_test.swift kernel/crypto/sha256.swift -o build/base_image_test
build/base_image_test build/base.img

Expected result:

PASS: packed base image format is readable, deterministic, and hash-consistent (signed v3)

Inspect the v3 header with Python:

python3 - <<'PY'
import struct
img = open("build/base.img", "rb").read(64)
magic = img[:8].decode()
version, header_size, entry_size, entry_count = struct.unpack_from("<IIII", img, 8)
entries_offset, strings_offset, strings_size, data_offset, data_size = struct.unpack_from("<QQQQQ", img, 24)
print("magic", magic)
print("version", version)
print("header_size", header_size)
print("entry_size", entry_size)
print("entry_count", entry_count)
print("signature_offset", strings_offset + strings_size)
print("data_offset", data_offset)
print("data_size", data_size)
PY

For the current root base image, version should be 3, entry_size should be 72, and data_offset should equal strings_offset + strings_size + 64.

Common Changes

Change A Static File

Edit the seed file, rebuild, and boot:

printf 'hello from the appliance profile\n' > base/www/index.html
make base-image
./tests/httpd_test.sh

Use this path for immutable application assets, static web content, default configuration, and files that should be present before any package is mounted.

Add A Native Program To /bin

1. Add the userland source and build rule.
2. Add its ELF to BASE_EXEC_ELFS in Makefile.
3. Copy the built ELF into $(BASE_ROOT)/bin/<name> in the $(BASE_IMG) rule.
4. Rebuild and run a focused boot test.

The full copy-paste recipe lives in Application Cookbook. For command documentation, also update Command Reference and the relevant acceptance test.

Bake A Default Package Repository

Build a custom base image with default package repository settings:

make BASE_IMG=build/base-hosted-url.img \
  PKG_DEFAULT_REPO_URL=http://packages.swift-os.test:8080 \
  PKG_DEFAULT_DNS_SERVER=10.0.2.3 \
  base-image

The generated guest files are /etc/pkg/repo-url and /etc/pkg/dns-server. The hosted package tests use this path to prove pkg update and pkg install NAME from a DNS-resolved repository URL.

Verification Matrix

Run the narrowest test that proves the change. For example, a static web-content change should run make base-image and the relevant service or HTTP test; a format or signing change should run the signed-image tests.

Troubleshooting

Security Notes

• The kernel embeds a single Ed25519 image trust root at build time through kernel/security/trust_root.S.
• The checked-in development keys are for repository validation and tests. A production signing story must replace them with controlled release keys and a key-rotation policy.
• The base image is authenticated as a whole metadata contract and then fail-closed per file for content reads.
• The current base image has owner and mode metadata, but it is still a read-only root filesystem. It is not a general writable Unix filesystem.
• Packages and package-store payloads layer beside the base image. The base image remains the root of early boot, identity, command availability, and trust-root distribution.

Source Of Truth

The implementation and tests that define this document are:

• tools/packfs.swift for the packed filesystem layout.
• tools/basepack.swift for signed base-image construction.
• Makefile for build/base-root staging and signing inputs.
• kernel/security/trust_root.S for the embedded image trust root.
• kernel/vfs/vfs.swift for mount-time signature verification and lazy per-file hash checks.
• tests/base_image_test.swift for host-side format validation.
• tests/signed_image_test.sh for tamper rejection behavior.
• tests/vfs_disk_test.sh, tests/disk_exec_test.sh, and tests/uefi_boot_test.sh for boot-time acceptance coverage.

Edit this page on GitHub