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

4.1 KiB

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:

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.

2. Make a machine trust the CA

On the swarm's store host, read the CA's public key:

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:

{
  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.