|
| 1 | +# SCI delivery step |
| 2 | + |
| 3 | +**Scope.** `sci-delivery.sh` is this repository's boot-test vehicle. The local |
| 4 | +boot proof runs it in a Garden Linux VM to test delivery reconciliation. |
| 5 | +Integration HVs receive manifest-selected raws through virtiofs instead (see |
| 6 | +section 8 of `../docs/sysext-virt.md`). It is not a supported consumer agent. |
| 7 | +The product is the signed release (see "Published boundary"). A consumer that |
| 8 | +reuses the step owns selection, staging persistence, key and anchor |
| 9 | +provisioning, and restart timing. Image mode and fetch mode are two ways to |
| 10 | +run the test vehicle, not two delivery products. Design and reasons: |
| 11 | +`../docs/sysext-virt.md`. |
| 12 | + |
| 13 | +## Pass contract |
| 14 | + |
| 15 | +These inputs are checked in order. Any validation failure exits non-zero and |
| 16 | +writes nothing to the host. |
| 17 | + |
| 18 | +1. Environment: `HOST_ROOT` exists; `INTERVAL` is a non-negative integer. |
| 19 | +2. Fetch mode, when `FETCH_URL` is set, builds the staging set first. |
| 20 | +3. Manifest: `<name> <restart-unit>...` entries; `#` comments and blank lines |
| 21 | + are ignored. A line `^[A-Z][A-Z0-9_]*=<value>$` is a directive. Unknown |
| 22 | + directives fail closed. `TARGET_BASE=<major>` is required and must be |
| 23 | + digits only. Every entry must have a staged `<name>.raw`; every |
| 24 | + `*-activation.service` shim must name an entry. |
| 25 | +4. Staged-raw integrity: `SHA256SUMS` must carry one standard line per entry |
| 26 | + (`<64-hex> <name>.raw`) and every raw named in the manifest must hash to |
| 27 | + its line. This runs before the gate and before any deployment. |
| 28 | +5. Base gate: read `<HOST_ROOT>/etc/os-release`, take the first dot-separated |
| 29 | + component of `IMAGE_VERSION` (fallback `GARDENLINUX_VERSION`), and compare |
| 30 | + it with `TARGET_BASE`. A mismatch, a missing field, or an unreadable file |
| 31 | + is a loud no-op: no deploy, no tool call, no delete, non-zero exit. |
| 32 | +6. Reconcile entries and `REMOVE` tombstones, then activate. |
| 33 | + |
| 34 | +## Environment |
| 35 | + |
| 36 | +| Variable | Meaning | |
| 37 | +|---|---| |
| 38 | +| `HOST_ROOT` | host root mount (default `/host`) | |
| 39 | +| `STAGING_DIR` | staging directory (default `/opt/sci`; fetch default `$FETCH_DIR/staging`) | |
| 40 | +| `INTERVAL` | seconds between passes; `0` runs one pass (default 60) | |
| 41 | +| `NSENTER` | `1` runs host tools via `nsenter -t 1 -m` (default); `0` runs them directly | |
| 42 | +| `FETCH_URL` | base URL of one release; unset selects image mode | |
| 43 | +| `FETCH_PUBKEY` | PEM key that verifies `SHA256SUMS.sig` (required in fetch mode) | |
| 44 | +| `FETCH_SUMS_DIGEST` | optional pinned sha256 of `SHA256SUMS` (64 lowercase hex) | |
| 45 | +| `FETCH_DIR` | writable fetch root (default `/var/lib/sci-sysext`) | |
| 46 | + |
| 47 | +`extensions.manifest` is in `delivery/extensions.manifest`. |
| 48 | + |
| 49 | +## Deploy and activate |
| 50 | + |
| 51 | +A raw that is missing or content-different is copied to |
| 52 | +`/var/lib/extensions/<name>.raw`; a staged shim that differs is copied to |
| 53 | +`/etc/systemd/system/<name>-activation.service`. Both use `.tmp` and `mv`. |
| 54 | +Equal files are not rewritten. When nothing changed and no marker is |
| 55 | +pending, no host-mutating command runs. |
| 56 | + |
| 57 | +`REMOVE=<name>` deletes only `<name>.raw`, `<name>-activation.service`, and |
| 58 | +its `multi-user.target.wants` symlink, then runs the normal activation flow |
| 59 | +and never restarts that extension's units. Removal is idempotent. A name |
| 60 | +that is also an entry, a duplicate, or an invalid name fails validation. |
| 61 | +Dropping an entry deletes nothing on the host. |
| 62 | + |
| 63 | +When anything changed, one sequence runs: |
| 64 | + |
| 65 | +`systemctl daemon-reload` → `systemd-sysext refresh` → `systemctl reload |
| 66 | +dbus.service` → `systemctl restart <units>` for each changed raw → |
| 67 | +`systemctl enable <name>-activation.service` for every shim and |
| 68 | +`systemctl restart` for changed or new entries. |
| 69 | + |
| 70 | +A failing per-extension unit restart is logged with the extension and units; |
| 71 | +the remaining restarts and all shims still run, and the pass exits non-zero. |
| 72 | +Only unit restarts are tolerant; the refresh trio and shim enable/restart |
| 73 | +are fatal. |
| 74 | + |
| 75 | +Before it deletes a host extension, the step writes |
| 76 | +`/var/lib/extensions/.sci-delivery-pending`. When only raw or shim files |
| 77 | +change, the step writes the marker after copying, before the activation flow. |
| 78 | +The step removes the marker when the flow completes. A pass that starts with |
| 79 | +the marker replays the full activation flow even when no file changed; without |
| 80 | +the marker there is no replay. In such a pass, an interruption after the copies |
| 81 | +and before the marker leaves the new files unactivated, and a later unchanged |
| 82 | +pass does not repair it. The marker is not an extension. |
| 83 | + |
| 84 | +## Known limitation |
| 85 | + |
| 86 | +`EXTENSION_RESTART_UNITS=` in extension-release files is inert on Garden |
| 87 | +Linux 2150.x (systemd 259 needs >= 262). The manifest carries the restart |
| 88 | +lists and must stay in sync with the extensions' metadata. |
| 89 | + |
| 90 | +## Fetch mode |
| 91 | + |
| 92 | +Fetch mode downloads one release and does not trust its staging directory. A |
| 93 | +pass downloads and verifies `SHA256SUMS` and `SHA256SUMS.sig`, treats the |
| 94 | +verified sums as the complete inventory, downloads only files whose staged |
| 95 | +hash differs, proves the full set with `sha256sum -c`, and prunes staging |
| 96 | +files the inventory no longer lists. It has no selection: the release |
| 97 | +manifest replaces any pre-seeded manifest. Every failure exits non-zero and |
| 98 | +writes nothing to the host. |
| 99 | + |
| 100 | +A converged pass downloads only `SHA256SUMS` and `SHA256SUMS.sig`. |
| 101 | +`STAGING_DIR` and `FETCH_DIR` must therefore live on storage that outlives the |
| 102 | +container. The shipped test image keeps them in the container layer. |
| 103 | + |
| 104 | +## Maintainer entry points |
| 105 | + |
| 106 | +```sh |
| 107 | +bash mkosi/build.sh # build all seven raws |
| 108 | +bash mkosi/build.sh <image> # build one image |
| 109 | +bash delivery/build-image.sh # stage, verify SHA256SUMS, build test image |
| 110 | +bash delivery/build-image.sh --stage-only |
| 111 | +bash delivery/build-image.sh --from-staging <dir> |
| 112 | +bash mkosi/boot-test.sh # local boot proofs |
| 113 | +.build/venv-test/bin/python -m pytest extensions/tests/ -q |
| 114 | +``` |
| 115 | + |
| 116 | +`build-image.sh` writes `SHA256SUMS` as standard `sha256sum` lines over the |
| 117 | +staged raws, then verifies it before the docker build. `--from-staging` |
| 118 | +verifies the shipped file instead of regenerating it. |
| 119 | + |
| 120 | +The test image carries only `sci-delivery:latest`. It is not published. |
| 121 | +`delivery/Containerfile` pins its Debian base by index digest. |
| 122 | + |
| 123 | +## Published boundary |
| 124 | + |
| 125 | +Publishing produces data only: the seven `<name>.raw` files, the four |
| 126 | +activation shims, `extensions.manifest`, `verity-run.crt`, `SHA256SUMS`, and |
| 127 | +`SHA256SUMS.sig`. The release tag is `<Release>-g<short sha>`. The publish |
| 128 | +job removes `sci-delivery.sh`, fails closed if it remains, regenerates the |
| 129 | +sums over the data set, and signs them. Without |
| 130 | +`SYSEXT_UNHARDENED_SIGNING_KEY` the release steps are skipped and no release |
| 131 | +exists. |
| 132 | + |
| 133 | +`sci-delivery.sh` and its image are test-only. The CI pipeline |
| 134 | +(`.github/workflows/sysext.yml`) builds, signs, and publishes; it is not a |
| 135 | +consumer deployment contract. See `../docs/sysext-virt.md` for the trust |
| 136 | +boundary and open responsibilities. |
0 commit comments