feat(headscale): allow-all default ACL with lockdown template

Ship allow-everything as the active default (first acl rule), with the
Tailscale default policy translated to headscale's acls format included but
commented for when you lock down. Pre-fix the headscale gotchas: tag:shared
owned by group:admins (not an autogroup), autogroup:self/ssh-check flagged
experimental. Rebuild embedded archive.
This commit is contained in:
57_Wolve committed 2026-06-12 16:32:41 -05:00
1 parent 6a3fc68b75
commit 73cf299417
2 files changed
+116 -105

No files matched your search

+36 -27
View File
@@ -1,39 +1,48 @@
// 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 "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.
// headscale uses Tailscale's legacy "acls" format (NOT the "grants" syntax
// from the Tailscale admin console) and is stricter: a "tagOwner" must be a
// user (has "@"), a "group:*", or a "tag:*" -- never an autogroup.
//
// Validate before relying on it:
// headscale policy check # uses the host CLI wrapper
// cd /srv/headscale && docker compose restart headscale # apply (mode=file)
// DEFAULT = allow everything (the first acl below). To lock down, comment out
// that one line and the tighter rules (your Tailscale default, translated)
// take over. ACLs are additive, so while allow-all is present it wins and the
// other rules are inert -- which is why they're safe to leave in place.
//
// The default below is permissive (allow-all), which is also headscale's
// behaviour with no policy. Tighten it using the commented examples.
// After ANY edit, validate before applying:
// headscale policy check
// cd /srv/headscale && docker compose restart headscale
{
// Static user groups. Members are OIDC identities (emails from pocket-id).
// "group:admins": ["alice@example.com", "bob@example.com"],
"groups": {},
// Admin users (OIDC emails from pocket-id). Required only if you enable the
// tag:shared owner below. Empty is fine while allow-all is active.
"groups": {
// "group:admins": ["alice@example.com", "bob@example.com"],
},
// 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": {},
// Tag owners MUST be a user / "group:*" / "tag:*" (not an autogroup).
// Uncomment together with group:admins above when you lock down.
"tagOwners": {
// "tag:shared": ["group:admins"],
},
// Network access rules (first match wins; default-deny otherwise).
"acls": [
// Allow everything. Replace with tighter rules, e.g.:
// { "action": "accept", "src": ["group:admins"], "dst": ["*:*"] },
// { "action": "accept", "src": ["*"], "dst": ["tag:shared:*"] },
// ===== DEFAULT: allow everything. Comment out this line to lock down. =====
{ "action": "accept", "src": ["*"], "dst": ["*:*"] },
// ===== Your Tailscale default, translated (active once allow-all is off) =====
// Each user can reach their own devices (autogroup:self is experimental
// in headscale -- validate with `headscale policy check`):
// { "action": "accept", "src": ["autogroup:member"], "dst": ["autogroup:self:*"] },
// Anyone can reach devices tagged tag:shared (needs the tagOwner above):
// { "action": "accept", "src": ["*"], "dst": ["tag:shared:*"] },
],
// Tailscale SSH (optional; nodes must run `tailscale up --ssh`). Example:
// "ssh": [
// { "action": "accept",
// "src": ["group:admins"],
// "dst": ["tag:shared"],
// "users": ["autogroup:nonroot", "root"] },
// ],
// Tailscale SSH (nodes must run `tailscale up --ssh`). Uncomment to allow
// SSH into your own devices. "check" = periodic browser re-auth.
"ssh": [
// { "action": "check",
// "src": ["autogroup:member"],
// "dst": ["autogroup:self"],
// "users": ["autogroup:nonroot", "root"] },
],
}