Accounts and sudo
The operator and agent accounts, their passwords, how much the agent may do as root, and how Rookery logs in to hosts.
Every host has two accounts, set under Operator Account and Agent Account on the host's Settings tab:
| Account | Default name | For |
|---|---|---|
| Operator | ops | You: SSH, Cockpit, the console and the laptop's login |
| Agent | agent | The coding agents that plugins install, T3 Code if installed, and the virtual desktop. Its home is /home/agent |
Separate accounts keep sessions apart, but they do not isolate data from an agent that can become root.
The operator
The operator is the account Rookery manages the host with. On every host it:
- Uses sudo without a password. The role writes
/etc/sudoers.d/99-rookery-operator. - Logs in over SSH with keys only.
/etc/ssh/sshd_config.d/00-rookery-operator.confholds aMatch Userblock that allows only key logins for it, whatever SSH hardening says. - Takes the SSH key of each installation that installs or applies the host. Each of these keys has a block of its own in the operator's
~/.ssh/authorized_keys, and no later apply removes it. An apply stops with an error before it changes SSH if that key is not there.
None of these can be switched off, on laptops either.
The operator's password is optional and only for local logins: the console, the laptop's graphical login and Cockpit. Cockpit checks it through PAM, not through SSH. Without a password the account's password field is *. No password logs in then, and SSH keys still do.
| Install | Operator password |
|---|---|
| USB installer | Required. The Ubuntu installer needs one for the account it creates |
| Cloud seed or created machine | Optional |
| Apply over SSH or to this machine | Optional. An empty one leaves the account's password as it is |
Passwords
On a password hash field, F4 generates a password and stores its hash, and F5 hashes a password you type. Rookery keeps a generated password in its store, beside the profile, and rookery host credentials NAME shows it. For a Rookery server's host the server generates it and keeps it. The profile itself only stores hashes.
- An empty agent password locks password login for the agent.
- Turning off the agent's passwordless sudo requires an agent password.
The first apply as another account
An existing machine may not have the operator yet. Rookery then applies as an account of the machine's own, the profile's SSH user. When sudo prompts that account for a password, switch on Ask for sudo password on the Run tab, or set access.sudo to password. Rookery asks for the password when it applies and when it connects, or takes the secret sudo/HOST when you keep it there. --sudo-password-stdin gives it where nobody can type it.
When the SSH user is the operator, Rookery writes what the apply made true once it has worked: access.sudo becomes none, a login with password becomes one with Rookery's key, and a kept sudo/HOST or ssh/HOST is deleted. The operator's sudo doesn't prompt from then on, and its SSH takes keys only. Any other SSH user keeps its setting.
Agent privileges
agent_privileges in the profile, Agent privileges on the Settings tab:
| Level | The agent's sudo |
|---|---|
full | Everything, without a password. For machines you can throw away |
limited | apt-get and apt with update, install, upgrade, dist-upgrade, full-upgrade and autoremove, and systemctl restart of plugin services that run as the agent. New profiles start here |
none | Nothing |
Under limited and none the agent cannot change SSH, Tailscale, the firewall, the operator's account or rookeryd.
limited guards against accidents, not intent
What a package installs runs as root, so an agent that may install packages can become root if it tries. An agent with full can administer the whole host. Use a dedicated machine or VM either way.
A profile without the setting has full, or sudo with the agent's password when agent_passwordless_sudo is off.
Logging in as the agent
On the host, switch from the operator to the agent:
sudo -iu agentFrom your machine, rookery ssh HOST --agent opens a shell as the agent, and the overview's Terminal switches between the two accounts with Space.
Logging in to hosts
Rookery reaches a host over SSH, as the SSH user of the host's Install tab, access.user in the profile. Log in with under the address says how, in access.auth:
| Method | auth | What Rookery gives ssh | Where |
|---|---|---|---|
| Rookery's key | rookery | The key rookery of its key ring, and no other. The default | Local and server |
| Another key | key:NAME | That key of the key ring, and no other | Local and server |
| Password | password | The password kept as the secret ssh/HOST, through Rookery's own askpass helper | Local and server |
| Your SSH | ssh | Your SSH configuration and agent, with Rookery's key offered after your keys | Local Rookery only |
A password never goes into a command line or an environment variable. Rookery is ssh's askpass helper itself and reads the password from the store when ssh asks. No other program is asked, so no password dialog of the desktop opens. Without a stored password Rookery's own logins fail and say so, and rookery ssh HOST asks on the terminal. For an apply, Rookery writes the password to a private file that Ansible reads, and Ansible gives it to ssh through its own helper.
rookery secret set ssh/studio # the SSH password of studio
rookery secret set sudo/studio # its sudo password, if you want it keptA host that Rookery reaches through access.link, such as a container, doesn't use a key.
Keys
Rookery keeps SSH keys in its store, by name, sealed when the store is encrypted. The key rookery always exists. Rookery writes a private half to keys/NAME in its data directory when ssh or Ansible needs it, and rookery host inventory names that file. Private halves never leave through the API or a command.
rookery key list # the keys, the hosts that use each, and what is pending
rookery key create deploy # make an ed25519 key
rookery key import deploy ~/.ssh/deploy # take in a private key; - reads standard input
rookery key show deploy # the public half, for an authorized_keys
rookery key remove deploy # refused while a host logs in with itRookery takes any private key ssh-keygen reads, and refuses one with a passphrase, as nobody would be there to type it. With a Rookery server set, these commands act on the server's keys. The Settings tab of the home screen lists the keys, and Enter copies a public half.
First contact
A machine Rookery did not set up doesn't take Rookery's key yet. Give it a password or a private key that works once:
rookery key trust studio # asks for the password without echo
rookery key trust studio --key ~/.ssh/provider_keyRookery tries the host's key first. If the host refuses it, Rookery logs in once with what you gave and adds the key to the SSH user's ~/.ssh/authorized_keys. The other lines of that file stay as they are. Then Rookery checks that a login with the key works, and forgets the one-time credential. A host whose method was password logs in with Rookery's key from then on, unless you add --keep-password, which keeps the password as the secret ssh/HOST.
Refused logins
sshd counts failed logins from each address. OpenSSH 10 then turns that address away for a while (PerSourcePenalties, on by default), and the wait grows with each failure, up to 10 minutes. A Rookery that kept trying a key a host refuses would shut itself out of that host, and of every other host behind the same address.
So Rookery remembers a refused login beside the host. For 30 minutes nothing Rookery does by itself logs in that way again, such as the Rookery server's channel to the host or the overview opening. The host shows why instead. Whatever you ask for still tries once, such as Try again or rookery key trust. A changed address, user, port or key is another login and is tried at once, and a login that works forgets the refusal. rookery key trust asks for the credential straight away while the key's refusal holds. The host then sees one failed login at most.
When sshd closes the connection before the login, Rookery says the host is turning the address away for a while. Wait a minute and try again. Rookery itself waits 2 minutes before it tries such a host by itself.
Host keys
Rookery records each host's SSH host key in its store and gives ssh a known-hosts file of its own for each host, under known_hosts/ of the data directory, written from the store. So a restored installation knows its hosts. The first login records the key and prints its fingerprint. A key that changes later is refused:
The SSH host key of studio is not the one rookery recorded: the machine was set up again or replaced, or something is in between. If you know which, accept the new key with: rookery host verify studio --acceptWhere the first key comes from depends on where the server runs:
| You run Rookery | The first host key |
|---|---|
With no server set, or with a rookery serve of your own on this machine | The key ~/.ssh/known_hosts of the server's user has for the host's address, when it has one. Otherwise the key the host shows at the first login |
| With a server elsewhere | The key the host shows the server at the first login. Nothing of your own files is sent to the server. Compare the fingerprint it prints, or rookery host verify studio, with the host's own |
rookery host verify studio shows the recorded key. When Rookery itself creates a host's machine again, it forgets the old key and records the new one without asking.
Rekeying
rookery key rotate replaces the key rookery, and rookery key rotate NAME another one:
- Rookery makes a new key and stores it beside the current one as pending.
- On each host that takes the key, it logs in and adds the new key. Once a login with the new key works, it removes the old one.
- A host that does not answer stays pending. Rookery offers it both keys until then, and an apply gives the operator both. The Hosts tab marks it.
- When no host is pending, the new key replaces the old one, which is deleted.
Running it again goes on where it stopped. With a Rookery server set, the rotation runs as a job on the server, and its output is shown as it comes.
Sudo
access.sudo says whether the SSH user's sudo asks for a password: none or password. Left out, Rookery asks only when the operator has no passwordless sudo and the user is not root. Rookery asks for the password when it needs it, or takes the secret sudo/HOST if you keep it there. It reaches sudo on standard input.
Last updated on