Choose selectors that last

Every rule names a source and a destination with one or more selectors. The selector you choose decides how much maintenance a rule needs later. This page covers which selector to use when.

Servers and shared machines: tags

Tag servers, build agents, printers and anything else that isn't someone's personal device. A rule written with tags keeps working when a server is rebuilt, re-addressed or replaced: apply the same tag to the new machine and it inherits the access.

{ "name": "Developers reach staging", "action": "accept",
  "source": ["group:developers"], "destination": ["tag:staging"],
  "ports": ["*"], "protocol": ["tcp", "udp"] }

Use an auth key with Auto-assign tags to tag servers as they enroll.

People's devices: email, group and role

When access should follow a person rather than a machine, use a person-based selector. It matches every device the person is signed in on, including ones they add later.

{ "name": "Alice reaches the jump host", "action": "accept",
  "source": ["email:alice@example.com"], "destination": ["tag:jump-host"],
  "ports": ["22"], "protocol": ["tcp"] }

{ "name": "SRE reaches the production database", "action": "accept",
  "source": ["group:sre"], "destination": ["tag:prod-db"],
  "ports": ["5432"], "protocol": ["tcp"] }

{ "name": "IT admins use RDP on Windows machines", "action": "accept",
  "source": ["role:it-admin"], "destination": ["tag:windows"],
  "ports": ["3389"], "protocol": ["tcp"] }

• Prefer group: over long lists of email: selectors. Adding someone to the group in Access → Groups updates every rule that uses it.
• role: follows the person's role in the console. Promoting someone grants them the access with no policy change.
• Person-based selectors never match tagged devices. See Tags, groups and roles.

A single device: client and ip

Use these only when one specific device can't be tagged:

• client:<deviceId> matches one device by its 9-digit device ID, shown on the device's page in the console.
• ip:<address> matches one overlay address exactly. CIDR ranges such as ip:100.100.0.0/24 never match anything.

ip: stops matching when the device's address changes, including when it's removed and rejoins. client: stops matching if the client is reinstalled without its state folder.

Lists are unions

A selector list matches if any entry matches. This source matches devices tagged admin or on-call:

"source": ["tag:admin", "tag:on-call"]

There is no way to require two tags at once. If you need "admin and on-call", create a third tag, such as on-call-admin, and apply it to the devices that should match.

Values without a prefix

A value with no prefix is matched against the device's overlay IP, device ID or tag name. A value containing @ is treated as an email address. Write the prefix anyway: tag:web is unambiguous, web is not.

Patterns to avoid

• Mixing selector kinds in one rule. A source list with a tag, an IP and an email is hard to review. Split it into separate rules.
• Tags that describe location. tag:rack-7 breaks when the server moves. tag:db-primary doesn't.
• Many tags per device. If a device carries ten tags, it's hard to say what it can reach.
• * as a destination. It's convenient on day one and hard to narrow later. Tag the devices that should be reachable instead.

Next steps

• How rules are evaluated
• Policy file reference