Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ Bring-up tools (`*-stage`, `display-hz`, `usbc-deadman`) stay per plan: they pok
| `BOOT_METHOD` | `android-v4` (default when omitted) | Generic images, flash, push and installer accept only `android-v4`; other methods are refused before phone access. `ram-only` marks a probe with no persistent install support. `android-v0` (enchilada) is a header-v0 phone: `images` packs one `boot.img` for `fastboot boot`, and fastboot, flash, push and the installer refuse it |
| `PAGESIZE`, `BASE`, `KERNEL_OFFSET`, `RAMDISK_OFFSET`, `SECOND_OFFSET`, `TAGS_OFFSET` | (enchilada: `4096`, `0x00000000`, `0x00008000`, `0x01000000`, `0x00f00000`, `0x00000100`) | `android-v0` only, all required: the header-v0 page size and load offsets, numbers in decimal or lower-case hex. `images` packs the gzip `Image` with the `DTB` appended as the kernel, the initramfs as the ramdisk and `CMDLINE` as the command line. `BOOT_IMAGES` is `boot` alone and `boot_b` must be on `UFS_RW` |
| `BOOT_IMAGES` | `boot init_boot vendor_boot vendor_kernel_boot dtbo` | The images written to slot B (the `_b` suffix is added by the tools and is not configurable). `boot`, `vendor_boot` and `dtbo` are always there. Without `init_boot`, `boot` carries the empty generic ramdisk and the OS version; without `vendor_kernel_boot`, `vendor_boot` carries the DTB and the initramfs (the Pixel 6: `boot vendor_boot dtbo`) |
| `BOOT_UPDATE_AUTO_WRITE` | (unset; defaults to `yes`) | Optional: `yes` or `no`. The installer records it as `AUTO_WRITE` in `/etc/omamobile/boot-update.conf`; `no` keeps an installed development root from writing slot B through package updates. It does not change the installer's own allowed writes |
| `UFS_RW` | `boot_b … dtbo_b userdata` | The storage guard's allowlist, packed into the initramfs as `/etc/omamobile-ufs-rw`. Only slot B's boot images (`boot_b`, `init_boot_b`, `vendor_boot_b`, `vendor_kernel_boot_b`, `dtbo_b`) and `userdata` are accepted, `userdata` and every `BOOT_IMAGES` entry must be on it, and each name only once. The init fails closed: a missing, empty or malformed file, or any other name in it, leaves every partition read-only |
| `UFS_RW_LUNS` | (unset) | Optional. The LUNs besides `sda` that hold `UFS_RW` partitions, as disk names `sdb` to `sdz`, packed as `/etc/omamobile-ufs-rw-luns`. The init guards each as it guards `sda`: the whole-disk node removed, the disk left writable, and only its `UFS_RW` partitions left writable. Absent (every descriptor so far), malformed, or with a closed allowlist: every LUN but `sda` stays read-only at the disk level. Boot-image writers on the phone (`omamobile-boot-update`) still look only on `sda` |
| `INITRAMFS_INIT` | `/initramfs/init` | The init script. A leading `/` is relative to the repo root, so devices share one script. Any other value is relative to the descriptor |
Expand Down Expand Up @@ -341,6 +342,18 @@ The bundle's signed `SHA256SUMS` covers its `MANIFEST`, which names the exact ro
- **Server:** `tools/server/releases-nginx.sh`, run once by the maintainer with sudo on the server, adds a `location ^~ /releases/` to the `pkgs.omamobile.org` vhost. The vhost already serves `/releases/` as plain files: a missing file is a 404, and byte ranges and `Content-Length` work. The script adds `Access-Control-Allow-Origin: *` with the exposed range headers and an answer to `OPTIONS` preflights, `Cross-Origin-Resource-Policy: cross-origin`, MIME types for `.json`, `.zst`, `.img`, `.sig` and `.sha256`, no gzip (so sizes stay exact), a year's immutable cache on version directories (but not on their 404s), `no-cache` on `latest.json`, a 403 for the upload's staging directories, and the security-headers snippet in every location. It does a dry run first, `nginx -t`, a verified reload and live checks, and it rolls back on any failure (`revert` undoes it).
- **Bandwidth:** each install downloads about 2.8 GB (a 2.7 GB root image plus about 80 MB of boot images, from the `.tar` or file by file; the `.tar` doubles the storage a release takes on the server, not the transfer), so 1 TB of transfer is about 350 installs. GitHub's per-file limit is 2 GiB, so a root image there would have to be split and joined again, which a browser flasher and the signed manifest would both have to know about. Our own server stays the one source; check the VPS plan's monthly transfer allowance before announcing a release.

### Development installer policy

A device descriptor may set `BOOT_UPDATE_AUTO_WRITE=no` to keep an installed
development root from writing boot images through package updates. The
installer records that value in `/etc/omamobile/boot-update.conf`; descriptors
that omit the key retain `AUTO_WRITE=yes`. Only `yes` and `no` are accepted.
This does not change which partitions the installer itself writes.

Use `tools/install-phone --serial <SERIAL>` to pin the phone for an install;
this is the installer's existing command-line check, independent of the
automatic boot-update policy.

## 7. Versions and tags

| Thing | Version | Where it is recorded |
Expand Down
18 changes: 18 additions & 0 deletions tests/install-phone
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,24 @@ OMAMOBILE_FIRSTBOOT_ROOT=$t/fbroot "$SRC/packages/omamobile-firstboot/bin/omamob
[[ $(debugfs -R 'cat /etc/omamobile/boot-update.conf' "$flashed" 2>/dev/null | grep -v '^#') == AUTO_WRITE=yes ]] \
|| fail "a release install turns the boot hook on (boot-update.conf AUTO_WRITE=yes)"
debugfs -R 'stat /etc/omamobile/boot-update.conf' "$flashed" 2>/dev/null | grep -c 'User: 0 Group: 0' >/dev/null || fail "boot-update.conf belongs to root"
# Development devices keep the hook off in the actual prepared image.
echo 'BOOT_UPDATE_AUTO_WRITE=no' >> "$R/device/testdev/device.conf"
install || { cat "$t/out"; fail "a development install succeeds"; }
policy_image=$t/userdata.flashed
if command -v simg2img >/dev/null && [[ $(head -c4 "$policy_image" | od -An -tx1 | tr -d ' ') == 3aff26ed ]]; then
simg2img "$policy_image" "$t/policy.img"; policy_image=$t/policy.img
fi
[[ $(debugfs -R 'cat /etc/omamobile/boot-update.conf' "$policy_image" 2>/dev/null | grep -v '^#') == AUTO_WRITE=no ]] ||
fail "the development image must disable automatic boot writes"
pass "development descriptor keeps automatic boot writes off in the image"
for value in '' YES true maybe; do
descriptor > "$R/device/testdev/device.conf"
printf 'BOOT_UPDATE_AUTO_WRITE=%s\n' "$value" >> "$R/device/testdev/device.conf"
if install --dry-run; then fail "invalid boot-update policy accepted: $value"; fi
[[ ! -s $t/fastboot.log ]] || fail 'invalid boot-update policy reached fastboot'
done
descriptor > "$R/device/testdev/device.conf"
pass "invalid boot-update policies refuse before any phone query"
pass "the image copy gets a root-only firstboot.conf (hash, not password) and root's key, which firstboot accepts"

# A root that already has /etc/omamobile and /root/.ssh (a restored or
Expand Down
15 changes: 9 additions & 6 deletions tools/install-phone
Original file line number Diff line number Diff line change
Expand Up @@ -28,10 +28,10 @@
# time zone, optional Wi-Fi and the SSH public key, writes them as
# /etc/omamobile/firstboot.conf (and root's authorized_keys) into a LOCAL
# COPY of the root image with debugfs (no root needed), with
# /etc/omamobile/boot-update.conf (AUTO_WRITE=yes: kernel package updates
# reach slot B through omamobile-boot-update, docs/RELEASES.md §5.3; a
# development phone, set up by hand, has no such file), shows exactly what it
# will run, and waits for the codename to be typed. The phone's first boot
# /etc/omamobile/boot-update.conf (AUTO_WRITE defaults to yes; descriptors
# may set BOOT_UPDATE_AUTO_WRITE=no to keep development kernel updates off
# slot B, docs/RELEASES.md §5.3), shows exactly what it will run, and waits
# for the codename to be typed. The phone's first boot
# (omamobile-firstboot) creates the user from that file and deletes it.
# The key also goes into a copy of slot B's ramdisk image, as
# omamobile-boot-update appends it, so the initramfs's rescue SSH takes it.
Expand Down Expand Up @@ -151,6 +151,9 @@ while IFS= read -r line || [[ -n $line ]]; do
done < "$conf"
CODENAME=${D[CODENAME]:-}
[[ $CODENAME =~ ^[a-z0-9]+$ ]] || die "$conf: no CODENAME"
BOOT_UPDATE_AUTO_WRITE=${D[BOOT_UPDATE_AUTO_WRITE]-yes}
[[ $BOOT_UPDATE_AUTO_WRITE == yes || $BOOT_UPDATE_AUTO_WRITE == no ]] ||\
die "$conf: BOOT_UPDATE_AUTO_WRITE must be yes or no"
[[ $mode == bundle || $CODENAME == "$device" ]] || die "$conf: CODENAME=$CODENAME, expected $device"
# Legacy descriptors omit BOOT_METHOD; only their Android v4 path is installable.
# Refuse before image preparation or any fastboot query/write.
Expand Down Expand Up @@ -547,7 +550,7 @@ trap cleanup EXIT
printf '%s\n' "$ssh_key" > "$keys_file"
printf '%s\n' "# Written by install-phone: a release install takes kernel updates through" \
"# omamobile-boot-update's pacman hook (docs/RELEASES.md §5.3). AUTO_WRITE=no stops it." \
"AUTO_WRITE=yes" > "$boot_conf"
"AUTO_WRITE=$BOOT_UPDATE_AUTO_WRITE" > "$boot_conf"
)
unset wifi_psk

Expand Down Expand Up @@ -590,7 +593,7 @@ cmp -s <(debugfs -R "cat /etc/omamobile/firstboot.conf" "$copy" 2>/dev/null) "$c
cmp -s <(debugfs -R "cat /root/.ssh/authorized_keys" "$copy" 2>/dev/null) "$keys_file" || die "writing authorized_keys into the image copy failed"
cmp -s <(debugfs -R "cat /etc/omamobile/boot-update.conf" "$copy" 2>/dev/null) "$boot_conf" || die "writing boot-update.conf into the image copy failed"
e2fsck -fn "$copy" >/dev/null 2>&1 || die "the image copy doesn't check clean after the writes"
note "firstboot.conf, root's authorized_keys and boot-update.conf (AUTO_WRITE=yes) written, file system checks clean"
note "firstboot.conf, root's authorized_keys and boot-update.conf (AUTO_WRITE=$BOOT_UPDATE_AUTO_WRITE) written, file system checks clean"
userdata_image=$copy
if command -v img2simg >/dev/null; then
img2simg "$copy" "$sparse"
Expand Down