From d0d747afe0cc335e423a203523640b70d601887f Mon Sep 17 00:00:00 2001
From: Geno Roupsky <185580+groupsky@users.noreply.github.com>
Date: Mon, 9 Nov 2026 07:52:36 +0200
Subject: [PATCH 1/2] docs: keep only key lines from ssh-keyscan, and count
 them in step 3

---
 docs/setup.md | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/setup.md b/docs/setup.md
index d8294b4..98a354d 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -1003,11 +1003,19 @@ of an agent machine: the agent can change that file.
 
    ```sh
    ssh-keyscan -t ed25519,ecdsa,rsa web-1.example.com 2>/dev/null |
-     awk '{print "web-1", $2, $3}' >> /run/nodkey-setup/known_hosts
+     awk '$1 !~ /^#/ {print "web-1", $2, $3}' >> /run/nodkey-setup/known_hosts
    ssh-keyscan -t ed25519,ecdsa,rsa -p 2222 web-2.example.com 2>/dev/null |
-     awk '{print "web-2", $2, $3}' >> /run/nodkey-setup/known_hosts
+     awk '$1 !~ /^#/ {print "web-2", $2, $3}' >> /run/nodkey-setup/known_hosts
    ```
 
+   `ssh-keyscan` also prints a comment line for each host, such as
+   `# web-1.example.com:22 SSH-2.0-OpenSSH_9.8`. Since OpenSSH 9.8 it
+   prints these lines on stdout, not on stderr
+   ([commit 1e84d0c](https://github.com/openssh/openssh-portable/commit/1e84d0cf40e94ae3a77d6a7ca8c036d8e3d55a40)),
+   so `2>/dev/null` does not remove them. The `awk` drops every line
+   that starts with `#`, so the file gets only key lines with each
+   version.
+
 3. Show the fingerprints of the fetched keys, and compare them with the
    list from step 1. Each one must be the same. If one differs, stop:
    something between the broker host and that host may change the keys.
@@ -1016,6 +1024,23 @@ of an agent machine: the agent can change that file.
    ssh-keygen -lf /run/nodkey-setup/known_hosts
    ```
 
+   `ssh-keygen -lf` skips a line that is not a key, and says nothing.
+   So also check that the file has one line for each fingerprint. The
+   two numbers must be the same:
+
+   ```sh
+   wc -l < /run/nodkey-setup/known_hosts
+   ssh-keygen -lf /run/nodkey-setup/known_hosts | wc -l
+   ```
+
+   If the first number is bigger, a line is not a key. This command
+   shows each such line with its number. Remove them, and run the check
+   again:
+
+   ```sh
+   awk '$2 !~ /^(ssh-|ecdsa-)/ {print NR ": " $0}' /run/nodkey-setup/known_hosts
+   ```
+
 4. Install the file:
 
    ```sh

From a48e97153a9a70efb8ca6dd5be99e8e0aa73217e Mon Sep 17 00:00:00 2001
From: Geno Roupsky <185580+groupsky@users.noreply.github.com>
Date: Mon, 9 Nov 2026 07:53:36 +0200
Subject: [PATCH 2/2] docs: note the commit message of 1e84d0c, and accept sk-
 keys in the check

---
 docs/setup.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/setup.md b/docs/setup.md
index 98a354d..3881ffc 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -1012,7 +1012,8 @@ of an agent machine: the agent can change that file.
    `# web-1.example.com:22 SSH-2.0-OpenSSH_9.8`. Since OpenSSH 9.8 it
    prints these lines on stdout, not on stderr
    ([commit 1e84d0c](https://github.com/openssh/openssh-portable/commit/1e84d0cf40e94ae3a77d6a7ca8c036d8e3d55a40)),
-   so `2>/dev/null` does not remove them. The `awk` drops every line
+   so `2>/dev/null` does not remove them. (The message of that commit
+   says the opposite, but its code moves the lines to stdout.) The `awk` drops every line
    that starts with `#`, so the file gets only key lines with each
    version.
 
@@ -1038,7 +1039,7 @@ of an agent machine: the agent can change that file.
    again:
 
    ```sh
-   awk '$2 !~ /^(ssh-|ecdsa-)/ {print NR ": " $0}' /run/nodkey-setup/known_hosts
+   awk '$2 !~ /^(ssh-|ecdsa-|sk-)/ {print NR ": " $0}' /run/nodkey-setup/known_hosts
    ```
 
 4. Install the file: