Skip to content

Connecting to Tailscale

How Protequ reaches it

Protequ does not reach a device here: this adapter makes the Protequ install itself join your Tailscale network (your "tailnet"). Once it has joined, authorised people on the tailnet can open the Protequ web interface from anywhere, with no port opened on your firewall. The connection is outbound only.

Before you start

  • A Tailscale account for your organisation, and an administrator who can open the Tailscale admin console.
  • A reusable, tagged auth key created by that administrator (steps below). Use a tag such as tag:protequ, so the node does not belong to one person and its key does not expire with a user.
  • Access rules in the tailnet that allow the people who need Protequ to reach that tag on port 443.
  • The Protequ server must be able to reach the internet over HTTPS (outbound).

On the Tailscale side

  1. Sign in to the Tailscale admin console and open Settings > Keys.
  2. Choose Generate auth key.
  3. Switch on Reusable. Set an expiry that suits your policy (the longest allowed is 90 days).
  4. Switch on Tags and pick the tag Protequ should use, for example tag:protequ.
  5. Copy the key. It is shown only once and starts with tskey-auth-.
  6. If you want Protequ to act as a subnet router (optional), later approve the advertised routes under the machine's entry in the console.

In Protequ

Add the Tailscale adapter, then add a Tailscale node device and fill in:

The settings may be shown under their parameter name (in brackets) rather than a friendly label.

Setting What it does
Auth key (auth_key) The key you copied above. Needed for the first registration, and again if the saved login is lost or expires. Hidden in the interface and audit log.
Hostname (hostname) The name of this Protequ install in your tailnet, for example protequ-site1. Leave empty to use the container name.
Expose the front door (serve_front_door) On by default. Makes the Protequ web interface reachable on port 443 of the node name.
Front door target (front_door_target) Where tailnet traffic is forwarded inside Protequ. Leave at the default nginx:443.
Advertised routes (advertise_routes) Optional list of networks (for example 192.168.10.0/24) this install announces to the tailnet as a subnet router. An administrator must approve them in the console.
Tailscale SSH (enable_ssh) Off by default. Turns on Tailscale's own SSH access.

Changes are not applied live. After editing any setting, restart the device; the new values are applied when it reconnects.

Confirm it works

The device goes online in Protequ and a connection-restored event is recorded. In the Tailscale admin console the machine appears under Machines with the tag you chose. From another device on the tailnet, open https://<node name>.<your tailnet>.ts.net.

Using the MagicDNS name for sign-in

Protequ only accepts sign-in on host names it knows. To use the Tailscale name (for example protequ-site1.tail1234.ts.net) you must tell Protequ about it once, by hand:

  1. Add the name to OIDC_EXTRA_HOSTS in the install's .env file.
  2. Make sure the front door certificate includes the name (add it to the certificate host names).
  3. Run the installer's configure-host step again so both changes are applied.

Until this is done, the page may load but sign-in is refused. This is not done automatically.

Security notes

  • The adapter opens no listening port; it only connects out to Tailscale.
  • The auth key is stored in the Protequ configuration like any other setting, is masked in the interface and audit log, is written to disk only for the moment it is used, and is never logged. Prefer a short expiry and replace it when it lapses.
  • Anyone the tailnet access rules allow to reach the node can reach the Protequ sign-in page. Protequ users still need their own accounts; restrict who can reach the tag with Tailscale access rules.
  • Advertised routes expose those networks to the tailnet once approved; advertise only what is needed.
  • The node state (its login) is kept in a volume of the adapter. Removing that volume, which also happens when the installer is run again, makes the node register again with the auth key; delete the old machine entry in the console.

If it does not connect

  • The device stays offline and the log says the node needs login. The auth key is missing, expired, already revoked, or not reusable and already used. Create a new key, enter it in the device, and restart the device.
  • The machine joined but your people cannot reach it. Check the Tailscale access rules allow their users to reach the tag on port 443.
  • Advertised routes show as pending. An administrator must approve them in the admin console (machine > Edit route settings).
  • The key worked once and now fails. The key reached its expiry. A node that is already registered keeps working without the key, but a new registration needs a fresh one.
  • The page loads but sign-in fails. The Tailscale name has not been added yet; see the section on the MagicDNS name above.
  • Nothing happens at all. The server may have no outbound internet access; check that HTTPS to Tailscale is allowed.