Skip to content

Change the broker config from git without SSH: a pullgate recipe in contrib/ #102

Closed

Description

@groupsky

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 the known_hosts / audit_log paths compared with the live config; then nodkey 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 end first 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, then nodkey broker reload or systemctl restart nodkey as 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 only systemctl 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.toml and known_hosts at 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 in SHA256SUMS, 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).

Activity

  1. added this to the later milestone on Oct 20, 2026
  2. groupsky commented on Nov 11, 2026

    @groupsky
    ContributorAuthor

    Design decided by the owner (2026-11-11). The work is split so nodkey stays small:

    Order: #29, #173 and #174 first, then the docs here, after pullgate's first release.

  3. changed the title [-]Change the broker config without SSH, with confirmation and rollback[/-] [+]Change the broker config from git without SSH: a pullgate recipe in contrib/[/+] on Nov 16, 2026
  4. groupsky commented on Nov 16, 2026

    @groupsky
    ContributorAuthor

    Scope update (2026-11-16). The parts are now there: reload without a restart (#29), nodkey broker check (#173) and nodkey 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.

  5. groupsky commented on Nov 17, 2026

    @groupsky
    ContributorAuthor

    Done in #204 (squash commit 22f8965). Evidence for each box:

    • contrib/pullgate/ holds nodkey-broker.toml (mode = "ask", on_failure = "rollback", refuse_symlinks = true, max_files = 20, max_tree_bytes), check.sh, summary.sh, apply.sh, health.sh, and lib.sh with the one rule for reload or restart (an allow-list of reload-safe parts; anything else, or a failed compare, is a restart).
      • Changed from the list, after the security review: summary.sh uses --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.sh and apply.sh also refuse a change of the gate itself: listen, tls_key, [telegram], [ntfy], a new or changed [store.*], besides the known_hosts and audit_log paths. health.sh waits for the broker's own status file (reload-status.json): the unit's main process, started or loaded, and the SHA-256 of the live broker.toml.
    • Tests: CI runs shellcheck on the scripts (ci.yml). contrib_pullgate_linux_test.go runs them with /bin/sh against a fake broker (a fake systemctl and nodkey broker reload, the real nodkey for check and diff): TestPullgateApply has a reload-safe change, a restart-type change, a refused reload, a failed restart, a broker that does not run, and a rollback; also TestPullgateCheck, TestPullgateSummary, TestPullgateApplyRefusesBadFiles, TestPullgateHealth.
    • docs/setup.md section 10, "Change the config from git with pullgate": the repo layout, what stays a step on the host, the install steps, and "Read the question" (⚠ lines first; tap Skip on a ⚠ line you did not ask for, or when the summary is cut).
    • THREAT-MODEL.md T52: who can write the repo, the gate is the tap on the host and not CI, the scripts are installed from the release and never run from the repo tree, and the cut summary as a risk that remains.
    • Release assets: release.yml packs contrib/pullgate/ and LICENSE as nodkey_VERSION_pullgate.tar.gz, in SHA256SUMS and the attestation (subject-path: dist/*.tar.gz); docs/releasing.md and T52 say so. The first release with it is the next one.
    • No host names, IPs or private repo names: only example-host, git.example.com, config-repo and 192.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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions