diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ba14465..5989104 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -99,9 +99,9 @@ jobs: echo "$out" # The "not executable" line of each service shows that systemd # really loaded our units. - n="$(echo "$out" | grep -c -E '^pullgate-(apply@[^ ]*|listen|run@[^ ]*)\.service: Command /usr/local/bin/pullgate is not executable' || true)" - if [ "$n" -ne 3 ]; then - echo "expected 3 'not executable' lines (apply, listen, run), got $n" >&2 + n="$(echo "$out" | grep -c -E '^pullgate-(apply@[^ ]*|listen|run@[^ ]*|update)\.service: Command /usr/local/bin/pullgate is not executable' || true)" + if [ "$n" -ne 4 ]; then + echo "expected 4 'not executable' lines (apply, listen, run, update), got $n" >&2 exit 1 fi if echo "$out" \ @@ -144,13 +144,21 @@ jobs: with: go-version-file: go.mod - name: Build - run: CGO_ENABLED=0 go build -trimpath -o "${RUNNER_TEMP}/pullgate" ./cmd/pullgate - - name: The README install, then a good commit and a failed one + # Two builds of this commit with release versions: the first is + # installed, /update moves it to the second. The versions are far + # above every real release, so the daily look at the real GitHub + # (before the fake one is in place) finds nothing newer. + run: | + CGO_ENABLED=0 go build -trimpath -ldflags "-X main.version=900.0.0" -o "${RUNNER_TEMP}/pullgate" ./cmd/pullgate + mkdir -p "${RUNNER_TEMP}/new" + CGO_ENABLED=0 go build -trimpath -ldflags "-X main.version=900.0.1" -o "${RUNNER_TEMP}/new/pullgate" ./cmd/pullgate + - name: The README install, a good commit, a failed one, and /update # The install commands come from README.md itself. Root and the # listener are different users, under the real units. A tap on a # fake Telegram applies a commit; a failing commit rolls back - # (DESIGN.md section 14, issue #27). - run: sudo sh test/units/full-loop.sh "${RUNNER_TEMP}/pullgate" + # (DESIGN.md section 14, issue #27). Then /update installs the + # second build from a fake GitHub, with its units (issue #9). + run: sudo sh test/units/full-loop.sh "${RUNNER_TEMP}/pullgate" --update-to "${RUNNER_TEMP}/new/pullgate" lint: runs-on: ubuntu-latest diff --git a/AGENTS.md b/AGENTS.md index 7aaddc6..3553f9a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,11 @@ change code. They are the rules the code must follow. list, the cut to one message (DESIGN.md section 12). - `internal/gate/` - `run`, `apply` and `status` (DESIGN.md sections 7, 9, 10, 13). + - `internal/selfupdate/` - `pullgate update`: the notice of a new release, + `/update`, and the install with its units (DESIGN.md section 15). +- `embed.go` - the files that the binary carries: `install.sh` and the + units of `contrib/systemd/`. The tests of `install.sh` are in the same + package. - `contrib/` - example systemd units and example configs. - `install.sh` - installs or updates a release on a host, after its checks (DESIGN.md section 16). Its tests are `install_linux_test.go`, at the diff --git a/DESIGN.md b/DESIGN.md index 4aa531b..256913d 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -32,6 +32,8 @@ protects, and where it stops. starts a normal run now, instead of at the next timer (sections 8 and 9). - **pause file**: `/var/lib/pullgate/NAME/paused`. While it exists, the instance does nothing: no run, no apply. +- **update question**: a question that names one release of pullgate + itself: its version and the SHA-256 of its tarball (section 15). ## 2. The rules @@ -78,6 +80,7 @@ These rules come from issue #1. Each one has tests (section 14). | `check`, `summary` | `check_user` (default `pullgate-check`) | `pullgate run` | nothing | | `apply`, `health` | root | `pullgate apply` | what the owner's command needs | | `pullgate status NAME` | root | the owner | nothing | +| `pullgate update` | root | a timer (`pullgate-update.timer`, daily), or a path unit (`pullgate-update.path`) for `/update` and a tap | the binary, the units, its own state (section 15) | Root and the listener never talk directly. They use a spool directory (section 8). Both units start the same `pullgate-run@NAME.service`, so a @@ -110,6 +113,9 @@ can be less strict; each example sets what its `apply` needs. | `/var/spool/pullgate/NAME/inbox` | listener, 0700 | approvals from the listener to root | | `/var/spool/pullgate/NAME/check` | listener, 0700 | check requests from the listener to root | | `/var/lib/pullgate-listener/state.json` | listener, 0600 | the listener's open questions | +| `/var/lib/pullgate/_update/` and `.../tmp/` | root, 0700 | the state, the lock and the downloads of `pullgate update` (section 15) | +| `/var/spool/pullgate/_update/` | as `NAME/` above | the outbox, inbox and check request of the updates | +| `/usr/local/bin/.pullgate.prev` | root | the old binary during an update (a hard link) | The paths can be changed with `--config-dir`, `--state-dir` and `--spool-dir`, for tests. @@ -490,7 +496,7 @@ usage text, which lists the instances and never repeats the message. **`/help`.** When the text is exactly `/help`, from `owner_id`, in `chat_id`, not edited, the listener replies with a fixed list: the -commands (`/check`, `/check NAME`, `/help`), the instance names from +commands (`/check`, `/check NAME`, `/update`, `/help`), the instance names from `instances`, what Apply and Skip do, and the root commands for the host (`pullgate status NAME`, `--pause`, `--resume`, `--ask-again`), at most once per minute. The @@ -752,6 +758,17 @@ that cannot be enabled, fails CI. Without root, CI also runs checks that each unit the README tells you to enable has an `[Install]` section with `WantedBy=`. +`internal/selfupdate` tests `pullgate update` with the real built-in +`install.sh` against a fake release (a fake `curl`, `gh` and `uname`, and +fake binaries): the question, the install, a wrong SHA-256, a failed +attestation, a wrong version (each before the question and on Apply), a +tarball that changed after the question, an older version, a newer release +while a question is open, Skip, an expired question, a listener that does +not start (rollback), a crash at each step, the daily notice (once, again +each day for a security release, off with `check = false`), and the unit +update (a changed unit, a new unit, a masked unit, a disabled unit, a +drop-in). + `test/units/full-loop.sh` (CI job `install-loop`, on each pull request and on `main`) is the path a user takes, as root on the throwaway runner: @@ -775,7 +792,14 @@ and on `main`) is the path a user takes, as root on the throwaway runner: 4. It restarts the listener and checks that it polls again. 5. A commit whose apply fails: the rollback runs, and its notice reaches the fake Telegram. -6. Each unit of the README `start` block is `enabled` and `active`. +6. With `--update-to` (the CI job builds this commit twice, as 900.0.0 + and 900.0.1): a fake GitHub (a fake `/usr/bin/curl` that serves local + files, and a fake gh in `[updates] gh`, because the build under test has + no attestation), a changed unit and a drop-in, then `/update` on the + fake Telegram. The fake taps Apply; root installs 900.0.1 with the + built-in `install.sh`, puts back the shipped unit, lists the drop-in, + restarts the listener, and the new listener sends the report. +7. Each unit of the README `start` block is `enabled` and `active`. After each loop, the outbox must be empty and the listener must have logged no error and no warning. So a message that root writes and the @@ -788,12 +812,143 @@ tag's own `install.sh --version X.Y.Z`, then runs The Release workflow calls it after it publishes; it also runs on `release: published` and by hand. -## 15. Not in version 0.1 +## 15. Updates of pullgate itself (`/update`) + +The owner updates pullgate from Telegram. It is the same gate as for a +commit: one question that names one exact release, and a tap. What it +trusts: THREAT-MODEL.md, T20. + +**The parts.** `pullgate update` runs as root, from +`pullgate-update.service`. Two units start it: `pullgate-update.timer` +(once a day) and `pullgate-update.path` (the check request or an approval +of the updates). It reads `/etc/pullgate/listener.toml` (it needs no +token), and uses its own state and spool, named `_update` +(`/var/lib/pullgate/_update/`, `/var/spool/pullgate/_update/`). An instance +name cannot start with `_`, so no instance can use them. The binary carries +two things of its own version: a copy of `install.sh` (section 16), and the +units of `contrib/systemd/` (`pullgate units` prints them as JSON, with the +list of units that the README enables). + +**The listener** handles `/update` as `/check`: only exactly `/update`, +from `owner_id`, in `chat_id`, not edited. It writes the check request +`_update/check/request` (the six bytes `check\n`, nothing from the +message), at most one in 10 seconds, and replies "Looking for a new release +of pullgate…". A tap on an update question writes an approval to +`_update/inbox`, as for an instance (section 9). It sends what root puts +in `_update/outbox`. + +**Looking for a release.** Root runs the built-in `install.sh +--check-only` with `TMPDIR=/var/lib/pullgate/_update/tmp`. The script does +the checks of section 16 on the newest release (the SHA-256 and the +attestation; it does not run the new binary before the tap), installs +nothing, and +prints lines that start with `@pullgate ` for root: `version X.Y.Z +security|normal`, `up-to-date X.Y.Z`, `fetched X.Y.Z`, `checked X.Y.Z +SHA256 security|normal`. A release is a security release when its notes +have the section `### Security` (release-please makes it from `security:` +pull requests, docs/releasing.md). Root itself checks again that the +version is newer than its own. Then: + +- **Up to date**: nothing. For `/update`, a notice says so. +- **A newer release that passed every check**: for `/update`, root asks. + From the timer, it sends one notice per release: the version, the link + to the release notes and "send /update to install it". A security + release says so on the first line, and its notice comes again each day + (23 hours) until it is installed. A notice has no buttons and needs no + tap. `[updates] check = false` in `listener.toml` stops the daily look + and its notices; `/update` still works. +- **A release that failed a check** (after its files were downloaded): + one warning notice per release ("failed a check, so it is not + offered"), with the reason from `install.sh`. It never gets a question + or the "/update" hint. For `/update`, the warning comes each time. +- **No answer from GitHub** (before the download): a log line; for + `/update`, a notice. A build from the source (`pullgate dev`) does + nothing and says so: it cannot know which release is newer. + +At most one `/update` per minute is acted on (`check_at` in root's state). + +**The question.** Root makes a new code, writes the question to its state +(synced), then to the outbox, as in section 7: + +``` +pullgate on HOST, update of pullgate +⚠ Security release. It fixes a security problem. (only for one) +Update pullgate to X.Y.Z? +Installed now: OLD +Release notes: https://github.com/code6x/pullgate/releases/tag/vX.Y.Z +File: pullgate_X.Y.Z_linux_ARCH.tar.gz +SHA-256: …64 hex digits… +``` + +It can be answered for 12 hours. At most one update question is open. +When the timer or `/update` finds a newer checked release while a question +is open, root closes the old one ("a newer question replaced this one") +and asks again. When the installed version is the newest again (installed +by hand), it closes the question. + +**Root's state**, `/var/lib/pullgate/_update/state.json` (root, 0600): +`question` (id, code, version, sha256, asked, expires), `notified` and +`warned` (release → time of its last notice), `check_at`, `check_note`, +and `in_progress` (version, from, started) while an update runs. + +**Apply.** `pullgate update` takes the lock (`_update/lock`), reads the +approvals as in section 9 (code with a constant-time compare, time, once), +and takes the version and the SHA-256 **from its own state**. Skip: a reply, +nothing else. Apply, forward only (the version must be newer than its +own; never an older one from Telegram): + +1. Write `in_progress` (synced). Give the old binary a second name, + `DIR/.pullgate.prev` (a hard link), and sync the directory. +2. Run the built-in `install.sh --version X.Y.Z --sha256 SHA256 + --forward-only --bin-dir DIR` (and `--gh` from `[updates] gh`). It + downloads the files again and does every check again; the tarball must + also have the SHA-256 of the question. It renames the new file over + `DIR/pullgate` as its last step. A failure here installs nothing: root + removes `.pullgate.prev`, clears `in_progress` and reports why. +3. Run `DIR/pullgate version`: it must print `pullgate X.Y.Z`. +4. Run `DIR/pullgate units` (the new binary). Check the list: only names + `pullgate-*.service`, `.timer`, `.path`, at most 32 files of 64 KiB. + Write each unit that differs from `/etc/systemd/system/NAME` (a + temporary file, sync, rename), and keep the old content. A unit there + that is a link (masked) is left alone. Drop-ins + (`/etc/systemd/system/pullgate-*.d/*`) are never changed; they are + listed in the report. +5. `systemctl daemon-reload`. For each unit that the README enables (for + each instance in `instances`): when it is enabled, or new in this + version, `systemctl reenable` and `systemctl restart` it. A unit that + the owner disabled stays disabled. The listener is re-enabled here, + but restarted last. +6. `systemctl restart pullgate-listen.service`, wait 5 seconds, and check + `systemctl is-active pullgate-listen.service`. +7. Remove `.pullgate.prev`, clear `in_progress`, and write the report: + "pullgate is updated: OLD → NEW", the units it installed, the links it + left alone, and every drop-in. The new listener sends it. + +When step 3, 4, 5 or 6 fails: rename `.pullgate.prev` back over +`DIR/pullgate`, write back the old unit files (and remove the new ones), +`daemon-reload`, restart the units and the listener, clear `in_progress`, +and report "the update failed: REASON. pullgate OLD is back". If the +rollback has problems too, the report says which, and how to fix it by +hand with `install.sh`. + +**A crash** leaves `in_progress`. The binary is the old file or the new +one: each change of the name `pullgate` is a rename in one directory, after +a sync (THREAT-MODEL.md, T10). The next start reports "the update was cut +off" with what `pullgate version` says, and how to check the host. It does +not guess, and leaves `.pullgate.prev` for the owner. + +**The config** (in `listener.toml`, every key optional): -- Self-update of pullgate. `install.sh` updates it only when root runs - the script (section 16). -- Signed commits (`git verify-commit`). -- A web UI. +```toml +[updates] +check = true # false: no daily look, no notices; /update works +listener_user = "pullgate" # the listener user: owns the inbox of the updates +gh = "/usr/bin/gh" # the gh that checks the attestation, as install.sh --gh +``` + +There is no key to skip a check. + +**Not yet**: signed commits (`git verify-commit`), a web UI. ## 16. The install script @@ -804,6 +959,13 @@ It is a POSIX `sh` script. Root runs it on the host itself: sh install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall] ``` +`pullgate update` runs the copy of this script that is built into the +binary, with three more flags (section 15): `--check-only` (every check, +install nothing), `--sha256 HEX` (with `--version`: install only a tarball +with this SHA-256) and `--forward-only` (never the same or an older +version). It reads the lines that start with `@pullgate ` on the standard +output. + All the work is in functions. Only the last line starts `main`, so a download that stops in the middle runs nothing. The steps: diff --git a/README.md b/README.md index 4141884..f4a2018 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,8 @@ the release (with `gh attestation verify`), and the version that the new binary prints. It needs `curl`, `tar`, `gzip`, `sed` and GNU coreutils. Without `--gh`, it downloads a pinned gh and checks its SHA-256. It replaces the old binary only in the last step, and restarts nothing: it prints what to -restart. Run it again to update. `--reinstall` installs the same version +restart. Run it again to update, or update from Telegram with `/update` +(below). `--reinstall` installs the same version again, or replaces a build of unknown version. Exit codes: 0 done or nothing to do, 1 failure (nothing was installed), 64 wrong usage. To get the script of one release, put its tag (`vX.Y.Z`) in the URL instead of `main`. @@ -118,6 +119,7 @@ systemctl daemon-reload systemctl enable --now pullgate-listen.service systemctl enable --now pullgate-apply@NAME.path pullgate-run@NAME.timer systemctl enable --now pullgate-check@NAME.path # optional: /check +systemctl enable --now pullgate-update.timer pullgate-update.path # optional: release notices, /update ``` Every step logs to the journal: `journalctl -t pullgate`. @@ -159,6 +161,59 @@ usual Apply question, or "No new commit (the applied commit is …)", or - Without `pullgate-check@NAME.path`, the request waits for the next timer run. +## Update pullgate: `/update` + +Once a day `pullgate-update.timer` looks for a new release of pullgate. For +each new release that passes the checks of `install.sh` (the SHA-256 and +the build attestation), the bot sends one notice: the version, the link to +the release notes, and "send /update to install it". A release that fixes +a security problem says so first, and its notice comes again each day +until it is installed. A notice never installs anything. + +The first look runs within an hour after the timer starts, and makes the +directories that `/update` needs. To have it at once, run +`systemctl start pullgate-update.service`. + +To install it, send the bot `/update`: + +1. The listener answers "Looking for a new release of pullgate…". +2. Root checks the newest release again and sends a question with the + version, the link to the release notes, the tarball for this CPU, and + its SHA-256, with **Apply** and **Skip**. +3. On **Apply**, root installs only that tarball, with every check of + `install.sh` done again. Then it installs the units of + `contrib/systemd/` of the new version where they differ from yours, + runs `systemctl daemon-reload`, re-enables and restarts the units, and + restarts the listener last. +4. The new listener sends the report: the old and the new version, the + units it installed, and your drop-ins (`/etc/systemd/system/pullgate-*.d/`). + Check that you still need each drop-in. + +If the new listener does not stay active, root puts the old binary and the +old units back, and reports why. pullgate never installs an older version +from Telegram; to install one, run `install.sh --version X.Y.Z` by hand. A +build from the source (`pullgate dev`) does not update itself. + +Keep your changes to a unit in a drop-in (`systemctl edit UNIT`): an +update replaces the unit files. A unit that you disabled stays disabled, +and a masked unit is left alone. + +The settings, in `/etc/pullgate/listener.toml` (all optional): + +```toml +[updates] +check = false # no daily look and no notices; /update still works +listener_user = "pullgate" # the user of the listener (default "pullgate") +gh = "/usr/bin/gh" # the gh that checks the attestation, as install.sh --gh +``` + +To use `/update` on a host that runs an older version: install this +version with `install.sh`, copy the units of `contrib/systemd/` again, run +`systemctl daemon-reload`, and enable the two new units: +`systemctl enable --now pullgate-update.timer pullgate-update.path`. +How it works: [DESIGN.md](DESIGN.md) section 15; what it trusts: +[THREAT-MODEL.md](THREAT-MODEL.md) T20. + ## Config The instance config `/etc/pullgate/NAME.toml`: @@ -256,6 +311,7 @@ better): |---|---|---| | `pullgate-listen.service` | 1.2 OK | own user, no capabilities, read-only system | | `pullgate-run@.service` | 2.4 OK | root, but only the capabilities it needs to run `check` as `check_user`, to stop it on a timeout, and to fix the spool; read-only system | +| `pullgate-update.service` | not measured | it installs pullgate and its units as root, and restarts them, so its sandbox is light | | `pullgate-apply@.service` | 7.9 EXPOSED | it runs your `apply` command as root, which must change the system. Add a drop-in for what your `apply` needs (`systemctl edit pullgate-apply@NAME.service`) | The run unit sets `MemoryDenyWriteExecute=yes`, which also holds for diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index 6d5a74d..622db79 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -223,9 +223,10 @@ file that `apply` should not touch. rollback runs the **old** apply on the old tree, with the commands of the current process (the old gate). So a rollback puts the old gate files back when `apply` installs them. If the new gate did break pullgate itself (for -example a bad binary), the next run fails to start and the owner sees the -failed unit; pullgate does not try to repair itself (self-update is not in -0.1). +example a bad binary that `apply` installed), the next run fails to start +and the owner sees the failed unit; the gate does not repair what `apply` +installed. Let `apply` not install pullgate: `/update` does that, with +every check of `install.sh` and a way back (T20). *Left.* An approved commit can change everything. This is the price of having the host manage itself. @@ -292,6 +293,18 @@ file, marks the SHA failed, and reports. It does not guess. The state is written to a temporary file, synced, and renamed, so it is never half written. +*The update of pullgate itself* (T20) has the same rule. Root syncs +`in_progress` before it touches the binary. The old binary gets a second +name (`.pullgate.prev`, a hard link in the same directory). `install.sh` +writes the new file under a temporary name, syncs it, and renames it over +`pullgate`; a rollback renames `.pullgate.prev` back. A rename in one +directory replaces the name in one step, so after a crash or a power loss +the host has the old binary or the new one, never none and never a part of +one. The next start of `pullgate update` sees `in_progress`, reports "the +update was cut off" with what `pullgate version` says, and does not guess. +A test stops the update at each step and checks this +(`TestCrashInTheSwap`). + ### T11. A wrong clock *Accident or attack.* The host clock jumps forward or back. @@ -335,6 +348,18 @@ file. from the host config; a read-only deploy key; no other protocols. git has a timeout and an output cap. The tree export has caps. +*Downloads of releases* (T17, T20). For `/update`, root also downloads +from GitHub, with the built-in `install.sh`: HTTPS only, also after a +redirect (`--proto '=https' --proto-redir '=https'`), TLS 1.2 or newer, a +size limit for each file (1 MiB, 64 MiB for a tarball), a time limit for +each download and 20 minutes for the whole script. A redirect may go to +another HTTPS host (GitHub serves its files from other hosts); the +SHA-256 and the attestation, not the host name, prove the file. The +script takes only the member `pullgate` out of the tarball, and only +after the attestation passed. GNU tar refuses members with `..` and +removes a leading `/`; a `pullgate` that is a link, a device or not a +regular file is refused. Root never runs anything else from the tarball. + ### T14. Weak gate files *Attack.* A local user can write the config, the deploy key, the known @@ -463,6 +488,73 @@ once per minute. *Left.* Someone with the bot token can read the help, as they can read every question. +### T20. The update of pullgate itself (`/update`) + +The update replaces the program that is the gate. A wrong or bad binary +removes the gate on that host. So it has the same rules as a commit, and +more checks. + +*Attack: a bad binary.* An attacker serves a tarball that the release +workflow did not build, or an older build under a newer name. +*Defense.* Root runs the copy of `install.sh` that is built into the +running binary, so the code that checks is the code that was checked and +installed before. **Before the question is sent** it checks the SHA-256 +from `SHA256SUMS` and runs `gh attestation verify` with the release bundle +and the release workflow identity. No code of the release runs before the +tap: `--check-only` does not run the new binary. On Apply it downloads the +files again and does every check of T17 again, and also runs the new +binary's `pullgate version`. On Apply, the tarball must also have the SHA-256 that the +question showed (`--sha256`), so Apply installs only that file (rule 2). The +attestation check is required. There is no setting that skips it. +`[updates] gh` names the gh that checks, as `install.sh --gh` does; it must +be gh 2.93.0 or newer and only root may change it. A release that fails a +check gets a warning notice, never a question and never the "/update" hint. + +*Attack: a stolen bot token.* The thief can send `/update` as a message, +but only the owner's user ID in the owner's chat counts (rule 4), and a +message holds nothing: the listener writes the six bytes `check\n`. A +forged request only makes root look for a release and ask. The thief +cannot tap as the owner (T1). Root takes the version and the SHA-256 from +its own state, never from the approval. + +*Attack: a compromised listener.* It can write requests and approvals in +`/var/spool/pullgate/_update/`, as for an instance (T2, T12). An approval +counts only with the code of the open question, within 12 hours, once. It +cannot name a version or a file. + +*Attack: a published release that is bad* (T16 failed). Forward only: +root never installs the same or an older version from Telegram (its own +check, and `install.sh --forward-only`). The owner taps Apply after reading +the release notes. A release is never installed without a tap: the daily +notice only says "send /update". The owner can install a pinned version by +hand with `install.sh --version X.Y.Z`. + +*Accident: the new binary does not start.* Root keeps the old binary as +`.pullgate.prev` until the new one works: it runs `pullgate version`, gets +the units of the new binary (`pullgate units`), installs the ones that +changed, reloads systemd, restarts the units, restarts the listener last, +and checks that the listener is still active 5 seconds later. When a step +fails, it puts the old binary and the old unit files back, reloads, +restarts the listener, and reports. The new listener sends the report of +a good update, so the report also shows that it runs. + +*The units.* Root writes only files named `pullgate-*.service`, `.timer` +or `.path` in `/etc/systemd/system`, at most 32 of 64 KiB, that the new +(attested) binary carries. A unit that is a link (for example masked) is +left alone. Drop-ins are never changed: they are listed in the report, so +the owner sees a workaround that a release made unneeded. A unit that the +owner disabled stays disabled; only a unit that is new in this version is +enabled. + +*Name space.* The updates use `/var/lib/pullgate/_update/` and +`/var/spool/pullgate/_update/`. An instance name matches +`[a-z0-9][a-z0-9-]{0,31}`, so no instance can be named `_update`, and an +instance named `pullgate` has its own directories (`TestUpdateQuestionsAreTheirOwn`). + +*Left.* Whoever controls the release workflow on `main`, or GitHub, can +ship a binary that passes (T16); the owner's tap is the last check. A +build from the source (`pullgate dev`) does not update itself. + ## 6. Out of scope - An attacker who is root on the host. diff --git a/cmd/pullgate/main.go b/cmd/pullgate/main.go index c4e4730..97081ad 100644 --- a/cmd/pullgate/main.go +++ b/cmd/pullgate/main.go @@ -4,18 +4,26 @@ package main import ( "context" + "encoding/json" "errors" "flag" "fmt" "io" "log/slog" "os" + "os/exec" "os/signal" + "path/filepath" + "runtime" "syscall" + "time" + "github.com/code6x/pullgate" "github.com/code6x/pullgate/internal/config" "github.com/code6x/pullgate/internal/gate" "github.com/code6x/pullgate/internal/listener" + "github.com/code6x/pullgate/internal/selfupdate" + "github.com/code6x/pullgate/internal/spool" "github.com/code6x/pullgate/internal/telegram" ) @@ -32,6 +40,9 @@ commands: --ask-again: ask about the last tip again; it also closes an open question for it, so the next run sends a new one listen [--config FILE] the Telegram listener (its own user) + update [--config FILE] look for a new release of pullgate, and install + one after a tap (pullgate-update.service runs it, as root) + units print the units this binary carries, as JSON version` func main() { @@ -66,7 +77,7 @@ func run(args []string, stdout, stderr io.Writer) int { } rest := fs.Args() if len(rest) == 0 { - return usageErr(stderr, "give a command: run, apply, status, listen or version") + return usageErr(stderr, "give a command: run, apply, status, listen, update, units or version") } log := slog.New(slog.NewTextHandler(stderr, nil)) ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM) @@ -156,6 +167,27 @@ func run(args []string, stdout, stderr io.Writer) int { return 1 } return 0 + case "units": + if len(rest) > 1 { + return usageErr(stderr, "pullgate units takes no arguments") + } + b, err := json.Marshal(selfupdate.UnitList{Units: pullgate.Units(), Enable: pullgate.Enable}) + if err != nil { + log.Error("units", "err", err) + return 1 + } + _, _ = fmt.Fprintln(stdout, string(b)) + return 0 + case "update": + uf := flag.NewFlagSet("update", flag.ContinueOnError) + uf.SetOutput(io.Discard) + path := uf.String("config", "/etc/pullgate/listener.toml", "") + unitDir := uf.String("unit-dir", "/etc/systemd/system", "") + if err := uf.Parse(rest[1:]); err != nil || uf.NArg() > 0 { + return usageErr(stderr, "unknown arguments after pullgate update") + } + log = log.With("step", "update") + return update(ctx, log, stderr, *path, *unitDir, *stateDir, *spoolDir, euid) default: return usageErr(stderr, fmt.Sprintf("unknown command %q", cmd)) } @@ -169,3 +201,65 @@ func done(log *slog.Logger, res string, err error) int { log.Info("done", "result", res) return 0 } + +// update is "pullgate update" (DESIGN.md section 15). +func update(ctx context.Context, log *slog.Logger, stderr io.Writer, path, unitDir, stateDir, spoolDir string, euid uint32) int { + cfg, err := config.LoadListenerForUpdate(path, euid) + if err != nil { + log.Error("config", "err", err) + return 78 + } + owners, err := gate.ResolveOwners(cfg.Updates.ListenerUser) + if err != nil { + log.Error("setup", "err", err) + return 78 + } + bin, err := os.Executable() + if err != nil || filepath.Base(bin) != "pullgate" || !filepath.IsAbs(bin) { + log.Error("setup: cannot tell where this binary is, or it is not named pullgate. Fix: install it as /usr/local/bin/pullgate, as the README says", "path", bin) + return 78 + } + host, _ := os.Hostname() + u := &selfupdate.Updater{ + Cfg: cfg, + StateDir: filepath.Join(stateDir, spool.SelfName), + Spool: spool.Dirs{Base: cfg.SpoolDir, Name: spool.SelfName}, + Owners: owners, + UID: euid, + Bin: bin, + Version: version, + Script: pullgate.InstallScript, + UnitDir: unitDir, + Host: host, + Path: selfupdate.RootPath, + Arch: runtime.GOARCH, + Systemctl: systemctl(log), + Log: log, + Out: stderr, + ListenerWait: 5 * time.Second, + } + if spoolDir != "/var/spool/pullgate" { + u.Spool.Base = spoolDir + } + res, err := u.Run(ctx) + return done(log, string(res), err) +} + +// systemctl runs systemctl, at most 2 minutes. +func systemctl(log *slog.Logger) selfupdate.Systemctl { + return func(parent context.Context, args ...string) error { + ctx, cancel := context.WithTimeout(parent, 2*time.Minute) + defer cancel() + prog := "/usr/bin/systemctl" + if _, err := os.Stat(prog); err != nil { + prog = "/bin/systemctl" + } + cmd := exec.CommandContext(ctx, prog, args...) //nolint:gosec // systemctl of the system, with fixed arguments from pullgate + cmd.Env = []string{"PATH=" + selfupdate.RootPath, "LC_ALL=C"} + out, err := cmd.CombinedOutput() + if err != nil && len(args) > 0 && args[0] != "is-enabled" && args[0] != "is-active" { + log.Warn("systemctl failed", "args", args, "err", err, "output", string(out)) + } + return err + } +} diff --git a/contrib/examples/listener.toml b/contrib/examples/listener.toml index 7735f60..a43b0e9 100644 --- a/contrib/examples/listener.toml +++ b/contrib/examples/listener.toml @@ -4,3 +4,9 @@ owner_id = 123456789 # your Telegram user ID chat_id = 123456789 # the private chat of the bot with you instances = ["config-repo", "playbooks"] + +# Updates of pullgate itself (DESIGN.md section 15). All keys are optional. +# [updates] +# check = false # no daily notice of new releases; /update still works +# listener_user = "pullgate" # the user of the listener +# gh = "/usr/bin/gh" # the gh that checks the attestation, as install.sh --gh diff --git a/contrib/systemd/pullgate-update.path b/contrib/systemd/pullgate-update.path new file mode 100644 index 0000000..287e513 --- /dev/null +++ b/contrib/systemd/pullgate-update.path @@ -0,0 +1,17 @@ +# Starts pullgate-update.service when the listener writes a request for +# /update, or an approval for an update question (DESIGN.md section 15). +# "_update" is not a valid instance name, so no instance can use these +# directories. +[Unit] +Description=pullgate update: /update and taps + +[Path] +PathExists=/var/spool/pullgate/_update/check/request +DirectoryNotEmpty=/var/spool/pullgate/_update/inbox +Unit=pullgate-update.service +# At most 10 starts a minute, as pullgate-check@.path. +TriggerLimitIntervalSec=60s +TriggerLimitBurst=10 + +[Install] +WantedBy=paths.target diff --git a/contrib/systemd/pullgate-update.service b/contrib/systemd/pullgate-update.service new file mode 100644 index 0000000..e6f7907 --- /dev/null +++ b/contrib/systemd/pullgate-update.service @@ -0,0 +1,29 @@ +# pullgate update: look for a new release of pullgate, and install one +# after the owner taps Apply (DESIGN.md section 15). The timer starts it +# once a day; pullgate-update.path starts it for /update and for a tap. +# It installs the binary in /usr/local/bin, the units in +# /etc/systemd/system, and restarts them, so the sandbox here is light. +[Unit] +Description=pullgate update: new releases of pullgate +Wants=network-online.target +After=network-online.target +# A stuck inbox must not start this in a loop. +StartLimitIntervalSec=60 +StartLimitBurst=10 + +[Service] +Type=oneshot +ExecStart=/usr/local/bin/pullgate update +SyslogIdentifier=pullgate +UMask=0022 +# gh attestation verify may take 5 minutes, twice for one update. +TimeoutStartSec=30min +KillMode=control-group +PrivateTmp=yes +ProtectHome=read-only +ProtectKernelModules=yes +ProtectKernelLogs=yes +ProtectClock=yes +RestrictRealtime=yes +LockPersonality=yes +SystemCallArchitectures=native diff --git a/contrib/systemd/pullgate-update.timer b/contrib/systemd/pullgate-update.timer new file mode 100644 index 0000000..2ce22ae --- /dev/null +++ b/contrib/systemd/pullgate-update.timer @@ -0,0 +1,14 @@ +# Starts pullgate-update.service once a day. It sends a notice for each +# new release that passed its checks; it installs nothing without /update +# and a tap. [updates] check = false in listener.toml stops the notices. +[Unit] +Description=pullgate update: look for a new release once a day + +[Timer] +OnBootSec=10min +OnCalendar=daily +RandomizedDelaySec=1h +Persistent=true + +[Install] +WantedBy=timers.target diff --git a/docs/releasing.md b/docs/releasing.md index 2106ed1..7d9bb93 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -13,7 +13,7 @@ workflow checks it. | type | release | changelog section | |---|---|---| -| `security` | patch | Security | +| `security` | patch | Security (see below) | | `feat` | minor (patch before 1.0) | Features | | `fix` | patch | Bug Fixes | | `perf` | patch | Performance Improvements | @@ -21,6 +21,11 @@ workflow checks it. | `docs` | patch | Documentation | | `chore`, `ci`, `test`, `refactor`, `build`, `style` | none | hidden | +A `security:` pull request makes a section `### Security` in the release +notes. `pullgate update` reads it (DESIGN.md section 15): the notice of such +a release says so first, and comes again each day until the release is +installed. Use `security:` only for the fix of a security problem. + ## What happens 1. After every push to `main`, the **Release** workflow runs release-please. diff --git a/embed.go b/embed.go new file mode 100644 index 0000000..7af1b50 --- /dev/null +++ b/embed.go @@ -0,0 +1,53 @@ +// Package pullgate holds the files that the binary carries: install.sh and +// the units of contrib/systemd/ of this version (DESIGN.md section 15). It +// also holds the tests of install.sh. +package pullgate + +import ( + "embed" + "io/fs" + "strings" +) + +// InstallScript is install.sh of this version. pullgate update runs it, so +// the code that checks a release is the code that was checked and +// installed before. +// +//go:embed install.sh +var InstallScript string + +//go:embed contrib/systemd +var unitFS embed.FS + +// Enable lists the units that README.md enables in its "start" block. +// NAME stands for each instance. pullgate update re-enables them after an +// update. A test checks this list against the README. +var Enable = []string{ + "pullgate-listen.service", + "pullgate-apply@NAME.path", + "pullgate-run@NAME.timer", + "pullgate-check@NAME.path", + "pullgate-update.timer", + "pullgate-update.path", +} + +// Units returns the unit files of contrib/systemd/ of this version, by +// name. +func Units() map[string]string { + out := map[string]string{} + entries, err := fs.ReadDir(unitFS, "contrib/systemd") + if err != nil { + panic("pullgate: the embedded units cannot be read: " + err.Error()) + } + for _, e := range entries { + if e.IsDir() || strings.HasPrefix(e.Name(), ".") { + continue + } + b, err := unitFS.ReadFile("contrib/systemd/" + e.Name()) + if err != nil { + panic("pullgate: the embedded unit " + e.Name() + " cannot be read: " + err.Error()) + } + out[e.Name()] = string(b) + } + return out +} diff --git a/embed_test.go b/embed_test.go new file mode 100644 index 0000000..6b715c2 --- /dev/null +++ b/embed_test.go @@ -0,0 +1,62 @@ +package pullgate + +import ( + "os" + "regexp" + "slices" + "strings" + "testing" +) + +// TestEnableIsTheReadme: Enable, which pullgate update re-enables after an +// update, is the list of units of the README "start" block. +func TestEnableIsTheReadme(t *testing.T) { + b, err := os.ReadFile("README.md") + if err != nil { + t.Fatal(err) + } + _, block, ok := strings.Cut(string(b), "\n```sh\n") + if !ok { + t.Fatal("README.md has no install-test:start block") + } + block, _, _ = strings.Cut(block, "```") + re := regexp.MustCompile(`pullgate-[a-z-]+(@NAME)?\.(service|timer|path)`) + var got []string + for line := range strings.SplitSeq(block, "\n") { + line, _, _ = strings.Cut(line, "#") + got = append(got, re.FindAllString(line, -1)...) + } + slices.Sort(got) + want := slices.Clone(Enable) + slices.Sort(want) + if !slices.Equal(got, want) { + t.Fatalf("the README start block enables %q, Enable is %q. Fix: change both together", got, want) + } + units := Units() + for _, e := range Enable { + if _, ok := units[strings.Replace(e, "@NAME.", "@.", 1)]; !ok { + t.Errorf("%s: no unit file in contrib/systemd", e) + } + } +} + +// TestUnitsAreEmbedded: the binary carries every file of contrib/systemd. +func TestUnitsAreEmbedded(t *testing.T) { + entries, err := os.ReadDir("contrib/systemd") + if err != nil { + t.Fatal(err) + } + units := Units() + if len(units) != len(entries) { + t.Fatalf("embedded %d units, contrib/systemd has %d files", len(units), len(entries)) + } + for _, e := range entries { + b, _ := os.ReadFile("contrib/systemd/" + e.Name()) + if units[e.Name()] != string(b) { + t.Errorf("%s: the embedded copy differs", e.Name()) + } + } + if b, _ := os.ReadFile("install.sh"); InstallScript != string(b) { + t.Error("the embedded install.sh differs") + } +} diff --git a/install.sh b/install.sh index d01591e..a0708e7 100644 --- a/install.sh +++ b/install.sh @@ -7,6 +7,11 @@ # # sh install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall] # +# "pullgate update" runs a copy of this script that is built into the +# binary, with --check-only, or with --sha256 and --forward-only (DESIGN.md +# section 15). Lines that start with "@pullgate " on the standard output +# are for it. +# # It installs nothing unless every check passes: # - only root can change the bin directory, the old file, the temporary # directory and the gh of --gh (when the script does not run as root, @@ -79,6 +84,13 @@ the host itself. $gh_version and check its SHA-256) --reinstall install also when this version is installed already, or when the installed pullgate has an unknown version + --check-only check the SHA-256 and the attestation of the newest + release (or of --version), but run and install nothing; + for pullgate update + --sha256 HEX install only a tarball with this SHA-256; needs + --version; for pullgate update + --forward-only never install the same or an older version; for + pullgate update --help print this help Before it installs anything, it checks the SHA-256 and the build @@ -94,6 +106,13 @@ say() { printf '%s\n' "$*" } +# tell prints a line for pullgate update: "@pullgate WORD VALUES". The +# values come from checks of this script (a version, a SHA-256), never +# text from the network as it came. +tell() { + printf '@pullgate %s\n' "$*" +} + # die prints the last line of a failed run and exits with 1. The old file # is replaced only in the very last step, so nothing is installed then. die() { @@ -321,6 +340,27 @@ parse_args() { reinstall=1 shift ;; + --check-only) + check_only=1 + shift + ;; + --forward-only) + forward_only=1 + shift + ;; + --sha256) + if [ "$#" -lt 2 ]; then + usage_error "--sha256 needs the SHA-256 of the tarball, 64 hex digits" + fi + case $2 in + *[!0-9a-f]*) usage_error "--sha256 must be 64 hex digits in lower case" ;; + esac + if [ "${#2}" -ne 64 ]; then + usage_error "--sha256 must be 64 hex digits in lower case" + fi + pin_sha256=$2 + shift 2 + ;; --help | -h) usage exit 0 @@ -338,6 +378,15 @@ parse_args() { '' | /*) ;; *) usage_error "--gh must be an absolute path" ;; esac + if [ -n "$pin_sha256" ] && [ -z "$want_version" ]; then + usage_error "--sha256 needs --version: a SHA-256 belongs to one version" + fi + if [ -n "$check_only" ] && [ -n "$pin_sha256" ]; then + usage_error "--check-only and --sha256 do not go together" + fi + if [ -n "$forward_only" ] && [ -n "$reinstall" ]; then + usage_error "--forward-only and --reinstall do not go together" + fi } # check_platform checks that this is Linux on amd64 or arm64. @@ -483,6 +532,14 @@ choose_version() { if [ -n "$want_version" ] && [ "$version" != "$want_version" ]; then die "GitHub names the release v$want_version as $tag; check the version at https://github.com/$repo/releases" fi + # A release that fixes a security problem has a section "### Security" + # in its notes (release-please-config.json). In the JSON text of the + # answer, the new line before it is the two characters \n. + security=normal + if grep -q -F '\n### Security' "$tmp/release.json"; then + security=security + fi + tell version "$version" "$security" } # check_installed reads the version of the installed pullgate, and stops @@ -511,9 +568,13 @@ check_installed() { return 0 fi compare_versions "$version" "$installed" + if [ -n "$forward_only" ] && [ "$cmp" != 1 ]; then + die "$target says that it is pullgate $installed, and $version is not newer; --forward-only installs only a newer version" + fi case $cmp in 0) if [ -z "$reinstall" ]; then + tell up-to-date "$installed" say "$target says that it is pullgate $version already. Nothing to do." say "This did not check the installed file. To replace it with a checked copy, run this again with --reinstall." exit 0 @@ -525,6 +586,7 @@ check_installed() { ;; *) if [ -z "$want_version" ]; then + tell up-to-date "$installed" say "$target says that it is pullgate $installed, which is newer than $version, the newest release. Nothing to do." say "This did not check the installed file. To install $version anyway, run this again with --version $version." exit 0 @@ -568,6 +630,10 @@ check_sha256() { if [ "$file_sha256" != "$want" ]; then die "the SHA-256 of $tarball is not the one in SHA256SUMS; the download is broken or changed, try again later" fi + tarball_sha256=$file_sha256 + if [ -n "$pin_sha256" ] && [ "$tarball_sha256" != "$pin_sha256" ]; then + die "the SHA-256 of $tarball is not the one that was approved; the release was changed after the question, so send /update to ask again" + fi } # get_gh sets gh to the gh that checks the attestation: the one of --gh, @@ -647,6 +713,11 @@ unpack() { die "$tarball holds no file pullgate; do not use this release, and report it at https://github.com/$repo/issues" fi chmod 0700 "$tmp/new/pullgate" || die "cannot make the new pullgate a program; check that chmod works in $tmp_parent" + # --check-only runs before the owner's tap (pullgate update): no code + # of the new release runs then. The version is checked on Apply. + if [ -n "$check_only" ]; then + return 0 + fi check_new_version "$tmp/new/pullgate" " (if programs cannot run in $tmp_parent, $tmp_fix)" } @@ -671,6 +742,7 @@ install_new() { tmp_target= renamed=1 sync -- "$bin_dir" 2>/dev/null || sync || : + tell installed "$version" "$tarball_sha256" } # print_restart prints what the new file says, and what to restart. It @@ -694,6 +766,11 @@ main() { want_version= gh= reinstall= + check_only= + forward_only= + pin_sha256= + security=normal + tarball_sha256= tmp= tmp_target= renaming= @@ -711,10 +788,18 @@ main() { choose_version check_installed download_release - check_sha256 get_gh + # From here on, a failure is a check of this release that failed (or + # the trusted root of Sigstore could not be fetched). + tell fetched "$version" + check_sha256 verify_attestation unpack + if [ -n "$check_only" ]; then + tell checked "$version" "$tarball_sha256" "$security" + say "Every check of pullgate $version passed. --check-only installs nothing." + exit 0 + fi install_new print_restart } diff --git a/install_linux_test.go b/install_linux_test.go index 65687a1..350dc1d 100644 --- a/install_linux_test.go +++ b/install_linux_test.go @@ -1,5 +1,3 @@ -// Package pullgate holds the tests of install.sh, the script at the root -// of the repository. The package has no other code. package pullgate import ( @@ -1078,6 +1076,12 @@ func TestInstallUsage(t *testing.T) { {[]string{"--bin-dir", "bin"}, "--bin-dir must be an absolute path"}, {[]string{"--gh"}, "--gh needs the path of gh"}, {[]string{"--gh", "gh"}, "--gh must be an absolute path"}, + {[]string{"--sha256"}, "--sha256 needs the SHA-256"}, + {[]string{"--version", "0.2.0", "--sha256", strings.Repeat("A", 64)}, "--sha256 must be 64 hex digits in lower case"}, + {[]string{"--version", "0.2.0", "--sha256", strings.Repeat("a", 63)}, "--sha256 must be 64 hex digits in lower case"}, + {[]string{"--sha256", strings.Repeat("a", 64)}, "--sha256 needs --version"}, + {[]string{"--check-only", "--version", "0.2.0", "--sha256", strings.Repeat("a", 64)}, "--check-only and --sha256 do not go together"}, + {[]string{"--forward-only", "--reinstall"}, "--forward-only and --reinstall do not go together"}, } { t.Run(strings.Join(tt.args, " "), func(t *testing.T) { in := newInstaller(t) diff --git a/internal/config/config.go b/internal/config/config.go index de06115..2e5176d 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -30,6 +30,10 @@ const ( var nameRE = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{0,31}$`) +// userRE is a user name: what useradd accepts, and nothing a shell or an +// option could read. +var userRE = regexp.MustCompile(`^[a-z_][a-z0-9_-]{0,31}$`) + // ValidName reports whether s is a valid instance name. func ValidName(s string) bool { return nameRE.MatchString(s) } @@ -335,11 +339,40 @@ type Listener struct { SpoolDir string `toml:"spool_dir"` StateFile string `toml:"state_file"` APIURL string `toml:"api_url"` + Updates Updates `toml:"updates"` +} + +// Updates is the [updates] table of the listener config: the updates of +// pullgate itself (DESIGN.md section 15). Root reads it; the listener +// only checks it. +type Updates struct { + // Check: a notice for each new release, once a day. Default true. + Check *bool `toml:"check"` + // ListenerUser is the user of the listener, who owns the inbox of the + // updates. Default "pullgate". + ListenerUser string `toml:"listener_user"` + // GH is the gh that checks the build attestation, as install.sh --gh. + // Default: install.sh downloads gh and checks its SHA-256. + GH string `toml:"gh"` +} + +// Notices reports whether the daily notice of new releases is on. +func (u Updates) Notices() bool { return u.Check == nil || *u.Check } + +// LoadListenerForUpdate reads the listener config for pullgate update, +// which runs as root. The file must be owned by root (uid) and not +// writable by others. It needs no token: root never reads the token. +func LoadListenerForUpdate(path string, uid uint32) (*Listener, error) { + return loadListener(path, uid, false) } // LoadListener reads the listener config. The file must be owned by // configUID (root) and not writable by others. func LoadListener(path string, configUID uint32) (*Listener, error) { + return loadListener(path, configUID, true) +} + +func loadListener(path string, configUID uint32, needToken bool) (*Listener, error) { if err := checkFile(path, configUID, false); err != nil { return nil, err } @@ -361,8 +394,11 @@ func LoadListener(path string, configUID uint32) (*Listener, error) { c.TokenFile = filepath.Join(d, "bot-token") } } + if c.Updates.ListenerUser == "" { + c.Updates.ListenerUser = "pullgate" + } switch { - case c.TokenFile == "": + case c.TokenFile == "" && needToken: return nil, fmt.Errorf("%s: token_file: it is missing. Fix: set token_file, or give a systemd credential named bot-token", path) case c.OwnerID <= 0: return nil, fmt.Errorf("%s: owner_id: it is missing. Fix: set the Telegram user ID of the owner", path) @@ -378,6 +414,12 @@ func LoadListener(path string, configUID uint32) (*Listener, error) { return nil, fmt.Errorf("%s: instances: %q is not an instance name", path, n) } } + if !userRE.MatchString(c.Updates.ListenerUser) { + return nil, fmt.Errorf("%s: updates.listener_user: %q is not a user name. Fix: give the user of the listener, such as \"pullgate\"", path, c.Updates.ListenerUser) + } + if g := c.Updates.GH; g != "" && (!filepath.IsAbs(g) || filepath.Clean(g) != g || strings.HasPrefix(g, "-")) { + return nil, fmt.Errorf("%s: updates.gh: %q is not a clean absolute path. Fix: give the path of the gh program, such as \"/usr/bin/gh\", or remove the key", path, g) + } return c, nil } diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 78080af..399defa 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -193,3 +193,42 @@ func TestExamples(t *testing.T) { t.Fatal(err) } } + +// TestListenerUpdates: the [updates] table (DESIGN.md section 15). Root +// reads the file without a token; bad values are refused. +func TestListenerUpdates(t *testing.T) { + dir := t.TempDir() + p := filepath.Join(dir, "listener.toml") + body := "owner_id = 1\nchat_id = 1\ninstances = [\"a\"]\n" + if err := os.WriteFile(p, []byte(body), 0o600); err != nil { + t.Fatal(err) + } + t.Setenv("CREDENTIALS_DIRECTORY", "") + if _, err := LoadListener(p, uid()); err == nil { + t.Fatal("the listener needs a token") + } + c, err := LoadListenerForUpdate(p, uid()) + if err != nil { + t.Fatalf("root needs no token: %v", err) + } + if !c.Updates.Notices() || c.Updates.ListenerUser != "pullgate" || c.Updates.GH != "" { + t.Fatalf("the defaults: %+v", c.Updates) + } + if err := os.WriteFile(p, []byte(body+"[updates]\ncheck = false\nlistener_user = \"pg-listen\"\ngh = \"/usr/bin/gh\"\n"), 0o600); err != nil { + t.Fatal(err) + } + if c, err = LoadListenerForUpdate(p, uid()); err != nil || c.Updates.Notices() || c.Updates.ListenerUser != "pg-listen" || c.Updates.GH != "/usr/bin/gh" { + t.Fatalf("got %+v, %v", c, err) + } + for _, bad := range []string{ + "listener_user = \"root;x\"", "listener_user = \"-x\"", "gh = \"gh\"", "gh = \"/usr/bin/../bin/gh\"", + "skip_attestation = true", "check = \"no\"", + } { + if err := os.WriteFile(p, []byte(body+"[updates]\n"+bad+"\n"), 0o600); err != nil { + t.Fatal(err) + } + if _, err := LoadListenerForUpdate(p, uid()); err == nil { + t.Errorf("%s must be refused", bad) + } + } +} diff --git a/internal/listener/listener.go b/internal/listener/listener.go index fc6d9bc..d21d16e 100644 --- a/internal/listener/listener.go +++ b/internal/listener/listener.go @@ -190,7 +190,7 @@ func (l *Listener) Outbox(ctx context.Context) { l.mu.Lock() defer l.mu.Unlock() instances: - for _, inst := range l.Cfg.Instances { + for _, inst := range append(slices.Clone(l.Cfg.Instances), spool.SelfName) { d := l.dirs(inst) files, err := d.ReadOutbox() if err != nil { @@ -246,6 +246,13 @@ instances: // only logged: the file is gone either way. func (l *Listener) badOutboxNotice(ctx context.Context, inst string) { name := html.EscapeString(inst) + if inst == spool.SelfName { + text := "pullgate: a message about an update of pullgate could not be read and was removed. It may have been a question. To ask again, send /update." + if _, err := l.TG.SendMessage(ctx, l.Cfg.ChatID, text, nil, 0); err != nil { + l.Log.Warn("send the notice about a bad outbox file", "instance", inst, "err", err) + } + return + } text := "pullgate: an outbox message of instance " + name + " could not be read and was removed. It may have been a question. To ask again, run as root: pullgate status " + name + " --ask-again" if _, err := l.TG.SendMessage(ctx, l.Cfg.ChatID, text, nil, 0); err != nil { l.Log.Warn("send the notice about a bad outbox file", "instance", inst, "err", err) @@ -259,6 +266,10 @@ func (l *Listener) send(ctx context.Context, inst string, m spool.Message) error if len(m.Code) != 22 || !l.now().Before(m.Expires) { // Expired or broken: never show buttons for it. l.Log.Warn("a question expired before it could be sent, dropped", "instance", inst, "question", m.Question) + if inst == spool.SelfName { + _, err := l.TG.SendMessage(ctx, chat, "pullgate: a question about an update of pullgate expired before it could be sent. Send /update to ask again.", nil, 0) + return err + } _, err := l.TG.SendMessage(ctx, chat, "pullgate: a question of instance "+html.EscapeString(inst)+" expired before it could be sent. The next commit, or pullgate status "+html.EscapeString(inst)+" --ask-again, asks again.", nil, 0) return err } @@ -413,6 +424,10 @@ const checkCommand = "/check" // helpCommand lists what the bot can do. const helpCommand = "/help" +// updateCommand asks root to look for a new release of pullgate (DESIGN.md +// section 15). +const updateCommand = "/update" + // HintGap is the least time between two "Not a command" replies, so that a // stuck client or a long paste cannot make the bot fill the chat. const HintGap = time.Minute @@ -428,6 +443,7 @@ func (l *Listener) helpText() string { "pullgate commands:", "/check: look for a new commit now, on every instance", "/check NAME: the same, on one instance", + "/update: look for a new release of pullgate; a question asks before it is installed", "/help: this list", "", "Instances: " + strings.Join(names, ", "), @@ -456,6 +472,10 @@ func (l *Listener) command(ctx context.Context, m *telegram.Message) { l.sendReply(ctx, m, l.helpText()) return } + if why == "update" { + l.update(ctx, m) + return + } if names == nil { l.Log.Info("message ignored", "reason", why, "from", fromID(m)) if why == "not a command" { @@ -518,6 +538,8 @@ func (l *Listener) checkNames(m *telegram.Message) ([]string, string, bool) { return nil, "an edited message", false case m.Text == helpCommand: return nil, "help", false + case m.Text == updateCommand: + return nil, "update", false case !strings.HasPrefix(m.Text, checkCommand): return nil, "not a command", false case m.Text == checkCommand: @@ -542,3 +564,26 @@ func (l *Listener) sendReply(ctx context.Context, m *telegram.Message, text stri l.Log.Warn("send a reply", "err", err) } } + +// update writes the check request of the updates (DESIGN.md section 15). +// Like /check, the request holds nothing from the message. Root looks for +// the release, checks it, and asks; the listener only asks root to look. +func (l *Listener) update(ctx context.Context, m *telegram.Message) { + if l.lastCheck == nil { + l.lastCheck = map[string]time.Time{} + } + now := l.now() + if d := now.Sub(l.lastCheck[spool.SelfName]); d < CheckGap && d > -CheckGap { + l.Log.Info("message ignored", "reason", "a second /update within a few seconds", "from", fromID(m)) + l.sendReply(ctx, m, "A look for a new release was asked a few seconds ago. Wait for its answer.") + return + } + if err := l.dirs(spool.SelfName).WriteCheck(); err != nil { + l.Log.Error("write the update request", "err", err) + l.sendReply(ctx, m, "Error: the /update request was not saved. pullgate-update.service makes its directory on its first run. Fix: on the host, as root, run systemctl enable --now pullgate-update.timer pullgate-update.path and systemctl start pullgate-update.service, then send /update again.") + return + } + l.lastCheck[spool.SelfName] = now + l.Log.Info("update request taken") + l.sendReply(ctx, m, "Looking for a new release of pullgate…") +} diff --git a/internal/listener/listener_test.go b/internal/listener/listener_test.go index b497726..8beaee9 100644 --- a/internal/listener/listener_test.go +++ b/internal/listener/listener_test.go @@ -524,3 +524,99 @@ func TestListenerAsksForMessages(t *testing.T) { t.Fatal("the message must arrive") } } + +// TestUpdateCommand: /update of the owner writes the check request of the +// updates, and only that one (DESIGN.md section 15). +func TestUpdateCommand(t *testing.T) { + f := newL(t) + self := spool.Dirs{Base: f.d.Base, Name: spool.SelfName} + if err := self.Ensure(uint32(os.Geteuid()), spool.Owners{ListenerUID: os.Geteuid(), ListenerGID: os.Getegid()}); err != nil { + t.Fatal(err) + } + for _, tt := range []struct { + from, chat int64 + text string + edited bool + }{ + {owner + 1, chat, "/update", false}, + {owner, chat + 1, "/update", false}, + {owner, chat, "/update", true}, + {owner, chat, "/update now", false}, + {owner, chat, "/update@otherbot", false}, + {owner, chat, "/check " + spool.SelfName, false}, + } { + f.say(tt.from, tt.chat, tt.text, tt.edited) + if self.HasCheck() || f.d.HasCheck() { + t.Fatalf("%+v must write no request", tt) + } + } + n := len(f.tg.Messages()) + f.say(owner, chat, "/update", false) + if !self.HasCheck() || f.d.HasCheck() { + t.Fatal("/update must write the request of the updates only") + } + ms := f.tg.Messages() + if len(ms) != n+1 || !strings.Contains(ms[n].Text, "Looking for a new release") || ms[n].ReplyTo == 0 { + t.Fatalf("the reply must say it looks: %+v", ms[n:]) + } + if c, bad, err := self.TakeChecks(os.Geteuid()); c != 1 || len(bad) != 0 || err != nil { + t.Fatalf("the request must be valid for root: %d %v %v", c, bad, err) + } + // A second /update within CheckGap writes nothing. + f.say(owner, chat, "/update", false) + if self.HasCheck() { + t.Fatal("a second /update within CheckGap must write nothing") + } +} + +// TestUpdateCommandWithoutDirectory: before root made the spool of the +// updates, /update says how to fix it. +func TestUpdateCommandWithoutDirectory(t *testing.T) { + f := newL(t) + f.say(owner, chat, "/update", false) + ms := f.tg.Messages() + if len(ms) != 1 || !strings.Contains(ms[0].Text, "was not saved") || !strings.Contains(ms[0].Text, "pullgate-update.service") { + t.Fatalf("want one reply that says how to fix it: %+v", ms) + } +} + +// TestUpdateQuestionsAreTheirOwn: an instance named "pullgate" and the +// updates use different spools, and a tap on an update question writes +// only to the inbox of the updates. +func TestUpdateQuestionsAreTheirOwn(t *testing.T) { + if config.ValidName(spool.SelfName) { + t.Fatalf("%q must not be a valid instance name", spool.SelfName) + } + f := newL(t) + owners := spool.Owners{ListenerUID: os.Geteuid(), ListenerGID: os.Getegid()} + pg := spool.Dirs{Base: f.d.Base, Name: "pullgate"} + self := spool.Dirs{Base: f.d.Base, Name: spool.SelfName} + for _, d := range []spool.Dirs{pg, self} { + if err := d.Ensure(uint32(os.Geteuid()), owners); err != nil { + t.Fatal(err) + } + } + f.l.Cfg.Instances = []string{"pullgate"} + f.say(owner, chat, "/check pullgate", false) + if !pg.HasCheck() || self.HasCheck() { + t.Fatal("/check pullgate must write to the instance pullgate only") + } + c := strings.Repeat("u", 22) + if err := self.Send(os.Getegid(), spool.Message{Kind: spool.KindAsk, Question: 1, Code: c, Expires: f.now.Add(time.Hour), Text: "update?"}); err != nil { + t.Fatal(err) + } + f.l.Outbox(context.Background()) + ms := f.tg.Messages() + m := ms[len(ms)-1] + if len(m.Buttons) != 2 { + t.Fatalf("the update question must be sent with buttons: %+v", m) + } + f.tap(owner, chat, m.ID, "a:"+c) + es, err := self.TakeApprovals(os.Geteuid(), 0) + if err != nil || len(es) != 1 || es[0].Approval.Code != c { + t.Fatalf("the tap must write the approval to the updates inbox: %+v %v", es, err) + } + if es, _ := pg.TakeApprovals(os.Geteuid(), 0); len(es) != 0 { + t.Fatal("the tap must not write to the instance pullgate") + } +} diff --git a/internal/selfupdate/install.go b/internal/selfupdate/install.go new file mode 100644 index 0000000..4eac6ad --- /dev/null +++ b/internal/selfupdate/install.go @@ -0,0 +1,406 @@ +package selfupdate + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "regexp" + "slices" + "strings" + "time" + + "github.com/code6x/pullgate/internal/message" + "github.com/code6x/pullgate/internal/state" +) + +// UnitList is what "pullgate units" prints: the units of contrib/systemd/ +// that the binary carries, and the units that README.md enables (NAME for +// each instance). +type UnitList struct { + Units map[string]string `json:"units"` + Enable []string `json:"enable"` +} + +var ( + unitNameRE = regexp.MustCompile(`^pullgate-[a-z0-9-]{1,40}@?\.(service|timer|path)$`) + enableNameRE = regexp.MustCompile(`^pullgate-[a-z0-9-]{1,40}(@NAME)?\.(service|timer|path)$`) +) + +// check checks the list that a new binary printed. The binary passed the +// attestation, but root still writes only files named pullgate-*. +func (l *UnitList) check() error { + if len(l.Units) == 0 || len(l.Units) > maxUnits { + return fmt.Errorf("pullgate units: %d units, want 1 to %d", len(l.Units), maxUnits) + } + for n, c := range l.Units { + if !unitNameRE.MatchString(n) { + return fmt.Errorf("pullgate units: %q is not a name of a pullgate unit", n) + } + if len(c) > maxUnitSize || strings.ContainsRune(c, 0) { + return fmt.Errorf("pullgate units: %s is too large or holds a NUL", n) + } + } + for _, e := range l.Enable { + if !enableNameRE.MatchString(e) { + return fmt.Errorf("pullgate units: %q is not a unit to enable", e) + } + if _, ok := l.Units[template(e)]; !ok { + return fmt.Errorf("pullgate units: %s is enabled, but there is no unit file %s", e, template(e)) + } + } + return nil +} + +// template is the file name of a unit: pullgate-run@NAME.timer is +// pullgate-run@.timer. +func template(unit string) string { return strings.Replace(unit, "@NAME.", "@.", 1) } + +// fileOf is the unit file of a unit: pullgate-run@config-repo.timer is +// pullgate-run@.timer. +func fileOf(unit string) string { + at := strings.Index(unit, "@") + dot := strings.LastIndex(unit, ".") + if at < 0 || dot < at { + return unit + } + return unit[:at+1] + unit[dot:] +} + +// unitChange is one unit file that the update wrote: what was there +// before, for a rollback. +type unitChange struct { + Name string + Old []byte + Existed bool +} + +// unitReport is what the update did to the units. +type unitReport struct { + changes []unitChange + links []string // unit files that are links (for example masked), left alone + dropins []string // every drop-in of a pullgate unit + enabled []string // the units that were re-enabled +} + +// install installs the release of q (DESIGN.md section 15). +func (u *Updater) install(ctx context.Context, st *State, q *Question) (Result, error) { + from := u.Version + st.InProgress = &InProgress{Version: q.Version, From: from, Started: u.now()} + if err := u.save(st); err != nil { + return "", err + } + u.Log.Info("update started", "version", q.Version, "sha256", q.SHA256, "from", from) + dir := filepath.Dir(u.Bin) + prev := filepath.Join(dir, ".pullgate.prev") + // Keep the old binary: a second name for the same file. The rename of + // install.sh puts the new file under the name pullgate; the old one + // stays as .pullgate.prev until the new one works. + if err := os.Remove(prev); err != nil && !errors.Is(err, fs.ErrNotExist) { + return u.failed(st, q, "cannot remove the old "+prev+": "+err.Error()) + } + if err := os.Link(u.Bin, prev); err != nil { + return u.failed(st, q, "cannot keep the old binary as "+prev+": "+err.Error()) + } + syncDir(dir) + if u.crash("kept") { + return "", errCrash + } + args := []string{"--version", q.Version, "--sha256", q.SHA256, "--forward-only", "--bin-dir", dir} + if u.Cfg.Updates.GH != "" { + args = append(args, "--gh", u.Cfg.Updates.GH) + } + tell, reason, err := u.script(ctx, args...) + if err != nil || !slices.Equal(tell["installed"], []string{q.Version, q.SHA256}) { + if err == nil { + reason = "install.sh did not install it. This is a bug in pullgate" + } + // install.sh renames the new file in its last step. When it says + // it did not get there, the old binary is still in place; check. + if out, verr := u.binVersion(ctx, u.Bin); verr != nil || out != "pullgate "+from { + return u.rollback(ctx, st, q, prev, nil, reason) + } + _ = os.Remove(prev) + return u.failed(st, q, reason) + } + if u.crash("installed") { + return "", errCrash + } + if out, err := u.binVersion(ctx, u.Bin); err != nil || out != "pullgate "+q.Version { + return u.rollback(ctx, st, q, prev, nil, "the new pullgate does not run, or does not say that it is "+q.Version) + } + rep, err := u.updateUnits(ctx) + if err != nil { + return u.rollback(ctx, st, q, prev, rep, err.Error()) + } + if u.crash("units") { + return "", errCrash + } + if err := u.restartListener(ctx); err != nil { + return u.rollback(ctx, st, q, prev, rep, err.Error()) + } + _ = os.Remove(prev) + syncDir(dir) + st.InProgress = nil + if err := u.save(st); err != nil { + return "", err + } + u.Log.Info("updated", "version", q.Version, "from", from, "units_changed", len(rep.changes)) + // The new listener sends this: so the report also shows that it runs. + u.reply(q.ID, "✅ pullgate is updated: "+message.Code(from)+" → "+message.Code(q.Version)+".\n"+rep.text()) + return ResInstalled, nil +} + +// failed reports an update that installed nothing. +func (u *Updater) failed(st *State, q *Question, reason string) (Result, error) { + st.InProgress = nil + if err := u.save(st); err != nil { + return "", err + } + u.Log.Error("update failed, nothing was installed", "version", q.Version, "reason", reason) + u.reply(q.ID, "❌ The update to "+message.Code(q.Version)+" failed: "+message.Code(reason)+". Nothing was installed; pullgate "+message.Code(u.Version)+" still runs. Send /update to try again.") + return ResFailed, nil +} + +// rollback puts the old binary back, and the old units, and restarts the +// listener. A rename in one directory: the binary is always the old file +// or the new one. +func (u *Updater) rollback(parent context.Context, st *State, q *Question, prev string, rep *unitReport, reason string) (Result, error) { + u.Log.Error("the update failed, rolling back", "version", q.Version, "reason", reason) + // A stop of the service must not stop the way back. + ctx, cancel := context.WithTimeout(context.WithoutCancel(parent), 5*time.Minute) + defer cancel() + var problems []string + if a, errA := os.Stat(prev); errA == nil { + if b, errB := os.Stat(u.Bin); errB == nil && os.SameFile(a, b) { + _ = os.Remove(prev) // the binary was never replaced + } + } + if _, err := os.Lstat(prev); errors.Is(err, fs.ErrNotExist) { + // nothing to put back + } else if err := os.Rename(prev, u.Bin); err != nil { + problems = append(problems, "the old binary was not put back: "+err.Error()) + } + syncDir(filepath.Dir(u.Bin)) + if rep != nil { + problems = append(problems, u.restoreUnits(ctx, rep)...) + } + if out, err := u.binVersion(ctx, u.Bin); err != nil || out != "pullgate "+u.Version { + problems = append(problems, "the binary does not say that it is "+u.Version) + } + if err := u.restartListener(ctx); err != nil { + problems = append(problems, err.Error()) + } + st.InProgress = nil + if err := u.save(st); err != nil { + return "", err + } + text := "❌ The update to " + message.Code(q.Version) + " failed: " + message.Code(reason) + ". pullgate " + message.Code(u.Version) + " is back, with its units." + if len(problems) > 0 { + u.Log.Error("the rollback had problems", "problems", strings.Join(problems, "; ")) + text = "❌ The update to " + message.Code(q.Version) + " failed: " + message.Code(reason) + ". The rollback to " + message.Code(u.Version) + " had problems: " + message.Code(strings.Join(problems, "; ")) + + ". Fix: as root, run " + message.Code("install.sh --version "+u.Version+" --reinstall") + ", copy the units of that version to /etc/systemd/system, and run " + message.Code("systemctl daemon-reload") + "." + } + u.reply(q.ID, text) + return ResFailed, nil +} + +// updateUnits takes the units of the new binary and installs the ones +// that differ, then reloads systemd, re-enables and restarts them (not +// the listener: restartListener does it last). +func (u *Updater) updateUnits(ctx context.Context) (*unitReport, error) { + rep := &unitReport{} + out, err := u.run(ctx, maxUnitsJSON, u.Bin, "units") + if err != nil { + return rep, fmt.Errorf("the new pullgate units failed: %w", err) + } + var l UnitList + dec := json.NewDecoder(strings.NewReader(out)) + dec.DisallowUnknownFields() + if err := dec.Decode(&l); err != nil { + return rep, fmt.Errorf("the new pullgate units printed no unit list: %w", err) + } + if err := l.check(); err != nil { + return rep, err + } + names := make([]string, 0, len(l.Units)) + for n := range l.Units { + names = append(names, n) + } + slices.Sort(names) + for _, n := range names { + p := filepath.Join(u.UnitDir, n) + c := unitChange{Name: n} + fi, err := os.Lstat(p) + switch { + case errors.Is(err, fs.ErrNotExist): + case err != nil: + return rep, fmt.Errorf("read %s: %w", p, err) + case fi.Mode()&fs.ModeSymlink != 0 || !fi.Mode().IsRegular(): + // Masked (a link to /dev/null) or linked by the owner. + rep.links = append(rep.links, n) + continue + default: + c.Existed = true + if c.Old, err = os.ReadFile(p); err != nil { //nolint:gosec // a unit file of pullgate + return rep, fmt.Errorf("read %s: %w", p, err) + } + if bytes.Equal(c.Old, []byte(l.Units[n])) { + continue + } + } + if err := state.WriteFileAtomic(p, []byte(l.Units[n]), 0o644); err != nil { + return rep, err + } + rep.changes = append(rep.changes, c) + } + if m, err := filepath.Glob(filepath.Join(u.UnitDir, "pullgate-*.d", "*")); err == nil { + for _, p := range m { + rel, _ := filepath.Rel(u.UnitDir, p) + rep.dropins = append(rep.dropins, rel) + } + } + if err := u.Systemctl(ctx, "daemon-reload"); err != nil { + return rep, fmt.Errorf("systemctl daemon-reload failed: %w", err) + } + isNew := map[string]bool{} + for _, c := range rep.changes { + isNew[c.Name] = !c.Existed + } + for _, e := range l.Enable { + for _, unit := range u.expand(e) { + if unit == ListenerUnit { + continue + } + // A unit that the owner turned off stays off; a unit that is + // new in this version is enabled, as the README says. + if !isNew[template(e)] && u.Systemctl(ctx, "is-enabled", "--quiet", unit) != nil { + continue + } + if err := u.Systemctl(ctx, "reenable", unit); err != nil { + return rep, fmt.Errorf("systemctl reenable %s failed: %w", unit, err) + } + rep.enabled = append(rep.enabled, unit) + if err := u.Systemctl(ctx, "restart", unit); err != nil { + return rep, fmt.Errorf("systemctl restart %s failed: %w", unit, err) + } + } + } + if slices.Contains(l.Enable, ListenerUnit) { + if err := u.Systemctl(ctx, "reenable", ListenerUnit); err != nil { + return rep, fmt.Errorf("systemctl reenable %s failed: %w", ListenerUnit, err) + } + rep.enabled = append(rep.enabled, ListenerUnit) + } + return rep, nil +} + +// expand gives the units of one entry of the enable list: one for each +// instance when it has NAME. +func (u *Updater) expand(e string) []string { + if !strings.Contains(e, "@NAME.") { + return []string{e} + } + var out []string + for _, inst := range u.Cfg.Instances { + out = append(out, strings.Replace(e, "@NAME.", "@"+inst+".", 1)) + } + return out +} + +// restoreUnits writes back the unit files of before the update. It +// returns what did not work. +func (u *Updater) restoreUnits(ctx context.Context, rep *unitReport) []string { + var problems []string + for _, c := range rep.changes { + p := filepath.Join(u.UnitDir, c.Name) + if c.Existed { + if err := state.WriteFileAtomic(p, c.Old, 0o644); err != nil { + problems = append(problems, "unit "+c.Name+" was not put back: "+err.Error()) + } + continue + } + for _, unit := range rep.enabled { + if fileOf(unit) == c.Name { + _ = u.Systemctl(ctx, "disable", "--now", unit) + } + } + if err := os.Remove(p); err != nil && !errors.Is(err, fs.ErrNotExist) { + problems = append(problems, "the new unit "+c.Name+" was not removed: "+err.Error()) + } + } + if len(rep.changes) > 0 { + if err := u.Systemctl(ctx, "daemon-reload"); err != nil { + problems = append(problems, "systemctl daemon-reload failed: "+err.Error()) + } + for _, unit := range rep.enabled { + if unit == ListenerUnit { + continue + } + if _, err := os.Lstat(filepath.Join(u.UnitDir, fileOf(unit))); err != nil { + continue // removed above + } + if err := u.Systemctl(ctx, "restart", unit); err != nil { + problems = append(problems, "systemctl restart "+unit+" failed") + } + } + } + return problems +} + +// restartListener restarts the listener, and checks that it is still +// active after ListenerWait. +func (u *Updater) restartListener(ctx context.Context) error { + if err := u.Systemctl(ctx, "restart", ListenerUnit); err != nil { + return fmt.Errorf("systemctl restart %s failed: %w", ListenerUnit, err) + } + select { + case <-ctx.Done(): + return ctx.Err() + case <-time.After(u.ListenerWait): + } + if err := u.Systemctl(ctx, "is-active", "--quiet", ListenerUnit); err != nil { + return fmt.Errorf("%s is not active %s after its restart", ListenerUnit, u.ListenerWait) + } + return nil +} + +// text is the part of the report about the units. +func (r *unitReport) text() string { + var lines []string + if len(r.changes) == 0 { + lines = append(lines, "Units: no change.") + } else { + var n []string + for _, c := range r.changes { + n = append(n, message.Code(c.Name)) + } + lines = append(lines, "Units installed from the new version: "+strings.Join(n, ", ")+".") + } + if len(r.links) > 0 { + var n []string + for _, c := range r.links { + n = append(n, message.Code(c)) + } + lines = append(lines, "Units that are links (masked?), left alone: "+strings.Join(n, ", ")+".") + } + if len(r.dropins) > 0 { + var n []string + for _, c := range r.dropins { + n = append(n, message.Code(c)) + } + lines = append(lines, "Drop-ins, not changed. Check that you still need them: "+strings.Join(n, ", ")+".") + } + return strings.Join(lines, "\n") +} + +func syncDir(dir string) { + if f, err := os.Open(dir); err == nil { //nolint:gosec // the bin directory, checked by install.sh + _ = f.Sync() + _ = f.Close() + } +} diff --git a/internal/selfupdate/selfupdate.go b/internal/selfupdate/selfupdate.go new file mode 100644 index 0000000..ec9e336 --- /dev/null +++ b/internal/selfupdate/selfupdate.go @@ -0,0 +1,633 @@ +// Package selfupdate is "pullgate update" (DESIGN.md section 15). Root +// looks for a new release of pullgate with the copy of install.sh that is +// built into the binary, sends a notice or asks the owner, and installs +// only the release that the owner approved, with every check of +// install.sh. Then it installs the units of the new version and restarts +// them. When the new binary does not start, it puts the old one back. +package selfupdate + +import ( + "context" + "crypto/subtle" + "errors" + "fmt" + "html" + "io" + "log/slog" + "os" + "os/exec" + "path/filepath" + "regexp" + "strconv" + "strings" + "syscall" + "time" + + "github.com/code6x/pullgate/internal/config" + "github.com/code6x/pullgate/internal/message" + "github.com/code6x/pullgate/internal/safedir" + "github.com/code6x/pullgate/internal/spool" + "github.com/code6x/pullgate/internal/state" +) + +// Repo is where the releases come from. install.sh has the same name. +const Repo = "code6x/pullgate" + +// RootPath is the PATH of every program root runs here, as in install.sh. +const RootPath = "/usr/sbin:/usr/bin:/sbin:/bin" + +// QuestionTTL is how long an update question can be answered. +const QuestionTTL = 12 * time.Hour + +// CheckInterval is the least time between two /update requests that root +// acts on. +const CheckInterval = time.Minute + +// RepeatSecurity is how often the notice of a security release comes +// again, until it is installed. +const RepeatSecurity = 23 * time.Hour + +// Limits of the programs that root runs here. +const ( + scriptTimeout = 20 * time.Minute // install.sh: two downloads and gh attestation verify + runTimeout = time.Minute // pullgate version, pullgate units + maxOutput = 256 << 10 // the output of install.sh that is kept + maxUnitsJSON = 1 << 20 // the output of pullgate units + maxUnits = 32 + maxUnitSize = 64 << 10 +) + +// ListenerUnit is the unit of the listener. It is restarted last. +const ListenerUnit = "pullgate-listen.service" + +var versionRE = regexp.MustCompile(`^(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})\.(0|[1-9][0-9]{0,8})$`) + +// ValidVersion reports whether v is a release version X.Y.Z. +func ValidVersion(v string) bool { return versionRE.MatchString(v) } + +func parts(v string) [3]int { + var p [3]int + for i, s := range strings.SplitN(v, ".", 3) { + p[i], _ = strconv.Atoi(s) + } + return p +} + +// newer reports whether version a is newer than version b. Both must be +// X.Y.Z; else it is false. +func newer(a, b string) bool { + if !ValidVersion(a) || !ValidVersion(b) { + return false + } + pa, pb := parts(a), parts(b) + for i := range 3 { + if pa[i] != pb[i] { + return pa[i] > pb[i] + } + } + return false +} + +var sha256RE = regexp.MustCompile(`^[0-9a-f]{64}$`) + +// Systemctl runs systemctl with its arguments. The error is nil only when +// systemctl exits 0. +type Systemctl func(ctx context.Context, args ...string) error + +// Updater holds what root needs for one start of pullgate update. +type Updater struct { + Cfg *config.Listener // the listener config: instances and [updates] + StateDir string // /var/lib/pullgate/_update + Spool spool.Dirs // /var/spool/pullgate/_update + Owners spool.Owners + UID uint32 // root: owns the state and the spool + Bin string // the installed binary, DIR/pullgate + Version string // the version of this process + Script string // install.sh, built into the binary + UnitDir string // /etc/systemd/system + Host string // shown in each message + Path string // the PATH of install.sh; RootPath + Arch string // runtime.GOARCH + Systemctl + Log *slog.Logger + Out io.Writer // the journal: the output of install.sh + ListenerWait time.Duration // how long the new listener must stay active + Now func() time.Time + + // Crash is for tests: when it returns true at a step, the update stops + // there at once, as if the host lost power. + Crash func(step string) bool +} + +// errCrash is what a step returns after Crash said so. +var errCrash = errors.New("crash (test)") + +func (u *Updater) now() time.Time { + if u.Now != nil { + return u.Now() + } + return time.Now() +} + +func (u *Updater) crash(step string) bool { return u.Crash != nil && u.Crash(step) } + +func (u *Updater) head() string { + return "pullgate on " + html.EscapeString(u.Host) + ", update of pullgate" +} + +func (u *Updater) send(m spool.Message) { + m.Text = u.head() + "\n" + m.Text + if err := u.Spool.Send(u.Owners.ListenerGID, m); err != nil { + u.Log.Error("write to the outbox", "kind", m.Kind, "err", err) + } +} + +func (u *Updater) notice(text string) { u.send(spool.Message{Kind: spool.KindNotice, Text: text}) } + +func (u *Updater) reply(q int64, text string) { + u.send(spool.Message{Kind: spool.KindReply, Question: q, Text: text}) +} + +func (u *Updater) edit(q int64, text string) { + u.send(spool.Message{Kind: spool.KindEdit, Question: q, Text: text}) +} + +// releaseURL is the page of the release notes. The version passed +// ValidVersion. +func releaseURL(v string) string { return "https://github.com/" + Repo + "/releases/tag/v" + v } + +func (u *Updater) tarball(v string) string { return "pullgate_" + v + "_linux_" + u.Arch + ".tar.gz" } + +// ensure makes the state directory (root, 0700), its tmp directory, and +// the spool (DESIGN.md section 4). +func (u *Updater) ensure() error { + if err := safedir.CheckParents(filepath.Dir(u.StateDir), u.UID); err != nil { + return fmt.Errorf("the state directory is not safe: %w", err) + } + for _, p := range []string{u.StateDir, u.tmpDir()} { + if err := os.Mkdir(p, 0o700); err != nil && !errors.Is(err, os.ErrExist) { + return fmt.Errorf("make %s: %w", p, err) + } + fi, err := os.Lstat(p) + if err != nil { + return err + } + if !fi.IsDir() { + return fmt.Errorf("%s is not a directory. Fix: remove it", p) + } + if err := os.Chmod(p, 0o700); err != nil { + return err + } + } + if err := safedir.CheckParents(u.tmpDir(), u.UID); err != nil { + return fmt.Errorf("the state directory is not safe: %w", err) + } + return u.Spool.Ensure(u.UID, u.Owners) +} + +func (u *Updater) tmpDir() string { return filepath.Join(u.StateDir, "tmp") } + +// Result is what one start did, for the log. +type Result string + +// The results. +const ( + ResDev Result = "dev build, no update" + ResNothing Result = "nothing to do" + ResChecked Result = "checked" + ResAsked Result = "asked" + ResNoticed Result = "notice sent" + ResInstalled Result = "installed" + ResFailed Result = "update failed" + ResSkipped Result = "skipped" +) + +// Run is one start of pullgate update: the approvals first, then a +// request for /update, else the daily look for a new release. +func (u *Updater) Run(ctx context.Context) (Result, error) { + if err := u.ensure(); err != nil { + return "", err + } + lock, err := state.Dir{Path: u.StateDir}.Lock(true) + if err != nil { + return "", err + } + defer func() { _ = lock.Close() }() + st, err := u.load() + if err != nil { + // Remove the request, so the path unit does not start this again + // and again, and tell the owner. + if n, _, _ := u.Spool.TakeChecks(u.Owners.ListenerUID); n > 0 { + u.notice("Error: " + message.Code(err.Error())) + } + return "", err + } + if st.InProgress != nil { + u.cutOff(ctx, st) + if err := u.save(st); err != nil { + return "", err + } + } + approvals, err := u.Spool.TakeApprovals(u.Owners.ListenerUID, 0) + if err != nil { + return "", err + } + requests, bad, err := u.Spool.TakeChecks(u.Owners.ListenerUID) + if err != nil { + return "", err + } + for _, b := range bad { + u.Log.Warn("a bad file in the update requests, removed", "err", b) + } + if !ValidVersion(u.Version) { + // A build from the source cannot know which release is newer. + u.Log.Info("this pullgate has no release version, so it does not update itself", "version", u.Version) + if requests > 0 || len(approvals) > 0 { + u.notice("This pullgate is a build from the source (version " + message.Code(u.Version) + "), so it does not update itself. Install a release with install.sh (README, section Install).") + } + return ResDev, nil + } + if u.expire(st) { + if err := u.save(st); err != nil { + return "", err + } + } + for _, a := range approvals { + if a.Err != nil { + u.Log.Warn("a bad approval file, removed", "file", a.Name, "err", a.Err) + continue + } + res, err := u.approval(ctx, st, a.Approval) + if err != nil || res == ResInstalled { + // At most one install per start; the new binary handles the + // next request. Other approvals were removed already: their + // question is gone with this one. + if requests > 0 && err == nil { + u.notice("The update ran, so the /update sent with it was not handled. Send /update again.") + } + return res, err + } + if requests == 0 && res != ResNothing { + return res, nil + } + } + if requests > 0 { + now := u.now() + if d := now.Sub(st.CheckAt); d < CheckInterval && d > -CheckInterval { + u.Log.Info("an /update request less than a minute after the last one, dropped") + if d := now.Sub(st.CheckNote); d >= CheckInterval || d <= -CheckInterval { + st.CheckNote = now + u.notice("A look for a new release ran less than a minute ago, so this /update was dropped.") + } + return ResNothing, u.save(st) + } + st.CheckAt = now + if err := u.save(st); err != nil { + return "", err + } + return u.look(ctx, st, true) + } + if len(approvals) > 0 || u.Spool.HasCheck() { + // Started for a tap, or a request came in the meantime (the path + // unit starts again for it): not the daily look. + return ResNothing, nil + } + return u.look(ctx, st, false) +} + +// expire closes the open question when its time is up. +func (u *Updater) expire(st *State) bool { + q := st.Question + if q == nil || u.now().Before(q.Expires) { + return false + } + u.edit(q.ID, "Expired: the update to "+message.Code(q.Version)+" was not answered in time. Send /update to ask again.") + st.Question = nil + return true +} + +// cutOff reports an update that a crash or a reboot cut off. The binary +// is the old file or the new one, never a part of one (the rename). The +// owner checks which one runs. +func (u *Updater) cutOff(ctx context.Context, st *State) { + ip := st.InProgress + st.InProgress = nil + says := "it does not run" + if out, err := u.binVersion(ctx, u.Bin); err == nil { + says = out + } + u.Log.Error("an update was cut off", "version", ip.Version, "from", ip.From, "binary", says) + u.notice("⚠ The update of pullgate from " + message.Code(ip.From) + " to " + message.Code(ip.Version) + + " was cut off (a crash or a reboot). " + message.Code(u.Bin+" version") + " says: " + message.Code(says) + + ". The units may be the old ones or the new ones. Check the host: " + message.Code("systemctl status 'pullgate-*'") + + ". Fix: run " + message.Code("install.sh --version "+ip.Version) + " as root, or send /update.") +} + +// approval handles one approval from the inbox. +func (u *Updater) approval(ctx context.Context, st *State, a spool.Approval) (Result, error) { + q := st.Question + if q == nil || subtle.ConstantTimeCompare([]byte(q.Code), []byte(a.Code)) != 1 { + u.Log.Info("an approval for no open update question, ignored") + u.notice("A tap came for an update question that is closed. Nothing was installed. Send /update to ask again.") + return ResNothing, nil + } + now := u.now() + if now.Before(q.Asked) || !now.Before(q.Expires) { + st.Question = nil + u.reply(q.ID, "Expired: nothing was installed. Send /update to ask again.") + return ResNothing, u.save(st) + } + // The code works once. + st.Question = nil + if err := u.save(st); err != nil { + return "", err + } + if a.Action == "skip" { + u.Log.Info("update skipped", "version", q.Version) + u.reply(q.ID, "Skipped: nothing was installed. Send /update to ask again.") + return ResSkipped, nil + } + // Forward only (rule 5): the version comes from root's own state. + if !newer(q.Version, u.Version) { + u.Log.Warn("refused: the release is not newer", "version", q.Version, "installed", u.Version) + u.reply(q.ID, "Refused: "+message.Code(q.Version)+" is not newer than "+message.Code(u.Version)+". pullgate never installs an older version from Telegram.") + return ResFailed, nil + } + return u.install(ctx, st, q) +} + +// found is what install.sh --check-only found. +type found struct { + Version string // the newest release; "" when it is not known + Security bool + Fetched bool // the files were downloaded: a failure after this is a failed check + Checked bool // every check passed + SHA256 string + Upto bool // the installed version is the newest + Reason string + Err error +} + +func (u *Updater) checkRelease(ctx context.Context) found { + args := []string{"--check-only", "--bin-dir", filepath.Dir(u.Bin)} + if u.Cfg.Updates.GH != "" { + args = append(args, "--gh", u.Cfg.Updates.GH) + } + tell, reason, err := u.script(ctx, args...) + var f found + if v := tell["version"]; len(v) == 2 && ValidVersion(v[0]) { + f.Version, f.Security = v[0], v[1] == "security" + } + _, f.Fetched = tell["fetched"] + if err != nil { + f.Err, f.Reason = err, reason + return f + } + if _, ok := tell["up-to-date"]; ok { + f.Upto = true + return f + } + c := tell["checked"] + if len(c) != 3 || c[0] != f.Version || !sha256RE.MatchString(c[1]) { + f.Err, f.Reason = errors.New("install.sh --check-only gave no result"), "install.sh gave no result. This is a bug in pullgate" + return f + } + f.Checked, f.SHA256 = true, c[1] + if !newer(f.Version, u.Version) { + f.Checked, f.Upto = false, true + } + return f +} + +// look finds the newest release. requested: the owner sent /update; else +// the timer started it. +func (u *Updater) look(ctx context.Context, st *State, requested bool) (Result, error) { + if !requested && !u.Cfg.Updates.Notices() { + u.Log.Info("the daily look for a new release is off ([updates] check = false)") + return ResNothing, nil + } + f := u.checkRelease(ctx) + now := u.now() + switch { + case f.Err != nil && !f.Fetched: + // The network, GitHub, or this host: no release to name. + u.Log.Warn("could not look for a new release", "err", f.Err, "reason", f.Reason) + if requested { + u.notice("Could not look for a new release: " + message.Code(f.Reason) + ". See the journal: journalctl -u pullgate-update.service") + } + return ResChecked, nil + case f.Err != nil: + u.Log.Error("a release failed a check", "version", f.Version, "reason", f.Reason) + if st.Warned == nil { + st.Warned = map[string]time.Time{} + } + _, warned := st.Warned[f.Version] + if requested || !warned { + st.Warned[f.Version] = now + name := "The newest release" + if f.Version != "" { + name = "pullgate " + message.Code(f.Version) + } + u.notice("⚠ " + name + " failed a check, so it is not offered: " + message.Code(f.Reason) + + ". Do not install it by hand. See the journal: journalctl -u pullgate-update.service") + } + return ResNoticed, u.save(st) + case f.Upto: + u.Log.Info("pullgate is up to date", "version", u.Version) + if q := st.Question; q != nil { + u.edit(q.ID, "Closed: "+message.Code(q.Version)+" is not newer than the installed "+message.Code(u.Version)+" any more.") + st.Question = nil + } + if requested { + u.notice("pullgate " + message.Code(u.Version) + " is installed. It is the newest release.") + } + return ResChecked, u.save(st) + } + // A newer release that passed every check. + if q := st.Question; q != nil { + if q.Version == f.Version && q.SHA256 == f.SHA256 { + if requested { + // Send it again: the listener sends it only when it does + // not know it yet (for example it lost the message). + u.send(spool.Message{Kind: spool.KindAsk, Question: q.ID, Code: q.Code, Expires: q.Expires, Text: u.questionText(f)}) + u.reply(q.ID, "The question for "+message.Code(q.Version)+" is still open.") + } + return ResChecked, nil + } + u.edit(q.ID, "Closed: a newer question replaced this one ("+message.Code(f.Version)+").") + st.Question = nil + if err := u.save(st); err != nil { + return "", err + } + requested = true // the owner asked for an update before: ask again + } + if requested { + return u.ask(st, f) + } + if st.Notified == nil { + st.Notified = map[string]time.Time{} + } + last, done := st.Notified[f.Version] + if done && (!f.Security || now.Sub(last) < RepeatSecurity) { + return ResChecked, nil + } + st.Notified[f.Version] = now + lines := []string{} + if f.Security { + lines = append(lines, "⚠ Security release. It fixes a security problem. Install it soon.") + } + lines = append(lines, + "pullgate "+message.Code(f.Version)+" is out. Installed: "+message.Code(u.Version)+".", + "Release notes: "+releaseURL(f.Version), + "Send /update to install it.") + u.notice(strings.Join(lines, "\n")) + u.Log.Info("notice of a new release sent", "version", f.Version, "security", f.Security) + return ResNoticed, u.save(st) +} + +// ask records the question in the state, then writes it to the outbox. +func (u *Updater) ask(st *State, f found) (Result, error) { + c, err := state.NewCode() + if err != nil { + return "", err + } + now := u.now() + q := &Question{ID: st.NextID, Code: c, Version: f.Version, SHA256: f.SHA256, Asked: now, Expires: now.Add(QuestionTTL)} + st.NextID++ + st.Question = q + if err := u.save(st); err != nil { + return "", err + } + m := spool.Message{Kind: spool.KindAsk, Question: q.ID, Code: c, Expires: q.Expires, Text: u.head() + "\n" + u.questionText(f)} + if err := u.Spool.Send(u.Owners.ListenerGID, m); err != nil { + st.Question = nil + _ = u.save(st) + return "", fmt.Errorf("write the update question to the outbox: %w", err) + } + u.Log.Info("asked", "version", f.Version, "sha256", f.SHA256, "question", q.ID) + return ResAsked, nil +} + +// questionText is the question, without the head. +func (u *Updater) questionText(f found) string { + var lines []string + if f.Security { + lines = append(lines, "⚠ Security release. It fixes a security problem.") + } + lines = append(lines, + "Update pullgate to "+message.Code(f.Version)+"?", + "Installed now: "+message.Code(u.Version), + "Release notes: "+releaseURL(f.Version), + "File: "+message.Code(u.tarball(f.Version)), + "SHA-256: "+message.Code(f.SHA256), + "", + "The SHA-256 and the build attestation passed. Apply installs only this file, after the same checks again, then the units of the new version, and restarts them.") + return strings.Join(lines, "\n") +} + +// capBuf keeps at most max bytes, and copies everything to w. +type capBuf struct { + b []byte + max int + w io.Writer + cut bool +} + +func (c *capBuf) Write(p []byte) (int, error) { + if c.w != nil { + _, _ = c.w.Write(p) + } + room := c.max - len(c.b) + if len(p) > room { + c.cut = true + } + if room > 0 { + c.b = append(c.b, p[:min(room, len(p))]...) + } + return len(p), nil +} + +// command makes a command with an empty environment (PATH and LC_ALL +// only, plus the proxy variables), in its own process group, which is +// killed when ctx ends. +func command(ctx context.Context, path string, extra []string, name string, args ...string) *exec.Cmd { + cmd := exec.CommandContext(ctx, name, args...) //nolint:gosec // /bin/sh with the built-in install.sh, or the binary that install.sh checked + cmd.Env = append([]string{"PATH=" + path, "LC_ALL=C"}, extra...) + for _, k := range []string{"https_proxy", "HTTPS_PROXY", "no_proxy", "NO_PROXY"} { + if v, ok := os.LookupEnv(k); ok { + cmd.Env = append(cmd.Env, k+"="+v) + } + } + cmd.Dir = "/" + cmd.Stdin = nil + cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} + cmd.Cancel = func() error { return syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) } + cmd.WaitDelay = 10 * time.Second + return cmd +} + +// script runs the built-in install.sh with args. It returns the +// "@pullgate WORD VALUES" lines by WORD, and the reason of a failure: the +// last line of install.sh, without "pullgate: " and "(exit 1)". +func (u *Updater) script(parent context.Context, args ...string) (map[string][]string, string, error) { + ctx, cancel := context.WithTimeout(parent, scriptTimeout) + defer cancel() + out := u.Out + if out == nil { + out = io.Discard + } + stdout := &capBuf{max: maxOutput, w: out} + stderr := &capBuf{max: maxOutput, w: out} + tmp := u.tmpDir() + cmd := command(ctx, u.Path, []string{"TMPDIR=" + tmp, "HOME=" + tmp}, "/bin/sh", append([]string{"-c", u.Script, "install.sh"}, args...)...) + cmd.Stdout, cmd.Stderr = stdout, stderr + err := cmd.Run() + tell := map[string][]string{} + for line := range strings.SplitSeq(string(stdout.b), "\n") { + if rest, ok := strings.CutPrefix(line, "@pullgate "); ok { + f := strings.Fields(rest) + if len(f) > 0 { + tell[f[0]] = f[1:] + } + } + } + if err == nil { + return tell, "", nil + } + reason := "install.sh failed: " + err.Error() + if ctx.Err() != nil { + reason = "install.sh ran longer than " + scriptTimeout.String() + } + lines := strings.Split(strings.TrimSpace(string(stderr.b)), "\n") + if last := strings.TrimSpace(lines[len(lines)-1]); strings.HasPrefix(last, "pullgate: ") { + last = strings.TrimPrefix(last, "pullgate: ") + last = strings.TrimSuffix(last, " (exit 1)") + last = strings.TrimSuffix(last, "; nothing was installed") + reason = last + } + return tell, reason, fmt.Errorf("install.sh %s: %w", strings.Join(args, " "), err) +} + +// run runs a program with no arguments from the network, at most +// runTimeout, and returns its standard output. +func (u *Updater) run(parent context.Context, max int, name string, args ...string) (string, error) { + ctx, cancel := context.WithTimeout(parent, runTimeout) + defer cancel() + stdout := &capBuf{max: max} + cmd := command(ctx, RootPath, nil, name, args...) + cmd.Stdout = stdout + cmd.Stderr = u.Out + if err := cmd.Run(); err != nil { + return "", err + } + if stdout.cut { + return "", fmt.Errorf("%s %s printed more than %d bytes", name, strings.Join(args, " "), max) + } + return string(stdout.b), nil +} + +// binVersion runs FILE version, and returns what it printed, on one line. +func (u *Updater) binVersion(ctx context.Context, file string) (string, error) { + out, err := u.run(ctx, 256, file, "version") + return strings.TrimSpace(out), err +} diff --git a/internal/selfupdate/selfupdate_test.go b/internal/selfupdate/selfupdate_test.go new file mode 100644 index 0000000..4f94974 --- /dev/null +++ b/internal/selfupdate/selfupdate_test.go @@ -0,0 +1,772 @@ +package selfupdate + +import ( + "archive/tar" + "bytes" + "compress/gzip" + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "errors" + "fmt" + "io" + "log/slog" + "os" + "os/exec" + "path/filepath" + "slices" + "strings" + "sync" + "syscall" + "testing" + "time" + + "github.com/code6x/pullgate" + "github.com/code6x/pullgate/internal/config" + "github.com/code6x/pullgate/internal/spool" +) + +// The tests run the real install.sh (built into the binary) against a fake +// release, as the tests of install.sh do: a fake curl serves the files of +// the release from a directory, a fake gh says that the attestation is +// valid or not, and each fake pullgate is a small script. They never use +// the network. They do not run as root: as root, install.sh runs only the +// programs of the system. + +func TestMain(m *testing.M) { + syscall.Umask(0o022) + os.Exit(m.Run()) +} + +const fakeCurl = `#!/bin/sh +# A fake curl: https://HOST/PATH is the file WEB/HOST/PATH. +out= +url= +while [ "$#" -gt 0 ]; do + case $1 in + --output) out=$2; shift ;; + esac + url=$1 + shift +done +case $url in +https://*) ;; +*) echo "fake curl: not HTTPS: $url" >&2; exit 1 ;; +esac +file=WEB/${url#https://} +if [ ! -f "$file" ]; then + echo "curl: (22) The requested URL returned error: 404" >&2 + exit 22 +fi +cp "$file" "$out" +` + +const fakeGh = `#!/bin/sh +# A fake gh: the attestation is valid unless WEB/gh-exit says otherwise. +if [ "$1" = --version ]; then + echo "gh version 2.102.0 (2026-09-30)" + exit 0 +fi +echo "$*" >>WEB/gh-calls +exit "$(cat WEB/gh-exit 2>/dev/null || echo 0)" +` + +const fakeUname = `#!/bin/sh +case $1 in +-s) echo Linux ;; +-m) echo x86_64 ;; +*) exit 1 ;; +esac +` + +// fakeBin is a fake pullgate: "version" prints the line; "units" prints +// the file units. +func fakeBin(versionLine, units string) []byte { + return fmt.Appendf(nil, "#!/bin/sh\ncase $1 in\nversion) echo '%s' ;;\nunits) cat '%s' ;;\n*) exit 1 ;;\nesac\n", versionLine, units) +} + +type rig struct { + t *testing.T + web string // the fake GitHub + fakes string + bin string // DIR/pullgate + units string // the unit directory + unitsV string // the units of the new versions (JSON) + spool spool.Dirs + u *Updater + now time.Time + calls []string // systemctl calls + mu sync.Mutex + enabled map[string]bool + // listenerDown: the listener is not active after its restart, while + // the binary says it is this version. + listenerDown string +} + +const installed = "0.2.0" + +func newRig(t *testing.T) *rig { + t.Helper() + if os.Geteuid() == 0 { + t.Skip("as root, install.sh runs only the programs of the system; the fakes would not count") + } + base := t.TempDir() + r := &rig{t: t, web: filepath.Join(base, "web"), fakes: filepath.Join(base, "fakes"), units: filepath.Join(base, "systemd"), + now: time.Date(2026, 11, 18, 12, 0, 0, 0, time.UTC), enabled: map[string]bool{}} + for _, d := range []string{r.web, r.fakes, r.units, filepath.Join(base, "bin"), filepath.Join(base, "state"), filepath.Join(r.units, "pullgate-listen.service.d")} { + if err := os.MkdirAll(d, 0o755); err != nil { + t.Fatal(err) + } + } + write(t, filepath.Join(r.fakes, "curl"), strings.ReplaceAll(fakeCurl, "WEB", r.web), 0o755) + write(t, filepath.Join(r.fakes, "uname"), fakeUname, 0o755) + gh := filepath.Join(r.fakes, "gh") + write(t, gh, strings.ReplaceAll(fakeGh, "WEB", r.web), 0o755) + r.unitsV = filepath.Join(r.web, "units.json") + r.setUnits(pullgate.Units(), pullgate.Enable) + // The units of the host: the listener unit is old, and has a drop-in. + // The other units are as shipped. + for n, c := range pullgate.Units() { + write(t, filepath.Join(r.units, n), c, 0o644) + } + write(t, filepath.Join(r.units, "pullgate-listen.service"), "# an old unit\n", 0o644) + write(t, filepath.Join(r.units, "pullgate-listen.service.d", "override.conf"), "[Service]\nRestartSec=1s\n", 0o644) + r.bin = filepath.Join(base, "bin", "pullgate") + write(t, r.bin, string(fakeBin("pullgate "+installed, r.unitsV)), 0o755) + for _, u := range []string{"pullgate-run@config-repo.timer", "pullgate-apply@config-repo.path", "pullgate-check@config-repo.path", "pullgate-update.timer", "pullgate-update.path"} { + r.enabled[u] = true + } + yes := true + cfg := &config.Listener{Instances: []string{"config-repo"}, SpoolDir: filepath.Join(base, "spool"), Updates: config.Updates{Check: &yes, ListenerUser: "pullgate", GH: gh}} + r.spool = spool.Dirs{Base: cfg.SpoolDir, Name: spool.SelfName} + r.u = &Updater{ + Cfg: cfg, StateDir: filepath.Join(base, "state", spool.SelfName), Spool: r.spool, + Owners: spool.Owners{ListenerUID: os.Geteuid(), ListenerGID: os.Getegid()}, UID: uint32(os.Geteuid()), + Bin: r.bin, Version: installed, Script: pullgate.InstallScript, UnitDir: r.units, Host: "example-host", + Path: r.fakes + ":" + os.Getenv("PATH"), Arch: "amd64", Systemctl: r.systemctl, + Log: slog.New(slog.NewTextHandler(io.Discard, nil)), Out: io.Discard, Now: func() time.Time { return r.now }, + } + if err := r.u.ensure(); err != nil { + t.Fatal(err) + } + return r +} + +func write(t *testing.T, p, s string, mode os.FileMode) { + t.Helper() + if err := os.WriteFile(p, []byte(s), mode); err != nil { + t.Fatal(err) + } + if err := os.Chmod(p, mode); err != nil { + t.Fatal(err) + } +} + +func (r *rig) setUnits(units map[string]string, enable []string) { + b, err := json.Marshal(UnitList{Units: units, Enable: enable}) + if err != nil { + r.t.Fatal(err) + } + write(r.t, r.unitsV, string(b), 0o644) +} + +func (r *rig) systemctl(_ context.Context, args ...string) error { + r.mu.Lock() + defer r.mu.Unlock() + r.calls = append(r.calls, strings.Join(args, " ")) + switch args[0] { + case "is-enabled": + if !r.enabled[args[len(args)-1]] { + return errors.New("disabled") + } + case "is-active": + out, _ := exec.Command(r.bin, "version").Output() + if r.listenerDown != "" && strings.TrimSpace(string(out)) == "pullgate "+r.listenerDown { + return errors.New("inactive") + } + } + return nil +} + +// release is one fake release. +type release struct { + version string + binLine string // what its pullgate version prints; default "pullgate VERSION" + security bool + badSum bool // SHA256SUMS has another SHA-256 + license string +} + +// publish puts a release on the fake GitHub, as the newest one, and +// returns the SHA-256 of its tarball. +func (r *rig) publish(rel release) string { + r.t.Helper() + if rel.binLine == "" { + rel.binLine = "pullgate " + rel.version + } + var buf bytes.Buffer + gz := gzip.NewWriter(&buf) + tw := tar.NewWriter(gz) + for _, f := range []struct { + name string + body []byte + mode int64 + }{{"pullgate", fakeBin(rel.binLine, r.unitsV), 0o755}, {"LICENSE", []byte("license\n" + rel.license), 0o644}} { + if err := tw.WriteHeader(&tar.Header{Name: f.name, Mode: f.mode, Size: int64(len(f.body)), Typeflag: tar.TypeReg}); err != nil { + r.t.Fatal(err) + } + _, _ = tw.Write(f.body) + } + _ = tw.Close() + _ = gz.Close() + sum := sha256.Sum256(buf.Bytes()) + hexSum := hex.EncodeToString(sum[:]) + listed := hexSum + if rel.badSum { + listed = strings.Repeat("0", 64) + } + dl := filepath.Join(r.web, "github.com/code6x/pullgate/releases/download/v"+rel.version) + api := filepath.Join(r.web, "api.github.com/repos/code6x/pullgate/releases") + for _, d := range []string{dl, filepath.Join(api, "tags")} { + if err := os.MkdirAll(d, 0o755); err != nil { + r.t.Fatal(err) + } + } + tarball := "pullgate_" + rel.version + "_linux_amd64.tar.gz" + write(r.t, filepath.Join(dl, tarball), buf.String(), 0o644) + write(r.t, filepath.Join(dl, "SHA256SUMS"), listed+" "+tarball+"\n", 0o644) + write(r.t, filepath.Join(dl, "pullgate_"+rel.version+".sigstore.json"), "{}\n", 0o644) + body := `## [` + rel.version + `](https://example.com)\n\n### Bug Fixes\n\n* a fix\n` + if rel.security { + body = `## [` + rel.version + `](https://example.com)\n\n### Security\n\n* a fix\n` + } + js := `{"tag_name": "v` + rel.version + `", "body": "` + body + `"}` + "\n" + write(r.t, filepath.Join(api, "latest"), js, 0o644) + write(r.t, filepath.Join(api, "tags", "v"+rel.version), js, 0o644) + return hexSum +} + +func (r *rig) run() Result { + r.t.Helper() + res, err := r.u.Run(context.Background()) + if err != nil { + r.t.Fatalf("Run: %v", err) + } + return res +} + +// outbox takes the messages that root wrote. +func (r *rig) outbox() []spool.Message { + r.t.Helper() + files, err := r.spool.ReadOutbox() + if err != nil { + r.t.Fatal(err) + } + var out []spool.Message + for _, f := range files { + if f.Err != nil { + r.t.Fatalf("a bad outbox file: %v", f.Err) + } + out = append(out, f.Message) + if err := r.spool.Done(f.Name); err != nil { + r.t.Fatal(err) + } + } + return out +} + +// update sends /update and runs root. +func (r *rig) update() (Result, []spool.Message) { + r.t.Helper() + if err := r.spool.WriteCheck(); err != nil { + r.t.Fatal(err) + } + r.now = r.now.Add(CheckInterval) + res := r.run() + return res, r.outbox() +} + +// tap answers the open question as the listener does, and runs root. +func (r *rig) tap(code, action string) (Result, []spool.Message) { + r.t.Helper() + if err := r.spool.WriteApproval(spool.Approval{Code: code, Action: action}); err != nil { + r.t.Fatal(err) + } + res := r.run() + return res, r.outbox() +} + +func (r *rig) binSays() string { + r.t.Helper() + out, err := exec.Command(r.bin, "version").Output() + if err != nil { + r.t.Fatalf("%s does not run: %v", r.bin, err) + } + return strings.TrimSpace(string(out)) +} + +func one(t *testing.T, ms []spool.Message, kind string, want ...string) spool.Message { + t.Helper() + if len(ms) != 1 || ms[0].Kind != kind { + t.Fatalf("want one %s message, got %+v", kind, ms) + } + for _, w := range want { + if !strings.Contains(ms[0].Text, w) { + t.Fatalf("the %s must hold %q:\n%s", kind, w, ms[0].Text) + } + } + return ms[0] +} + +// ask publishes the release and sends /update; it returns the question. +func (r *rig) ask(rel release) spool.Message { + r.t.Helper() + sum := r.publish(rel) + res, ms := r.update() + if res != ResAsked { + r.t.Fatalf("/update: got %q, want %q (%+v)", res, ResAsked, ms) + } + return one(r.t, ms, spool.KindAsk, ""+rel.version+"", ""+sum+"", + "https://github.com/code6x/pullgate/releases/tag/v"+rel.version, "pullgate_"+rel.version+"_linux_amd64.tar.gz") +} + +func TestUpdateAsksAndInstalls(t *testing.T) { + r := newRig(t) + q := r.ask(release{version: "0.3.0"}) + if r.binSays() != "pullgate "+installed { + t.Fatal("a question must install nothing") + } + res, ms := r.tap(q.Code, "apply") + if res != ResInstalled { + t.Fatalf("got %q, want %q: %+v", res, ResInstalled, ms) + } + m := one(t, ms, spool.KindReply, "updated", "0.2.0 → 0.3.0", "pullgate-listen.service", + "pullgate-listen.service.d/override.conf") + if m.Question != q.Question { + t.Fatal("the report must answer the question") + } + if r.binSays() != "pullgate 0.3.0" { + t.Fatalf("the binary says %q, want 0.3.0", r.binSays()) + } + if _, err := os.Lstat(filepath.Join(filepath.Dir(r.bin), ".pullgate.prev")); err == nil { + t.Fatal("the old binary must be removed after a good update") + } + // The unit that differed is the shipped one now, and the drop-in is + // untouched. + got, _ := os.ReadFile(filepath.Join(r.units, "pullgate-listen.service")) + if string(got) != pullgate.Units()["pullgate-listen.service"] { + t.Fatal("the listener unit must be the one of the new version") + } + if got, _ := os.ReadFile(filepath.Join(r.units, "pullgate-listen.service.d", "override.conf")); string(got) != "[Service]\nRestartSec=1s\n" { + t.Fatal("a drop-in must not be changed") + } + for _, want := range []string{"daemon-reload", "reenable pullgate-run@config-repo.timer", "restart pullgate-run@config-repo.timer", + "reenable pullgate-update.path", "reenable pullgate-listen.service", "restart pullgate-listen.service", "is-active --quiet pullgate-listen.service"} { + if !slices.Contains(r.calls, want) { + t.Errorf("systemctl %s was not called: %q", want, r.calls) + } + } + if i, j := slices.Index(r.calls, "daemon-reload"), slices.Index(r.calls, "restart pullgate-listen.service"); i < 0 || j < i || + r.calls[len(r.calls)-1] != "is-active --quiet pullgate-listen.service" { + t.Errorf("the reload comes first and the listener last: %q", r.calls) + } + // The code works once. + if res, ms := r.tap(q.Code, "apply"); res != ResNothing || len(ms) != 1 || strings.Contains(ms[0].Text, "updated") { + t.Fatalf("a second tap must install nothing: %q %+v", res, ms) + } +} + +// TestUnitUpdate: a new unit is installed and enabled; a unit that the +// owner turned off stays off; a masked unit is left alone. +func TestUnitUpdate(t *testing.T) { + r := newRig(t) + units := pullgate.Units() + units["pullgate-new.timer"] = "[Timer]\nOnCalendar=daily\n\n[Install]\nWantedBy=timers.target\n" + units["pullgate-run@.service"] += "# changed\n" + r.setUnits(units, append(slices.Clone(pullgate.Enable), "pullgate-new.timer")) + r.enabled["pullgate-update.timer"] = false + if err := os.Remove(filepath.Join(r.units, "pullgate-check@.path")); err != nil { + t.Fatal(err) + } + if err := os.Symlink("/dev/null", filepath.Join(r.units, "pullgate-check@.path")); err != nil { + t.Fatal(err) + } + q := r.ask(release{version: "0.3.0"}) + res, ms := r.tap(q.Code, "apply") + if res != ResInstalled { + t.Fatalf("got %q: %+v", res, ms) + } + one(t, ms, spool.KindReply, "pullgate-new.timer", "pullgate-run@.service", "links", "pullgate-check@.path") + if got, _ := os.ReadFile(filepath.Join(r.units, "pullgate-new.timer")); string(got) != units["pullgate-new.timer"] { + t.Fatal("a new unit must be installed") + } + if l, err := os.Readlink(filepath.Join(r.units, "pullgate-check@.path")); err != nil || l != "/dev/null" { + t.Fatal("a masked unit must stay masked") + } + if !slices.Contains(r.calls, "reenable pullgate-new.timer") { + t.Errorf("a new unit must be enabled: %q", r.calls) + } + if slices.Contains(r.calls, "reenable pullgate-update.timer") { + t.Errorf("a unit that the owner turned off must stay off: %q", r.calls) + } +} + +func TestUpdateDenyPaths(t *testing.T) { + for _, tt := range []struct { + name string + rel release + gh string // the exit of gh attestation verify + want string + }{ + {name: "wrong SHA-256", rel: release{version: "0.3.0", badSum: true}, want: "SHA-256"}, + {name: "failed attestation", rel: release{version: "0.3.0"}, gh: "1", want: "attestation"}, + } { + t.Run(tt.name+" before the question", func(t *testing.T) { + r := newRig(t) + r.publish(tt.rel) + if tt.gh != "" { + write(t, filepath.Join(r.web, "gh-exit"), tt.gh+"\n", 0o644) + } + res, ms := r.update() + if res != ResNoticed { + t.Fatalf("got %q: %+v", res, ms) + } + one(t, ms, spool.KindNotice, "failed a check", "not offered", tt.want) + if strings.Contains(ms[0].Text, "/update to install") { + t.Fatal("a release that failed a check must never get the /update hint") + } + // The daily look warns once, not every day. + r.now = r.now.Add(24 * time.Hour) + if res := r.run(); res != ResNoticed || len(r.outbox()) != 0 { + t.Fatal("the warning must come once") + } + if r.binSays() != "pullgate "+installed { + t.Fatal("nothing must be installed") + } + }) + t.Run(tt.name+" on Apply", func(t *testing.T) { + r := newRig(t) + q := r.ask(release{version: "0.3.0"}) + // The release changes after the question. + r.publish(tt.rel) + if tt.gh != "" { + write(t, filepath.Join(r.web, "gh-exit"), tt.gh+"\n", 0o644) + } + res, ms := r.tap(q.Code, "apply") + if res != ResFailed { + t.Fatalf("got %q: %+v", res, ms) + } + one(t, ms, spool.KindReply, "failed", "Nothing was installed") + if r.binSays() != "pullgate "+installed { + t.Fatal("nothing must be installed") + } + if _, err := os.Lstat(filepath.Join(filepath.Dir(r.bin), ".pullgate.prev")); err == nil { + t.Fatal("the kept old binary must be removed when nothing was installed") + } + }) + } +} + +// TestApplyInstallsOnlyTheApprovedFile: a release whose tarball changed +// after the question (and still passes every other check) is refused. +func TestApplyInstallsOnlyTheApprovedFile(t *testing.T) { + r := newRig(t) + q := r.ask(release{version: "0.3.0"}) + r.publish(release{version: "0.3.0", license: "changed\n"}) // another file, same version + res, ms := r.tap(q.Code, "apply") + if res != ResFailed { + t.Fatalf("got %q: %+v", res, ms) + } + one(t, ms, spool.KindReply, "not the one that was approved") + if r.binSays() != "pullgate "+installed { + t.Fatal("nothing must be installed") + } +} + +func TestOlderVersionIsNeverInstalled(t *testing.T) { + r := newRig(t) + r.publish(release{version: "0.1.1"}) + res, ms := r.update() + if res != ResChecked { + t.Fatalf("got %q", res) + } + one(t, ms, spool.KindNotice, "It is the newest release") + // A question for an older version in root's state (the state is + // root's own; this stands for a bug) is refused on Apply. + r.publish(release{version: "0.3.0"}) + q := r.ask(release{version: "0.3.0"}) + r.u.Version = "0.4.0" + res, ms = r.tap(q.Code, "apply") + if res != ResFailed { + t.Fatalf("got %q", res) + } + one(t, ms, spool.KindReply, "Refused", "never installs an older version") + if r.binSays() != "pullgate "+installed { + t.Fatal("nothing must be installed") + } +} + +func TestNewerReleaseClosesTheOpenQuestion(t *testing.T) { + r := newRig(t) + q1 := r.ask(release{version: "0.3.0"}) + sum := r.publish(release{version: "0.4.0"}) + // The daily look finds it, closes the old question and asks again. + r.now = r.now.Add(time.Hour) + if res := r.run(); res != ResAsked { + t.Fatalf("got %q", res) + } + ms := r.outbox() + if len(ms) != 2 || ms[0].Kind != spool.KindEdit || ms[0].Question != q1.Question || ms[1].Kind != spool.KindAsk || + !strings.Contains(ms[1].Text, sum) { + t.Fatalf("want the edit of the old question and a new one: %+v", ms) + } + // A tap on the old question installs nothing. + if res, ms := r.tap(q1.Code, "apply"); res != ResNothing || len(ms) != 1 || !strings.Contains(ms[0].Text, "closed") { + t.Fatalf("a tap on the closed question must install nothing: %q %+v", res, ms) + } + if res, _ := r.tap(ms[1].Code, "apply"); res != ResInstalled || r.binSays() != "pullgate 0.4.0" { + t.Fatalf("the new question installs 0.4.0: %q %s", res, r.binSays()) + } +} + +func TestSkip(t *testing.T) { + r := newRig(t) + q := r.ask(release{version: "0.3.0"}) + res, ms := r.tap(q.Code, "skip") + if res != ResSkipped { + t.Fatalf("got %q", res) + } + one(t, ms, spool.KindReply, "Skipped", "nothing was installed") + if r.binSays() != "pullgate "+installed || len(r.calls) != 0 { + t.Fatal("Skip must install and restart nothing") + } +} + +func TestExpiredQuestion(t *testing.T) { + r := newRig(t) + q := r.ask(release{version: "0.3.0"}) + r.now = r.now.Add(QuestionTTL) + res, ms := r.tap(q.Code, "apply") + if res != ResNothing || r.binSays() != "pullgate "+installed { + t.Fatalf("an expired question must install nothing: %q", res) + } + if len(ms) != 2 || ms[0].Kind != spool.KindEdit || !strings.Contains(ms[0].Text, "Expired") { + t.Fatalf("want the edit that it expired: %+v", ms) + } +} + +// TestNewBinaryDoesNotStart: the listener of the new version does not +// stay active, so the old binary and the old units come back. +func TestNewBinaryDoesNotStart(t *testing.T) { + r := newRig(t) + r.listenerDown = "0.3.0" + before, _ := os.ReadFile(filepath.Join(r.units, "pullgate-listen.service")) + q := r.ask(release{version: "0.3.0"}) + res, ms := r.tap(q.Code, "apply") + if res != ResFailed { + t.Fatalf("got %q: %+v", res, ms) + } + one(t, ms, spool.KindReply, "failed", "is not active", "pullgate 0.2.0 is back") + if r.binSays() != "pullgate "+installed { + t.Fatalf("the old binary must be back: %s", r.binSays()) + } + if got, _ := os.ReadFile(filepath.Join(r.units, "pullgate-listen.service")); !bytes.Equal(got, before) { + t.Fatal("the old units must be back") + } + if n := strings.Count(strings.Join(r.calls, "\n"), "restart pullgate-listen.service"); n != 2 { + t.Fatalf("the listener must be restarted again with the old binary: %q", r.calls) + } + st, _ := r.u.load() + if st.InProgress != nil { + t.Fatal("the rollback must clear the update in progress") + } +} + +// TestCrashInTheSwap (THREAT-MODEL.md T10): after a crash at each step, +// the binary is the old file or the new one, never none or a part of one, +// and the next start reports the cut-off update. +func TestCrashInTheSwap(t *testing.T) { + for _, step := range []string{"kept", "installed", "units"} { + t.Run(step, func(t *testing.T) { + r := newRig(t) + q := r.ask(release{version: "0.3.0"}) + r.u.Crash = func(s string) bool { return s == step } + if err := r.spool.WriteApproval(spool.Approval{Code: q.Code, Action: "apply"}); err != nil { + t.Fatal(err) + } + if _, err := r.u.Run(context.Background()); !errors.Is(err, errCrash) { + t.Fatalf("want the crash, got %v", err) + } + if says := r.binSays(); says != "pullgate 0.2.0" && says != "pullgate 0.3.0" { + t.Fatalf("after a crash the binary says %q", says) + } + // No temporary file of the swap is left as the binary. + r.u.Crash = nil + res := r.run() + ms := r.outbox() + if res != ResChecked && res != ResNothing && res != ResNoticed { + t.Fatalf("got %q", res) + } + if len(ms) == 0 || !strings.Contains(ms[0].Text, "was cut off") { + t.Fatalf("the next start must report the cut-off update: %+v", ms) + } + if st, _ := r.u.load(); st.InProgress != nil { + t.Fatal("the report must clear the update in progress") + } + }) + } +} + +func TestDailyNotice(t *testing.T) { + r := newRig(t) + // Up to date: no notice. + r.publish(release{version: installed}) + if res := r.run(); res != ResChecked || len(r.outbox()) != 0 { + t.Fatalf("up to date must send nothing: %q", res) + } + r.publish(release{version: "0.3.0"}) + if res := r.run(); res != ResNoticed { + t.Fatalf("got %q", res) + } + m := one(t, r.outbox(), spool.KindNotice, "0.3.0 is out", "https://github.com/code6x/pullgate/releases/tag/v0.3.0", "/update") + if m.Code != "" || strings.Contains(m.Text, "Security") { + t.Fatalf("a notice asks nothing: %+v", m) + } + // One notice per release. + r.now = r.now.Add(25 * time.Hour) + if res := r.run(); res != ResChecked || len(r.outbox()) != 0 { + t.Fatal("a release gets one notice") + } + // A security release: it says so first, and comes again each day. + r.publish(release{version: "0.3.1", security: true}) + r.run() + m = one(t, r.outbox(), spool.KindNotice, "Security release", "0.3.1 is out") + if strings.Index(m.Text, "Security release") > strings.Index(m.Text, "is out") { + t.Fatal("a security release must say so first") + } + r.now = r.now.Add(time.Hour) + if r.run(); len(r.outbox()) != 0 { + t.Fatal("not again within a day") + } + r.now = r.now.Add(RepeatSecurity) + r.run() + one(t, r.outbox(), spool.KindNotice, "Security release") + // check = false stops the notice. + no := false + r.u.Cfg.Updates.Check = &no + r.publish(release{version: "0.4.0"}) + r.now = r.now.Add(RepeatSecurity) + if res := r.run(); res != ResNothing || len(r.outbox()) != 0 { + t.Fatal("check = false must stop the notices") + } + if _, err := os.Stat(filepath.Join(r.web, "gh-calls")); err != nil { + t.Fatal("the notice must come only after the attestation check") + } +} + +func TestUpdateRequestLimit(t *testing.T) { + r := newRig(t) + r.publish(release{version: installed}) + r.update() + if err := r.spool.WriteCheck(); err != nil { + t.Fatal(err) + } + r.now = r.now.Add(time.Second) + if res := r.run(); res != ResNothing { + t.Fatalf("a second /update within a minute must be dropped: %q", res) + } + one(t, r.outbox(), spool.KindNotice, "less than a minute ago") +} + +func TestDevBuildDoesNotUpdate(t *testing.T) { + r := newRig(t) + r.u.Version = "dev" + r.publish(release{version: "0.3.0"}) + res, ms := r.update() + if res != ResDev { + t.Fatalf("got %q", res) + } + one(t, ms, spool.KindNotice, "build from the source") + if _, err := os.Stat(filepath.Join(r.web, "gh-calls")); err == nil { + t.Fatal("a dev build must not look for a release") + } +} + +func TestUnitListCheck(t *testing.T) { + for _, tt := range []UnitList{ + {}, + {Units: map[string]string{"../evil.service": "x"}}, + {Units: map[string]string{"sshd.service": "x"}}, + {Units: map[string]string{"pullgate-a.service": "x\x00"}}, + {Units: map[string]string{"pullgate-a.service": "x"}, Enable: []string{"pullgate-b.service"}}, + {Units: map[string]string{"pullgate-a@.service": "x"}, Enable: []string{"pullgate-a@x;y.service"}}, + } { + if err := tt.check(); err == nil { + t.Errorf("%+v must be refused", tt) + } + } + ok := UnitList{Units: pullgate.Units(), Enable: pullgate.Enable} + if err := ok.check(); err != nil { + t.Fatalf("the units of this version must pass: %v", err) + } +} + +func TestNewer(t *testing.T) { + for _, tt := range []struct { + a, b string + want bool + }{{"0.3.0", "0.2.0", true}, {"0.10.0", "0.9.0", true}, {"1.0.0", "0.99.99", true}, {"0.2.0", "0.2.0", false}, + {"0.1.9", "0.2.0", false}, {"dev", "0.1.0", false}, {"0.3.0", "dev", false}, {"0.3", "0.2.0", false}, {"01.0.0", "0.2.0", false}} { + if got := newer(tt.a, tt.b); got != tt.want { + t.Errorf("newer(%q, %q) = %v", tt.a, tt.b, got) + } + } +} + +// TestWrongVersion: no code of a release runs before the tap; on Apply, a +// binary that does not say it is the version asked for is not installed. +func TestWrongVersion(t *testing.T) { + r := newRig(t) + q := r.ask(release{version: "0.3.0", binLine: "pullgate 0.2.9"}) + res, ms := r.tap(q.Code, "apply") + if res != ResFailed { + t.Fatalf("got %q: %+v", res, ms) + } + one(t, ms, spool.KindReply, "does not say that it is pullgate 0.3.0", "Nothing was installed") + if r.binSays() != "pullgate "+installed { + t.Fatal("nothing must be installed") + } +} + +// TestRollbackOfANewTemplate: a template unit that is new in the release +// is disabled per instance and removed when the update rolls back. +func TestRollbackOfANewTemplate(t *testing.T) { + r := newRig(t) + r.listenerDown = "0.3.0" + units := pullgate.Units() + units["pullgate-x@.path"] = "[Path]\nPathExists=/x\n\n[Install]\nWantedBy=paths.target\n" + r.setUnits(units, append(slices.Clone(pullgate.Enable), "pullgate-x@NAME.path")) + q := r.ask(release{version: "0.3.0"}) + if res, _ := r.tap(q.Code, "apply"); res != ResFailed { + t.Fatalf("got %q", res) + } + if !slices.Contains(r.calls, "disable --now pullgate-x@config-repo.path") { + t.Errorf("the new instance must be disabled: %q", r.calls) + } + if _, err := os.Lstat(filepath.Join(r.units, "pullgate-x@.path")); err == nil { + t.Error("the new template must be removed") + } +} + +func TestCapBuf(t *testing.T) { + c := &capBuf{max: 10} + _, _ = c.Write([]byte("123456789")) + if c.cut { + t.Fatal("9 bytes fit in 10") + } + _, _ = c.Write([]byte("ab")) + if !c.cut || len(c.b) != 10 { + t.Fatalf("11 bytes do not fit: %v %d", c.cut, len(c.b)) + } +} diff --git a/internal/selfupdate/state.go b/internal/selfupdate/state.go new file mode 100644 index 0000000..26256d3 --- /dev/null +++ b/internal/selfupdate/state.go @@ -0,0 +1,87 @@ +package selfupdate + +import ( + "bytes" + "encoding/json" + "errors" + "fmt" + "io/fs" + "os" + "path/filepath" + "time" + + "github.com/code6x/pullgate/internal/state" +) + +// Question is the open update question. Root takes the version and the +// SHA-256 from here on Apply, never from the approval. +type Question struct { + ID int64 `json:"id"` + Code string `json:"code"` + Version string `json:"version"` + SHA256 string `json:"sha256"` + Asked time.Time `json:"asked"` + Expires time.Time `json:"expires"` +} + +// InProgress is an update that has started and not ended. A crash leaves +// it in the state, and the next start reports it. +type InProgress struct { + Version string `json:"version"` + From string `json:"from"` + Started time.Time `json:"started"` +} + +// State is /var/lib/pullgate/_update/state.json. +type State struct { + Version int `json:"version"` + NextID int64 `json:"next_id"` + Question *Question `json:"question,omitempty"` + Notified map[string]time.Time `json:"notified,omitempty"` // release → its last notice + Warned map[string]time.Time `json:"warned,omitempty"` // release → its "failed a check" notice + CheckAt time.Time `json:"check_at,omitzero"` // the last /update that was taken + CheckNote time.Time `json:"check_note,omitzero"` + InProgress *InProgress `json:"in_progress,omitempty"` +} + +func (u *Updater) stateFile() string { return filepath.Join(u.StateDir, "state.json") } + +func (u *Updater) load() (*State, error) { + b, err := os.ReadFile(u.stateFile()) + if errors.Is(err, fs.ErrNotExist) { + // IDs from the clock: after the file was removed, a new question + // never has the ID of one that the listener still knows. + return &State{Version: 1, NextID: u.now().Unix()}, nil + } + if err != nil { + return nil, fmt.Errorf("read the update state: %w", err) + } + s := &State{} + dec := json.NewDecoder(bytes.NewReader(b)) + dec.DisallowUnknownFields() + err = dec.Decode(s) + if err == nil && s.Version != 1 { + err = fmt.Errorf("version %d, not 1", s.Version) + } + if err != nil { + return nil, fmt.Errorf("the update state %s is broken: %w. Fix: remove it; an open update question then stops working, and /update asks again", u.stateFile(), err) + } + return s, nil +} + +// save writes the state, synced to the disk. +func (u *Updater) save(s *State) error { + // Keep only the releases newer than this version: older ones are done. + for _, m := range []map[string]time.Time{s.Notified, s.Warned} { + for v := range m { + if !newer(v, u.Version) { + delete(m, v) + } + } + } + b, err := json.MarshalIndent(s, "", " ") + if err != nil { + return err + } + return state.WriteFileAtomic(u.stateFile(), append(b, '\n'), 0o600) +} diff --git a/internal/spool/spool.go b/internal/spool/spool.go index 7735887..81d817f 100644 --- a/internal/spool/spool.go +++ b/internal/spool/spool.go @@ -76,6 +76,11 @@ func (d Dirs) Inbox() string { return filepath.Join(d.inst(), "inbox") } // CheckDir is the path of the directory of check requests. func (d Dirs) CheckDir() string { return filepath.Join(d.inst(), "check") } +// SelfName is the spool name of the updates of pullgate itself (DESIGN.md +// section 15): Base/_update/{outbox,inbox,check}. An instance name matches +// [a-z0-9][a-z0-9-]{0,31}, so no instance can have this name. +const SelfName = "_update" + // CheckFile is the one name a check request has in the check directory. const CheckFile = "request" diff --git a/test/units/faketg.py b/test/units/faketg.py index a91acfa..91ef8aa 100644 --- a/test/units/faketg.py +++ b/test/units/faketg.py @@ -12,7 +12,9 @@ - appends the text of each sendMessage to TEXTS, as one JSON string per line, so a test can wait for "Applied" or "Rolled back"; - taps the Apply button of each question it gets, two seconds later, as - the owner (user 4242) in the chat 4242, through getUpdates. + the owner (user 4242) in the chat 4242, through getUpdates; +- on POST /test/say with {"text": "..."}, sends that text as a message of + the owner in the chat, through getUpdates (full-loop.sh sends /update). Usage: python3 -I faketg.py PORT LOG [--tap TEXTS] """ @@ -59,6 +61,24 @@ def do_POST(self): req = json.loads(raw or b"{}") except ValueError: req = {} + if self.path == "/test/say": + with lock: + state["updates"].append({ + "at": time.monotonic(), + "update": { + "update_id": state["next_update"], + "message": { + "message_id": 100000 + state["next_update"], + "from": {"id": OWNER}, + "chat": {"id": CHAT}, + "text": str(req.get("text", "")), + }, + }, + }) + state["next_update"] += 1 + self.send_response(204) + self.end_headers() + return method = self.path.rsplit("/", 1)[-1] with lock: with open(LOG, "a", encoding="utf-8") as f: diff --git a/test/units/first-run.sh b/test/units/first-run.sh index a59d850..20f853f 100644 --- a/test/units/first-run.sh +++ b/test/units/first-run.sh @@ -198,7 +198,7 @@ systemctl disable pullgate-listen.service || err "systemctl disable pullgate-lis # Enable the units as the README says (no --now here). Each must then be # "enabled", not "static": a unit with no [Install] section does not start # after a reboot (issue #20). -for u in pullgate-listen.service "pullgate-apply@$name.path" "pullgate-run@$name.timer" "pullgate-check@$name.path"; do +for u in pullgate-listen.service "pullgate-apply@$name.path" "pullgate-run@$name.timer" "pullgate-check@$name.path" pullgate-update.timer pullgate-update.path; do systemctl enable "$u" || err "systemctl enable $u failed" state="$(systemctl is-enabled "$u" 2>/dev/null || true)" if [ "$state" != enabled ]; then diff --git a/test/units/full-loop.sh b/test/units/full-loop.sh index 7633a1e..d548d4a 100644 --- a/test/units/full-loop.sh +++ b/test/units/full-loop.sh @@ -15,7 +15,11 @@ # 6. It restarts the listener and checks that it comes back. # 7. A commit whose apply fails: the rollback, and its notice reaches the # fake Telegram. -# 8. Every unit the README enables is enabled and active. +# 8. With --update-to: /update from the installed build to a newer one, +# through a fake GitHub (a fake curl and a fake gh): the question, the +# tap, the install with the checks of install.sh, a changed unit put +# back, a drop-in listed, and the report from the new listener. +# 9. Every unit the README enables is enabled and active. # After each loop, every message root wrote must have been read and sent # by the listener: the outbox is empty, and the listener logged no error # and no warning. @@ -24,8 +28,12 @@ # and writes to /etc, /usr/local/lib, /srv and /var. Run it only as root, # on a machine you throw away, such as a CI runner. # -# Usage: sudo sh test/units/full-loop.sh PATH-TO-PULLGATE-BINARY +# Usage: sudo sh test/units/full-loop.sh PATH-TO-PULLGATE-BINARY [--update-to PATH-TO-NEWER-BINARY] # sudo sh test/units/full-loop.sh --installed X.Y.Z +# +# With --update-to, both binaries must have a release version (built with +# -ldflags "-X main.version=X.Y.Z"), the second one newer. Then the script +# moves /usr/bin/curl aside for a fake one, and puts it back at the end. set -eu if [ "$(id -u)" -ne 0 ]; then @@ -33,11 +41,17 @@ if [ "$(id -u)" -ne 0 ]; then exit 1 fi usage() { - echo "usage: full-loop.sh PATH-TO-PULLGATE-BINARY | full-loop.sh --installed X.Y.Z" >&2 + echo "usage: full-loop.sh PATH-TO-PULLGATE-BINARY [--update-to PATH-TO-NEWER-BINARY] | full-loop.sh --installed X.Y.Z" >&2 exit 64 } installed="" binary="" +update_to="" +if [ $# -eq 3 ] && [ "$2" = --update-to ]; then + [ -f "$3" ] || usage + update_to="$(cd "$(dirname "$3")" && pwd)/$(basename "$3")" + set -- "$1" +fi case "${1:-}" in --installed) [ $# -eq 2 ] || usage @@ -270,7 +284,14 @@ tglog="$(mktemp)" texts="$(mktemp)" python3 -I "$here/faketg.py" "$port" "$tglog" --tap "$texts" & tgpid=$! -trap 'kill "$tgpid" 2>/dev/null || true; rm -rf "$work"' EXIT +cleanup() { + kill "$tgpid" 2>/dev/null || true + rm -rf "$work" + if [ -f /usr/bin/curl.full-loop ]; then + mv -f /usr/bin/curl.full-loop /usr/bin/curl + fi +} +trap cleanup EXIT i=0 until python3 -I -c 'import socket, sys; socket.create_connection(("127.0.0.1", int(sys.argv[1])), 1)' "$port" 2>/dev/null; do i=$((i + 1)) @@ -278,6 +299,81 @@ until python3 -I -c 'import socket, sys; socket.create_connection(("127.0.0.1", sleep 0.5 done +if [ -n "$update_to" ]; then + step "3b. A fake GitHub for /update" + old_v="$(pullgate --version | sed 's/^pullgate //')" + new_v="$("$update_to" --version | sed 's/^pullgate //')" + case "$(uname -m)" in + x86_64) arch=amd64 ;; + aarch64) arch=arm64 ;; + *) die "no release for $(uname -m)" ;; + esac + web="$out/web" + # install.sh refuses a bin directory that group or others can write. + # The runner image may have one; fix it, as an owner would. + stat -c '%U %a' /usr/local/bin + chown root:root /usr/local/bin + chmod go-w /usr/local/bin + # fake_release VERSION [BINARY]: the newest release on the fake GitHub. + # With BINARY, also its files, made as the release workflow makes them. + fake_release() { + api="$web/api.github.com/repos/code6x/pullgate/releases" + install -d -m 0755 "$api" + install -d -m 0755 "$api/tags" + printf '{"tag_name": "v%s", "body": "## v%s\\n\\n### Bug Fixes\\n\\n* a fix\\n"}\n' "$1" "$1" >"$api/latest" + cp "$api/latest" "$api/tags/v$1" + [ $# -eq 2 ] || return 0 + dl="$web/github.com/code6x/pullgate/releases/download/v$1" + stage="$(mktemp -d)" + install -d -m 0755 "$dl" + install -m 0755 "$2" "$stage/pullgate" + cp "$top/LICENSE" "$top/README.md" "$stage/" + tar --owner=0 --group=0 --numeric-owner --mode=go-w -C "$stage" -cf - pullgate LICENSE README.md | + gzip -9n >"$dl/pullgate_$1_linux_$arch.tar.gz" + rm -rf "$stage" + (cd "$dl" && sha256sum -- *.tar.gz >SHA256SUMS) + echo '{}' >"$dl/pullgate_$1.sigstore.json" + } + fake_release "$old_v" + # The fake curl serves https://HOST/PATH from $web/HOST/PATH. install.sh + # runs as root with PATH=/usr/sbin:/usr/bin:/sbin:/bin, so it must be + # /usr/bin/curl. The trap puts the real one back. + mv /usr/bin/curl /usr/bin/curl.full-loop + cat >/usr/bin/curl <&2; exit 1 ;; +esac +file="$web/\${url#https://}" +[ -f "\$file" ] || { echo "curl: (22) The requested URL returned error: 404" >&2; exit 22; } +cp "\$file" "\$out" +FAKE + chmod 0755 /usr/bin/curl + # The fake gh: the build under test has no attestation. It writes down + # each call. [updates] gh names it, as install.sh --gh does. + cat >"$lib/gh" <>"$out/gh-calls" +if [ "\$1" = --version ]; then + echo "gh version 2.102.0 (2026-09-30)" +fi +exit 0 +FAKE + chown root:root "$lib/gh" + chmod 0755 "$lib/gh" + printf '\n[updates]\ngh = "%s"\n' "$lib/gh" >>/etc/pullgate/listener.toml +fi + step "4. The README start: enable --now" readme start @@ -328,7 +424,51 @@ pullgate status "$name" listener_read_all "after the rollback" unit_quiet "pullgate-run@$name.service" -step "8. Every unit the README enables" +if [ -n "$update_to" ]; then + step "8. /update from $old_v to $new_v, with its units" + # The timer has a random delay of up to an hour. One run now makes the + # directories of the updates, so the listener can write /update. + systemctl start pullgate-update.service || err "pullgate-update.service failed before the new release" + fake_release "$new_v" "$update_to" + sum="$(cut -d ' ' -f 1 "$web/github.com/code6x/pullgate/releases/download/v$new_v/SHA256SUMS")" + # A unit that differs from the shipped one, and a drop-in. + printf '# changed by full-loop.sh\n' >>/etc/systemd/system/pullgate-run@.timer + install -d -m 0755 /etc/systemd/system/pullgate-listen.service.d + printf '[Service]\nEnvironment=PULLGATE_LOOP=1\n' >/etc/systemd/system/pullgate-listen.service.d/loop.conf + systemctl daemon-reload + python3 -I -c 'import json, sys, urllib.request +urllib.request.urlopen(urllib.request.Request("http://127.0.0.1:%s/test/say" % sys.argv[1], data=json.dumps({"text": sys.argv[2]}).encode(), method="POST"), timeout=5)' "$port" /update + if ! wait_text "pullgate is updated" 300; then + journalctl --no-pager -o cat -u pullgate-update.service -u pullgate-listen.service || true + die "no 'pullgate is updated' report reached the fake Telegram" + fi + grep -F "Update pullgate to" "$texts" | grep -q -F "$sum" || err "the update question does not show the SHA-256 $sum" + got="$(/usr/local/bin/pullgate --version || true)" + [ "$got" = "pullgate $new_v" ] || err "after /update, pullgate --version says '$got', want 'pullgate $new_v'" + cmp -s "$top/contrib/systemd/pullgate-run@.timer" /etc/systemd/system/pullgate-run@.timer || + err "/update did not put back the shipped pullgate-run@.timer" + grep -q -F 'pullgate-run@.timer' "$texts" || err "the report does not list the unit it installed" + grep -q -F 'pullgate-listen.service.d/loop.conf' "$texts" || err "the report does not list the drop-in" + [ -f /etc/systemd/system/pullgate-listen.service.d/loop.conf ] || err "/update removed a drop-in" + [ "$(grep -c '^attestation verify' "$out/gh-calls" || true)" -ge 2 ] || + err "gh attestation verify must run before the question and again on Apply" + [ ! -e /usr/local/bin/.pullgate.prev ] || err "the old binary is still kept after a good update" + i=0 + while [ "$i" -lt 30 ] && [ -n "$(ls -A /var/spool/pullgate/_update/outbox)" ]; do + i=$((i + 1)) + sleep 1 + done + [ -z "$(ls -A /var/spool/pullgate/_update/outbox)" ] || err "the listener did not take every update message from the outbox" + journalctl --sync || true + if journalctl --no-pager -o cat -u pullgate-update.service | grep -E 'level=ERROR'; then + err "pullgate-update.service logged an error (above)" + fi + journalctl --no-pager -o cat -u pullgate-update.service | grep -q 'msg=updated ' || err "pullgate-update.service did not log 'updated'" + systemctl is-active --quiet pullgate-listen.service || err "the listener is not active after /update" + listener_read_all "after /update" +fi + +step "9. Every unit the README enables" units="$(sh "$here/readme-block.sh" start "$top/README.md" | sed -e 's/#.*//' -e "s/NAME/$name/g" | tr -s ' \t' '\n' | grep -E '^pullgate-[A-Za-z0-9@._-]+\.(service|path|timer)$' | sort -u)" n=0