You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit aae5203
Browse filesBrowse the repository at this point in the historyBrowse files
feat: update pullgate from Telegram: a notice for each new release, /update installs it with its units
pullgate update (root, pullgate-update.timer and pullgate-update.path)
looks for a new release with the copy of install.sh built into the
binary. It sends one notice per new release that passed the SHA-256 and
attestation checks (a security release says so and repeats daily), and
a warning for a release that failed them. /update asks with the version,
the SHA-256 and the release link. Apply installs only that tarball, with
every check again, then the units the new binary carries, reloads,
re-enables and restarts them, restarts the listener last, and rolls
back when the listener does not stay active.
Fixes#9
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|`apply`, `health`| root |`pullgate apply`| what the owner's command needs |
80
82
|`pullgate status NAME`| root | the owner | nothing |
83
+
|`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) |
81
84
82
85
Root and the listener never talk directly. They use a spool directory
83
86
(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.
110
113
|`/var/spool/pullgate/NAME/inbox`| listener, 0700 | approvals from the listener to root |
111
114
|`/var/spool/pullgate/NAME/check`| listener, 0700 | check requests from the listener to root |
112
115
|`/var/lib/pullgate-listener/state.json`| listener, 0600 | the listener's open questions |
116
+
|`/var/lib/pullgate/_update/` and `.../tmp/`| root, 0700 | the state, the lock and the downloads of `pullgate update` (section 15) |
117
+
|`/var/spool/pullgate/_update/`| as `NAME/` above | the outbox, inbox and check request of the updates |
118
+
|`/usr/local/bin/.pullgate.prev`| root | the old binary during an update (a hard link) |
113
119
114
120
The paths can be changed with `--config-dir`, `--state-dir` and
115
121
`--spool-dir`, for tests.
@@ -490,7 +496,7 @@ usage text, which lists the instances and never repeats the message.
490
496
491
497
**`/help`.** When the text is exactly `/help`, from `owner_id`, in
492
498
`chat_id`, not edited, the listener replies with a fixed list: the
493
-
commands (`/check`, `/check NAME`, `/help`), the instance names from
499
+
commands (`/check`, `/check NAME`, `/update`, `/help`), the instance names from
494
500
`instances`, what Apply and Skip do, and the root commands for the host
495
501
(`pullgate status NAME`, `--pause`, `--resume`, `--ask-again`), at most
496
502
once per minute. The
@@ -752,6 +758,17 @@ that cannot be enabled, fails CI. Without root, CI also runs
752
758
checks that each unit the README tells you to enable has an `[Install]`
753
759
section with `WantedBy=`.
754
760
761
+
`internal/selfupdate` tests `pullgate update` with the real built-in
762
+
`install.sh` against a fake release (a fake `curl`, `gh` and `uname`, and
763
+
fake binaries): the question, the install, a wrong SHA-256, a failed
764
+
attestation, a wrong version (each before the question and on Apply), a
765
+
tarball that changed after the question, an older version, a newer release
766
+
while a question is open, Skip, an expired question, a listener that does
767
+
not start (rollback), a crash at each step, the daily notice (once, again
768
+
each day for a security release, off with `check = false`), and the unit
769
+
update (a changed unit, a new unit, a masked unit, a disabled unit, a
770
+
drop-in).
771
+
755
772
`test/units/full-loop.sh` (CI job `install-loop`, on each pull request
756
773
and on `main`) is the path a user takes, as root on the throwaway runner:
757
774
@@ -775,7 +792,14 @@ and on `main`) is the path a user takes, as root on the throwaway runner:
775
792
4. It restarts the listener and checks that it polls again.
776
793
5. A commit whose apply fails: the rollback runs, and its notice reaches
777
794
the fake Telegram.
778
-
6. Each unit of the README `start` block is `enabled` and `active`.
795
+
6. With `--update-to` (the CI job builds this commit twice, as 900.0.0
796
+
and 900.0.1): a fake GitHub (a fake `/usr/bin/curl` that serves local
797
+
files, and a fake gh in `[updates] gh`, because the build under test has
798
+
no attestation), a changed unit and a drop-in, then `/update` on the
799
+
fake Telegram. The fake taps Apply; root installs 900.0.1 with the
800
+
built-in `install.sh`, puts back the shipped unit, lists the drop-in,
801
+
restarts the listener, and the new listener sends the report.
802
+
7. Each unit of the README `start` block is `enabled` and `active`.
779
803
780
804
After each loop, the outbox must be empty and the listener must have
781
805
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
788
812
The Release workflow calls it after it publishes; it also runs on
789
813
`release: published` and by hand.
790
814
791
-
## 15. Not in version 0.1
815
+
## 15. Updates of pullgate itself (`/update`)
816
+
817
+
The owner updates pullgate from Telegram. It is the same gate as for a
818
+
commit: one question that names one exact release, and a tap. What it
819
+
trusts: THREAT-MODEL.md, T20.
820
+
821
+
**The parts.**`pullgate update` runs as root, from
822
+
`pullgate-update.service`. Two units start it: `pullgate-update.timer`
823
+
(once a day) and `pullgate-update.path` (the check request or an approval
824
+
of the updates). It reads `/etc/pullgate/listener.toml` (it needs no
825
+
token), and uses its own state and spool, named `_update`
826
+
(`/var/lib/pullgate/_update/`, `/var/spool/pullgate/_update/`). An instance
827
+
name cannot start with `_`, so no instance can use them. The binary carries
828
+
two things of its own version: a copy of `install.sh` (section 16), and the
829
+
units of `contrib/systemd/` (`pullgate units` prints them as JSON, with the
830
+
list of units that the README enables).
831
+
832
+
**The listener** handles `/update` as `/check`: only exactly `/update`,
833
+
from `owner_id`, in `chat_id`, not edited. It writes the check request
834
+
`_update/check/request` (the six bytes `check\n`, nothing from the
835
+
message), at most one in 10 seconds, and replies "Looking for a new release
836
+
of pullgate…". A tap on an update question writes an approval to
837
+
`_update/inbox`, as for an instance (section 9). It sends what root puts
838
+
in `_update/outbox`.
839
+
840
+
**Looking for a release.** Root runs the built-in `install.sh
841
+
--check-only` with `TMPDIR=/var/lib/pullgate/_update/tmp`. The script does
842
+
the checks of section 16 on the newest release (the SHA-256 and the
843
+
attestation; it does not run the new binary before the tap), installs
844
+
nothing, and
845
+
prints lines that start with `@pullgate ` for root: `version X.Y.Z
0 commit comments