Skip to content

feat: nodkey broker check — check a config without starting the broker #173

Closed

Description

@groupsky

Why

A tool that changes the broker config from git must check a new config
before it is applied (#102). Today there are two checks, and neither
fits:

  • a start of the broker. A bad config is found only when the broker
    fails to start;
  • nodkey doctor broker --config FILE. It loads the config without
    starting, but it runs as root and also checks the live host: the unit,
    the credentials, swap, the service. It also reads the files that the
    config names at their absolute paths, so a new config is checked with
    the old known_hosts.

This issue takes the config part of doctor broker into its own command.

Wanted

nodkey broker check --config FILE [--files DIR]:

  • runs every check that a start runs, on the given file and the files it
    names (known_hosts and others), then exits; it starts nothing and
    opens no port;
  • with --files DIR, reads the files that the config names (such as
    /etc/nodkey/known_hosts) from DIR, by base name, instead of their
    absolute paths. So a new config is checked with its own new files, also
    in CI, where /etc/nodkey/ does not exist;
  • prints each problem in plain words, and exits 0 when the config is good,
    1 when it is not, and 64 on wrong usage (as nodkey doctor does);
  • runs as an unprivileged user with no access to the credentials.
    A check that needs a credential (a ${CREDENTIALS_DIRECTORY}/ path)
    says "skipped: needs the credential". With --credentials DIR, it
    checks only that a file with that name exists in DIR.

Done when

  • The command exists, with the exit codes above.
  • It runs the same check code as a start (one code path, not a copy).
    A test proves that a config the start refuses is also refused by
    the check. nodkey doctor broker uses the same code for its config
    part.
  • With --files DIR, a known_hosts in DIR is used, and the one at
    the absolute path is not read. A test.
  • It does not need root, the credentials, or the network. Tests.
  • docs/setup.md section 7 shows it.

Related: #102 (config changes without SSH), #29 (reload without a
restart), and #174 (config-diff).

Activity

  1. groupsky commented on Nov 11, 2026

    @groupsky
    ContributorAuthor

    Not started yet. The job run on 2026-11-11 built #29 first (merged in #175), and the budget of that run was not enough for this issue too. Nothing is done here yet; everything in "Done when" is still open.

    Note for this work: #175 added config.Broker.ReloadFixed, SameClient, SameSecret, SameKey and KeyHost (internal/config/reload.go), and a Sum field (the SHA-256 of the config file). They may help here, so the check and the diff can share the config code with the start and the reload.

  2. groupsky commented on Nov 11, 2026

    @groupsky
    ContributorAuthor

    Done in #178, squash merged as 0abb4a2. CI was green (tests on go.mod and stable Go, lint, vuln, end-to-end test, title check). The security-reviewer agent had no open finding at the end.

    Evidence for each "Done when" box:

    • The command exists, with the exit codes above.
      nodkey broker check [--config FILE] [--files DIR] [--credentials DIR] (cmd/nodkey/brokercheck.go). Exit 0 when the config is good, 1 with one line that says why, 64 on wrong usage. Tests: TestBrokerCheckUsage (64 for a wrong flag, an extra argument, a missing --files or --credentials directory; --help exits 0; a missing config exits 1), and the tests below for 0 and 1.
    • It runs the same check code as a start. A test proves that a config the start refuses is also refused by the check. nodkey doctor broker uses the same code for its config part.
      The parser is config.loadBroker, now with a files directory; LoadBroker (start and reload), ReadBroker (nodkey doctor broker) and the new ReadBrokerFiles (the check) all call it. The file checks are CheckFilesAs, used by the start, doctor and the check; its list of private files is now one function, PrivateFiles. TestBrokerCheckRefusesWhatTheStartRefuses: for 5 bad configs (a bad pin, a host that known_hosts does not have, a store program that others can change, a known_hosts that others can change, an audit log that is another file of the broker), the real nodkey broker in a child process exits 1, and the check exits 1 with the same reason. A good config passes.
    • With --files DIR, a known_hosts in DIR is used, and the one at the absolute path is not read. A test.
      TestBrokerCheckFiles: the known_hosts at the config's path is removed, and the check with --files passes. Then a good file at the path and one in DIR without a host that a key needs: the check refuses the config.
    • It does not need root, the credentials, or the network. Tests.
      TestBrokerCheckNeedsNoCredentials runs as a user that is not root, while the test holds the listen address (a start would fail there). Without --credentials, each credential is "skipped: needs the credential". With --credentials DIR, it finds NAME and NAME.cred files with mode 0, so it does not read them. It refuses a missing credential, a directory in place of one, a directory that it cannot enter (with its own error), and a path with ... The command has no network code. TestBrokerCheckCleansConfigText: text from a config (such as a line break in a path) cannot add lines to the output, for configs from pull requests in CI.
    • docs/setup.md section 7 shows it.
      New part "Check a config before you use it" in section 7, and a link from "Change the config without a restart" in section 10. DESIGN.md section 15 and THREAT-MODEL.md (after T42) describe it too.

    What it cannot find: problems that only the content of a credential shows, such as a key file that does not parse. The start and a reload still check these.

    Follow-up: #179 (the start accepts a credential path with ..; the check refuses it).

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

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions