Repository navigation
Labels
enhancementNew feature or requestNew feature or request
Milestone
Description
Why
Today every change to broker.toml needs an admin SSH login to the broker
host, an edit by hand, and a restart. A typo is found only when the broker
fails to start, and then the owner fixes it by hand, again over SSH.
Adding secrets is a common change (for example, two secrets per mail
account). It should not need SSH every time.
Wanted
- Change the broker config without SSH to the broker host.
- The owner confirms each change before it takes effect.
- If the new config does not work, the broker goes back to the previous
one by itself.
Design (2026-11-16): the broker host pulls its config with pullgate; see "Done when".
Related: #29 (reload without a restart).
Done when
Updated 2026-11-16: the broker side is in v0.6.0 (#29, #173, #174), and pullgate (https://github.com/code6x/pullgate) does the pull, the question and the rollback. This issue is now the recipe that ties them together.
-
contrib/pullgate/holds a working example for one pullgate instance: the instance config (mode = "ask",on_failure = "rollback", limits incl.refuse_symlinks,max_files,max_tree_bytes), and the four scripts:check.sh(as the check user): both files present and not symlinks; refuses a change of theknown_hosts/audit_logpaths compared with the live config; thennodkey broker check --files "$PULLGATE_TREE";summary.sh:nodkey broker config-diff --short --max-chars 2000(against the live config on the first apply), and⚠ needs a broker restart: all grants endfirst when a part that a reload refuses changed (one shared helper with an allow-list of reload-safe parts; anything else, or a failed compare, means restart);apply.sh(root): installs both files, thennodkey broker reloadorsystemctl restart nodkeyas the helper says; on a failure puts the old files back and reloads/restarts again; exits non-zero;health.sh: waits for a real answer from the broker with a timeout (not onlysystemctl is-active).
- Tests for the scripts (shellcheck, and a test that runs them against a fake broker: a reload-safe change, a restart-type change, a refused reload, a failed restart).
- docs/setup.md gets a section "Change the config from git with pullgate": the repo layout (
broker.tomlandknown_hostsat the root, no secret values), the install steps, and how the owner reads the question (⚠ lines first; skip a ⚠ line you did not ask for). - THREAT-MODEL.md covers the new way to change the config: who can write the repo, why the gate is the tap on the host and not CI, and that the scripts are installed on the host (never run from the repo tree).
- The
contrib/pullgate/files are release assets of nodkey (listed inSHA256SUMS, covered by the attestation), so a host installs them pinned and checked, never from a config repo's tree; THREAT-MODEL.md says so. - No host names, IPs or private repo names (public repo).
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
groupsky commentedon Nov 11, 2026
Design decided by the owner (2026-11-11). The work is split so nodkey stays small:
nodkey broker check, to check a config without starting.nodkey broker config-diff, a change list by meaning that marks every change that widens access. pullgate shows it in the question.Order: #29, #173 and #174 first, then the docs here, after pullgate's first release.
[-]Change the broker config without SSH, with confirmation and rollback[/-][+]Change the broker config from git without SSH: a pullgate recipe in contrib/[/+]groupsky commentedon Nov 16, 2026
Scope update (2026-11-16). The parts are now there: reload without a restart (#29),
nodkey broker check(#173) andnodkey broker config-diff(#174), in v0.6.0. Together with pullgate (https://github.com/code6x/pullgate, public, Apache-2.0) they do what this issue wants: the broker host pulls its config from a git repo, asks the owner on its own Telegram bot with the change list, applies only after a tap, and rolls back by itself. This setup has been run on a real broker host.What is left here is to make that easy for others: a ready recipe in this repo. See the new "Done when" below.
groupsky commentedon Nov 17, 2026
Done in #204 (squash commit 22f8965). Evidence for each box:
contrib/pullgate/holdsnodkey-broker.toml(mode = "ask",on_failure = "rollback",refuse_symlinks = true,max_files = 20,max_tree_bytes),check.sh,summary.sh,apply.sh,health.sh, andlib.shwith the one rule for reload or restart (an allow-list of reload-safe parts; anything else, or a failed compare, is a restart).summary.shuses--max-chars 1200, not 2000, because pullgate puts the summary last and cuts a long message from the end (HTML escaping makes the text longer).check.shandapply.shalso refuse a change of the gate itself:listen,tls_key,[telegram],[ntfy], a new or changed[store.*], besides theknown_hostsandaudit_logpaths.health.shwaits for the broker's own status file (reload-status.json): the unit's main process,startedorloaded, and the SHA-256 of the livebroker.toml.ci.yml).contrib_pullgate_linux_test.goruns them with/bin/shagainst a fake broker (a fakesystemctlandnodkey broker reload, the realnodkeyfor check and diff):TestPullgateApplyhas a reload-safe change, a restart-type change, a refused reload, a failed restart, a broker that does not run, and a rollback; alsoTestPullgateCheck,TestPullgateSummary,TestPullgateApplyRefusesBadFiles,TestPullgateHealth.release.ymlpackscontrib/pullgate/andLICENSEasnodkey_VERSION_pullgate.tar.gz, inSHA256SUMSand the attestation (subject-path: dist/*.tar.gz);docs/releasing.mdand T52 say so. The first release with it is the next one.example-host,git.example.com,config-repoand192.0.2.0/24.Left: pullgate puts the summary after the commits and the changed files; putting it first would be a change for pullgate. The
test (stable)CI job failed three times on an existing flaky test, filed as #205.