Profile
The fields of a host profile, which Rookery keeps in its store, and where each is set in the terminal UI.
A profile is a JSON document that describes one host. Rookery keeps it in its store and writes it from the set-up tabs. The fields below can also be edited by hand: write the profile to a file, change it and save it back.
rookery host export studio > studio.json
rookery host import studio studio.json--set - reads the profile from standard input. Rookery checks it as the terminal UI reads a profile and saves it as it is. The profile of a Rookery server's host is saved on the server.
A profile can also stay in a file of its own. rookery host import studio studio.json saves one from a file, and rookery host export studio writes it out again.
Settings of the Ansible role go under ansible_vars, and how Rookery reaches and installs the host under builder.
{
"hostname": "studio",
"target": "laptop",
"operator_username": "ops",
"operator_ssh_public_keys": ["ssh-ed25519 AAAA... you@workstation"],
"agent_username": "agent",
"agent_privileges": "limited",
"target_disk_mode": "auto",
"keyboard": "us",
"ansible_vars": {
"rookery_plugin_features": ["github/cli", "unity/cli"]
},
"access": { "address": "studio.example.ts.net", "user": "ops", "auth": "rookery" }
}Host
Prop
Type
Accounts
Prop
Type
The operator always has sudo without a password and logs in over SSH with keys only. See Accounts and sudo.
The key of Rookery itself
Each installation makes an ed25519 key of its own the first time it needs one: the key rookery of its key ring. It keeps the key in its store. An installation restored from the store gets the same key back. The operator of a host always takes it along with the keys in the profile, so the Rookery that set a host up can always log in to it without a key of yours. That matters most for a Rookery server, which has no keys until you give it some. A host that logs in with another key of the ring, key:NAME, takes that key too. During a rotation the operator takes the new key as well.
rookery key show prints the public half. To copy it, choose This Rookery's SSH key on the Settings tab of the home screen. With a Rookery server set, it copies the server's key.
Add the key as an SSH key at your cloud provider, and every machine you create there takes it. Rookery then logs in to a new machine without a key of yours. On a host set up some other way, add it to the operator's ~/.ssh/authorized_keys.
Each installation that installs or applies a host leaves its key there in a block of its own in the operator's ~/.ssh/authorized_keys. A later apply, from this installation or another, does not remove it. To take a Rookery's key away, delete its ROOKERY block by hand.
USB installer
Prop
Type
Role settings (ansible_vars)
Any rookery_ setting of the role. The ones the terminal UI edits:
| Setting | In Rookery | Default |
|---|---|---|
rookery_plugin_features | Features tab | github/cli |
rookery_tools_* (one per category) | Features tab | on |
rookery_install_playwright | Features tab | on |
rookery_software_rendering | Software graphics, Features tab | on |
rookery_geometry | Desktop size, under Desktop on the Settings tab | 1600x900 |
rookery_bootstrap_ssh_cidr | Recovery SSH CIDR, Settings tab | none |
rookery_harden_ssh | SSH hardening, under Access on the Settings tab | on |
rookery_install_cockpit | Cockpit web console, Features tab | on |
rookery_install_docker | Docker on host, Features tab | on |
rookery_install_tailscale | Tailscale, Install tab: whether the host joins the tailnet, with a key Rookery makes | on, or off for a new host while Rookery has no secret tailnet_api_key |
Others, such as rookery_tailscale_serve and the backup settings, are described where they are used. Rookery sets the variables of joining the tailnet itself, and a profile's ansible_vars can't: rookery_tailscale_auth_key, rookery_tailscale_login_server, rookery_tailscale_key_command and rookery_tailnet_problem.
Only rookery_ settings are taken. Ansible's own variables, such as ansible_connection, ansible_ssh_common_args or ansible_python_interpreter, would change how and where Ansible runs commands. Rookery sets the connection itself from access, so it refuses them in a profile from any caller. Each entry of rookery_plugin_features is PLUGIN/FEATURE. An apply leaves such variables out and says so in a line.
Rookery marks the values it gives Ansible as text, so {{ … }} in a setting is never a template.
A host joins the tailnet on its apply with a key Rookery makes, unless it's on the tailnet already. All defaults are in defaults/main.yml.
Type
Prop
Type
An ssh or managed host needs only its type and access. A node also takes target, the Tailscale fields and ansible_vars, and refuses the fields of the agent and the operator (Nodes). The other fields are for a workstation. See Host types.
{
"type": "ssh",
"access": { "address": "192.0.2.4", "user": "ops", "auth": "rookery" }
}Power (power)
How Rookery stops a host that no provisioner made. A host a provisioner made is started and stopped through it, when its machines have the verbs start and stop. See Starting and stopping.
Prop
Type
{
"type": "managed",
"access": { "address": "192.0.2.4", "user": "ops" },
"power": { "stop": { "by": "controller" } }
}Each of stop and start is an object, so that a way can take settings of its own beside by.
Access (access)
Where the host is and how Rookery logs in to it. Every host has it. See Logging in to hosts.
Prop
Type
After an apply as the operator, Rookery writes what the role made true: sudo becomes none, and a host that logged in with password logs in with rookery, as the operator takes keys only. key:NAME and ssh stay. A password kept for the first apply, as the secret ssh/HOST or sudo/HOST, is deleted.
Install (builder)
How Rookery installs the host. These settings stay on your machine.
Prop
Type
Beside the profile
Rookery keeps more of a host in its store, beside the profile:
| What | Holds | How to see it |
|---|---|---|
| Generated passwords | The passwords F4 made for the host's accounts | rookery host credentials HOST |
| The machine's record | The resource of a machine Rookery created for the host, with its provisioner and id | rookery host show HOST |
rookery host credentials prints an account and its password to a line, and only to a terminal unless --show is given. For a Rookery server's host it asks the server, which keeps them. rookery host remove HOST forgets the profile and both of these at once. A machine Rookery created for the host is left as it is, and its record stays as a resource with no host, unless --destroy destroys the machine too (Removing a host). rookery host duplicate copies neither to the new host.
Secrets and registries a host gets are listed in the profile by name (secrets, registries). Their values stay in Rookery's store.
Last updated on