amduat-api/ops/asl-auth-host-image-1.md

ASL/AUTH-HOST-IMAGE/1 - Bootable Image and Overlay Layout

Status: Draft Owner: Architecture Version: 0.1.0 SoT: No Last Updated: 2026-01-17 Tags: [ops, authority, image]

Document ID: ASL/AUTH-HOST-IMAGE/1 Layer: O2I - Authority host image profile

Depends on (normative):

• ASL/AUTH-HOST/1
• ENC-ASL-AUTH-HOST/1

Informative references:

• ASL/AUTH-HOST-CONFIG/1

---

0. Conventions

The key words MUST, MUST NOT, REQUIRED, SHOULD, and MAY are to be interpreted as in RFC 2119.

---

1. Purpose and Scope

This document defines a bootable, offline authority host image. It specifies base system requirements, overlay layout, and the boot workflow used to initialize authority operations.

---

2. Base Image Requirements

The base OS MUST:

• Boot in offline mode by default
• Include minimal POSIX tooling
• Disable network services unless explicitly enabled

---

3. Overlay Layout

/overlay/
├── bin/
│   ├── asl-auth-host
│   ├── asl-rescue
│   └── init-asl-host.sh
│   └── sign_dam.sh
│   └── add_artifact.sh
├── etc/
│   └── asl-auth-host/
│       ├── config.yaml
│       └── policy.hash
├── var/
│   ├── lib/
│   │   └── asl/
│   │       ├── common/
│   │       ├── personal/
│   │       └── pools/
│   └── log/
│       └── asl-auth-host.log
└── usr/
    └── local/
        └── bin/
            └── asl-admin

The overlay MUST be merged into the ISO root at build time.

---

4. ISO Root Layout (Runtime)

/iso_root/
├── bin/
├── etc/
│   └── asl-auth-host/
├── var/
│   ├── lib/
│   │   └── asl/
│   └── log/
└── usr/local/bin/

---

5. Boot Workflow

1. Boot offline image.
2. Run init-asl-host.sh to mount storage pools and apply config.
3. Initialize or open domain stores per config.
4. Start the authority host service.
5. Enforce witness authority (DAM) before general userspace services start.

---

6. Persistence Strategy

Writable storage MUST be mounted separately from the read-only system image. Examples:

• ZFS datasets mounted under /var/lib/asl
• External disk mounted at /mnt and bound to /var/lib/asl

---

7. Build Pipeline (Informative)

A typical pipeline:

1. Create minimal root via debootstrap or equivalent.
2. Merge overlay into ISO root.
3. Configure bootloader (isolinux or GRUB).
4. Build ISO with xorriso or equivalent.

---

8. Container Build Notes (Informative)

Building the ISO in a container is supported with the following constraints:

• ZFS pool creation typically requires host kernel support; create datasets at boot time instead.
• The ISO filesystem and overlay can be built entirely in a Debian container.
• Boot testing must occur on a VM or physical host.

Recommended packages in the build container:

debootstrap squashfs-tools xorriso genisoimage

---

9. Offline Debian Mirror Workflow (Informative)

To build offline images without network access, create a local Debian mirror as an artifact and use it with debootstrap.

Example (online host):

debmirror \
  --arch=amd64 \
  --section=main \
  --dist=bullseye \
  --method=http \
  --host=deb.debian.org \
  --root=debian \
  /srv/debian-mirror

Offline build:

debootstrap --arch=amd64 bullseye /target/root file:///srv/debian-mirror

The mirror directory SHOULD be treated as immutable input for reproducibility.

---

10. Pre-Image Capture Workflow (Informative)

To preserve provenance of the ISO build, capture each build step as artifacts and receipts before composing the final image.

Suggested workflow:

1. Initialize a temporary ASL store for build artifacts.
2. Wrap debootstrap and package installation in asl-capture.
3. Capture overlay binaries and scripts as artifacts.
4. Run the ISO build under asl-capture to produce a final ISO artifact.
5. Seed the ISO with the captured artifacts and receipts.
6. Optionally wrap build steps with asl-capture to record build provenance.
7. Add bootloader config.
8. Build ISO with xorriso or equivalent tool.

---

8. Versioning

Backward-incompatible image changes MUST bump the major version.