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