292 lines
5.7 KiB
Markdown
292 lines
5.7 KiB
Markdown
Perfect — then let’s be very concrete and **treat the overlay itself as a specification**, not just “put binaries somewhere”.
|
||
|
||
Below is a **clean, minimal, opinionated overlay schema** for an **ASL intake / rescue environment**, aligned with everything you’ve defined (ASL, STORE-INDEX, federation, ZFS optional).
|
||
|
||
No diagrams, no fluff.
|
||
|
||
---
|
||
|
||
# ASL SystemRescue Overlay – Intake Schema
|
||
|
||
This overlay defines **what exists at boot**, **where state lives**, and **what is immutable vs runtime**.
|
||
|
||
---
|
||
|
||
## 1. High-level intent
|
||
|
||
The overlay must:
|
||
|
||
* Make ASL tools **always available**
|
||
* Be **stateless by default**
|
||
* Support **local ZFS intake OR remote ASL intake**
|
||
* Keep **semantic state out of the rescue image**
|
||
* Be safe on crashed systems
|
||
|
||
So the overlay provides:
|
||
|
||
* **executables**
|
||
* **configuration defaults**
|
||
* **service wiring**
|
||
* **well-known mount points**
|
||
|
||
Nothing else.
|
||
|
||
---
|
||
|
||
## 2. Canonical overlay layout
|
||
|
||
```
|
||
overlay/
|
||
├── usr/
|
||
│ └── local/
|
||
│ ├── bin/
|
||
│ │ ├── asl-intake
|
||
│ │ ├── asl-admin
|
||
│ │ └── asl-debug
|
||
│ └── lib/
|
||
│ └── libasl.so
|
||
│
|
||
├── etc/
|
||
│ └── asl/
|
||
│ ├── asl.conf # mode selection, endpoints
|
||
│ ├── federation.conf # domain + peer config
|
||
│ └── logging.conf
|
||
│
|
||
├── etc/systemd/system/
|
||
│ ├── asl-intake.service
|
||
│ └── asl-preflight.service
|
||
│
|
||
├── var/
|
||
│ └── lib/
|
||
│ └── asl/
|
||
│ ├── runtime/ # ephemeral runtime state
|
||
│ ├── cache/ # optional CAS cache
|
||
│ └── locks/
|
||
│
|
||
├── run/
|
||
│ └── asl/
|
||
│ └── sockets/ # if used (optional)
|
||
│
|
||
└── mnt/
|
||
└── asl/
|
||
├── local/ # local ZFS mount target
|
||
└── remote/ # optional remote FS
|
||
```
|
||
|
||
This is the **entire contract** between SystemRescue and ASL.
|
||
|
||
---
|
||
|
||
## 3. What each directory *means* (important)
|
||
|
||
### `/usr/local/bin`
|
||
|
||
**Immutable tools**
|
||
|
||
* `asl-intake`
|
||
Primary recovery/intake executable
|
||
* `asl-admin`
|
||
Inspection, snapshot listing, GC checks
|
||
* `asl-debug`
|
||
Low-level validation, block/segment inspection
|
||
|
||
> These must never write here.
|
||
|
||
---
|
||
|
||
### `/etc/asl`
|
||
|
||
**Declarative configuration only**
|
||
|
||
Example `asl.conf`:
|
||
|
||
```
|
||
mode = auto # auto | local | remote
|
||
local.mount = /mnt/asl/local
|
||
remote.endpoint = https://asl-backend
|
||
domain.id = rescue-domain
|
||
```
|
||
|
||
Rules:
|
||
|
||
* No secrets unless unavoidable
|
||
* No mutable state
|
||
* Safe to ship in ISO
|
||
|
||
---
|
||
|
||
### `/var/lib/asl`
|
||
|
||
**All mutable local state**
|
||
|
||
This is the *only* place your tools write to by default.
|
||
|
||
```
|
||
/var/lib/asl/runtime # PID files, temp metadata
|
||
/var/lib/asl/cache # optional local CAS cache
|
||
/var/lib/asl/locks # advisory locks
|
||
```
|
||
|
||
This may live:
|
||
|
||
* in RAM (default)
|
||
* on USB persistence
|
||
* never on the broken system disk
|
||
|
||
---
|
||
|
||
### `/mnt/asl/local`
|
||
|
||
**Local ASL backend mount (ZFS)**
|
||
|
||
If local intake is possible:
|
||
|
||
```
|
||
zpool import rescuepool
|
||
zfs mount rescuepool/asl → /mnt/asl/local
|
||
```
|
||
|
||
Your tool treats this as:
|
||
|
||
```
|
||
/mnt/asl/local/
|
||
├── blocks/
|
||
├── segments/
|
||
├── snapshots/
|
||
└── logs/
|
||
```
|
||
|
||
(Exact internal layout is backend-defined, not overlay-defined.)
|
||
|
||
---
|
||
|
||
### `/mnt/asl/remote`
|
||
|
||
Optional:
|
||
|
||
* NFS
|
||
* SSHFS
|
||
* Debug mounts
|
||
|
||
Not required for normal operation.
|
||
|
||
---
|
||
|
||
## 4. systemd services (minimal and safe)
|
||
|
||
### `asl-preflight.service`
|
||
|
||
Runs once at boot.
|
||
|
||
Responsibilities:
|
||
|
||
* Detect network
|
||
* Detect ZFS availability
|
||
* Detect importable pools
|
||
* Write decision to `/run/asl/mode`
|
||
|
||
No mutations.
|
||
|
||
---
|
||
|
||
### `asl-intake.service`
|
||
|
||
Starts the tool.
|
||
|
||
Example behavior:
|
||
|
||
* Reads `/run/asl/mode`
|
||
* Chooses:
|
||
|
||
* local ZFS backend
|
||
* or remote ASL endpoint
|
||
* Starts intake loop or waits for operator
|
||
|
||
This keeps **policy out of the binary**.
|
||
|
||
---
|
||
|
||
## 5. Local vs remote handling (explicit contract)
|
||
|
||
### Local ZFS mode
|
||
|
||
The overlay guarantees:
|
||
|
||
```
|
||
/mnt/asl/local exists
|
||
/var/lib/asl writable
|
||
/usr/local/bin contains tools
|
||
```
|
||
|
||
Your tool guarantees:
|
||
|
||
* Never mutate unsealed data
|
||
* Never auto-import pools without operator or config approval
|
||
|
||
---
|
||
|
||
### Remote ASL mode
|
||
|
||
The overlay guarantees:
|
||
|
||
* Network tools available
|
||
* TLS roots present
|
||
* Configurable endpoint
|
||
|
||
Your tool guarantees:
|
||
|
||
* Snapshot-bounded reads
|
||
* Deterministic uploads
|
||
* Idempotent retries
|
||
|
||
---
|
||
|
||
## 6. What is *explicitly forbidden* in the overlay
|
||
|
||
These rules prevent disasters:
|
||
|
||
❌ Writing to `/usr`, `/bin`, `/lib`
|
||
❌ Storing state in `/etc`
|
||
❌ Auto-mounting the crashed system root
|
||
❌ Assuming ZFS exists
|
||
❌ Assuming network exists
|
||
|
||
All assumptions must be **detected, not presumed**.
|
||
|
||
---
|
||
|
||
## 7. Why this schema works with your ASL design
|
||
|
||
This layout aligns perfectly with your specs because:
|
||
|
||
* **ASL-STORE-INDEX**
|
||
→ persistence lives outside the overlay
|
||
|
||
* **Federation**
|
||
→ domain identity is config, not state
|
||
|
||
* **PEL / TGK**
|
||
→ execution artifacts are handled like any other artifact
|
||
|
||
* **Determinism**
|
||
→ overlay never contains semantic state
|
||
|
||
The overlay is **pure capability**, not data.
|
||
|
||
---
|
||
|
||
## 8. Summary (the one-paragraph version)
|
||
|
||
> The SystemRescue overlay should contain **only tools, config, and wiring**.
|
||
> All mutable ASL state lives either in `/var/lib/asl` (ephemeral) or in a mounted backend (`/mnt/asl/local` or remote).
|
||
> The overlay never encodes semantic state, snapshots, or artifacts — only the ability to access and produce them.
|
||
|
||
If you want, next we can:
|
||
|
||
* Turn this into a **formal overlay contract doc**
|
||
* Define a **preflight decision table**
|
||
* Or map this schema directly onto your ASL backend spec
|
||
|
||
But this layout is already “correct by construction.”
|
||
|