211 lines
8.1 KiB
Markdown
211 lines
8.1 KiB
Markdown
# OEM Install + First-Boot Setup Plan
|
|
|
|
## Goal
|
|
|
|
Create a second ISO flavor for OEM preloading that is installed to internal storage at factory time, then boots into customer setup on first power-on (no external media required), and ends in a fully encrypted Omarchy install.
|
|
|
|
## Product Requirements
|
|
|
|
- Factory can preload one image to internal disk.
|
|
- Customer first boot launches setup flow automatically (already works: `.automated_script.sh` runs configurator on tty1).
|
|
- Customer chooses credentials/settings.
|
|
- Final installed OS uses full-disk encryption (LUKS) with customer password (already works: configurator collects password and passes it to archinstall as `encryption_password`).
|
|
- Existing consumer ISO behavior remains unchanged.
|
|
|
|
---
|
|
|
|
## Chosen Architecture
|
|
|
|
### Bootstrapping model
|
|
- OEM devices ship with an OEM bootstrap ISO image written to internal disk.
|
|
- On first boot, `copytoram=y` kernel arg loads the live environment into RAM, freeing the internal disk.
|
|
- Bootstrap environment launches existing configurator + installer.
|
|
- Installer performs a fresh install to internal disk with LUKS encryption enabled.
|
|
- Bootstrap environment is overwritten during install.
|
|
|
|
### Recovery model: zero-recovery
|
|
- No permanent recovery partition.
|
|
- Simplest and strongest security story.
|
|
- Recovery requires external reinstall media.
|
|
|
|
---
|
|
|
|
## Non-Goals
|
|
|
|
- No on-device recovery workflow.
|
|
- No changes to normal installer UX outside explicit OEM mode checks and warnings.
|
|
- No factory credential provisioning.
|
|
|
|
---
|
|
|
|
## Repo Implementation Plan
|
|
|
|
## 1) Add OEM build mode
|
|
|
|
### Files
|
|
- `bin/omarchy-iso-make`
|
|
- `builder/build-iso.sh`
|
|
|
|
### Changes
|
|
- Add CLI flag `--oem` to `bin/omarchy-iso-make`.
|
|
- Pass `OMARCHY_MODE=oem` into Docker build env (default `normal`).
|
|
- In `builder/build-iso.sh`, write mode marker `/root/omarchy_mode` containing `oem` or `normal` (same pattern as `omarchy_mirror`).
|
|
- When `OMARCHY_MODE=oem`, inject `copytoram=y` into all bootloader entry points before `mkarchiso` runs:
|
|
- `grub/grub.cfg`: append to `linux` cmdline entries.
|
|
- `efiboot/loader/entries/01-archiso-x86_64-linux.conf`: append to `options` line.
|
|
- `syslinux/archiso_sys-linux.cfg`: append to `APPEND` lines.
|
|
- When `OMARCHY_MODE=oem`, override `iso_application` in `profiledef.sh` to `"Omarchy OEM Installer"`.
|
|
- Rename output ISO with `-oem` suffix (in addition to existing `-$OMARCHY_INSTALLER_REF` suffix).
|
|
|
|
### Hardening
|
|
- Add post-injection build assertion that fails build if any expected boot config does not contain `copytoram=y`.
|
|
- Make injection idempotent (do not duplicate `copytoram=y` if already present).
|
|
|
|
### Acceptance criteria
|
|
- `./bin/omarchy-iso-make --oem` builds successfully.
|
|
- OEM ISO boot entries contain `copytoram=y` in all supported boot paths.
|
|
- Normal build output and behavior remain unchanged.
|
|
|
|
### Suggested verification commands
|
|
- `bsdtar -xOf out/<iso>.iso loader/entries/01-archiso-x86_64-linux.conf | rg copytoram=y`
|
|
- `bsdtar -xOf out/<iso>.iso boot/grub/grub.cfg | rg copytoram=y`
|
|
- `bsdtar -xOf out/<iso>.iso boot/syslinux/archiso_sys-linux.cfg | rg copytoram=y`
|
|
|
|
---
|
|
|
|
## 2) Add OEM safety guardrails
|
|
|
|
### Why
|
|
OEM image boots from internal disk and later wipes that same disk. Live environment must be fully in RAM before install begins.
|
|
|
|
### File
|
|
- `configs/airootfs/root/.automated_script.sh`
|
|
|
|
### Changes
|
|
- Before `run_configurator`, if `/root/omarchy_mode` is `oem`:
|
|
- Verify `/proc/cmdline` contains `copytoram=y`; abort with clear actionable error if missing.
|
|
- Verify memory safety using `MemAvailable` (not total memory):
|
|
- Minimum threshold: `max(6 GiB, 1.5 x ISO size + 1 GiB)`.
|
|
- Abort with clear error if below threshold.
|
|
- Verify runtime state indicates live root is in RAM (for example, expected archiso runtime mounts present and boot media not actively mounted as install target path).
|
|
|
|
### Acceptance criteria
|
|
- OEM mode aborts safely if `copytoram=y` missing from cmdline.
|
|
- OEM mode aborts safely if available memory below threshold.
|
|
- OEM mode aborts safely if runtime state does not confirm RAM-backed live environment.
|
|
|
|
### Error message requirements
|
|
- State exactly what failed.
|
|
- State why install is blocked.
|
|
- Provide next step (reboot using proper OEM media or use external recovery media).
|
|
|
|
---
|
|
|
|
## 3) OEM disk warning
|
|
|
|
### Why
|
|
With `copytoram=y`, archiso copies squashfs to RAM and releases boot device. Existing configurator call `findmnt -no SOURCE /run/archiso/bootmnt` may return empty, so exclusion filter is skipped and all physical disks are shown, including former boot disk. No disk selection logic change is required.
|
|
|
|
OEM mode still needs an unmistakable warning before destructive install proceeds.
|
|
|
|
### File
|
|
- `configs/airootfs/root/configurator`
|
|
|
|
### Changes
|
|
- Read mode from `/root/omarchy_mode`.
|
|
- If mode is `oem`, add OEM-specific warning text before existing destructive confirmation.
|
|
- Upgrade confirmation in OEM mode to explicit typed confirmation (for example: `YES, WIPE DISK`) while preserving existing normal-mode flow.
|
|
|
|
### Acceptance criteria
|
|
- Normal ISO behavior is unchanged.
|
|
- OEM ISO shows OEM-specific warning before disk wipe confirmation.
|
|
- OEM typed confirmation is required before destructive action.
|
|
- In VM with `copytoram=y`, former boot disk appears in disk list without exclusion-logic changes.
|
|
|
|
---
|
|
|
|
## 4) Documentation
|
|
|
|
### File
|
|
- `README.md`
|
|
|
|
### Changes
|
|
- Document `--oem` build flag and resulting artifact naming.
|
|
- Document factory workflow: writing OEM ISO to internal disk and expected first-boot UX.
|
|
- Document failure and recovery behavior:
|
|
- Missing `copytoram=y` or low memory causes safe abort.
|
|
- Interrupted/failed install requires external reinstall media.
|
|
- Add short operator checklist for manufacturing line validation.
|
|
|
|
---
|
|
|
|
## 5) Validation
|
|
|
|
### VM test matrix
|
|
1. Build OEM ISO.
|
|
2. Write OEM ISO to virtual disk (not external media emulation).
|
|
3. Boot from virtual disk and verify:
|
|
- `/proc/cmdline` contains `copytoram=y`.
|
|
- Guardrail checks pass in healthy case.
|
|
4. Complete setup flow on first boot.
|
|
5. Install to same disk.
|
|
6. Reboot into installed OS.
|
|
7. Verify encryption:
|
|
- `lsblk` shows crypt mapping.
|
|
- `cryptsetup status` reports active LUKS device.
|
|
- Boot requires unlock passphrase.
|
|
8. Validate OEM warning + typed confirmation appears and gates destructive action.
|
|
|
|
### Boot path coverage
|
|
- UEFI + systemd-boot path.
|
|
- UEFI + GRUB path (if supported in current profile).
|
|
- BIOS/syslinux path (if still shipped).
|
|
|
|
### Hardware test matrix
|
|
- UEFI test on at least two hardware families (Intel + AMD).
|
|
- Confirm no external media required.
|
|
- Confirm first boot starts setup automatically.
|
|
|
|
### Negative tests
|
|
- OEM boot without `copytoram=y` -> safe abort with clear error.
|
|
- Low `MemAvailable` -> safe abort with clear error.
|
|
- Runtime state not RAM-backed -> safe abort with clear error.
|
|
- Power interruption before installer starts -> deterministic reboot behavior.
|
|
- Power interruption during install -> recovery requires external media (documented).
|
|
|
|
---
|
|
|
|
## 6) Security hardening checklist
|
|
|
|
- No factory credentials exist; customer sets all passwords at first boot.
|
|
- Clear shell history and transient setup artifacts at end of install.
|
|
- Verify no secrets in logs shipped to customer.
|
|
- Regenerate host identity on first installed boot as needed:
|
|
- `machine-id`
|
|
- SSH host keys (if installed/enabled)
|
|
- Keep package signature verification and keyring handling intact.
|
|
|
|
---
|
|
|
|
## Rollout Plan
|
|
|
|
1. Implement OEM build flag, mode marker, boot config injection, and build assertions.
|
|
2. Implement copytoram, memory, and runtime-state guardrails in `.automated_script.sh`.
|
|
3. Add OEM warning text and typed destructive confirmation in configurator.
|
|
4. Add docs and operator checklist.
|
|
5. Run VM matrix, including negative tests.
|
|
6. Run hardware matrix.
|
|
7. Cut first OEM preproduction release for manufacturing pilot.
|
|
|
|
---
|
|
|
|
## Definition of Done
|
|
|
|
- `--oem` build exists and is documented.
|
|
- Device preloaded with OEM image boots directly to setup.
|
|
- Setup installs to internal disk without external media.
|
|
- Final installed system is LUKS-encrypted with customer-owned passphrase.
|
|
- OEM safety guardrails fail closed with actionable errors.
|
|
- Existing non-OEM ISO behavior remains unchanged.
|
|
- VM and hardware QA matrix pass.
|