Skip to content

Remote-Pulse Tailscale Tags Reference

Source: ADR-0008 Apéndice E
Last updated: 2026-05-25

Tag Assignments

Tag Group Hosts (current) Hosts (planned) Purpose
tag:rp-server (n/a) rp-server (LXC 280 @ 192.168.0.196) — Remote-Pulse control plane
tag:rp-agent-prod prod (TBD: pmx-50, pmx-51, select LXCs) All homelab infra Production homelab hosts
tag:rp-agent-family family mac-mini-carmelo, openclaw-vm (live) Carmelo Mac mini, hermano laptop Family member devices
tag:rp-agent-iarq iarq (none) iarq-rag, iarq-locator VMs Client project hosts
tag:rp-agent-default default (ninguno; MacBook Air de Ramon está sin tag) (transitional) Testing/uncategorized hosts

Group Definitions

Defined in Tailscale ACL groups section.

group:admins

  • Members: [email protected]
  • Permissions: Full access to all tags, all ports, SSH as root
  • Use case: Infrastructure administration

group:family

  • Members: (to be populated)
  • Permissions: Access only to tag:rp-agent-family hosts, SSH as non-root
  • Use case: Family members managing their own devices

group:iarq

  • Members: (to be populated)
  • Permissions: Access only to tag:rp-agent-iarq hosts
  • Use case: Client project separation

ACL Design Principles

  1. Default-deny: Only explicitly allowed src→dst pairs are accepted
  2. Lateral movement blocked: Agents cannot reach other agents
  3. Least privilege: Users/agents get minimum required access
  4. Group isolation: Family cannot reach prod, iarq cannot reach prod/family
  5. Admin escape hatch: group:admins has unrestricted access for troubleshooting

Changing a Host's Tag

If you need to move a host between groups:

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

Example: Move mac-ramon-test from default to prod: 

ssh root@mac-ramon-test
tailscale up --reset --advertise-tags=tag:rp-agent-prod --hostname=mac-ramon-test

Note: --reset clears previous state. The host will re-authenticate with new tag.

Adding a New Tag

If you need a new group (e.g., tag:rp-agent-contractor):

  1. Edit ansible/roles/remote_pulse_server/files/tailscale-acl-policy.hujson
  2. Add to tagOwners: 
    "tag:rp-agent-contractor": ["[email protected]"],
  3. Add to groups (optional): 
    "group:contractor": ["[email protected]"],
  4. Add ACL rules (follow pattern of existing rules)
  5. Add test cases
  6. Validate with scripts/validate-tailscale-acl.sh
  7. Apply via runbook (docs/runbooks/rp-tailscale-acl-apply.md)

Common Patterns

Pattern 1: Server reaches all agents

{
  "action": "accept",
  "src": ["tag:rp-server"],
  "dst": ["tag:rp-agent-*:*"]
}

Pattern 2: Agents reach server (limited ports)

{
  "action": "accept",
  "src": ["tag:rp-agent-prod", "tag:rp-agent-family"],
  "dst": ["tag:rp-server:443,8080"]
}

Pattern 3: Group isolation

{
  "action": "accept",
  "src": ["group:family"],
  "dst": ["tag:rp-agent-family:*"]
}

SSH Access Matrix

Actor Destination User Result
group:admins Any agent root / non-root ✓ Accept (check 12h)
group:family tag:rp-agent-family non-root ✓ Accept (check 24h)
group:family tag:rp-agent-family root ✗ Deny
group:family tag:rp-agent-prod any ✗ Deny
tag:rp-agent-prod tag:rp-server any ✗ Deny (agents cannot SSH to server)
tag:rp-agent-iarq tag:rp-agent-prod any ✗ Deny (lateral movement blocked)

Note: "check" action = Tailscale SSH with passkey/MFA re-auth at specified interval.

Verifying Current Tags

Via Web UI

  1. Go to https://login.tailscale.com/admin/machines
  2. Find host in list
  3. Check "Tags" column

Via CLI (on host)

tailscale status --json | jq -r '.Self.Tags[]'

Via CLI (remote)

tailscale status --json | jq -r '.Peer[] | select(.HostName=="<hostname>") | .Tags[]'

Troubleshooting

Tag not applying

  • Check tagOwners in ACL includes your user email
  • Verify you're logged into Tailscale with correct account
  • Try tailscale up --reset (clears stale state)

Host not visible in group

  • Confirm tag was applied: tailscale status --json | jq .Self.Tags
  • Check ACL syntax is valid: scripts/validate-tailscale-acl.sh
  • Wait ~30s for ACL propagation across tailnet

SSH rejected despite tag

  • Verify Tailscale SSH is enabled on host: tailscale up --ssh
  • Check ACL ssh section includes rule for your src→dst pair
  • Confirm user is in correct group in ACL

References

  • ADR-0008 Apéndice E (design rationale)
  • ACL policy file: ansible/roles/remote_pulse_server/files/tailscale-acl-policy.hujson
  • Application runbook: docs/runbooks/rp-tailscale-acl-apply.md
  • Tailscale docs: https://tailscale.com/kb/1068/tags