194 lines
4.2 KiB
Markdown
194 lines
4.2 KiB
Markdown
# 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.
|
|
3. Optionally wrap build steps with `asl-capture` to record build provenance.
|
|
4. Add bootloader config.
|
|
5. Build ISO with `xorriso` or equivalent tool.
|
|
|
|
---
|
|
|
|
## 8. Versioning
|
|
|
|
Backward-incompatible image changes MUST bump the major version.
|