fix(headscale): valid default ACL + document /admin gating

headscale rejects autogroups as tagOwners (only user/group:/tag:), which made
the shipped policy fatal. Replace with a valid allow-all default plus correct
commented examples for tightening. Document gating /admin to a pocket-id
superuser group via the headplane client's Allowed User Groups. Rebuild archive.
This commit is contained in:
57_Wolve committed 2026-06-12 16:17:26 -05:00
1 parent 1ca79938cd
commit 6a3fc68b75
3 files changed
+109 -114

No files matched your search

+25 -35
View File
@@ -1,49 +1,39 @@
// headscale ACL policy (HuJSON: JSON with // comments and trailing commas).
//
// IMPORTANT: headscale uses Tailscale's *legacy* policy format -- the top-level
// "acls" array -- NOT the newer "grants" syntax from the Tailscale admin
// console. This file is the grants-style default translated into "acls".
// "acls" array -- NOT the "grants" syntax from the Tailscale admin console.
// It is also stricter than Tailscale in places; notably, a "tagOwner" must be
// a user (has "@"), a "group:*", or a "tag:*" -- NOT an autogroup.
//
// Edit, then:
// headscale policy check # validate (uses the wrapper)
// docker compose restart headscale # apply (policy mode = file)
// Validate before relying on it:
// headscale policy check # uses the host CLI wrapper
// cd /srv/headscale && docker compose restart headscale # apply (mode=file)
//
// A few features here (autogroup:self, the ssh block) are newer/experimental
// in headscale and may depend on your version. If headscale rejects this
// policy at start, switch to the permissive fallback at the bottom.
// The default below is permissive (allow-all), which is also headscale's
// behaviour with no policy. Tighten it using the commented examples.
{
// Static user groups, e.g. "group:admins": ["alice@example.com"].
// Static user groups. Members are OIDC identities (emails from pocket-id).
// "group:admins": ["alice@example.com", "bob@example.com"],
"groups": {},
// Who may apply which tags to devices.
"tagOwners": {
// tag:shared -- a device any member is allowed to reach.
"tag:shared": ["autogroup:member"],
},
// Who may apply which tags to devices. Owners must be a user, "group:*", or
// "tag:*" (NOT an autogroup -- headscale rejects e.g. "autogroup:member").
// "tag:shared": ["group:admins"],
"tagOwners": {},
// Network access rules (first match wins; default-deny otherwise).
"acls": [
// Each user can reach their own devices, on all ports.
{ "action": "accept", "src": ["autogroup:member"], "dst": ["autogroup:self:*"] },
// Anyone can reach devices tagged tag:shared, on all ports.
{ "action": "accept", "src": ["*"], "dst": ["tag:shared:*"] },
// Allow everything. Replace with tighter rules, e.g.:
// { "action": "accept", "src": ["group:admins"], "dst": ["*:*"] },
// { "action": "accept", "src": ["*"], "dst": ["tag:shared:*"] },
{ "action": "accept", "src": ["*"], "dst": ["*:*"] },
],
// Tailscale SSH rules (nodes must run `tailscale up --ssh`).
"ssh": [
// SSH into your own devices. "check" = periodic browser re-auth (the
// Tailscale default). Use "accept" if your headscale lacks check mode.
{
"action": "check",
"src": ["autogroup:member"],
"dst": ["autogroup:self"],
"users": ["autogroup:nonroot", "root"],
},
],
// ---- Permissive fallback ----------------------------------------------
// Replace the "acls" above with this (and drop "ssh") if the rules are
// rejected, to allow everything while you iterate:
// "acls": [ { "action": "accept", "src": ["*"], "dst": ["*:*"] } ],
// Tailscale SSH (optional; nodes must run `tailscale up --ssh`). Example:
// "ssh": [
// { "action": "accept",
// "src": ["group:admins"],
// "dst": ["tag:shared"],
// "users": ["autogroup:nonroot", "root"] },
// ],
}