mesh-tools
acf075fa63
mesh/merge-gate head acf075fa63cc merged into trunk 9675babf528b — pass: builds ssh-client → ace, g14, novox, shanks; no bus step; every machine composes w…
mesh/repo-check head acf075fa63cc merged into trunk 9675babf528b — pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (go), merge-…
mesh/delivery delivered
ssh-client owns ~/.ssh, but treated every file it did not place as found, so a predecessor's drop-in and old copies stayed there for weeks. Its process now sweeps at start and every ten minutes: keys at any depth (and links to them), authorized_keys, authorized_keys2 and sockets stay, and a folder holding one is gone into; everything else moves to ~/.local/state/ssh-client/retired/<UTC time>/, a folder never shared with another sweep, with a list beside it, which ssh_client_check shows. Nothing is deleted.
114 lines
8.0 KiB
Markdown
114 lines
8.0 KiB
Markdown
# ssh-client
|
|
|
|
The operator account's `~/.ssh` as a module (novox/hq research 027/03, ADR 0182; to-be 42 phase 1,
|
|
item 9). `sshd` is the machine's side.
|
|
|
|
## What it declares, by ADR 0182's classes
|
|
|
|
| path | class | how |
|
|
|---|---|---|
|
|
| `~/.ssh/` | owned | directory, the account's, mode 0700 |
|
|
| `~/.ssh/config.d/` | owned | directory, the account's, mode 0700. It holds only the files this module declares (ADR 0415 §6). As every module's owned path, ssh-client is the only module that writes under `~/.ssh`: another module that needs a host there provides it through a provision, and this module writes it (ADR 0349 §1; the forge's host comes from `forge-account`). A host of the operator's own goes in `~/.ssh/config` below the mesh's region |
|
|
| `~/.ssh/config.d/10-forge` | owned | the forge's host, with the machine's own key (ADR 0399) |
|
|
| `~/.ssh/mesh_ed25519`, `.pub` | written by the module's own process | the machine's account's key for the forge, made once (keykeeper.go) |
|
|
| `~/.ssh/config.d/00-mesh` | owned | a Host block per other machine of the mesh (a roster fact), regenerated whenever a machine joins, leaves or is renamed. It begins with the mesh's header |
|
|
| `~/.ssh/config` | written into, **at the start** | the mesh's region, `# BEGIN mesh ssh-client.config` … `# END …`. It holds one `Include ~/.ssh/config.d/*`. Every line below the region is the operator's, kept byte for byte |
|
|
| `~/.ssh/authorized_keys` | found | see *The gap* |
|
|
| `~/.ssh/known_hosts` | found | see *The gap* |
|
|
| private keys, public keys, certificates | kept | never read, never written, never moved, at any depth and whatever their name. `ssh_client_keys` and `ssh_client_check` read a file's first line to recognise a key, and ask `ssh-keygen` about it |
|
|
| anything else | swept | moved out of `~/.ssh` by the sweep (below) |
|
|
|
|
### Why an include, not Host blocks in the region
|
|
|
|
ssh takes the first value it finds for each option. Research 027/03 asks that the mesh's hosts come
|
|
before anything else in `~/.ssh/config`. Before this change, the region was written at the end: a
|
|
predecessor's hosts above it won, for the same machines.
|
|
|
|
A roster fact cannot be placed at the start. The controller gives facts no `at`, and the host leaves
|
|
an existing region where it is. So the region at the start holds only the include, and the hosts
|
|
are a whole file in `config.d` that the include reads first. `00-` sorts it before any other drop-in.
|
|
|
|
ssh restores the including file's section after an `Include` (OpenSSH `readconf.c`). So an operator
|
|
line just below the region is global again, as it was at the top of the file. This module's tests
|
|
parse the declared region and check it, and `ssh -G` was compared before and after on every machine.
|
|
|
|
The old region, `ssh-client.fact-ssh-config` at the end of `~/.ssh/config`, is no longer declared, so
|
|
the host removes it, and only it, at the first push.
|
|
|
|
## The gap: authorized keys and known hosts
|
|
|
|
Research 027/03 gives the mesh a region in `authorized_keys` (the operator's keys as the mesh records
|
|
them) and one in `known_hosts` (every machine's host key). **The controller holds neither fact.**
|
|
|
|
- A roster template sees each machine's name, mesh name, address and account, and nothing else
|
|
(mesh-controller `roster.go`).
|
|
- No machine fact carries an ssh host key.
|
|
- The only key the controller knows for the operator is a sealing key for secrets, not an ssh key.
|
|
|
|
So both files stay *found*, and this module invents nothing.
|
|
|
|
**What would close it:**
|
|
|
|
1. The host reports its machine's public host keys in its profile, and the roster gains a field for
|
|
them.
|
|
2. The operator's public keys become a mesh record: per account, with a comment saying whose and
|
|
where.
|
|
|
|
Each region is then one more `into: block` resource here. Until then, `ssh_client_check` reads the
|
|
files as they are, and `ssh_client_revoke` / `ssh_client_known_host` act on them by hand.
|
|
|
|
## The sweep: `~/.ssh` holds only what this module knows (ADR 0415, issue 1017)
|
|
|
|
The module owns `~/.ssh`, so it keeps it to what it knows. Its process sweeps when it starts and every
|
|
ten minutes. It knows the paths in the table above, every key (a private key by its first line, a
|
|
public key or certificate by its line, at any depth and whatever its name) and sockets (ssh's own
|
|
runtime). Every other path is moved, whole, into
|
|
`~/.local/state/ssh-client/retired/<UTC time>/`, keeping its path relative to `~/.ssh`, and the list
|
|
of what moved is written beside it as `<UTC time>.json`. Nothing is deleted. A folder that holds a key
|
|
is gone into rather than moved whole, so the key stays where it is. A file or folder that cannot be read to
|
|
tell whether it holds a key is left and named in the log.
|
|
|
|
So the predecessor's `config.d/mesh`, `config.bak-*`, `known_hosts.old`, `removed-*` and
|
|
`authorized_keys.revoked-*` leave `~/.ssh` at the first sweep. Each move is logged by the process, and
|
|
`ssh_client_check` lists every sweep that moved something, with where each path lies now.
|
|
|
|
The predecessor's lines inside `~/.ssh/config`, below the mesh's region (its header comment and its
|
|
`Include ~/.ssh/config.d/mesh`), are the operator's part of a written-into file and stay. ssh skips an
|
|
`Include` that matches no file.
|
|
|
|
## Tools
|
|
|
|
They run as the operator account and never escalate. No answer carries a key: fingerprints only.
|
|
|
|
| tool | | what |
|
|
|---|---|---|
|
|
| `ssh_client_hosts` | r | every Host and Match section in the order ssh reads it, each with file, line and source (`mesh`, `drop-in`, `operator`); duplicates; what is set outside any section |
|
|
| `ssh_client_resolve` | r | `ssh -G` for one host: what ssh would use, and which sections matched |
|
|
| `ssh_client_check` | r | modes of the directory and every file; keys with no passphrase (`ssh-keygen -y -P ""`, output used only to compare with the `.pub`), weak, old, unused, or whose `.pub` is another key's; one key under several names; the mesh's region first with its include; duplicate hosts; `known_hosts` for the mesh's machines, missing or stale (scanned live, 5 s each in parallel, unless `scan` is false); authorized keys without a comment; debris; what the sweep moved out of `~/.ssh` and where each lies now. It says what it did not check |
|
|
| `ssh_client_keys` | r | every private key, by its public half: type, size, fingerprint, comment, mode, age, passphrase, whether ssh offers it by itself |
|
|
| `ssh_client_authorized` | r | `authorized_keys` by fingerprint, type, size, comment and options |
|
|
| `ssh_client_revoke` | a | removes every line with one fingerprint, keeping the file first as `authorized_keys.revoked-<time>`. It refuses the last key (a lockout) and a key in a mesh region (a push would write it back) |
|
|
| `ssh_client_known_host` | r/a | known entries against what the host offers now: `matches`, `changed`, `not known` or `unreachable`. With `refresh`, it replaces the host's entries through `ssh-keygen -R` (which keeps `known_hosts.old`) with what was scanned. That trusts whatever answers |
|
|
| `ssh_client_test` | r | one batch-mode connection that runs only `true`: the address reached, the method and key that authenticated, or why not and which keys were offered. A key with a passphrase works only through an agent. The runtime has none in its environment, so the tool looks for the account's agent socket under `/run/user/<uid>` and names the one it used, or says there was none |
|
|
|
|
## Tests
|
|
|
|
```
|
|
go test ./...
|
|
```
|
|
|
|
The tests use a temporary home and a fake runner, with public keys made for the tests only. They cover:
|
|
|
|
- reading order and source across includes, with an operator line after the include being global
|
|
again;
|
|
- the declared region parsed as ssh reads it;
|
|
- duplicates;
|
|
- keys: fingerprints computed as `ssh-keygen -l` does, RSA size, passphrase asked and never prompted,
|
|
a mismatched `.pub`;
|
|
- `authorized` never printing a key;
|
|
- `revoke`: the backup, the mode kept, a lockout refused, a mesh region refused;
|
|
- `known_host` matching, changed and refreshed, and an unreachable host never refreshed;
|
|
- `test`: success, and failure with the agent named;
|
|
- `check`'s findings;
|
|
- that the tools served are the manifest's `tools`.
|