From 1a143b2959394ac5c285265ec6e5863a3cebd74b Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:41:55 +0200 Subject: [PATCH 1/3] test: each unit the README enables can be enabled Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 6 +++-- test/units/first-run.sh | 23 ++++++++++++++++++- test/units/install-sections.sh | 40 ++++++++++++++++++++++++++++++++++ 3 files changed, 66 insertions(+), 3 deletions(-) create mode 100644 test/units/install-sections.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d5c94d7..37b4a18 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -81,6 +81,8 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - name: Each unit the README enables has an [Install] section + run: sh test/units/install-sections.sh - name: Check the example scripts and units run: | set -eu @@ -131,7 +133,7 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - name: shellcheck install.sh and test/units/first-run.sh + - name: shellcheck install.sh and test/units/*.sh # A fixed release of ShellCheck, checked by its SHA-256. Dependabot # does not update it. Update it by hand: the version and the SHA-256 # of shellcheck-VERSION.linux.x86_64.tar.xz together. @@ -147,7 +149,7 @@ jobs: echo "${SHELLCHECK_SHA256} $dir/shellcheck.tar.xz" | sha256sum --strict -c - tar -xJf "$dir/shellcheck.tar.xz" -C "$dir" "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --version - "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh test/units/first-run.sh + "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh test/units/first-run.sh test/units/install-sections.sh - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: go-version-file: go.mod diff --git a/test/units/first-run.sh b/test/units/first-run.sh index 78ed1c6..847e655 100644 --- a/test/units/first-run.sh +++ b/test/units/first-run.sh @@ -5,7 +5,8 @@ # `pullgate listen` under the real pullgate-listen.service, with no # drop-in. Then it checks the owners and modes of DESIGN.md section 4, and # that the listener read the outbox and sent the question. So a unit -# setting that breaks a run fails here (issue #19). +# setting that breaks a run fails here (issue #19). At the end it enables +# the units as the README says, and checks that each is enabled (#20). # # It changes the system: it installs /usr/local/bin/pullgate, adds users, # and writes to /etc and /var. Run it only as root, on a machine you throw @@ -176,6 +177,26 @@ if ! systemctl is-active --quiet pullgate-listen.service; then fi systemctl stop pullgate-listen.service +# A host with the workaround of 0.1.0 for issue #20, updated as the README +# says ("Update from 0.1.0"): add-wants, then reenable. +systemctl add-wants multi-user.target pullgate-listen.service || err "systemctl add-wants failed" +systemctl reenable pullgate-listen.service || err "systemctl reenable pullgate-listen.service failed" +if [ ! -L /etc/systemd/system/multi-user.target.wants/pullgate-listen.service ]; then + err "after reenable, multi-user.target does not want pullgate-listen.service" +fi +systemctl disable pullgate-listen.service || err "systemctl disable pullgate-listen.service failed" + +# 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 + systemctl enable "$u" || err "systemctl enable $u failed" + state="$(systemctl is-enabled "$u" 2>/dev/null || true)" + if [ "$state" != enabled ]; then + err "$u: systemctl is-enabled says '$state' after enable, want 'enabled'" + fi +done + if [ "$fail" -ne 0 ]; then exit 1 fi diff --git a/test/units/install-sections.sh b/test/units/install-sections.sh new file mode 100644 index 0000000..6ae31fa --- /dev/null +++ b/test/units/install-sections.sh @@ -0,0 +1,40 @@ +#!/bin/sh +# Each unit that the README tells you to enable must have an [Install] +# section with WantedBy=. Without it, `systemctl enable` does nothing, and +# the unit does not start after a reboot (issue #20). +# +# Usage: sh test/units/install-sections.sh (from the top of the repo) +set -eu + +units="$(grep -E '^[[:space:]]*systemctl enable' README.md \ + | sed -e 's/#.*//' \ + | tr -s ' \t' '\n' \ + | grep -E '^pullgate-[A-Za-z0-9@._-]+\.(service|path|timer|socket)$' \ + | sort -u || true)" +if [ -z "$units" ]; then + echo "FAIL: found no 'systemctl enable' unit in README.md" >&2 + exit 1 +fi + +fail=0 +for u in $units; do + # pullgate-run@NAME.timer is an instance of pullgate-run@.timer. + f="contrib/systemd/$(echo "$u" | sed -E 's/@[^.]+\./@./')" + if [ ! -f "$f" ]; then + echo "FAIL: README.md enables $u, but $f does not exist" >&2 + fail=1 + continue + fi + # The [Install] section and a WantedBy= line in it. + if ! awk ' + /^\[/ { sec = $0; next } + sec == "[Install]" && /^WantedBy=[^[:space:]]/ { ok = 1 } + END { exit ok ? 0 : 1 } + ' "$f"; then + echo "FAIL: $f has no [Install] section with WantedBy=. Fix: add one, so that systemctl enable starts $u at boot" >&2 + fail=1 + continue + fi + echo "ok: $u ($f) has [Install] with WantedBy=" +done +exit "$fail" From 6ea02daf9585cc457f547cb295e8d63ccbd18012 Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:43:37 +0200 Subject: [PATCH 2/3] fix: pullgate-listen.service gets an [Install] section Co-Authored-By: Claude Opus 5.5 --- DESIGN.md | 9 ++++++-- README.md | 29 +++++++++++++++++++++---- contrib/systemd/pullgate-listen.service | 5 +++++ 3 files changed, 37 insertions(+), 6 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 7ac300c..7570676 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -696,8 +696,13 @@ says, with no drop-in. It runs the first `pullgate run` under the real `pullgate-run@.service`, checks the owners and modes of section 4, then runs `pullgate listen` under the real `pullgate-listen.service` against a fake Telegram on `127.0.0.1`, and checks that the listener sent the -question and removed it from the outbox. So a unit setting that breaks a -run or the listener fails CI. +question and removed it from the outbox. At the end it runs +`systemctl enable` on the units the README names, and checks that each is +`enabled`. So a unit setting that breaks a run or the listener, or a unit +that cannot be enabled, fails CI. Without root, CI also runs +`systemd-analyze verify` on every unit, and `test/units/install-sections.sh` +checks that each unit the README tells you to enable has an `[Install]` +section with `WantedBy=`. ## 15. Not in version 0.1 diff --git a/README.md b/README.md index 632f7c8..ce317ef 100644 --- a/README.md +++ b/README.md @@ -245,10 +245,14 @@ not work there. ### Update from 0.1.0 -In 0.1.0 the first `pullgate run` failed under `pullgate-run@.service` -with `chmod .../outbox: operation not permitted` (issue #19). A host may -have a drop-in with `RestrictSUIDSGID=no` for the run unit as a -workaround. Newer versions do not need it. After you update the binary: +To update a host from 0.1.0: update the binary, and copy the units of +`contrib/systemd/` of the new version to `/etc/systemd/system/` again. +Then undo the two workarounds below, if the host has them. + +**The run unit (issue #19).** In 0.1.0 the first `pullgate run` failed +under `pullgate-run@.service` with +`chmod .../outbox: operation not permitted`. A host may have a drop-in +with `RestrictSUIDSGID=no` for the run unit. Newer versions do not need it. 1. Find the drop-in: `systemctl cat pullgate-run@NAME.service` shows each file and its path. It is in `/etc/systemd/system/pullgate-run@.service.d/` @@ -259,6 +263,23 @@ workaround. Newer versions do not need it. After you update the binary: The next run takes the setgid bit off the outbox by itself. +**The listener at boot (issue #20).** In 0.1.0, `pullgate-listen.service` +had no `[Install]` section, so `systemctl enable` did nothing and the +listener did not start after a reboot. A host may have the workaround +`systemctl add-wants multi-user.target pullgate-listen.service`. That made +the same link that `systemctl enable` makes now +(`/etc/systemd/system/multi-user.target.wants/pullgate-listen.service`). +systemd has no `remove-wants`. Run: + +```sh +systemctl daemon-reload +systemctl reenable pullgate-listen.service +systemctl is-enabled pullgate-listen.service # prints: enabled +``` + +`reenable` removes the old link and makes it again from the new +`[Install]` section. + ## Development ```sh diff --git a/contrib/systemd/pullgate-listen.service b/contrib/systemd/pullgate-listen.service index 88ab118..2ac82a7 100644 --- a/contrib/systemd/pullgate-listen.service +++ b/contrib/systemd/pullgate-listen.service @@ -48,3 +48,8 @@ SystemCallFilter=~@privileged @resources SystemCallErrorNumber=EPERM DevicePolicy=closed PrivateIPC=yes + +[Install] +# systemctl enable starts the listener at boot. Without it, no question +# gets an answer after a reboot. +WantedBy=multi-user.target From e3774e56dd0c14ac66b62079920db76743ffd438 Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:45:43 +0200 Subject: [PATCH 3/3] fix: review findings: test the real 0.1.0 update, reenable on every host Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 3 ++- DESIGN.md | 6 ++++-- README.md | 18 +++++++++++------- test/units/first-run.sh | 13 +++++++++++-- test/units/install-sections.sh | 11 ++++++++--- 5 files changed, 36 insertions(+), 15 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 37b4a18..aafae61 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -124,7 +124,8 @@ jobs: # A fresh install with contrib/systemd/ and no drop-in: pullgate run # under pullgate-run@.service, then pullgate listen under # pullgate-listen.service against a fake Telegram. A unit setting - # that breaks a run fails here (issue #19). + # that breaks a run fails here (issue #19). Then it enables the + # units as the README says, and each must be enabled (issue #20). run: sudo sh test/units/first-run.sh "${RUNNER_TEMP}/pullgate" lint: diff --git a/DESIGN.md b/DESIGN.md index 7570676..0afc955 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -697,8 +697,10 @@ says, with no drop-in. It runs the first `pullgate run` under the real runs `pullgate listen` under the real `pullgate-listen.service` against a fake Telegram on `127.0.0.1`, and checks that the listener sent the question and removed it from the outbox. At the end it runs -`systemctl enable` on the units the README names, and checks that each is -`enabled`. So a unit setting that breaks a run or the listener, or a unit +`systemctl enable` on the four units of the README (a list in the +script), and checks that each is `enabled`. It also follows the README's +update from 0.1.0 for the listener: the old unit with `add-wants`, then the +new unit and `reenable`. So a unit setting that breaks a run or the listener, or a unit that cannot be enabled, fails CI. Without root, CI also runs `systemd-analyze verify` on every unit, and `test/units/install-sections.sh` checks that each unit the README tells you to enable has an `[Install]` diff --git a/README.md b/README.md index ce317ef..69a0d42 100644 --- a/README.md +++ b/README.md @@ -247,7 +247,9 @@ not work there. To update a host from 0.1.0: update the binary, and copy the units of `contrib/systemd/` of the new version to `/etc/systemd/system/` again. -Then undo the two workarounds below, if the host has them. +The copy replaces the unit files, so keep your own changes in drop-ins +(`systemctl edit UNIT`); `systemctl cat UNIT` shows them. Then do the two +steps below. **The run unit (issue #19).** In 0.1.0 the first `pullgate run` failed under `pullgate-run@.service` with @@ -265,20 +267,22 @@ The next run takes the setgid bit off the outbox by itself. **The listener at boot (issue #20).** In 0.1.0, `pullgate-listen.service` had no `[Install]` section, so `systemctl enable` did nothing and the -listener did not start after a reboot. A host may have the workaround +listener did not start after a reboot. Every host updated from 0.1.0 must +enable it again. A host may have the workaround `systemctl add-wants multi-user.target pullgate-listen.service`. That made the same link that `systemctl enable` makes now -(`/etc/systemd/system/multi-user.target.wants/pullgate-listen.service`). -systemd has no `remove-wants`. Run: +(`/etc/systemd/system/multi-user.target.wants/pullgate-listen.service`), so +there is nothing to remove first (systemd has no `remove-wants`). With or +without the workaround, run: ```sh systemctl daemon-reload systemctl reenable pullgate-listen.service -systemctl is-enabled pullgate-listen.service # prints: enabled +ls -l /etc/systemd/system/multi-user.target.wants/pullgate-listen.service ``` -`reenable` removes the old link and makes it again from the new -`[Install]` section. +`reenable` removes the old link, if there is one, and makes it again from +the new `[Install]` section. The `ls` shows the link. ## Development diff --git a/test/units/first-run.sh b/test/units/first-run.sh index 847e655..a59d850 100644 --- a/test/units/first-run.sh +++ b/test/units/first-run.sh @@ -177,13 +177,22 @@ if ! systemctl is-active --quiet pullgate-listen.service; then fi systemctl stop pullgate-listen.service -# A host with the workaround of 0.1.0 for issue #20, updated as the README -# says ("Update from 0.1.0"): add-wants, then reenable. +# A host updated from 0.1.0 with its workaround for issue #20, as the +# README says ("Update from 0.1.0"): the old unit (no [Install]) and +# add-wants, then the new unit, daemon-reload and reenable. +sed '/^\[Install\]/,$d' "$top/contrib/systemd/pullgate-listen.service" >/etc/systemd/system/pullgate-listen.service +systemctl daemon-reload systemctl add-wants multi-user.target pullgate-listen.service || err "systemctl add-wants failed" +install -m 0644 -o root -g root "$top/contrib/systemd/pullgate-listen.service" /etc/systemd/system/ +systemctl daemon-reload systemctl reenable pullgate-listen.service || err "systemctl reenable pullgate-listen.service failed" if [ ! -L /etc/systemd/system/multi-user.target.wants/pullgate-listen.service ]; then err "after reenable, multi-user.target does not want pullgate-listen.service" fi +state="$(systemctl is-enabled pullgate-listen.service 2>/dev/null || true)" +if [ "$state" != enabled ]; then + err "after reenable, systemctl is-enabled says '$state', want 'enabled'" +fi systemctl disable pullgate-listen.service || err "systemctl disable pullgate-listen.service failed" # Enable the units as the README says (no --now here). Each must then be diff --git a/test/units/install-sections.sh b/test/units/install-sections.sh index 6ae31fa..f4299a9 100644 --- a/test/units/install-sections.sh +++ b/test/units/install-sections.sh @@ -6,13 +6,18 @@ # Usage: sh test/units/install-sections.sh (from the top of the repo) set -eu -units="$(grep -E '^[[:space:]]*systemctl enable' README.md \ +# Lines joined at a trailing backslash; "sudo" and options before +# "enable" are allowed. +units="$(sed -e ':a' -e '/\\$/N; s/\\\n//; ta' README.md \ + | grep -E '^[[:space:]]*(sudo[[:space:]]+)?systemctl([[:space:]]+--?[A-Za-z-]+)*[[:space:]]+(re)?enable[[:space:]]' \ | sed -e 's/#.*//' \ | tr -s ' \t' '\n' \ | grep -E '^pullgate-[A-Za-z0-9@._-]+\.(service|path|timer|socket)$' \ | sort -u || true)" -if [ -z "$units" ]; then - echo "FAIL: found no 'systemctl enable' unit in README.md" >&2 +# The README enables 4 units today. Fewer means the parsing broke. +n="$(echo "$units" | grep -c . || true)" +if [ "$n" -lt 4 ]; then + echo "FAIL: found $n 'systemctl enable' units in README.md, want at least 4. Fix: check the README, or this script" >&2 exit 1 fi