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
feat: nodkey broker check — check a config without starting the broker #173
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).
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.
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).
Activity
groupsky commentedon Nov 11, 2026
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,SameKeyandKeyHost(internal/config/reload.go), and aSumfield (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.groupsky commentedon Nov 11, 2026
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-revieweragent had no open finding at the end.Evidence for each "Done when" box:
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--filesor--credentialsdirectory;--helpexits 0; a missing config exits 1), and the tests below for 0 and 1.nodkey doctor brokeruses 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 newReadBrokerFiles(the check) all call it. The file checks areCheckFilesAs, 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 realnodkey brokerin a child process exits 1, and the check exits 1 with the same reason. A good config passes.--files DIR, aknown_hostsin 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--filespasses. Then a good file at the path and one in DIR without a host that a key needs: the check refuses the config.TestBrokerCheckNeedsNoCredentialsruns 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 findsNAMEandNAME.credfiles 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.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).