swarm ui ssh row with target snippets, docs for the per-agent switch
This commit is contained in:
parent
624d5f24f8
commit
e621397252
1 changed files with 417 additions and 94 deletions
|
|
@ -1,44 +1,33 @@
|
|||
# SSH access to a machine
|
||||
|
||||
Let an agent SSH into a machine you name, such as a test VM, without copying a
|
||||
key onto it. The agent holds no standing SSH key. It asks the swarm's secret
|
||||
store for a certificate that lasts an hour, and the machine trusts the swarm's
|
||||
SSH certificate authority (CA) instead of a list of keys.
|
||||
key onto it. The agent holds no standing SSH key. While you allow it, the agent
|
||||
gets a certificate from the swarm's SSH certificate authority (CA) that lasts
|
||||
an hour. The machine trusts the CA, so it needs no list of keys.
|
||||
|
||||
Agent-side, nothing changes until you do both of these:
|
||||
Two things have to be true before an agent gets in:
|
||||
|
||||
1. Switch SSH on for the agent and name the machines it may reach.
|
||||
2. Make each machine trust the CA and list the agents allowed in.
|
||||
1. **You switch SSH on for that agent**, in the swarm UI.
|
||||
2. **The machine trusts the CA** and lists the agent.
|
||||
|
||||
The permission to get a certificate is in the policy every agent shares, so
|
||||
every agent with a store identity can already get a certificate for its own
|
||||
name, whether or not you switch SSH on for it. That's harmless: no machine
|
||||
trusts a name it doesn't list. Switching SSH on only sets up the key, the
|
||||
renewal and the client config.
|
||||
Every agent already has an SSH client, a key it makes in memory, and a
|
||||
certificate unit. The switch alone decides whether the swarm signs.
|
||||
|
||||
## 1. Switch it on for an agent
|
||||
|
||||
In the agent's config:
|
||||
Open the agent's card in the swarm UI and find the **ssh** row. Select it and
|
||||
tick **allow the agent to get SSH certificates**. The default is off. The
|
||||
agent has a certificate within about 25 minutes of the change. Untick the box
|
||||
to stop new certificates. The row also shows the three forms of the target
|
||||
setup below, already filled in with the swarm's CA key and the agent's name.
|
||||
|
||||
```nix
|
||||
services.hyperhive.agent.ssh = {
|
||||
enable = true;
|
||||
hosts.testvm = {
|
||||
hostName = "10.0.0.7";
|
||||
user = "test";
|
||||
port = 22; # the default
|
||||
hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
|
||||
};
|
||||
};
|
||||
```
|
||||
The agent then runs `ssh user@host`, with no other setup. It offers its
|
||||
certificate and nothing else.
|
||||
|
||||
`hostKey` is the machine's own host public key, the one line in
|
||||
`/etc/ssh/ssh_host_ed25519_key.pub` on it. The agent pins it: it refuses a
|
||||
machine that presents any other key, and never trusts a key on first sight.
|
||||
|
||||
The agent then runs `ssh testvm` with no other flag. The agent's SSH client
|
||||
offers its certificate and nothing else. The option needs the agent to have a
|
||||
store identity, the same as for its other store credentials.
|
||||
**Host keys use trust on first use.** The agent accepts the key a machine
|
||||
shows on the first connection, keeps it in its state directory (so it survives
|
||||
restarts), and refuses a changed key afterwards. A swapped machine on the first
|
||||
contact would go unnoticed. The row's explainer says so.
|
||||
|
||||
This doesn't open the network. If you set the hive's `egress.forward` to
|
||||
`reject`, the hive refuses the agent's direct connection to the machine's port
|
||||
|
|
@ -47,33 +36,31 @@ until a separate allowance exists; the default `log` lets it through. See
|
|||
|
||||
## 2. Make a machine trust the CA
|
||||
|
||||
On the swarm's store host, read the CA's public key:
|
||||
Open **on the target** in the same row. It shows the swarm's CA public key, a
|
||||
public value, and the agent's name, in three forms. Replace `<user>` with the
|
||||
account the agent logs in as. The target never contacts the swarm.
|
||||
|
||||
- **NixOS:** the CA key in `services.openssh.settings.TrustedUserCAKeys` and
|
||||
`users.users.<user>.openssh.authorizedPrincipals = [ "<agent>" ];`. The same
|
||||
as one module: import `hyperhive.nixosModules.agent-ssh-target` and set
|
||||
`services.hyperhive.agentSshTarget` (`enable`, `caPublicKey`,
|
||||
`principals.<user>`).
|
||||
- **home-manager:** `home.file.".ssh/authorized_keys".text` holding one
|
||||
`cert-authority` line.
|
||||
- **plain ssh:** one line in the account's `~/.ssh/authorized_keys`:
|
||||
|
||||
```
|
||||
cert-authority,principals="<agent>" ssh-ed25519 AAAA…
|
||||
```
|
||||
|
||||
This works on any machine without a change to its sshd config.
|
||||
|
||||
To read the CA key outside the UI, run this on the swarm's store host:
|
||||
|
||||
```bash
|
||||
bao read -field=public_key ssh-agents/config/ca
|
||||
```
|
||||
|
||||
The store also serves the same key without a token at
|
||||
`<store address>/v1/ssh-agents/public_key`. The key is public and you set it
|
||||
once. Then import the module on the machine, which can be any NixOS machine,
|
||||
and not only a hive host:
|
||||
|
||||
```nix
|
||||
{
|
||||
imports = [ hyperhive.nixosModules.agent-ssh-target ];
|
||||
|
||||
services.hyperhive.agentSshTarget = {
|
||||
enable = true;
|
||||
caPublicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
|
||||
principals.test = [ "atlas" "maia" ];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
`principals.<user>` lists the agents that may log in as that local account. The
|
||||
account has to exist. An account with no entry accepts no certificate. The
|
||||
module writes no `authorized_keys`.
|
||||
|
||||
## What an agent can and can't do
|
||||
|
||||
- It can only get a certificate for **its own name**. The store signs for the
|
||||
|
|
@ -86,19 +73,17 @@ module writes no `authorized_keys`.
|
|||
|
||||
## Revoking access
|
||||
|
||||
- **One agent from one machine:** remove its name from that user's
|
||||
`principals` and deploy the machine. The next login attempt fails.
|
||||
- **One agent from every machine:** remove its name from every machine's
|
||||
`principals`. That's the revocation. No swarm-wide switch
|
||||
stops signing for an agent that a hive still declares: if you delete
|
||||
its cert-auth role `hive-agent-<name>` in the store, `swarm-controller`
|
||||
writes it back within five minutes. Signing stops only once no hive declares
|
||||
the agent any more (you destroyed it); the controller then stops renewing
|
||||
its store identity, and the identity lapses with its 7-day certificate.
|
||||
- **A certificate already issued** stays valid until it expires, at most three
|
||||
hours, whatever you remove. Removing a principal blocks new logins at once.
|
||||
- **The CA itself:** if the CA key changes, every machine needs the
|
||||
new public key. Nothing replaces the CA by itself.
|
||||
- **One agent from one machine:** remove its principal (the `authorizedPrincipals`
|
||||
entry, or the `cert-authority` line) and deploy the machine. The next login
|
||||
attempt fails.
|
||||
- **One agent from every machine:** untick the switch. The swarm stops signing
|
||||
for it within five minutes; an agent already signed in can still sign
|
||||
for up to an hour. Destroying the agent cuts its store identity off within
|
||||
minutes. Either way a certificate already signed stays valid until it
|
||||
expires, at most three hours, so removing the principal on a machine is what
|
||||
cuts it off there at once.
|
||||
- **The CA itself:** if the CA key changes, every machine needs the new public
|
||||
key. Nothing replaces the CA by itself.
|
||||
|
||||
For the bao paths, field names and units, see
|
||||
[the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md).
|
||||
|
|
|
|||
Loading…
Reference in a new issue