Access and the desktop
How to reach a host's desktop, T3 Code, Cockpit and SSH, on the tailnet or through a tunnel.
A host serves its desktop, Cockpit and T3 Code, when a plugin installed it, only to the tailnet or to loopback. Access links and desktop password on the overview prints the addresses and the desktop's password, or from the command line:
rookery run studio access| Service | Address on the tailnet | Port on the host |
|---|---|---|
| Desktop (noVNC) | https://HOST.TAILNET.ts.net/vnc.html | 6080 |
| T3 Code, when installed | https://HOST.TAILNET.ts.net:8443/ | 3773 |
| Cockpit | https://HOST.TAILNET.ts.net:9090 | 9090 |
| SSH | ssh ops@TAILNET-ADDRESS | 22 |
In the panel, Alt+R shows the links as QR codes. Scan one with a phone to open it there. The pairing link of Use T3 from another device works the same way.
The desktop link printed by the action includes the password after # and signs in by itself, so treat it like the password. The names are the ones tailscale status reports for the host, such as HOST.TAILNET.ts.net on Tailscale. They need the tailnet's DNS on the machine you browse from, while the tailnet address works without it. Rookery configures no Funnel or public proxy for them.
Joining the tailnet
A host joins the tailnet while it is set up, with a one-use key Rookery makes through the API of the tailnet's control server. Nobody pastes a key. The one choice in a profile is Tailscale on the host's Install tab (rookery_install_tailscale): whether the host joins at all.
Rookery needs the control server's API key in the secret tailnet_api_key:
rookery secret set tailnet_api_key
rookery config set tailnet_tags tag:rookery # if the tailnet wants tagsThe secret is one of these:
| Control server | The secret | Lifetime |
|---|---|---|
| Tailscale | An OAuth client with the scopes auth_keys and devices:core, as CLIENT_ID:CLIENT_SECRET | The client doesn't expire. Rookery trades it for an access token of an hour each time it uses it |
| Tailscale | An API access token from the admin console | 1 to 90 days, chosen when you make it |
| Headscale | An API key from headscale apikeys create | 90 days unless you choose otherwise |
Prefer an OAuth client for Tailscale, so the secret doesn't run out. Keys it makes have tags, from those the client may give, so set tailnet_tags to them. On the Secrets tab of the home screen, Enter replaces the value. With a Rookery server, the server keeps the secret and the tailnet_ settings.
Rookery makes a key only at the moment it's used:
| When | Key valid for |
|---|---|
| A seed or installer is made | 24 hours, for writing the installer and the first boot |
| An apply finds the host not on the tailnet | 1 hour |
Every key joins one host once. It's pre-approved, not reusable and not ephemeral, and it gets the tags of tailnet_tags. The role reads it from a private file, never from the command line. A seed has its key written into its files, which only you can read, and the installed host deletes its copy after it has joined. Until then, whoever has the seed or the USB stick can join a machine to the tailnet with it. The API key never leaves the machine that runs Rookery.
When Rookery writes a seed or an installer, it says until when the key works. A machine first started later is set up without the tailnet, and the next apply from Rookery joins it with a new key.
A host that's on the tailnet already is left alone, so applying again goes without a key and leaves the host logged in. Once it has joined, it publishes the desktop and T3 Code, if installed, there. That's rookery_tailscale_serve, on by default, and it needs HTTPS certificates enabled for the tailnet. Enable them if Tailscale asks, then run Publish desktop and T3 on the tailnet. That action also gives Cockpit the tailnet's trusted certificate in place of its self-signed one.
The host's device
The same key looks after the host's device on the tailnet:
| When | What Rookery does |
|---|---|
| An apply | Records the device's id, its name and its addresses, from tailscale status on the host |
rookery host remove HOST --destroy | Removes the device once the provisioner has destroyed the machine |
The next apply after rookery host rename OLD NEW --hostname | Gives the device the name NEW, after the machine has taken the hostname |
The rename waits for the apply so the name on the tailnet changes when the machine's hostname does. Until then the old MagicDNS name keeps working, so Rookery can still connect for the apply. When the profile's address is the old name, Rookery changes it to the new one.
Removing a host without --destroy leaves its device alone, and so does a rename without --hostname. A copy made with duplicate joins as a device of its own.
A host that has not been applied since it joined has no record. Until its next apply Rookery looks for its device among the tailnet's devices, by the host's address and then by its hostname. It acts only when exactly one device matches, and says so otherwise.
The key needs these permissions:
| The secret | To make keys | To list, remove and rename devices |
|---|---|---|
| A Tailscale OAuth client | The scope auth_keys | The scope devices:core. Tailscale asks for tags when a client gets it |
| A Tailscale API access token | The permissions of the user who made it | The same |
| A Headscale API key | Any key | Any key |
When the control server refuses, or Rookery has no key, the job says so, and the host is removed all the same. Remove the device in the admin console then. A rename that's refused waits for the next apply.
When Rookery has no API key
A host whose profile wants the tailnet needs the secret. Without it, Rookery stops before anything runs and says what to do: set the secret, or switch Tailscale off for the host. A seed, an installer or a new machine isn't made, and the set-up tabs show the problem for them. An apply stops before its first change. A host that's on the tailnet already is applied as usual, as it doesn't need a key.
A new host on an installation without the secret starts with Tailscale off.
Headscale
Headscale is a control server you run yourself, for the same tailscale client. Point Rookery at it:
rookery config set tailnet_login_server https://hs.example.org
rookery config set tailnet_user agents # the user new hosts belong to
rookery secret set tailnet_api_key # from: headscale apikeys createRookery makes its keys through Headscale's API with that key, and hosts join with --login-server https://hs.example.org. Headscale keys need a user or tags (tailnet_tags). Some things differ from Tailscale:
| On Headscale | |
|---|---|
| The secret | An API key. Headscale has no OAuth clients |
| Names | Those of Headscale's MagicDNS, HOST.BASE_DOMAIN. Rookery shows what tailscale status reports |
tailscale serve, Funnel | Headscale doesn't offer them, so the desktop and T3 aren't published. The access action shows SSH tunnels for them instead |
| HTTPS certificates | Headscale doesn't issue them. Cockpit stays on its self-signed certificate, at https://TAILNET-ADDRESS:9090 |
The desktop
The agent's desktop is XFCE on a persistent virtual X display, :1, from TigerVNC, which also provides the loopback VNC endpoint. websockify connects the browser to it, and noVNC is the client in the browser. The password is generated on the host by TigerVNC's password utility. The agent can read it at ~/.config/tigervnc/password.
The desktop keeps running when you close the browser, and agents can drive it with box desktop. Set its size with Desktop size under Host on the Settings tab (rookery_geometry, such as 1600x900).
Cockpit
Full hosts get the Cockpit web console by default (rookery_install_cockpit, or Cockpit web console under Host Services on the Features tab). It shows logs, systemd services, storage and software updates, and has a file browser and a terminal, plus network settings on laptops. It listens on port 9090 and the firewall only admits it from the tailnet.
Log in as the operator with its password. Cockpit does not accept SSH keys, so give the operator a password under Operator Account on the Settings tab. The agent has no password unless you set one.
Without a tailnet, tunnel it and open https://127.0.0.1:9090:
ssh -L 9090:127.0.0.1:9090 ops@HOSTSwitching the option off on an existing host stops the console and closes the port but leaves the packages installed.
SSH
The operator logs in over SSH with keys only, on every host. The role writes a Match User block for it to /etc/ssh/sshd_config.d/00-rookery-operator.conf with AuthenticationMethods publickey, PasswordAuthentication no and KbdInteractiveAuthentication no. No setting turns it off.
rookery_harden_ssh (SSH hardening on the Settings tab, on by default) does the same for every other account and refuses root. It writes PasswordAuthentication no, KbdInteractiveAuthentication no and PermitRootLogin no to /etc/ssh/sshd_config.d/00-rookery.conf. With it off, the agent and other accounts log in as the SSH server's own settings allow, and the operator still uses keys only.
Hardening is applied only when a key login for a non-root account will exist afterwards. That is the case when the operator has a key in the profile or the key of Rookery, or the account used for installing has its own authorized keys. Otherwise the run says so and leaves the server as it was.
Passwords remain in use for the console, the laptop's graphical login and Cockpit. The operator's sudo needs none. Root has no password and is not managed by the role.
For which addresses may reach SSH, see the firewall.
Without a tailnet
Switch Tailscale off for a host, and Rookery reaches it over SSH at its address. The access action says so where the tailnet's links would be, and shows the tunnels. Tunnel the ports over SSH and open them on your own machine:
ssh -L 16080:127.0.0.1:6080 -L 13773:127.0.0.1:3773 ops@HOSTThen the desktop is at http://127.0.0.1:16080/vnc.html and T3 at http://127.0.0.1:13773/.
Last updated on