Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/docs/2-handbook/external-accounts/ssh.md

104 lines
4.1 KiB
Markdown

# 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.
Agent-side, nothing changes until you do both of these:
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.
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.
## 1. Switch it on for an agent
In the agent's config:
```nix
services.hyperhive.agent.ssh = {
enable = true;
hosts.testvm = {
hostName = "10.0.0.7";
user = "test";
port = 22; # the default
hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
};
};
```
`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.
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
until a separate allowance exists; the default `log` lets it through. See
[the network page](../../4-implementation/networking/network.md).
## 2. Make a machine trust the CA
On the swarm's store host, read the CA's public key:
```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
name its identity carries, so atlas can't obtain one that says maia.
- The certificate lasts an hour, and the agent signs a new one every 20
minutes. The key lives in the agent's `/run` (memory) and never reaches disk.
A new container start makes a new key.
- It signs ed25519 user keys only, and the certificate allows a terminal
(`permit-pty`) and nothing else.
## 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.
For the bao paths, field names and units, see
[the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md).