From 03da2b6d314a13476951709a1ab2e2b10194e155 Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Wed, 18 Nov 2026 17:58:59 +0200 Subject: [PATCH] feat: an Ansible role that installs nodkey from a checked release contrib/ansible holds a role (broker or agent side), two fixed playbooks for a data file, check-data and build.sh. The first install runs the install.sh of the tag after a check of its pinned SHA-256; an update runs only "nodkey update --version X" of the installed binary, forward only. The release packs the recipe as nodkey_VERSION_ansible.tar.gz, in SHA256SUMS and covered by the attestation. CI runs ansible-lint and the role in a Debian container with systemd. Fixes #193 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 45 +++- .github/workflows/release.yml | 9 + AGENTS.md | 8 + DESIGN.md | 69 ++++- THREAT-MODEL.md | 66 +++++ contrib/ansible/README.md | 213 +++++++++++++++ contrib/ansible/build.sh | 64 +++++ contrib/ansible/check-data | 196 ++++++++++++++ contrib/ansible/playbooks/agent-host.yml | 97 +++++++ contrib/ansible/playbooks/broker-host.yml | 96 +++++++ .../ansible/roles/nodkey/defaults/main.yml | 30 +++ .../ansible/roles/nodkey/handlers/main.yml | 73 +++++ contrib/ansible/roles/nodkey/meta/main.yml | 14 + contrib/ansible/roles/nodkey/tasks/agent.yml | 107 ++++++++ contrib/ansible/roles/nodkey/tasks/broker.yml | 92 +++++++ .../ansible/roles/nodkey/tasks/installed.yml | 73 +++++ contrib/ansible/roles/nodkey/tasks/main.yml | 249 +++++++++++++++++ .../roles/nodkey/tasks/restart-due.yml | 19 ++ .../templates/nodkey-ssh-agent.service.j2 | 16 ++ contrib/ansible/test/Dockerfile | 15 ++ contrib/ansible/test/ci.sh | 253 ++++++++++++++++++ contrib_ansible_linux_test.go | 236 ++++++++++++++++ docs/releasing.md | 8 +- docs/setup.md | 24 +- 24 files changed, 2064 insertions(+), 8 deletions(-) create mode 100644 contrib/ansible/README.md create mode 100755 contrib/ansible/build.sh create mode 100755 contrib/ansible/check-data create mode 100644 contrib/ansible/playbooks/agent-host.yml create mode 100644 contrib/ansible/playbooks/broker-host.yml create mode 100644 contrib/ansible/roles/nodkey/defaults/main.yml create mode 100644 contrib/ansible/roles/nodkey/handlers/main.yml create mode 100644 contrib/ansible/roles/nodkey/meta/main.yml create mode 100644 contrib/ansible/roles/nodkey/tasks/agent.yml create mode 100644 contrib/ansible/roles/nodkey/tasks/broker.yml create mode 100644 contrib/ansible/roles/nodkey/tasks/installed.yml create mode 100644 contrib/ansible/roles/nodkey/tasks/main.yml create mode 100644 contrib/ansible/roles/nodkey/tasks/restart-due.yml create mode 100644 contrib/ansible/roles/nodkey/templates/nodkey-ssh-agent.service.j2 create mode 100644 contrib/ansible/test/Dockerfile create mode 100755 contrib/ansible/test/ci.sh create mode 100644 contrib_ansible_linux_test.go diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3f1fe2b..57e6a32 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,14 +35,15 @@ jobs: with: go-version-file: ${{ matrix.go == 'go.mod' && 'go.mod' || '' }} go-version: ${{ matrix.go == 'stable' && 'stable' || '' }} - - name: Install ssh and sshd for the SSH tests - # The tests of internal/sshauth run the real ssh and sshd. GitHub + - name: Install ssh and sshd for the SSH tests, and PyYAML + # The tests of internal/sshauth run the real ssh and sshd, and the + # tests of contrib/ansible/check-data need PyYAML. GitHub # sets CI=true, and then these tests fail instead of skip when a # program is missing. if: runner.os == 'Linux' run: | sudo apt-get update - sudo apt-get install --yes --no-install-recommends openssh-client openssh-server + sudo apt-get install --yes --no-install-recommends openssh-client openssh-server python3-yaml # The package starts the system ssh service; the tests run their # own sshd, so stop it and keep port 22 closed. sudo systemctl disable --now ssh.socket ssh.service || true @@ -63,7 +64,7 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - name: shellcheck install.sh and contrib/pullgate + - name: shellcheck install.sh, contrib/pullgate and contrib/ansible # 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. @@ -83,6 +84,7 @@ jobs: # The scripts of the pullgate recipe source lib.sh from their own # directory. (cd contrib/pullgate && "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh -x -- *.sh) + "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh contrib/ansible/build.sh contrib/ansible/test/ci.sh - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: go-version-file: go.mod @@ -121,6 +123,41 @@ jobs: # and image that it makes. It fails if one is left. run: go test -race -tags e2e ./test/e2e/... + ansible: + name: ansible role + runs-on: ubuntu-latest + timeout-minutes: 30 + env: + # Two releases with a Sigstore bundle: the test installs OLD, updates + # it to NEW, and installs NEW. Update both by hand after a release. + ANSIBLE_TEST_OLD: 0.6.0 + ANSIBLE_TEST_NEW: 0.7.0 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + # The test takes install.sh and the unit from the tags. + fetch-depth: 0 + - name: Install ansible-lint + # Fixed versions. Dependabot does not update them. Update them by + # hand, both together. + run: | + set -euo pipefail + python3 -m venv "${RUNNER_TEMP}/ansible" + "${RUNNER_TEMP}/ansible/bin/pip" install --quiet ansible-core==2.21.6 ansible-lint==26.11.0 + - name: ansible-lint + working-directory: contrib/ansible + run: | + set -euo pipefail + export PATH="${RUNNER_TEMP}/ansible/bin:$PATH" + ansible-lint --version + ansible-lint --strict --profile production . + - name: The role in a Debian container with systemd + # contrib/ansible/test/ci.sh: both sides, a second run with no + # change, the unit of the tag, a wrong SHA-256, an older and a + # newer version. It removes the containers and the image. + run: sh contrib/ansible/test/ci.sh "$ANSIBLE_TEST_OLD" "$ANSIBLE_TEST_NEW" + vuln: runs-on: ubuntu-latest steps: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b5510e3..2980e3d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -107,6 +107,15 @@ jobs: # LC_ALL=C: the same order of the names on every runner. (cd "$stage" && export LC_ALL=C && tar --owner=0 --group=0 --numeric-owner --mode=go-w --mtime="$mtime" \ -cf - -- *) | gzip -9n > "dist/${name}.tar.gz" + # The Ansible recipe (contrib/ansible): the role, the playbooks + # and check-data. build.sh puts the install.sh and the unit of + # this tag into the role, and pins their SHA-256 in it. A host + # installs it from here, checked as the binaries are. + name="nodkey_${VERSION}_ansible" + stage="${RUNNER_TEMP}/${name}" + sh contrib/ansible/build.sh "$VERSION" . "$stage" + (cd "$stage" && export LC_ALL=C && tar --sort=name --owner=0 --group=0 --numeric-owner --mode=go-w --mtime="$mtime" \ + -cf - -- *) | gzip -9n > "dist/${name}.tar.gz" cd dist sha256sum -- *.tar.gz > SHA256SUMS cat SHA256SUMS diff --git a/AGENTS.md b/AGENTS.md index 822a6e3..408cf22 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,6 +66,14 @@ Planned. Each v1 issue adds its part. "Change the config from git with pullgate"; THREAT-MODEL.md T52). Its tests are in `contrib_pullgate_linux_test.go`, at the root of the module. The release packs it as `nodkey_VERSION_pullgate.tar.gz`. +- `contrib/ansible/` - the Ansible recipe: the role `roles/nodkey` (broker + or agent side), the playbooks `broker-host.yml` and `agent-host.yml` + for a data file, `check-data`, and `build.sh`, which makes the recipe + of a release with the `install.sh` and the unit of the tag (DESIGN.md + section 18, THREAT-MODEL.md T53). Its tests are in + `contrib_ansible_linux_test.go`, at the root of the module, and + `contrib/ansible/test/ci.sh`, which runs the role in a container with + systemd. The release packs it as `nodkey_VERSION_ansible.tar.gz`. - `contrib/systemd/` - the example systemd unit of the broker, with encrypted credentials and a sandbox (DESIGN.md section 16). - `docs/` - the guides for people: diff --git a/DESIGN.md b/DESIGN.md index a381f85..c8dbc69 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -4609,8 +4609,9 @@ Infisical SDK in the broker (section 4, `internal/store/infisical.go`): version and creates the GitHub Release. A job then builds static Linux binaries (`CGO_ENABLED=0`, amd64 and arm64, `-trimpath`), the tarball of the pullgate recipe (`nodkey__pullgate.tar.gz`: the files - of `contrib/pullgate/` and `LICENSE`), a `SHA256SUMS` file of all - tarballs, and a build provenance attestation of all of them. The + of `contrib/pullgate/` and `LICENSE`), the tarball of the Ansible + recipe (`nodkey__ansible.tar.gz`, below), a `SHA256SUMS` file + of all tarballs, and a build provenance attestation of all of them. The attestation is also a file of the release (`nodkey_.sigstore.json`), so it can be checked with no GitHub login. @@ -4643,6 +4644,70 @@ Infisical SDK in the broker (section 4, `internal/store/infisical.go`): tests (`contrib_pullgate_linux_test.go`) run the scripts with `/bin/sh` against a fake `systemctl` and a fake `nodkey broker reload`, with the real `nodkey` for the check and the diff. CI runs shellcheck on them. +- The Ansible recipe (`contrib/ansible/`, issue #193) installs nodkey + on the broker host or an agent machine (THREAT-MODEL.md T53). It is a + plain role, `contrib/ansible/roles/nodkey`, not an Ansible collection: + a host uses it from a checked release file by its path, with no Galaxy + and no second place to publish. Two fixed playbooks + (`playbooks/broker-host.yml`, `playbooks/agent-host.yml`) run it from + one data file, and `check-data` checks that file. `build.sh` makes the + recipe of one release: it copies `install.sh` and + `contrib/systemd/nodkey.service` of the tag into the role, and writes + their SHA-256 and the version into `roles/nodkey/vars/main.yml`. The + release packs it as `nodkey__ansible.tar.gz`. The source in + the repository has none of these files, and refuses to run. The rules: + - The role of release X installs only nodkey X, with the `install.sh` + and the unit of the tag vX. `nodkey_version` must be X. + - Before any change, the role checks the SHA-256 of its `install.sh` + and its unit against the pins, and the SHA-256 of `install.sh` again + after the copy to the host. Before it runs the installed nodkey + (`tasks/installed.yml`, also run by the playbooks), it checks that the + file is a plain file and no link, and that only root can change it + and `/`, `/usr`, `/usr/local` and `/usr/local/bin`. + - The first install runs that `install.sh` with `--version X`: the + checks of the SHA-256 in `SHA256SUMS`, of the attestation and of the + version. An update runs only `nodkey update --version X` of the + installed binary, so the checks come from the checked nodkey on the + host, never from the role. Forward only: the role refuses a version + older than the installed one, and an installed nodkey that is not a + release. Then `nodkey version` must print X. + - Broker side: the user and group `nodkey`, `/etc/nodkey` (root, + `0755`), `/etc/nodkey/credentials` (root, `0700`, left empty) and the + unit of the tag, unchanged, in `/etc/systemd/system/nodkey.service`. + It never writes `broker.toml`, `known_hosts`, a drop-in or a + credential. With `nodkey_broker_config`, it runs + `nodkey broker check --config` as the user `nodkey`. A changed binary + or unit writes the mark `/var/lib/nodkey-ansible/restart-due` at once, + and a handler at the end of the play runs `systemctl daemon-reload` + and `systemctl try-restart nodkey` (only a `daemon-reload` and a + message when `nodkey_restart` is false), then removes the mark. A run + that finds the mark does the restart, so a play that failed after an + update does not leave it undone. It never enables or starts the + broker. A unit that differs is kept as a backup file. + - Agent side, with `nodkey_ssh_agent_user`: the user unit + `/etc/systemd/user/nodkey-ssh-agent.service` with `ConditionUser=`, + enabled for all accounts by a link in + `/etc/systemd/user/default.target.wants`, and linger for the + account. The role never writes into a home directory, which the + agent can change (a link there would turn a write as root into a + write anywhere). With no account, it removes the unit and its link. + - The playbooks take the path of the data file + (`-e nodkey_data_file=PATH`), copy it to a private temporary + directory, run `check-data` on the copy, and only then read the same + copy into one variable with `include_vars name:`. So no key of the + file becomes a variable of its own, which could change a pin of the + role. `check-data` accepts only the keys of the side, each with its + type, refuses a key that is there twice, and a version older than + the installed one (`--installed`, which is required; it never runs + nodkey). A text value may hold only the characters of a path or an + account name, so no value is an Ansible template, and a config path + must be in `/etc/nodkey/`. It prints no value of the file, and a key + name only if it is plain. The role needs ansible-core 2.19 or newer. + - Its tests: `contrib_ansible_linux_test.go` tests `check-data` and + `build.sh`; `contrib/ansible/test/ci.sh`, in the CI job `ansible`, + runs both sides in a Debian stable container with systemd, against + two real releases. CI runs `ansible-lint` with the `production` + profile on it. - `install.sh`, at the root of the repository, installs a release on the host itself, as root: the broker host or an agent machine. It needs `sh`, `curl`, `tar`, `gzip`, `sha256sum`, `install`, `mktemp`, `stat` diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index baf2bdf..b2387c7 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -1827,6 +1827,72 @@ What nodkey does not do: - The git host is one more outbound connection of the broker host. Risk that remains: low, when the owner reads every `⚠` line. +**T53. The Ansible role installs a changed nodkey or unit, as root.** +The role in `contrib/ansible/` (DESIGN.md section 18) runs as root on +the broker host or an agent machine, and downloads a release. The new +parties: the copy of the role on the machine that runs Ansible, and, +with the playbooks, the data file of the host and who can write it. +What nodkey does: +- **The same checks as `install.sh`, and no way to skip them.** The + first install runs the `install.sh` of the tag, which checks the + SHA-256 in `SHA256SUMS`, the attestation with `gh attestation verify` + and the version of the new binary (T20). An update runs only + `nodkey update --version X` of the installed nodkey, so its checks + come from the checked binary on the host, not from the role, a play or + a repo. The role has no setting to skip the attestation or any other + check. +- **The role comes checked, from the release.** The release file + `nodkey_VERSION_ansible.tar.gz` holds the role, the playbooks and + `check-data`, with the `install.sh` and the unit of the tag in the + role, and their SHA-256 pinned in `roles/nodkey/vars/main.yml`. It is + in `SHA256SUMS` and covered by the build attestation of the release, + as the binaries are. The guide (`contrib/ansible/README.md`) checks it + with both, and unpacks it into a directory that only root can change. + The role checks the pinned SHA-256 of its `install.sh` and unit before + any change, and the source in the repository refuses to run. +- **It runs no file that someone else can change.** Before it runs the + installed `/usr/local/bin/nodkey` as root, the role and the playbooks + check that it is a plain file, no link, and that only root can change + it and each directory above it, as `install.sh` does. On an agent + machine, the agent may be able to change such a file. +- **Forward only.** The role refuses a version older than the installed + one, so a change of the version cannot take a host back to an older + release with a known bug. It installs only the version of its own + release, with the unit of the same tag. +- **The data file is only data.** The playbooks copy the file to a + private directory, run `check-data` on the copy, and read the same + copy with `include_vars name:` into one variable: only known keys, + each with its type. A key of the file cannot set a pin or another + setting of the role. Ansible renders a text value with `{{` as a + template; `check-data` allows only the characters of a path or an + account name, so no value of the file is a template. A config path of + the file must be in `/etc/nodkey/`, so a failed check shows no line of + a file elsewhere. Keep no secret in `/etc/nodkey/` that the user + `nodkey` can read: the credentials are in `credentials/`, which only + root can enter. The role writes no + `broker.toml`, no drop-in and no credential; the credential directory + stays an empty slot (`0700`, root). +- On an agent machine, the role writes no file in the home directory of + the account, which the agent controls: a link there would turn a + write as root into a write anywhere. +What nodkey does not do: +- It cannot protect a role that is run from a place that someone else + can change: then that person can change any task, which runs as root. + Run it only from the checked release file, from a directory that only + root can change. +- Who can write the data file can only confirm the version of the + recipe that is installed on the host, turn the restart on or off, + and, on an agent machine, choose the account of the user unit. Who + installs a newer recipe on the host chooses the release. A restart + ends all grants. Nobody can choose an older release or a file that is + not checked through the data file. +- A version that the role pins was checked only by its build; a bad + release is a bad release (T20). +- When a play fails after an update, the old binary may still run until + the next run that passes: the mark `/var/lib/nodkey-ansible/restart-due` + makes that run restart it. +Risk that remains: low, when the role comes from a checked release file. + ## 7. Assumptions - The broker host is patched, has no agent on it, and only the owner has diff --git a/contrib/ansible/README.md b/contrib/ansible/README.md new file mode 100644 index 0000000..18aed25 --- /dev/null +++ b/contrib/ansible/README.md @@ -0,0 +1,213 @@ +# The Ansible recipe of nodkey + +An Ansible role that installs nodkey on the broker host or on an agent +machine, as [docs/setup.md](../../docs/setup.md) says, with the same +checks as `install.sh`. Two fixed playbooks run it from a data file, for +a host that keeps only data in its repository. Why it works this way: +[DESIGN.md section 18](../../DESIGN.md#18-build-ci-and-releases) and +[THREAT-MODEL.md T53](../../THREAT-MODEL.md). + +- `roles/nodkey/`: the role. +- `playbooks/broker-host.yml`, `playbooks/agent-host.yml`: the playbooks + for a data file. +- `check-data`: checks a data file. +- `build.sh`: makes the recipe of one release. The release workflow runs + it. + +## What the role does + +Both sides (`nodkey_side`): + +- The first time, it runs the `install.sh` of the tag of + `nodkey_version`. The role holds that file, and checks its SHA-256 + before it does anything. `install.sh` checks the SHA-256 of the + release in `SHA256SUMS`, its build attestation with + `gh attestation verify`, and the version of the new binary. If a check + fails, nothing is installed. +- When nodkey is installed already, it updates it only with the + installed binary: `nodkey update --version X.Y.Z`. That runs the + installer that is built into the installed, checked nodkey, with the + same checks. The role brings no check of its own for an update. +- Before it runs the installed `/usr/local/bin/nodkey`, it checks that + only root can change it and each directory above it, and that it is no + link, as `install.sh` does. +- **Forward only.** It refuses a version older than the installed one. + It also refuses an installed nodkey that is not a release, such as a + build from the source. +- After the install or the update, it checks that `nodkey version` prints + the version. + +`nodkey_side: broker` also makes: + +- the system user and group `nodkey`, with the home `/var/lib/nodkey` + and the shell `/usr/sbin/nologin` (setup.md section 3); +- `/etc/nodkey` (root, `0755`) and `/etc/nodkey/credentials` (root, + `0700`), an empty slot for the credentials; +- `/etc/systemd/system/nodkey.service`: `contrib/systemd/nodkey.service` + of the same tag, unchanged. + +It never writes `broker.toml`, `known_hosts` or a credential. Fit the +unit to the host with a drop-in, such as +`/etc/systemd/system/nodkey.service.d/local.conf`. The role never changes +that directory. For example, to load only two credentials: + +```ini +[Service] +LoadCredentialEncrypted= +LoadCredentialEncrypted=broker-tls-key:/etc/nodkey/credentials/broker-tls-key.cred +LoadCredentialEncrypted=telegram-token:/etc/nodkey/credentials/telegram-token.cred +``` + +The empty line removes the lines of the unit. The role does not enable or +start the broker: do that once by hand, after the setup of setup.md +sections 4 to 10. After a change of the binary or the unit, it restarts +the broker only if it runs (`systemctl try-restart`). The restart ends +all grants; `nodkey_restart: false` turns it off. + +The restart is a handler at the end of the play, so a failed task, such +as a failed config check, restarts nothing. The role writes the mark +`/var/lib/nodkey-ansible/restart-due` as soon as the binary or the unit +changed, and removes it after the restart. So the next run that passes +does a restart that a failed run left due. + +A broker that you set up by hand may have changes in +`/etc/systemd/system/nodkey.service`. Before the first run, move them to +a drop-in, and look at `--check --diff`. The role keeps the old unit as +a backup file next to it. + +`nodkey_side: agent` with `nodkey_ssh_agent_user` also runs +`nodkey ssh-agent` as a user unit of that account (setup.md section 11). +The unit is `/etc/systemd/user/nodkey-ssh-agent.service`, owned by root, +with `ConditionUser=` set to the account, and enabled as with +`systemctl --global enable`. So the role never writes into the home +directory of the account, which the agent can change. It turns on linger +for the account, so the agent starts at boot. The role does not write +the client config (setup.md section 11). With `nodkey_ssh_agent_user` +empty, the role removes the user unit. It never turns linger off: the +account may need it for other units. + +## Get the role + +Each release from 0.8.0 on has the file `nodkey__ansible.tar.gz`. +It is in `SHA256SUMS` and covered by the build attestation, as the +binaries are. Download and check it on a trusted machine or on the host, +as root, with the steps of +[docs/releasing.md, "Verify a download"](../../docs/releasing.md#verify-a-download), +with the name of this file. Then unpack it into a directory that only +root can change: + +```sh +VERSION=0.8.0 +install -d -o root -g root -m 0755 "/opt/nodkey-ansible-$VERSION" +tar -xzf "nodkey_${VERSION}_ansible.tar.gz" -C "/opt/nodkey-ansible-$VERSION" --no-same-owner +``` + +The role of release X.Y.Z installs only nodkey X.Y.Z: it holds the +`install.sh` and the unit of that tag. The source of the role in the +repository has neither, and it refuses to run. To try the source, build +it: `sh contrib/ansible/build.sh X.Y.Z TAGDIR OUTDIR`, where `TAGDIR` is +a checkout of the tag `vX.Y.Z`. + +## Settings + +The defaults are in `roles/nodkey/defaults/main.yml`. + +| setting | default | what it does | +|---|---|---| +| `nodkey_side` | `agent` | `broker` or `agent`. | +| `nodkey_version` | the version of the role | The release to install, `X.Y.Z`. It must be the version of the role. | +| `nodkey_restart` | `true` | Restart the broker (only if it runs), or the user unit, after a change of the binary or the unit. | +| `nodkey_broker_config` | `""` | Broker side: the path of the config that the host provides. The role checks it with `runuser -u nodkey -- nodkey broker check --config PATH`, and fails if the check fails. Empty: no check. A data file may name only a file in `/etc/nodkey/`. | +| `nodkey_ssh_agent_user` | `""` | Agent side: the account that runs `nodkey ssh-agent`. Never `root`. Empty: no user unit. | +| `nodkey_ssh_agent_linger` | `true` | Agent side: turn on linger for that account. | + +`roles/nodkey/vars/main.yml` is written by `build.sh`: the version of the +role, and the SHA-256 of its `install.sh` and of its unit. There is no +setting to skip a check. + +The role needs ansible-core 2.19 or newer. An example play, run as root +on the host: + +```yaml +- name: nodkey broker + hosts: example-host + become: true + roles: + - role: /opt/nodkey-ansible-0.8.0/roles/nodkey + vars: + nodkey_side: broker + nodkey_broker_config: /etc/nodkey/broker.toml +``` + +It works with `ansible-playbook --connection local` too, for a host that +applies its own config. `--check --diff` shows what would change. A +second run with the same version changes nothing. + +## The data file + +For a host that keeps only data in its repository, such as a host that +applies its config with pullgate, run a fixed playbook of the installed +recipe, with the data file of the host. As root, on the host: + +```sh +cd /opt/nodkey-ansible-0.8.0 +ansible-playbook -i localhost, --connection local playbooks/broker-host.yml -e nodkey_data_file=/etc/config-repo/nodkey.yml +``` + +Give the path with `-e nodkey_data_file=PATH`, never as `-e @PATH`. With +`@`, each key of the file would become a variable of Ansible, and a key +could change a setting that the file must not set. The playbook first +copies the file to a private temporary directory, runs `check-data` on +the copy, and reads the copy only if the check passes, into one +variable. So the file cannot change between the check and the read. +Then it runs the role with the keys of the schema. + +The data file is YAML: one map, with only these keys. + +| key | side | type | required | +|---|---|---|---| +| `nodkey_version` | both | text `X.Y.Z`, such as `"0.8.0"` | yes | +| `nodkey_restart` | both | `true` or `false` | no | +| `nodkey_broker_config` | broker | the path of a file in `/etc/nodkey/`, or `""` | no | +| `nodkey_ssh_agent_user` | agent | the name of an account, not `root`, or `""` | no | +| `nodkey_ssh_agent_linger` | agent | `true` or `false` | no | + +`check-data` fails on another key, a key that is there twice, a wrong +type, a version that is not `X.Y.Z`, and a version older than the +installed nodkey. A text value may hold only the characters of a path +or an account name, so no value is an Ansible template. The role still +checks that the version is the version of the role. Check a file before +you commit it: + +```sh +./check-data --side broker --installed 0.8.0 nodkey.yml +``` + +`--installed` names the installed version; `--installed none` means +that no nodkey is installed. `check-data` never runs nodkey. It prints no +value of the file, and the name of a key only if it is a plain name. +Exit codes: 0 good, 1 not good, 64 wrong usage. + +An example for the broker host: + +```yaml +nodkey_version: "0.8.0" +nodkey_broker_config: /etc/nodkey/broker.toml +nodkey_restart: false +``` + +## Update + +Get the recipe of the new release, and check it, as in "Get the role". +Then set `nodkey_version` to the new version in the data file or the +play, and run it with the new recipe. It runs `nodkey update --version` +of the installed nodkey, installs the unit of the new tag, and restarts +the broker if it runs. Read the changes first: `nodkey update --notes` +(setup.md section 13). + +## Tests + +`contrib/ansible/test/ci.sh OLD NEW` runs the recipe in a Debian stable +container with systemd, for both sides, against two real releases. CI +runs it. `contrib_ansible_linux_test.go`, at the root of the module, +tests `check-data` and `build.sh`. diff --git a/contrib/ansible/build.sh b/contrib/ansible/build.sh new file mode 100755 index 0000000..198ffe4 --- /dev/null +++ b/contrib/ansible/build.sh @@ -0,0 +1,64 @@ +#!/bin/sh +# build.sh makes the Ansible recipe of one nodkey release: the role, the +# playbooks and check-data, with the install.sh and the unit of the tag +# in the role, and their SHA-256 in roles/nodkey/vars/main.yml. +# +# sh contrib/ansible/build.sh VERSION TAGDIR OUTDIR +# +# VERSION is X.Y.Z. TAGDIR holds install.sh and +# contrib/systemd/nodkey.service of the tag vX.Y.Z: the release workflow +# passes the checkout of the tag. OUTDIR must not exist; build.sh makes it. +# The release workflow packs OUTDIR into nodkey_VERSION_ansible.tar.gz +# (DESIGN.md section 18). +# +# Exit codes: 0 done, 1 failure, 64 wrong usage. + +set -eu + +usage_error() { + printf 'build.sh: %s; usage: sh contrib/ansible/build.sh VERSION TAGDIR OUTDIR (exit 64)\n' "$1" >&2 + exit 64 +} + +die() { + printf 'build.sh: %s (exit 1)\n' "$1" >&2 + exit 1 +} + +[ "$#" -eq 3 ] || usage_error "give VERSION, TAGDIR and OUTDIR" +version=$1 +tagdir=$2 +out=$3 + +# X.Y.Z, without leading zeros: the same rule as install.sh. +printf '%s\n' "$version" | grep -Eqx '(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)' || + usage_error "VERSION \"$version\" is not X.Y.Z" +[ -f "$tagdir/install.sh" ] || die "$tagdir/install.sh is not there; give the checkout of the tag v$version as TAGDIR" +[ -f "$tagdir/contrib/systemd/nodkey.service" ] || + die "$tagdir/contrib/systemd/nodkey.service is not there; give the checkout of the tag v$version as TAGDIR" +[ ! -e "$out" ] || die "$out is there already; give a new directory as OUTDIR" + +src=$(cd "$(dirname "$0")" && pwd) + +mkdir -p "$out" +cp "$src/README.md" "$src/check-data" "$out/" +cp -R "$src/playbooks" "$src/roles" "$out/" +cp "$src/../../LICENSE" "$out/" +mkdir -p "$out/roles/nodkey/files" "$out/roles/nodkey/vars" +cp "$tagdir/install.sh" "$out/roles/nodkey/files/install.sh" +cp "$tagdir/contrib/systemd/nodkey.service" "$out/roles/nodkey/files/nodkey.service" + +install_sh_sha256=$(sha256sum <"$out/roles/nodkey/files/install.sh" | cut -d' ' -f1) +unit_sha256=$(sha256sum <"$out/roles/nodkey/files/nodkey.service" | cut -d' ' -f1) + +cat >"$out/roles/nodkey/vars/main.yml" <= len(argv): + usage_error("%s needs a value" % arg) + if arg == "--side": + side = argv[i + 1] + else: + installed = argv[i + 1] + i += 2 + continue + if arg.startswith("-"): + usage_error("unknown option %s" % arg) + files.append(arg) + i += 1 + if side not in SIDES: + usage_error("give --side broker or --side agent") + if len(files) != 1: + usage_error("give one data file") + if installed is None or (installed != "none" and not VERSION_RE.fullmatch(installed)): + usage_error("give --installed X.Y.Z, the version of the installed nodkey, or --installed none") + return side, installed, files[0] + + +def key_name(key, line=None): + """The name of a key for an error, only if it is a plain name.""" + if isinstance(key, str) and KEY_RE.fullmatch(key): + return key + return "at line %d" % line if line else "with a name that is not plain" + + +def as_tuple(version): + return tuple(int(p) for p in version.split(".")) + + +def check_value(key, kind, value): + fix = 'see README.md, "The data file"' + if kind == "bool": + if not isinstance(value, bool): + raise Bad("%s must be true or false; %s" % (key, fix)) + elif kind == "version": + if not isinstance(value, str) or not VERSION_RE.fullmatch(value): + raise Bad('%s must be a version X.Y.Z in quotes, such as "0.8.0"; %s' % (key, fix)) + elif kind == "path": + if not isinstance(value, str) or not (value == "" or (PATH_RE.fullmatch(value) and value.startswith("/etc/nodkey/"))): + raise Bad("%s must be the path of a file in /etc/nodkey/, or empty; %s" % (key, fix)) + if "/../" in value + "/" or "/./" in value + "/": + raise Bad("%s must not have . or .. in it; %s" % (key, fix)) + elif kind == "user": + if not isinstance(value, str) or not (value == "" or USER_RE.fullmatch(value)): + raise Bad("%s must be the name of an account, or empty; %s" % (key, fix)) + if value == "root": + raise Bad("%s must not be root: run the agent as a normal account; %s" % (key, fix)) + + +def check(side, installed, path): + try: + with open(path, "rb") as f: + raw = f.read(MAX_SIZE + 1) + except OSError as err: + raise Bad("cannot read it (%s); check the path" % err.strerror) from None + if len(raw) > MAX_SIZE: + raise Bad("it is larger than %d bytes; a data file has only a few keys" % MAX_SIZE) + try: + text = raw.decode("utf-8") + except UnicodeDecodeError: + raise Bad("it is not UTF-8 text") from None + try: + data = yaml.load(text, Loader=StrictLoader) # noqa: S506 - a safe loader + except yaml.YAMLError as err: + mark = getattr(err, "problem_mark", None) + where = "line %d" % (mark.line + 1) if mark else "somewhere" + raise Bad("it is not valid YAML (%s); fix that line" % where) from None + if not isinstance(data, dict): + raise Bad('it must be a map of keys, such as nodkey_version: "0.8.0"; see README.md, "The data file"') + schema = SIDES[side] + for key in data: + if key not in schema: + raise Bad( + 'the key %s is not a key of the %s side; remove it (README.md, "The data file", lists the keys)' + % (key_name(key), side) + ) + for key in REQUIRED: + if key not in data: + raise Bad('it has no %s; add it, such as nodkey_version: "0.8.0"' % key) + for key, value in data.items(): + check_value(key, schema[key], value) + if installed == "none": + installed = None + want = data["nodkey_version"] + if installed is not None and as_tuple(want) < as_tuple(installed): + raise Bad( + "nodkey_version %s is older than the installed nodkey %s; the playbooks never go back:" + " set nodkey_version to %s or newer" % (want, installed, installed) + ) + + +def main(argv): + side, installed, path = parse_args(argv) + try: + check(side, installed, path) + except Bad as err: + print("check-data: %s: %s (exit 1)" % (path, err), file=sys.stderr) + return 1 + print("check-data: %s: good for the %s side" % (path, side)) + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/contrib/ansible/playbooks/agent-host.yml b/contrib/ansible/playbooks/agent-host.yml new file mode 100644 index 0000000..489cfde --- /dev/null +++ b/contrib/ansible/playbooks/agent-host.yml @@ -0,0 +1,97 @@ +--- +# The fixed playbook of the agent side, for a host that keeps only data +# in its repository (README.md, "The data file"). Run it as root: +# +# ansible-playbook -i localhost, --connection local \ +# playbooks/agent-host.yml -e nodkey_data_file=/path/to/host.yml +# +# It reads the data file itself, into one variable, after check-data +# passed. So a key of the file can never change a setting of the role +# that the file must not set, such as a pinned SHA-256. Do not pass the +# file with -e @host.yml: then each key would become a variable. + +- name: Install nodkey, the agent side, from a data file + hosts: all + gather_facts: true + gather_subset: + - "!all" + - "min" + tasks: + - name: Check nodkey_data_file + ansible.builtin.assert: + that: + - nodkey_data_file is defined + - nodkey_data_file is string + - nodkey_data_file is match('^/') + fail_msg: >- + Give the absolute path of the data file: + -e nodkey_data_file=/path/to/host.yml (README.md, "The data file"). + quiet: true + + # The same safe read as the role: only a nodkey that only root can + # change runs here. + - name: Read the installed nodkey + ansible.builtin.include_tasks: ../roles/nodkey/tasks/installed.yml + + # Read the file once: check-data and include_vars both read a + # private copy, so the file cannot change between the check and the + # read. Ansible renders a value with "{{" as a template; check-data + # lets no such value through. + - name: Check and read the data file + delegate_to: localhost + become: false + block: + - name: Make a private directory for the copy + ansible.builtin.tempfile: + state: directory + prefix: nodkey-data. + register: nodkey_data_tmp + # A scratch copy, removed below: not a change of the host. + changed_when: false + check_mode: false + + - name: Copy the data file + ansible.builtin.copy: + src: "{{ nodkey_data_file }}" + dest: "{{ nodkey_data_tmp.path }}/host.yml" + mode: "0600" + changed_when: false + check_mode: false + diff: false + + - name: Check the data file with check-data + ansible.builtin.command: + argv: + - "{{ ansible_playbook_python }}" + - "{{ playbook_dir }}/../check-data" + - --side + - agent + - --installed + - "{{ nodkey_installed if nodkey_installed is match('^[0-9]+[.][0-9]+[.][0-9]+$') else 'none' }}" + - "{{ nodkey_data_tmp.path }}/host.yml" + changed_when: false + check_mode: false + + - name: Read the data file + ansible.builtin.include_vars: + file: "{{ nodkey_data_tmp.path }}/host.yml" + name: nodkey_data + always: + - name: Remove the copy + ansible.builtin.file: + path: "{{ nodkey_data_tmp.path }}" + state: absent + changed_when: false + check_mode: false + when: nodkey_data_tmp.path is defined + + # The role next to the playbooks, so it needs no roles_path. + - name: Run the nodkey role # noqa: role-name[path] + ansible.builtin.include_role: + name: "{{ playbook_dir }}/../roles/nodkey" + vars: + nodkey_side: agent + nodkey_version: "{{ nodkey_data.nodkey_version }}" + nodkey_restart: "{{ nodkey_data.nodkey_restart | default(true) }}" + nodkey_ssh_agent_user: "{{ nodkey_data.nodkey_ssh_agent_user | default('') }}" + nodkey_ssh_agent_linger: "{{ nodkey_data.nodkey_ssh_agent_linger | default(true) }}" diff --git a/contrib/ansible/playbooks/broker-host.yml b/contrib/ansible/playbooks/broker-host.yml new file mode 100644 index 0000000..c0f17a6 --- /dev/null +++ b/contrib/ansible/playbooks/broker-host.yml @@ -0,0 +1,96 @@ +--- +# The fixed playbook of the broker side, for a host that keeps only data +# in its repository (README.md, "The data file"). Run it as root: +# +# ansible-playbook -i localhost, --connection local \ +# playbooks/broker-host.yml -e nodkey_data_file=/path/to/host.yml +# +# It reads the data file itself, into one variable, after check-data +# passed. So a key of the file can never change a setting of the role +# that the file must not set, such as a pinned SHA-256. Do not pass the +# file with -e @host.yml: then each key would become a variable. + +- name: Install nodkey, the broker side, from a data file + hosts: all + gather_facts: true + gather_subset: + - "!all" + - "min" + tasks: + - name: Check nodkey_data_file + ansible.builtin.assert: + that: + - nodkey_data_file is defined + - nodkey_data_file is string + - nodkey_data_file is match('^/') + fail_msg: >- + Give the absolute path of the data file: + -e nodkey_data_file=/path/to/host.yml (README.md, "The data file"). + quiet: true + + # The same safe read as the role: only a nodkey that only root can + # change runs here. + - name: Read the installed nodkey + ansible.builtin.include_tasks: ../roles/nodkey/tasks/installed.yml + + # Read the file once: check-data and include_vars both read a + # private copy, so the file cannot change between the check and the + # read. Ansible renders a value with "{{" as a template; check-data + # lets no such value through. + - name: Check and read the data file + delegate_to: localhost + become: false + block: + - name: Make a private directory for the copy + ansible.builtin.tempfile: + state: directory + prefix: nodkey-data. + register: nodkey_data_tmp + # A scratch copy, removed below: not a change of the host. + changed_when: false + check_mode: false + + - name: Copy the data file + ansible.builtin.copy: + src: "{{ nodkey_data_file }}" + dest: "{{ nodkey_data_tmp.path }}/host.yml" + mode: "0600" + changed_when: false + check_mode: false + diff: false + + - name: Check the data file with check-data + ansible.builtin.command: + argv: + - "{{ ansible_playbook_python }}" + - "{{ playbook_dir }}/../check-data" + - --side + - broker + - --installed + - "{{ nodkey_installed if nodkey_installed is match('^[0-9]+[.][0-9]+[.][0-9]+$') else 'none' }}" + - "{{ nodkey_data_tmp.path }}/host.yml" + changed_when: false + check_mode: false + + - name: Read the data file + ansible.builtin.include_vars: + file: "{{ nodkey_data_tmp.path }}/host.yml" + name: nodkey_data + always: + - name: Remove the copy + ansible.builtin.file: + path: "{{ nodkey_data_tmp.path }}" + state: absent + changed_when: false + check_mode: false + when: nodkey_data_tmp.path is defined + + # The role next to the playbooks, so it needs no roles_path. + - name: Run the nodkey role # noqa: role-name[path] + ansible.builtin.include_role: + name: "{{ playbook_dir }}/../roles/nodkey" + vars: + nodkey_side: broker + nodkey_version: "{{ nodkey_data.nodkey_version }}" + nodkey_restart: "{{ nodkey_data.nodkey_restart | default(true) }}" + nodkey_broker_config: "{{ nodkey_data.nodkey_broker_config | default('') }}" diff --git a/contrib/ansible/roles/nodkey/defaults/main.yml b/contrib/ansible/roles/nodkey/defaults/main.yml new file mode 100644 index 0000000..d4cd312 --- /dev/null +++ b/contrib/ansible/roles/nodkey/defaults/main.yml @@ -0,0 +1,30 @@ +--- +# The defaults of the nodkey role. README.md (next to the playbooks) +# explains each one. + +# broker: the broker host. agent: an agent machine (a client). +nodkey_side: agent + +# The release to install, X.Y.Z. It must be the version of this role: +# the role of release X.Y.Z installs nodkey X.Y.Z, with the install.sh +# and the unit of the same tag. The release tarball sets +# nodkey_role_version in vars/main.yml. +nodkey_version: "{{ nodkey_role_version | default('') }}" + +# A changed binary or unit restarts the broker (only if it runs), and the +# nodkey ssh-agent user unit. A restart of the broker ends all grants: +# set false to restart it yourself. +nodkey_restart: true + +# Broker side: the config file that the host provides. The role never +# writes it. When set, the role checks it with nodkey broker check, as +# the user nodkey. Empty: no check. +nodkey_broker_config: "" + +# Agent side: the account that runs nodkey ssh-agent as a user unit. +# Empty: no user unit. +nodkey_ssh_agent_user: "" + +# Agent side: turn on linger for that account, so its user manager, and +# the agent, start at boot and not only at a login. +nodkey_ssh_agent_linger: true diff --git a/contrib/ansible/roles/nodkey/handlers/main.yml b/contrib/ansible/roles/nodkey/handlers/main.yml new file mode 100644 index 0000000..ef03654 --- /dev/null +++ b/contrib/ansible/roles/nodkey/handlers/main.yml @@ -0,0 +1,73 @@ +--- +# Handlers run at the end of the play, in this order, and only after +# every task passed: a failed config check restarts nothing. The mark +# /var/lib/nodkey-ansible/restart-due stays then, so the next run that +# passes does the restart. + +# try-restart: only a broker that runs. A restart ends all grants. The +# systemd_service module has no try-restart. +- name: Restart the broker + ansible.builtin.shell: | + set -eu + systemctl daemon-reload + systemctl try-restart nodkey.service + changed_when: true + when: + - nodkey_side == 'broker' + - nodkey_restart | bool + listen: nodkey restart due + +- name: Reload the units without a restart + ansible.builtin.systemd_service: + daemon_reload: true + when: + - nodkey_side == 'broker' + - not (nodkey_restart | bool) + listen: nodkey restart due + +- name: Say that the broker needs a restart + ansible.builtin.debug: + msg: >- + nodkey: the binary or the unit changed, and nodkey_restart is false. + If the broker runs, restart it as root when it suits you: + systemctl restart nodkey. The restart ends all grants. + when: + - nodkey_side == 'broker' + - not (nodkey_restart | bool) + listen: nodkey restart due + +# Only when the user manager of the account runs. As the account, it +# needs no D-Bus. It reads the unit again, and starts the agent, or +# starts it again with the new binary. +- name: Restart nodkey ssh-agent of the account + ansible.builtin.shell: | + set -eu + run="/run/user/$(id -u -- "$NODKEY_USER")" + [ -d "$run/systemd" ] || exit 0 + runuser -u "$NODKEY_USER" -- env XDG_RUNTIME_DIR="$run" systemctl --user daemon-reload + runuser -u "$NODKEY_USER" -- env XDG_RUNTIME_DIR="$run" systemctl --user restart nodkey-ssh-agent.service + environment: + NODKEY_USER: "{{ nodkey_ssh_agent_user }}" + changed_when: true + when: + - nodkey_side == 'agent' + - nodkey_ssh_agent_user != '' + - nodkey_restart | bool + listen: nodkey restart due + +- name: Say that nodkey ssh-agent needs a restart + ansible.builtin.debug: + msg: >- + nodkey: the binary or the unit changed, and nodkey_restart is false. + Restart nodkey ssh-agent of the account when it suits you. + when: + - nodkey_side == 'agent' + - nodkey_ssh_agent_user != '' + - not (nodkey_restart | bool) + listen: nodkey restart due + +- name: Remove the mark of the restart + ansible.builtin.file: + path: /var/lib/nodkey-ansible/restart-due + state: absent + listen: nodkey restart due diff --git a/contrib/ansible/roles/nodkey/meta/main.yml b/contrib/ansible/roles/nodkey/meta/main.yml new file mode 100644 index 0000000..028990b --- /dev/null +++ b/contrib/ansible/roles/nodkey/meta/main.yml @@ -0,0 +1,14 @@ +--- +galaxy_info: + role_name: nodkey + namespace: code6x + author: nodkey contributors + description: >- + Install nodkey, the broker or an agent machine, from a checked release. + license: Apache-2.0 + min_ansible_version: "2.19" + platforms: + - name: Debian + versions: + - trixie +dependencies: [] diff --git a/contrib/ansible/roles/nodkey/tasks/agent.yml b/contrib/ansible/roles/nodkey/tasks/agent.yml new file mode 100644 index 0000000..13e944b --- /dev/null +++ b/contrib/ansible/roles/nodkey/tasks/agent.yml @@ -0,0 +1,107 @@ +--- +# The agent side: nodkey ssh-agent as a user unit of one account +# (docs/setup.md section 11). All files are in /etc/systemd/user, owned by +# root. The role never writes into the home directory of the account, +# which the agent can change. + +# When the account changes, or is removed, stop the agent of the old +# account: ConditionUser= does not stop a unit that runs. +- name: Read the user unit of an earlier run + ansible.builtin.slurp: + src: /etc/systemd/user/nodkey-ssh-agent.service + register: nodkey_agent_old_unit + failed_when: false + +- name: Set the account of the earlier run + ansible.builtin.set_fact: + nodkey_agent_old_user: >- + {{ ((nodkey_agent_old_unit.content | default('') | b64decode) + | regex_findall('(?m)^ConditionUser=([a-z_][a-z0-9_-]{0,31})$') + [''])[0] }} + +- name: Stop nodkey ssh-agent of the old account + ansible.builtin.shell: | + set -eu + run="/run/user/$(id -u -- "$NODKEY_USER")" || exit 0 + [ -d "$run/systemd" ] || exit 0 + runuser -u "$NODKEY_USER" -- env XDG_RUNTIME_DIR="$run" systemctl --user stop nodkey-ssh-agent.service + environment: + NODKEY_USER: "{{ nodkey_agent_old_user }}" + changed_when: true + when: + - nodkey_agent_old_user != '' + - nodkey_agent_old_user != nodkey_ssh_agent_user + - not ansible_check_mode + +- name: Set up the user unit + when: nodkey_ssh_agent_user != '' + block: + - name: Read the account + ansible.builtin.getent: + database: passwd + key: "{{ nodkey_ssh_agent_user }}" + fail_key: false + + - name: Check that the account is there + ansible.builtin.assert: + that: + - ansible_facts['getent_passwd'][nodkey_ssh_agent_user] is not none + fail_msg: >- + nodkey role: the account {{ nodkey_ssh_agent_user }} of + nodkey_ssh_agent_user is not on the host. Make it first, or set + nodkey_ssh_agent_user to "". + quiet: true + + - name: Install the user unit nodkey-ssh-agent + ansible.builtin.template: + src: nodkey-ssh-agent.service.j2 + dest: /etc/systemd/user/nodkey-ssh-agent.service + owner: root + group: root + mode: "0644" + register: nodkey_agent_unit + + - name: Make /etc/systemd/user/default.target.wants + ansible.builtin.file: + path: /etc/systemd/user/default.target.wants + state: directory + owner: root + group: root + mode: "0755" + + # The same link as "systemctl --global enable nodkey-ssh-agent". + # force: in check mode, the unit is not there yet. + - name: Enable the user unit + ansible.builtin.file: + src: ../nodkey-ssh-agent.service + dest: /etc/systemd/user/default.target.wants/nodkey-ssh-agent.service + state: link + force: true + owner: root + group: root + register: nodkey_agent_link + + - name: Note that a restart is due + ansible.builtin.include_tasks: restart-due.yml + when: nodkey_agent_unit is changed or nodkey_agent_link is changed + + # Linger starts the user manager of the account at boot, and with it + # the agent. Without it, the agent starts only at a login. The role + # never turns linger off: the account may need it for other units. + - name: Turn on linger for the account + ansible.builtin.command: + argv: + - loginctl + - enable-linger + - "{{ nodkey_ssh_agent_user }}" + creates: "/var/lib/systemd/linger/{{ nodkey_ssh_agent_user }}" + when: nodkey_ssh_agent_linger | bool + +# No account: no user unit. This removes one that an earlier run made. +- name: Remove the user unit + ansible.builtin.file: + path: "{{ item }}" + state: absent + loop: + - /etc/systemd/user/default.target.wants/nodkey-ssh-agent.service + - /etc/systemd/user/nodkey-ssh-agent.service + when: nodkey_ssh_agent_user == '' diff --git a/contrib/ansible/roles/nodkey/tasks/broker.yml b/contrib/ansible/roles/nodkey/tasks/broker.yml new file mode 100644 index 0000000..3ccb71e --- /dev/null +++ b/contrib/ansible/roles/nodkey/tasks/broker.yml @@ -0,0 +1,92 @@ +--- +# The broker side: the user, the directories and the unit of +# docs/setup.md sections 3, 7 and 8. The role never writes broker.toml, +# known_hosts or a credential. + +- name: Make the group nodkey + ansible.builtin.group: + name: nodkey + system: true + +- name: Make the user nodkey + ansible.builtin.user: + name: nodkey + group: nodkey + system: true + home: /var/lib/nodkey + create_home: false + shell: /usr/sbin/nologin + register: nodkey_user + +- name: Make /etc/nodkey + ansible.builtin.file: + path: /etc/nodkey + state: directory + owner: root + group: root + mode: "0755" + +# An empty slot: the role never writes a credential into it. +- name: Make /etc/nodkey/credentials + ansible.builtin.file: + path: /etc/nodkey/credentials + state: directory + owner: root + group: root + mode: "0700" + +# The unit of the tag, unchanged. Fit it to the host with a drop-in in +# /etc/systemd/system/nodkey.service.d/, which the role never changes. +# A unit changed by hand is kept as a backup file next to it. The mark +# is a task, not a handler, so that it stays when the play fails later. +- name: Install the unit of the tag + ansible.builtin.copy: + src: nodkey.service + dest: /etc/systemd/system/nodkey.service + owner: root + group: root + mode: "0644" + backup: true + register: nodkey_unit_copy + +- name: Note that a restart is due # noqa: no-handler + ansible.builtin.include_tasks: restart-due.yml + when: nodkey_unit_copy is changed + +- name: Check the config of the host + when: nodkey_broker_config != '' + block: + - name: Look for the config file + ansible.builtin.stat: + path: "{{ nodkey_broker_config }}" + register: nodkey_config_file + + - name: Check that the config file is there + ansible.builtin.assert: + that: + - nodkey_config_file.stat.exists + - nodkey_config_file.stat.isreg + fail_msg: >- + nodkey role: nodkey_broker_config is {{ nodkey_broker_config }}, + but that is not a file on the host. The role never writes it: put + the config there (docs/setup.md section 7), or set + nodkey_broker_config to "". + quiet: true + + # In check mode before the first install, there is no nodkey and no + # user nodkey yet to run the check. + - name: Check the config with nodkey broker check + ansible.builtin.command: + argv: + - runuser + - -u + - nodkey + - -- + - /usr/local/bin/nodkey + - broker + - check + - --config + - "{{ nodkey_broker_config }}" + changed_when: false + check_mode: false + when: not (ansible_check_mode and (nodkey_action == 'install' or nodkey_user is changed)) diff --git a/contrib/ansible/roles/nodkey/tasks/installed.yml b/contrib/ansible/roles/nodkey/tasks/installed.yml new file mode 100644 index 0000000..b148f68 --- /dev/null +++ b/contrib/ansible/roles/nodkey/tasks/installed.yml @@ -0,0 +1,73 @@ +--- +# Read the version of the installed nodkey, safely. It runs as root, so +# it first checks, as install.sh does, that only root can change the +# file and each directory above it, and that the file is no link. Else +# whoever can change it (on an agent machine: maybe the agent) would run +# a program as root here. The playbooks run this file too, before +# check-data. Sets nodkey_installed: "" (none), a version X.Y.Z, or +# "not a release". + +- name: Look at the directories of /usr/local/bin/nodkey + ansible.builtin.stat: + path: "{{ item }}" + follow: false + get_checksum: false + loop: [/, /usr, /usr/local, /usr/local/bin] + register: nodkey_dirs + +- name: Check that only root can change these directories + ansible.builtin.assert: + that: + - item.stat.exists + - item.stat.isdir + - not item.stat.islnk + - item.stat.uid == 0 + - not item.stat.wgrp + - not item.stat.woth + fail_msg: >- + nodkey role: {{ item.item }} is not a directory that only root can + change (owner root, no write for group and others, no link). Nothing + was run or installed. Fix it as root, such as with + chown root:root {{ item.item }} and chmod go-w {{ item.item }}. + quiet: true + loop: "{{ nodkey_dirs.results }}" + loop_control: + label: "{{ item.item }}" + +- name: Look for an installed nodkey + ansible.builtin.stat: + path: /usr/local/bin/nodkey + follow: false + get_checksum: false + register: nodkey_binary + +- name: Check that only root can change the installed nodkey + ansible.builtin.assert: + that: + - nodkey_binary.stat.isreg + - not nodkey_binary.stat.islnk + - nodkey_binary.stat.uid == 0 + - not nodkey_binary.stat.wgrp + - not nodkey_binary.stat.woth + fail_msg: >- + nodkey role: /usr/local/bin/nodkey is not a file that only root can + change (a plain file, owner root, no write for group and others). + It was not run. Check it as root; if you did not put it there, + remove it and run the role again. + quiet: true + when: nodkey_binary.stat.exists + +- name: Read the version of the installed nodkey + ansible.builtin.command: /usr/local/bin/nodkey version + register: nodkey_installed_out + changed_when: false + failed_when: false + check_mode: false + when: nodkey_binary.stat.exists + +- name: Set the installed version + ansible.builtin.set_fact: + nodkey_installed: >- + {{ '' if not nodkey_binary.stat.exists + else ((((nodkey_installed_out.stdout_lines | default([])) + [''])[0] | regex_replace('^nodkey ', '')) + if nodkey_installed_out.rc == 0 else 'not a release') }} diff --git a/contrib/ansible/roles/nodkey/tasks/main.yml b/contrib/ansible/roles/nodkey/tasks/main.yml new file mode 100644 index 0000000..04c5e03 --- /dev/null +++ b/contrib/ansible/roles/nodkey/tasks/main.yml @@ -0,0 +1,249 @@ +--- +# The nodkey role: it installs nodkey on the broker host or on an agent +# machine, as docs/setup.md says, with the checks of install.sh. How it +# works, and why: contrib/ansible/README.md and DESIGN.md section 18. + +- name: Check that this is a role from a release + ansible.builtin.assert: + that: + - nodkey_role_version is defined + - nodkey_install_sh_sha256 is defined + - nodkey_unit_sha256 is defined + fail_msg: >- + nodkey role: this is the source of the role, without the install.sh + and the unit of a release. Use the role from the release file + nodkey_X.Y.Z_ansible.tar.gz, or build it with contrib/ansible/build.sh + (contrib/ansible/README.md, "Get the role"). + quiet: true + +- name: Check nodkey_side + ansible.builtin.assert: + that: + - nodkey_side in ['broker', 'agent'] + fail_msg: >- + nodkey role: nodkey_side is "{{ nodkey_side }}"; set it to broker or + agent (contrib/ansible/README.md, "Settings"). + quiet: true + +- name: Check nodkey_version + ansible.builtin.assert: + that: + - nodkey_version is string + - nodkey_version is match('^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$') + - nodkey_version == nodkey_role_version + fail_msg: >- + nodkey role: nodkey_version is "{{ nodkey_version }}", but this is the + role of nodkey {{ nodkey_role_version }}, and it installs only that + release, with the install.sh and the unit of its tag. Set + nodkey_version to {{ nodkey_role_version }}, or get the role of the + release you want (contrib/ansible/README.md, "Update"). + quiet: true + +- name: Check the other settings + ansible.builtin.assert: + that: + - nodkey_restart is boolean + - nodkey_ssh_agent_linger is boolean + - nodkey_broker_config is string + - nodkey_broker_config == '' or nodkey_broker_config is match('^/[^\n]*$') + - nodkey_ssh_agent_user is string + - nodkey_ssh_agent_user == '' or nodkey_ssh_agent_user is match('^[a-z_][a-z0-9_-]{0,31}$') + - nodkey_ssh_agent_user != 'root' + fail_msg: >- + nodkey role: a setting has a wrong value. nodkey_restart and + nodkey_ssh_agent_linger are true or false; nodkey_broker_config is + empty or an absolute path; nodkey_ssh_agent_user is empty or the name + of an account other than root. See contrib/ansible/README.md, + "Settings". + quiet: true + +- name: Check the host + ansible.builtin.assert: + that: + - ansible_facts['system'] == 'Linux' + - ansible_facts['service_mgr'] == 'systemd' + fail_msg: >- + nodkey role: the host must run Linux with systemd. Gather the facts + (gather_facts: true) and run the role on such a host. + quiet: true + +# The pins: the SHA-256 of install.sh and of the unit, which build.sh +# wrote into vars/main.yml from the tag. This runs before any change. +- name: Check the SHA-256 of install.sh in the role + ansible.builtin.assert: + that: + - lookup('ansible.builtin.file', 'install.sh', rstrip=false) | hash('sha256') == nodkey_install_sh_sha256 + fail_msg: >- + nodkey role: files/install.sh of the role does not have the SHA-256 of + vars/main.yml. Nothing was installed. Get the role again from the + release and check it (contrib/ansible/README.md, "Get the role"). + quiet: true + +- name: Check the SHA-256 of the unit in the role + ansible.builtin.assert: + that: + - lookup('ansible.builtin.file', 'nodkey.service', rstrip=false) | hash('sha256') == nodkey_unit_sha256 + fail_msg: >- + nodkey role: files/nodkey.service of the role does not have the + SHA-256 of vars/main.yml. Nothing was installed. Get the role again + from the release and check it (contrib/ansible/README.md, "Get the + role"). + quiet: true + +- name: Read the installed nodkey + ansible.builtin.include_tasks: installed.yml + +- name: Check the installed nodkey + ansible.builtin.assert: + that: + - nodkey_installed == '' or nodkey_installed is match('^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$') + fail_msg: >- + nodkey role: /usr/local/bin/nodkey is there, but "nodkey version" does + not name a release (exit {{ nodkey_installed_out.rc | default('-') }}). + The role updates only a release. As root, install a release by hand + (docs/setup.md section 2), or remove the file; then run the role + again. + quiet: true + +# Forward only: a host never goes back to an older release through the +# role. To go back, a person does it by hand (docs/setup.md section 13). +- name: Refuse a version older than the installed one + ansible.builtin.assert: + that: + - nodkey_installed == '' or nodkey_installed is version(nodkey_version, '<=') + fail_msg: >- + nodkey role: nodkey {{ nodkey_installed }} is installed, which is newer + than nodkey_version {{ nodkey_version }}. The role never goes back to + an older release. Use the role of nodkey {{ nodkey_installed }} or + newer, or go back by hand as root (docs/setup.md section 13). + quiet: true + +- name: Set what to do + ansible.builtin.set_fact: + nodkey_action: >- + {{ 'install' if nodkey_installed == '' + else ('update' if nodkey_installed is version(nodkey_version, '<') else 'none') }} + +- name: Show the change in check mode + ansible.builtin.debug: + msg: >- + nodkey: would {{ nodkey_action }} nodkey {{ nodkey_version }} + {{ '(installed: ' ~ nodkey_installed ~ ')' if nodkey_installed else '' }} + changed_when: true + when: + - ansible_check_mode + - nodkey_action != 'none' + +# The first install: the install.sh of the tag, checked above and again +# on the host. It checks the SHA-256 of the release, its attestation and +# the version of the new binary, and installs nothing if a check fails. +- name: Install nodkey with the install.sh of the tag + when: + - nodkey_action == 'install' + - not ansible_check_mode + block: + - name: Make a temporary directory + ansible.builtin.tempfile: + state: directory + prefix: nodkey-role. + register: nodkey_tmp + + - name: Copy install.sh to the host + ansible.builtin.copy: + src: install.sh + dest: "{{ nodkey_tmp.path }}/install.sh" + owner: root + group: root + mode: "0700" + + - name: Read the SHA-256 of install.sh on the host + ansible.builtin.stat: + path: "{{ nodkey_tmp.path }}/install.sh" + checksum_algorithm: sha256 + register: nodkey_install_sh + + - name: Check the SHA-256 of install.sh on the host + ansible.builtin.assert: + that: + - nodkey_install_sh.stat.checksum == nodkey_install_sh_sha256 + fail_msg: >- + nodkey role: install.sh on the host does not have the pinned + SHA-256. Nothing was installed. Run the role again. + quiet: true + + - name: Run install.sh + ansible.builtin.command: + argv: + - /bin/sh + - "{{ nodkey_tmp.path }}/install.sh" + - --version + - "{{ nodkey_version }}" + changed_when: true + register: nodkey_install_run + always: + - name: Remove the temporary directory + ansible.builtin.file: + path: "{{ nodkey_tmp.path }}" + state: absent + when: nodkey_tmp.path is defined + +# An update: only the installed, checked binary, with the installer that +# is built into it. The role brings no check of its own for an update. +- name: Update nodkey with the installed nodkey + ansible.builtin.command: + argv: + - /usr/local/bin/nodkey + - update + - --version + - "{{ nodkey_version }}" + changed_when: true + register: nodkey_update_run + when: + - nodkey_action == 'update' + - not ansible_check_mode + +- name: Note that a restart is due + ansible.builtin.include_tasks: restart-due.yml + when: nodkey_install_run is changed or nodkey_update_run is changed + +- name: Read the version of the new nodkey + ansible.builtin.command: /usr/local/bin/nodkey version + register: nodkey_new_out + changed_when: false + check_mode: false + when: not (ansible_check_mode and nodkey_action == 'install') + +- name: Check that nodkey is the pinned version + ansible.builtin.assert: + that: + - (nodkey_new_out.stdout_lines + [''])[0] == 'nodkey ' ~ nodkey_version + fail_msg: >- + nodkey role: /usr/local/bin/nodkey says "{{ (nodkey_new_out.stdout_lines + [''])[0] }}", + not "nodkey {{ nodkey_version }}". Check the host as root with + "nodkey version" (docs/setup.md section 2). + quiet: true + when: + - not ansible_check_mode or nodkey_action == 'none' + +- name: Set up the broker side + ansible.builtin.include_tasks: broker.yml + when: nodkey_side == 'broker' + +- name: Set up the agent side + ansible.builtin.include_tasks: agent.yml + when: nodkey_side == 'agent' + +# A restart is due until a handler did it. The mark stays when the play +# fails before the handlers, so the next run restarts. Else a failed +# config check after an update would leave the old binary running. +- name: Look for a restart that is due + ansible.builtin.stat: + path: /var/lib/nodkey-ansible/restart-due + register: nodkey_restart_due + +- name: Restart at the end of the play + ansible.builtin.debug: + msg: "nodkey: a restart is due; it runs at the end of the play." + changed_when: true + notify: nodkey restart due + when: nodkey_restart_due.stat.exists or (ansible_check_mode and nodkey_action != 'none') diff --git a/contrib/ansible/roles/nodkey/tasks/restart-due.yml b/contrib/ansible/roles/nodkey/tasks/restart-due.yml new file mode 100644 index 0000000..79e7bee --- /dev/null +++ b/contrib/ansible/roles/nodkey/tasks/restart-due.yml @@ -0,0 +1,19 @@ +--- +# Mark that a restart is due: the handlers remove the mark after the +# restart. The directory is the role's own, and only root can enter it. + +- name: Make /var/lib/nodkey-ansible + ansible.builtin.file: + path: /var/lib/nodkey-ansible + state: directory + owner: root + group: root + mode: "0700" + +- name: Mark that a restart is due + ansible.builtin.copy: + content: "nodkey {{ nodkey_version }}\n" + dest: /var/lib/nodkey-ansible/restart-due + owner: root + group: root + mode: "0600" diff --git a/contrib/ansible/roles/nodkey/templates/nodkey-ssh-agent.service.j2 b/contrib/ansible/roles/nodkey/templates/nodkey-ssh-agent.service.j2 new file mode 100644 index 0000000..9787872 --- /dev/null +++ b/contrib/ansible/roles/nodkey/templates/nodkey-ssh-agent.service.j2 @@ -0,0 +1,16 @@ +# Made by the nodkey Ansible role (contrib/ansible in the nodkey +# repository). The role changes this file again at its next run. +# +# The unit of docs/setup.md (section 11), for one account only: it is a +# user unit of every account, but ConditionUser= lets it start only for +# this one. It is in /etc/systemd/user, owned by root, so the role never +# writes into the home directory of the account. +[Unit] +Description=nodkey ssh-agent: SSH logins with the keys of the broker +ConditionUser={{ nodkey_ssh_agent_user }} + +[Service] +ExecStart=/usr/local/bin/nodkey ssh-agent + +[Install] +WantedBy=default.target diff --git a/contrib/ansible/test/Dockerfile b/contrib/ansible/test/Dockerfile new file mode 100644 index 0000000..21dbca8 --- /dev/null +++ b/contrib/ansible/test/Dockerfile @@ -0,0 +1,15 @@ +# A Debian stable host with systemd as PID 1, for the test of the +# Ansible role (contrib/ansible/test/ci.sh). Ansible runs inside it with +# --connection local, as on a host that applies its own config. +FROM debian:trixie-slim@sha256:a72b4433de1cf7d6bae0c4cee74d0547f58601a643b3375f070c51600d63b6b2 + +RUN apt-get update \ + && apt-get install --yes --no-install-recommends \ + systemd systemd-sysv dbus libpam-systemd \ + ansible-core python3-yaml \ + ca-certificates curl gzip tar \ + && rm -rf /var/lib/apt/lists/* \ + && useradd --create-home --shell /bin/bash example-user + +STOPSIGNAL SIGRTMIN+3 +CMD ["/sbin/init"] diff --git a/contrib/ansible/test/ci.sh b/contrib/ansible/test/ci.sh new file mode 100755 index 0000000..de3b67b --- /dev/null +++ b/contrib/ansible/test/ci.sh @@ -0,0 +1,253 @@ +#!/bin/sh +# ci.sh tests the Ansible recipe in a Debian stable container with +# systemd, for both sides, against real releases on GitHub: +# +# - a first run installs the release, and nodkey version prints it; +# - a second run, and a run with --check --diff, change nothing; +# - the unit that the role installs is the one of the tag; +# - a wrong SHA-256 of install.sh fails, and installs nothing; +# - an older version is refused; a newer one installs with nodkey update; +# - a data file with an unknown key fails before any change. +# +# sh contrib/ansible/test/ci.sh OLD NEW +# +# OLD and NEW are two releases, X.Y.Z, both with a Sigstore bundle. It +# runs from the root of a git checkout with the tags vOLD and vNEW. It +# needs Docker and network access, and removes the containers and the +# image that it makes. + +set -eu + +[ "$#" -eq 2 ] || { + echo 'ci.sh: give OLD and NEW, such as: sh contrib/ansible/test/ci.sh 0.6.0 0.7.0 (exit 64)' >&2 + exit 64 +} +old=$1 +new=$2 +image=nodkey-ansible-test:$$ +work=$(mktemp -d) +cts="" + +cleanup() { + for ct in $cts; do docker rm -f "$ct" >/dev/null 2>&1 || :; done + docker rmi -f "$image" >/dev/null 2>&1 || : + rm -rf "$work" || : +} +trap cleanup EXIT + +fail() { + printf 'FAIL: %s\n' "$*" >&2 + exit 1 +} + +pass() { + printf 'PASS: %s\n' "$*" +} + +# build VERSION: the recipe of that release, with the files of its tag. +build() { + mkdir -p "$work/tag-$1" + git archive "v$1" install.sh contrib/systemd/nodkey.service | tar -x -C "$work/tag-$1" + sh contrib/ansible/build.sh "$1" "$work/tag-$1" "$work/recipe-$1" >/dev/null +} + +# start NAME: a new container with systemd, and the recipes in /opt. +start() { + ct="nodkey-ansible-$1-$$" + cts="$cts $ct" + docker run -d --name "$ct" --privileged --cgroupns=host \ + --tmpfs /run --tmpfs /run/lock \ + -v /sys/fs/cgroup:/sys/fs/cgroup:rw "$image" >/dev/null + # systemd needs a moment before systemctl can reach it. + state="" + for _ in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20; do + state=$(docker exec "$ct" systemctl is-system-running --wait 2>/dev/null || :) + case $state in running | degraded) break ;; esac + sleep 1 + done + case $state in + running | degraded) ;; + *) fail "systemd in $ct did not start: $state" ;; + esac + docker cp "$work/recipe-$old" "$ct:/opt/recipe-$old" + docker cp "$work/recipe-$new" "$ct:/opt/recipe-$new" + docker cp "$work/data" "$ct:/opt/data" +} + +# play CT VERSION SIDE DATA [ARGS...]: run the playbook of a side as +# root in the container, with --connection local. Its output is in +# $work/out. +play() { + p_ct=$1 p_version=$2 p_side=$3 p_data=$4 + shift 4 + docker exec "$p_ct" ansible-playbook -i localhost, --connection local \ + "/opt/recipe-$p_version/playbooks/$p_side-host.yml" \ + -e "nodkey_data_file=/opt/data/$p_data" "$@" >"$work/out" 2>&1 +} + +recap_changed() { + sed -n 's/.* changed=\([0-9]*\) .*/\1/p' "$work/out" | tail -n 1 +} + +show() { + cat "$work/out" >&2 +} + +# result TASK: the result of the last run of a task in $work/out, such as +# "changed". A task runs at most once in a play here. +result() { + # Ansible may print an error with its lines before "fatal:". + grep -A20 -F "$1]" "$work/out" | sed -n 's/^\(ok\|changed\|skipping\|fatal\|failed\):.*/\1/p' | head -n 1 +} + +installed() { + docker exec "$1" /usr/local/bin/nodkey version | head -n 1 +} + +docker build -q -t "$image" contrib/ansible/test >/dev/null +build "$old" +build "$new" + +mkdir -p "$work/data" +printf 'nodkey_version: "%s"\nnodkey_broker_config: ""\n' "$new" >"$work/data/broker-new.yml" +printf 'nodkey_version: "%s"\n' "$old" >"$work/data/broker-old.yml" +printf 'nodkey_version: "%s"\nnodkey_ssh_agent_user: example-user\n' "$new" >"$work/data/agent-new.yml" +printf 'nodkey_version: "%s"\nnodkey_install_sh_sha256: "%s"\n' "$new" \ + 0000000000000000000000000000000000000000000000000000000000000000 >"$work/data/broker-unknown-key.yml" + +# --- The broker side. +start broker +ct="nodkey-ansible-broker-$$" +play "$ct" "$new" broker broker-unknown-key.yml && { show; fail "a data file with an unknown key passed"; } +grep -q 'the key nodkey_install_sh_sha256 is not a key of the broker side' "$work/out" || { show; fail "no error for the unknown key"; } +docker exec "$ct" test ! -e /usr/local/bin/nodkey || fail "the unknown key installed nodkey" +pass "broker: a data file with an unknown key fails, and installs nothing" + +play "$ct" "$new" broker broker-new.yml || { show; fail "the first run of the broker side failed"; } +[ "$(installed "$ct")" = "nodkey $new" ] || fail "nodkey version is not nodkey $new" +pass "broker: the first run installs nodkey $new" + +git show "v$new:contrib/systemd/nodkey.service" >"$work/unit-tag" +docker cp "$ct:/etc/systemd/system/nodkey.service" "$work/unit-host" +cmp -s "$work/unit-tag" "$work/unit-host" || fail "the unit on the host is not the unit of the tag v$new" +pass "broker: the unit is contrib/systemd/nodkey.service of the tag v$new" + +for spec in "root:root:755:/etc/nodkey" "root:root:700:/etc/nodkey/credentials"; do + path=${spec##*:} + want=${spec%:*} + got=$(docker exec "$ct" stat -c '%U:%G:%a' "$path") + [ "$got" = "$want" ] || fail "$path is $got, not $want" +done +docker exec "$ct" getent passwd nodkey | grep -q ':/var/lib/nodkey:/usr/sbin/nologin$' || fail "the user nodkey is wrong" +[ -z "$(docker exec "$ct" ls -A /etc/nodkey/credentials)" ] || fail "/etc/nodkey/credentials is not empty" +docker exec "$ct" test ! -e /etc/nodkey/broker.toml || fail "the role wrote broker.toml" +pass "broker: the user, /etc/nodkey and the empty /etc/nodkey/credentials" + +play "$ct" "$new" broker broker-new.yml || { show; fail "the second run failed"; } +[ "$(recap_changed)" = 0 ] || { show; fail "the second run changed something"; } +play "$ct" "$new" broker broker-new.yml --check --diff || { show; fail "the run with --check --diff failed"; } +[ "$(recap_changed)" = 0 ] || { show; fail "the run with --check --diff shows a change"; } +pass "broker: a second run, and a run with --check --diff, change nothing" + +play "$ct" "$old" broker broker-old.yml && { show; fail "an older version was not refused"; } +grep -q "is older than the installed nodkey $new" "$work/out" || { show; fail "no error for the older version"; } +[ "$(installed "$ct")" = "nodkey $new" ] || fail "the older version changed nodkey" +pass "broker: an older version is refused, and nodkey $new stays" + +# A restart that a failed run left due is done by the next run. +docker exec "$ct" sh -c 'install -d -m 0700 /var/lib/nodkey-ansible && touch /var/lib/nodkey-ansible/restart-due' +play "$ct" "$new" broker broker-new.yml || { show; fail "the run with a restart due failed"; } +[ "$(result 'Restart the broker')" = changed ] || { show; fail "the due restart did not run"; } +docker exec "$ct" test ! -e /var/lib/nodkey-ansible/restart-due || fail "the mark of the restart is still there" +pass "broker: a restart that is due runs at the next run" + +# A broker config that the host provides: the role checks it. +docker exec "$ct" sh -c 'printf "listen = 1\n" > /etc/nodkey/broker.toml' +printf 'nodkey_version: "%s"\nnodkey_broker_config: /etc/nodkey/broker.toml\n' "$new" >"$work/broker-config.yml" +docker cp "$work/broker-config.yml" "$ct:/opt/data/broker-config.yml" +play "$ct" "$new" broker broker-config.yml && { show; fail "a bad broker.toml passed"; } +[ "$(result 'Check the config with nodkey broker check')" = fatal ] || { show; fail "the config check did not fail"; } +pass "broker: a bad broker.toml of the host fails nodkey broker check" + +# --- A new host: --check --diff passes and changes nothing. +start sha +ct="nodkey-ansible-sha-$$" +play "$ct" "$new" broker broker-new.yml --check --diff || { show; fail "--check --diff on a new host failed"; } +docker exec "$ct" test ! -e /usr/local/bin/nodkey || fail "--check installed nodkey" +docker exec "$ct" test ! -e /etc/systemd/system/nodkey.service || fail "--check installed the unit" +pass "broker: --check --diff on a new host passes, and installs nothing" + +# --- A link in place of nodkey is never run. +docker exec "$ct" sh -c 'printf "#!/bin/sh\ntouch /ran-as-root\n" > /tmp/evil && chmod 755 /tmp/evil && ln -s /tmp/evil /usr/local/bin/nodkey' +play "$ct" "$new" broker broker-new.yml && { show; fail "a link in place of nodkey passed"; } +grep -q 'is not a file that only root can' "$work/out" || { show; fail "no error for the link"; } +docker exec "$ct" test ! -e /ran-as-root || fail "the link was run as root" +docker exec "$ct" rm -f /usr/local/bin/nodkey /tmp/evil +pass "a link in place of nodkey is refused, and not run" + +# --- A wrong SHA-256 of install.sh: nothing is installed. +play "$ct" "$new" broker broker-new.yml -e nodkey_install_sh_sha256=0000000000000000000000000000000000000000000000000000000000000000 && + { show; fail "a wrong SHA-256 passed"; } +grep -q 'does not have the SHA-256 of' "$work/out" || { show; fail "no error for the wrong SHA-256"; } +docker exec "$ct" test ! -e /usr/local/bin/nodkey || fail "a wrong SHA-256 installed nodkey" +docker exec "$ct" test ! -e /etc/systemd/system/nodkey.service || fail "a wrong SHA-256 installed the unit" +pass "a wrong SHA-256 of install.sh fails, and installs nothing" + +# --- An update: OLD first, then NEW through nodkey update. +play "$ct" "$old" broker broker-old.yml || { show; fail "the run with nodkey $old failed"; } +[ "$(installed "$ct")" = "nodkey $old" ] || fail "nodkey version is not nodkey $old" +play "$ct" "$new" broker broker-new.yml || { show; fail "the update to nodkey $new failed"; } +[ "$(result 'Update nodkey with the installed nodkey')" = changed ] || { show; fail "the update did not use nodkey update"; } +[ "$(result 'Run install.sh')" = skipping ] || { show; fail "the update ran install.sh"; } +[ "$(installed "$ct")" = "nodkey $new" ] || fail "the update did not install nodkey $new" +docker cp "$ct:/etc/systemd/system/nodkey.service" "$work/unit-host" +cmp -s "$work/unit-tag" "$work/unit-host" || fail "after the update, the unit is not the unit of the tag v$new" +pass "an update from nodkey $old to $new goes through nodkey update" + +# The role in a play of its own, without the data file: its own check +# refuses the older version too. +cat >"$work/role-old.yml" <"$work/out" 2>&1 && + { show; fail "the role took an older version"; } +grep -q "which is newer than nodkey_version $old" "$work/out" || { show; fail "no error of the role for the older version"; } +[ "$(installed "$ct")" = "nodkey $new" ] || fail "the older role changed nodkey" +pass "the role alone refuses an older version too" + +# --- The agent side. +start agent +ct="nodkey-ansible-agent-$$" +play "$ct" "$new" agent agent-new.yml --check --diff || { show; fail "agent: --check --diff on a new host failed"; } +docker exec "$ct" test ! -e /usr/local/bin/nodkey || fail "agent: --check installed nodkey" +pass "agent: --check --diff on a new host passes, and installs nothing" +play "$ct" "$new" agent agent-new.yml || { show; fail "the first run of the agent side failed"; } +[ "$(installed "$ct")" = "nodkey $new" ] || fail "nodkey version is not nodkey $new" +docker exec "$ct" grep -qx 'ConditionUser=example-user' /etc/systemd/user/nodkey-ssh-agent.service || fail "the user unit is wrong" +docker exec "$ct" test -L /etc/systemd/user/default.target.wants/nodkey-ssh-agent.service || fail "the user unit is not enabled" +docker exec "$ct" test -e /var/lib/systemd/linger/example-user || fail "linger is off" +docker exec "$ct" test ! -e /etc/systemd/system/nodkey.service || fail "the agent side installed the broker unit" +docker exec "$ct" test ! -e /home/example-user/.config || fail "the role wrote into the home directory" +pass "agent: the first run installs nodkey $new and the user unit" + +play "$ct" "$new" agent agent-new.yml || { show; fail "the second run of the agent side failed"; } +[ "$(recap_changed)" = 0 ] || { show; fail "the second run of the agent side changed something"; } +play "$ct" "$new" agent agent-new.yml --check --diff || { show; fail "the agent run with --check --diff failed"; } +[ "$(recap_changed)" = 0 ] || { show; fail "the agent run with --check --diff shows a change"; } +pass "agent: a second run, and a run with --check --diff, change nothing" + +printf 'nodkey_version: "%s"\nnodkey_ssh_agent_user: ""\n' "$new" >"$work/agent-none.yml" +docker cp "$work/agent-none.yml" "$ct:/opt/data/agent-none.yml" +play "$ct" "$new" agent agent-none.yml || { show; fail "the agent run without an account failed"; } +[ "$(result 'Stop nodkey ssh-agent of the old account')" = changed ] || { show; fail "the agent of the old account was not stopped"; } +docker exec "$ct" test ! -e /etc/systemd/user/nodkey-ssh-agent.service || fail "the user unit is still there" +docker exec "$ct" test ! -L /etc/systemd/user/default.target.wants/nodkey-ssh-agent.service || fail "the link of the user unit is still there" +pass "agent: without an account, the agent stops and the user unit is removed" + +echo "ci.sh: all tests passed" diff --git a/contrib_ansible_linux_test.go b/contrib_ansible_linux_test.go new file mode 100644 index 0000000..cd03eb3 --- /dev/null +++ b/contrib_ansible_linux_test.go @@ -0,0 +1,236 @@ +package nodkey + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "errors" + "os" + "os/exec" + "path/filepath" + "strings" + "testing" +) + +// The tests of the Ansible recipe in contrib/ansible: check-data, the +// check of a data file of the playbooks, and build.sh, which makes the +// recipe of a release. contrib/ansible/test/ci.sh runs the role itself in +// a container with systemd; CI runs it in the job "ansible". + +// ansiblePython is python3 with PyYAML, or it skips the test. In CI, it +// fails instead. +func ansiblePython(t *testing.T) string { + t.Helper() + py, err := exec.LookPath("python3") + if err == nil { + err = exec.CommandContext(context.Background(), py, "-c", "import yaml").Run() //nolint:gosec // G204: a fixed program. + } + if err != nil { + if os.Getenv("CI") != "" { + t.Fatalf("python3 with PyYAML is needed for the tests of check-data: %v", err) + } + t.Skipf("no python3 with PyYAML: %v", err) + } + return py +} + +// checkData runs check-data on a file with this text, and returns its +// exit code and its output. +func checkData(t *testing.T, text string, args ...string) (int, string) { + t.Helper() + py := ansiblePython(t) + file := filepath.Join(t.TempDir(), "host.yml") + if err := os.WriteFile(file, []byte(text), 0o600); err != nil { + t.Fatal(err) + } + argv := append([]string{"-I", "contrib/ansible/check-data"}, args...) + argv = append(argv, file) + out, err := exec.CommandContext(context.Background(), py, argv...).CombinedOutput() //nolint:gosec // G204: the test's own script. + var exit *exec.ExitError + if errors.As(err, &exit) { + return exit.ExitCode(), string(out) + } + if err != nil { + t.Fatalf("run check-data: %v", err) + } + return 0, string(out) +} + +func TestCheckDataGood(t *testing.T) { + cases := []struct { + name, side, installed, text string + }{ + {"broker, all keys", "broker", "0.7.0", "nodkey_version: \"0.8.0\"\nnodkey_restart: false\nnodkey_broker_config: /etc/nodkey/broker.toml\n"}, + {"broker, the same version", "broker", "0.8.0", "nodkey_version: \"0.8.0\"\n"}, + {"broker, no config", "broker", "none", "nodkey_version: 0.8.0\nnodkey_broker_config: \"\"\n"}, + {"agent, all keys", "agent", "none", "nodkey_version: \"0.8.0\"\nnodkey_restart: true\nnodkey_ssh_agent_user: example-user\nnodkey_ssh_agent_linger: false\n"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + code, out := checkData(t, c.text, "--side", c.side, "--installed", c.installed) + if code != 0 || !strings.Contains(out, "good for the "+c.side+" side") { + t.Fatalf("exit %d, want 0; output:\n%s", code, out) + } + }) + } +} + +func TestCheckDataBad(t *testing.T) { + cases := []struct { + name, side, installed, text, want string + }{ + {"unknown key", "broker", "none", "nodkey_version: \"0.8.0\"\nnodkey_install_sh_sha256: \"00\"\n", "the key nodkey_install_sh_sha256 is not a key of the broker side"}, + {"a key of the other side", "broker", "none", "nodkey_version: \"0.8.0\"\nnodkey_ssh_agent_user: example-user\n", "the key nodkey_ssh_agent_user is not a key of the broker side"}, + {"a broker key on the agent side", "agent", "none", "nodkey_version: \"0.8.0\"\nnodkey_broker_config: /etc/x\n", "the key nodkey_broker_config is not a key of the agent side"}, + {"wrong type of restart", "broker", "none", "nodkey_version: \"0.8.0\"\nnodkey_restart: \"no\"\n", "nodkey_restart must be true or false"}, + {"wrong type of version", "broker", "none", "nodkey_version: 1.0\n", "nodkey_version must be a version X.Y.Z"}, + {"version with a v", "broker", "none", "nodkey_version: \"v0.8.0\"\n", "nodkey_version must be a version X.Y.Z"}, + {"version with a leading zero", "broker", "none", "nodkey_version: \"0.08.0\"\n", "nodkey_version must be a version X.Y.Z"}, + {"version as a list", "broker", "none", "nodkey_version: [\"0.8.0\"]\n", "nodkey_version must be a version X.Y.Z"}, + {"older than installed", "broker", "0.8.1", "nodkey_version: \"0.8.0\"\n", "nodkey_version 0.8.0 is older than the installed nodkey 0.8.1"}, + {"older minor than installed", "agent", "0.10.0", "nodkey_version: \"0.9.9\"\n", "is older than the installed nodkey 0.10.0"}, + {"no version", "broker", "none", "nodkey_restart: true\n", "it has no nodkey_version"}, + {"a key twice", "broker", "none", "nodkey_version: \"0.8.0\"\nnodkey_version: \"0.9.0\"\n", "the key nodkey_version is there twice"}, + {"not a map", "broker", "none", "- nodkey_version\n", "it must be a map of keys"}, + {"empty", "broker", "none", "", "it must be a map of keys"}, + {"not YAML", "broker", "none", "nodkey_version: [\n", "it is not valid YAML (line"}, + {"relative config path", "broker", "none", "nodkey_version: \"0.8.0\"\nnodkey_broker_config: etc/broker.toml\n", "nodkey_broker_config must be the path of a file in /etc/nodkey/"}, + {"config path outside /etc/nodkey", "broker", "none", "nodkey_version: \"0.8.0\"\nnodkey_broker_config: /root/secret.txt\n", "nodkey_broker_config must be the path of a file in /etc/nodkey/"}, + {"config path with ..", "broker", "none", "nodkey_version: \"0.8.0\"\nnodkey_broker_config: /etc/nodkey/../shadow\n", "must not have . or .. in it"}, + {"a template", "agent", "none", "nodkey_version: \"0.8.0\"\nnodkey_ssh_agent_user: \"{{ lookup('pipe', 'id') }}\"\n", "nodkey_ssh_agent_user must be the name of an account"}, + {"a template in the path", "broker", "none", "nodkey_version: \"0.8.0\"\nnodkey_broker_config: \"/etc/nodkey/{{ x }}\"\n", "nodkey_broker_config must be the path"}, + {"user root", "agent", "none", "nodkey_version: \"0.8.0\"\nnodkey_ssh_agent_user: root\n", "nodkey_ssh_agent_user must not be root"}, + {"user with a space", "agent", "none", "nodkey_version: \"0.8.0\"\nnodkey_ssh_agent_user: \"a b\"\n", "nodkey_ssh_agent_user must be the name of an account"}, + {"a Python tag", "broker", "none", "nodkey_version: !!python/object/apply:os.system [\"true\"]\n", "it is not valid YAML"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + code, out := checkData(t, c.text, "--side", c.side, "--installed", c.installed) + if code != 1 || !strings.Contains(out, c.want) { + t.Fatalf("exit %d, want 1 and %q; output:\n%s", code, c.want, out) + } + if !strings.HasSuffix(strings.TrimSpace(out), "(exit 1)") { + t.Fatalf("the error does not end with (exit 1):\n%s", out) + } + }) + } +} + +// The error never shows a value of the file, only the names of keys. +func TestCheckDataPrintsNoValue(t *testing.T) { + const marker = "secret-looking-value-1234" + for _, text := range []string{ + "nodkey_version: \"" + marker + "\"\n", + "nodkey_version: \"0.8.0\"\nnodkey_restart: " + marker + "\n", + "nodkey_version: \"0.8.0\"\nnodkey_broker_config: \"" + marker + "\"\n", + "nodkey_version: [\"" + marker + "\"\n", + "nodkey_version: \"0.8.0\"\n\"\\e[31m" + marker + "\\nx\": 1\n", + "nodkey_version: \"0.8.0\"\n\"" + marker + " \": 1\n\"" + marker + " \": 2\n", + } { + code, out := checkData(t, text, "--side", "broker", "--installed", "none") + if code != 1 || strings.Contains(out, marker) { + t.Fatalf("exit %d, want 1 and no value in the output:\n%s", code, out) + } + } +} + +func TestCheckDataUsage(t *testing.T) { + for _, args := range [][]string{ + {"--installed", "none"}, + {"--side", "both", "--installed", "none"}, + {"--side", "broker", "--installed", "latest"}, + {"--side", "broker", "--installed", "none", "--force"}, + {"--side", "broker"}, + } { + code, out := checkData(t, "nodkey_version: \"0.8.0\"\n", args...) + if code != 64 || strings.Count(strings.TrimSpace(out), "\n") != 0 || !strings.HasSuffix(strings.TrimSpace(out), "(exit 64)") { + t.Fatalf("%v: exit %d, want 64 and one line; output:\n%s", args, code, out) + } + } +} + +// build.sh copies the install.sh and the unit of the tag into the role, +// and pins their SHA-256 in vars/main.yml. +func TestAnsibleBuild(t *testing.T) { + tag := t.TempDir() + if err := os.MkdirAll(filepath.Join(tag, "contrib", "systemd"), 0o750); err != nil { + t.Fatal(err) + } + installSh := []byte("#!/bin/sh\necho the install.sh of the tag\n") + unit := []byte("[Unit]\nDescription=the unit of the tag\n") + if err := os.WriteFile(filepath.Join(tag, "install.sh"), installSh, 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(tag, "contrib", "systemd", "nodkey.service"), unit, 0o600); err != nil { + t.Fatal(err) + } + out := filepath.Join(t.TempDir(), "recipe") + if b, err := exec.CommandContext(context.Background(), "sh", "contrib/ansible/build.sh", "1.2.3", tag, out).CombinedOutput(); err != nil { //nolint:gosec // G204: the test's own script. + t.Fatalf("build.sh: %v\n%s", err, b) + } + for _, f := range []string{"README.md", "LICENSE", "check-data", "playbooks/broker-host.yml", "playbooks/agent-host.yml", "roles/nodkey/tasks/main.yml"} { + if _, err := os.Stat(filepath.Join(out, f)); err != nil { + t.Errorf("the recipe has no %s: %v", f, err) + } + } + for name, want := range map[string][]byte{"install.sh": installSh, "nodkey.service": unit} { + got, err := os.ReadFile(filepath.Join(out, "roles", "nodkey", "files", name)) //nolint:gosec // G304: the test's own file. + if err != nil || string(got) != string(want) { + t.Errorf("files/%s is not the file of the tag: %v", name, err) + } + } + vars, err := os.ReadFile(filepath.Join(out, "roles", "nodkey", "vars", "main.yml")) //nolint:gosec // G304: the test's own file. + if err != nil { + t.Fatal(err) + } + sum := func(b []byte) string { s := sha256.Sum256(b); return hex.EncodeToString(s[:]) } + for _, line := range []string{ + `nodkey_role_version: "1.2.3"`, + `nodkey_install_sh_sha256: "` + sum(installSh) + `"`, + `nodkey_unit_sha256: "` + sum(unit) + `"`, + } { + if !strings.Contains(string(vars), line+"\n") { + t.Errorf("vars/main.yml has no line %s:\n%s", line, vars) + } + } + + // The source of the role has no pins and no files of a tag. + for _, f := range []string{"vars/main.yml", "files/install.sh", "files/nodkey.service"} { + if _, err := os.Stat(filepath.Join("contrib", "ansible", "roles", "nodkey", f)); err == nil { + t.Errorf("contrib/ansible/roles/nodkey/%s is in the repository; only build.sh makes it", f) + } + } +} + +func TestAnsibleBuildRefuses(t *testing.T) { + tag := t.TempDir() + if err := os.MkdirAll(filepath.Join(tag, "contrib", "systemd"), 0o750); err != nil { + t.Fatal(err) + } + for _, f := range []string{"install.sh", "contrib/systemd/nodkey.service"} { + if err := os.WriteFile(filepath.Join(tag, f), []byte("x\n"), 0o600); err != nil { + t.Fatal(err) + } + } + there := t.TempDir() + cases := []struct { + name string + args []string + code int + want string + }{ + {"bad version", []string{"1.2", tag, filepath.Join(t.TempDir(), "o")}, 64, `VERSION "1.2" is not X.Y.Z`}, + {"no tag dir", []string{"1.2.3", filepath.Join(t.TempDir(), "none"), filepath.Join(t.TempDir(), "o")}, 1, "install.sh is not there"}, + {"out exists", []string{"1.2.3", tag, there}, 1, "is there already"}, + {"too few", []string{"1.2.3"}, 64, "give VERSION, TAGDIR and OUTDIR"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + b, err := exec.CommandContext(context.Background(), "sh", append([]string{"contrib/ansible/build.sh"}, c.args...)...).CombinedOutput() //nolint:gosec // G204: the test's own script. + var exit *exec.ExitError + if !errors.As(err, &exit) || exit.ExitCode() != c.code || !strings.Contains(string(b), c.want) { + t.Fatalf("err %v, want exit %d and %q; output:\n%s", err, c.code, c.want, b) + } + }) + } +} diff --git a/docs/releasing.md b/docs/releasing.md index ae79fbe..fe86d53 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -176,7 +176,9 @@ After every push to `main`, the **Release** workflow runs release-please. one with `LICENSE` and `README.md` into `nodkey__linux_.tar.gz`. It packs the files of `contrib/pullgate/` with `LICENSE` into - `nodkey__pullgate.tar.gz`, and writes `SHA256SUMS`. + `nodkey__pullgate.tar.gz`. It makes the Ansible recipe + with `contrib/ansible/build.sh` and packs it into + `nodkey__ansible.tar.gz`, and writes `SHA256SUMS`. - `publish` gets these files from `build`. It checks them against `SHA256SUMS` and checks the tag again. Then it makes a signed build provenance attestation for the tarballs. It saves the attestation as @@ -400,6 +402,10 @@ A release has these files: - `nodkey__pullgate.tar.gz`: the pullgate recipe, the files of `contrib/pullgate/` and `LICENSE` (docs/setup.md, "Change the config from git with pullgate"). Releases before 0.7.0 do not have it; +- `nodkey__ansible.tar.gz`: the Ansible recipe, the role, the + playbooks and `check-data` of `contrib/ansible/`, with the `install.sh` + and the unit of the tag in the role, and `LICENSE` + (contrib/ansible/README.md). Releases before 0.8.0 do not have it; - `SHA256SUMS`: the SHA-256 of all tarballs; - `nodkey_.sigstore.json`: the build provenance attestation of all tarballs, as a Sigstore bundle. 0.1.0 does not have this file. diff --git a/docs/setup.md b/docs/setup.md index 63924ce..869d4b3 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -136,7 +136,8 @@ broker, which trusts nothing from the client: a changed client binary gets no more than what you approve on the phone ([THREAT-MODEL.md T20](../THREAT-MODEL.md)). -There are two ways to install: the installer, or by hand. +There are three ways to install: the installer, the Ansible role, or by +hand. ### The installer @@ -184,6 +185,21 @@ Later, `nodkey update` runs the copy of the installer that is built into the installed nodkey ([section 13](#a-new-version-of-nodkey)). It takes `--version`, `--gh` and `--reinstall` too. +### The Ansible role + +For hosts that you run with Ansible, the release file +`nodkey__ansible.tar.gz` (from 0.8.0 on) holds a role that +does the steps of this guide: it installs nodkey with the installer of +the same tag, and the same checks. On the broker host, it also makes the +user `nodkey`, `/etc/nodkey`, an empty `/etc/nodkey/credentials` and the +unit of section 8. On an agent machine, it can add the `nodkey ssh-agent` +user unit of section 11. Later, it updates nodkey only with +`nodkey update` of the installed nodkey, and never to an older version. +It never writes the config or a credential. Two fixed playbooks run it +from a data file, for a host that keeps only data in its repository. +How to get it, check it and use it: +[contrib/ansible/README.md](../contrib/ansible/README.md). + ### By hand Use a trusted machine for this, never an agent machine @@ -2714,6 +2730,12 @@ get a silent notice that names that client. `nodkey update --version 0.2.0`. Then restart `nodkey ssh-agent` there. +With the Ansible role ([section 2](#the-ansible-role)), get the role of +the new release, and run it instead of steps 2 to 5. It runs +`nodkey update`, installs the unit of the new tag, and restarts the +broker and `nodkey ssh-agent`, unless you set `nodkey_restart: false`. Keep your changes to the unit in a +drop-in, as its README says. + A restart ends all grants. Rarely, right after a restart, Telegram reports a polling conflict, and the broker stops with exit code 76: a poll of the old broker was still on its way