Skip to content

Remote-Pulse Tailscale ACL Application Runbook

Owner: Ramón
Source: ADR-0008 Apéndice E
Cadence: Apply once during F8, review quarterly

Prerequisites

  • Access to https://login.tailscale.com/admin/acls (admin role on tailnet monxas)
  • HuJSON syntax familiarity (JSON + comments + trailing commas)
  • tailscale CLI installed (for tagging hosts)
  • Access to affected hosts via SSH

Backup Current Policy

CRITICAL: Always backup before applying changes.

  1. Navigate to https://login.tailscale.com/admin/acls
  2. Click "Show ACL" → Select all → Copy
  3. Save to secrets/tailscale-acl-backup-$(date +%Y%m%d-%H%M).hujson
# Example (manual paste required)
mkdir -p secrets
vim secrets/tailscale-acl-backup-20260525-1430.hujson

Note: secrets/ is gitignored. Keep backups safe.

Apply Policy

  1. Open ansible/roles/remote_pulse_server/files/tailscale-acl-policy.hujson
  2. Copy entire contents
  3. Navigate to https://login.tailscale.com/admin/acls
  4. Paste into editor
  5. Click "Save"
  6. Wait for auto-validation: Green checkmark = tests passed

Option B: API (Advanced)

export TAILSCALE_API_KEY="tskey-api-..."
export TAILNET="monxas.ts.net"

curl -fsS -X POST "https://api.tailscale.com/api/v2/tailnet/$TAILNET/acl" \
  -u "$TAILSCALE_API_KEY:" \
  -H "Content-Type: application/hujson" \
  --data-binary "@ansible/roles/remote_pulse_server/files/tailscale-acl-policy.hujson"

Validate Tests

Tests run automatically on policy save. Confirm all pass:

  • Web UI: Green indicators next to each test
  • API response: Check JSON output for "tests": "passed"

If any test fails: 1. Do NOT proceed with tagging 2. Review test error messages 3. Fix policy or tests 4. Re-apply

Apply Tags to Hosts

After ACL is live, tag devices.

Tag the Server (LXC 280)

ssh [email protected]
tailscale up --reset --advertise-tags=tag:rp-server --hostname=rp-server
tailscale status | head -1  # Confirm "rp-server" tag applied

Tag Agents by Group

Prod agents (homelab infra): 

ssh root@<host>
tailscale up --reset --advertise-tags=tag:rp-agent-prod --hostname=$(hostname -s)

Family agents (Carmelo Mac, etc.): 

ssh <user>@<host>
tailscale up --reset --advertise-tags=tag:rp-agent-family --hostname=$(hostname -s)

Iarq agents (client projects): 

ssh <user>@<host>
tailscale up --reset --advertise-tags=tag:rp-agent-iarq --hostname=$(hostname -s)

Default agents (transitional, e.g. mac-ramon-test): 

ssh <user>@<host>
tailscale up --reset --advertise-tags=tag:rp-agent-default --hostname=$(hostname -s)

Bulk tagging helper: 

# See scripts/tailscale-tag-host.sh
./scripts/tailscale-tag-host.sh <host> tag:rp-agent-prod

Validate Connectivity

Test 1: Admin Full Access

From Ramón's laptop: 

ssh [email protected]  # Should succeed with passkey check

Test 2: Server → Agent

From LXC 280: 

ssh root@<agent-hostname>.monxas.ts.net  # Should succeed

Test 3: Agent → Server

From any agent: 

curl -v http://rp-server.monxas.ts.net:8080/v1/health  # Should succeed
ssh [email protected]  # Should FAIL (server SSH not exposed to agents)

Test 4: Lateral Movement Blocked

From tag:rp-agent-iarq host: 

ssh root@<prod-agent>.monxas.ts.net  # Should FAIL (timeout or connection refused)

Test 5: Family User Isolation

From family user's laptop (after adding to group:family): 

ssh user@<family-agent>.monxas.ts.net  # Should succeed
ssh root@<prod-agent>.monxas.ts.net    # Should FAIL

Rollback

If connectivity breaks or tests fail:

  1. Open https://login.tailscale.com/admin/acls
  2. Paste contents of backup file (secrets/tailscale-acl-backup-<date>.hujson)
  3. Click "Save"
  4. Verify connectivity restored

Post-rollback: - Review what went wrong - Fix policy offline - Re-apply with updated version

Adding Users to Groups

To populate group:family or group:iarq:

  1. Edit ACL policy
  2. Add user email to group array: 
    "group:family": ["[email protected]", "[email protected]"],
  3. Save policy (tests re-run automatically)
  4. Notify user to accept Tailscale invite

User onboarding checklist: - User joins tailnet via invite link - User installs Tailscale on their device - User authenticates with their identity provider - Admin applies group membership via ACL - User can now SSH to their tagged agents

Review Cadence

  • Quarterly: Review tags, groups, and rules
  • On new host group: Update ACL before enrolling first host
  • On security incident: Immediate review + potential tag revocation

Troubleshooting

"Permission denied" on SSH despite ACL

  • Check Tailscale SSH is enabled: tailscale status --json | jq .Self.SSH
  • Verify host has correct tag: tailscale status --json | jq .Self.Tags
  • Confirm user is in correct group: Check ACL groups section

"Connection timeout" between hosts

  • Check ACL acls section for missing src→dst rule
  • Run tailscale ping <destination> to test reachability
  • Review Tailscale admin console "Access controls" tab for denied connections

ACL tests fail on save

  • Read error message carefully (indicates which test failed)
  • Common issues:
  • Typo in tag name
  • User email not in tailnet
  • Port number mismatch
  • Fix and re-save

References

  • ADR-0008 Apéndice E (policy design rationale)
  • /Users/ramonkamibayashicarrera/homelab-infra/docs/docs/reference/rp-tailscale-tags.md (tag→group mapping)
  • Tailscale ACL docs: https://tailscale.com/kb/1018/acls