IP sets

An IP set is a way to manage groups of IP addresses. It can encapsulate a collection of targets, such as IP addresses, CIDRs, hosts, autogroups, and other IP sets. Tailscale translates everything in the IP set to a list of IP address ranges. You can use the ipset syntax to create IP sets within your tailnet policy file and reference them from access control policies such as ACLs and grants.

The primary benefit of IP sets is that they let you group multiple network parts into a single collection, enabling you to apply access control policies to the collection rather than the individual IP addresses, hosts, or subnets.

You can leverage IP sets in a variety of ways. For example, you can:

• Target and manage logical cross-sections of your tailnet independently of other groupings like subnets, tags, and groups.
• Target a subnet in access control policies while excluding a few specific hosts.
• Customize an autogroup to exclude some private or public subnets from global exit node access.
• Facilitate a more modular organization of your tailnet policy file.

Limitations

IP sets have the following limitations:

• You can’t include tags, users, or groups in IP sets.
• You can’t use circular references to IP sets.
• The only supported autogroup is autogroup:internet.

Syntax

An ipset is an object within the tailnet policy file that defines one or more named ipsets. Each named ipset contains one or more operations, each adding or removing a target.

The following example demonstrates the basic syntax for creating an ipset in the tailnet policy file where <name> is the name of the IP set and <target> is a CIDR, IP address, host, autogroup, or IP set.

"ipsets": {
    "ipset:<name>": [
        "add <target>"
        "remove <target>"
    ]
}

Operations

The ipset syntax supports two operations: add and remove. Each named IP set can have one or more operations, which are processed in order.

You must include the operation type before the target unless the named IP set only uses add operations.

Targets

A target is a CIDR, IP address, host, autogroup, or IP set that you add to or remove from a named IP set. Each target must be preceded by an operation (add or remove) unless the named IP set only adds targets (and doesn’t remove any IP addresses).

References

You can reference named IP sets from specific parts of the tailnet policy file using the format ipset:<name> where <name> is the name of the IP set.

The following sections of the tailnet policy file support referencing IP sets:

• ACLs (sources and destinations)
• Grants (sources and destinations)
• IP sets

Examples

The following examples illustrate how to leverage IP sets.

• Create an IP set with only add operations.
• Create an IP set that contains several subnets and excludes a single IP address.
• Create an IP set that excludes another IP set.
• Reference IP sets in grants.
• Reference IP sets in ACLs.
• Customize autogroup:internet.

Create IP sets with only add operations

The following IP sets don’t remove any targets. As a result, they can use a simplified syntax that omits the operation type (because add is assumed).

"ipsets": {
    "ipset:prod": ["192.0.2.0/24"],
    "ipset:dev": [
        "198.51.100.0/24",
        "203.0.113.0/24",
        "host:sql-server-1",
     ]
}

Create an IP set that adds several subnets and excludes a single IP address

The following example shows how to create an IP set that includes several subnets and excludes a single IP address.

"ipsets": {
    "ipset:prod": [
        "add 192.0.2.0/24",
        "add 2001:db8::/32",
        "add 198.51.100.0/24",
        "add 203.0.113.0/24",
        "remove 192.0.2.33",
    ],
}

Create an IP set that excludes another IP set

The following example creates a dev IP set and a prod IP set. The prod IP set excludes anything in the dev IP set.

"ipsets": {
    "ipset:dev": ["host:sql-server-1"],
    "ipset:prod": [
        "add 192.0.2.0/24",
        "add 198.51.100.0/24",
        "remove ipset:dev",
     ]
}

Reference IP sets in grants

The following example shows how to create grants that reference the dev IP set.

"grants": [
  {
    "src": ["group:devops"],
    "dst": ["ipset:dev"],
    "ip": ["80,443,22"]
  },
  {
    "src": ["group:dev"],
    "dst": ["ipset:dev"],
    "ip": ["80,443"],
    "via": ["tag:office-routers"],
  },
]

Reference IP sets in ACLs

The following example shows how to create ACLs that reference the prod IP set.

"acls": [
        {
            "src":    ["group:devops"],
            "dst":    ["ipset:prod:*"],
            "action": "accept",
        },
],

Customize autogroup:internet

You can use IP sets to customize the traffic that flows through an exit node (when enabled) in the tailnet using autogroup:internet.

The following example creates an IP set named internet that customizes autogroup:internet by doing the following:

• Adds autogroup:internet.
• Removes the production application gateways (ipset:cdn-edge).
• Removes the publicly accessible partner network (ipset:partner-net).
• Grants the internet IP set (a subset of internet-bound traffic) access to the Seattle and London office exit nodes.

"ipsets": {
  "ipset:internet": [
    "add autogroup:internet",
    "remove ipset:cdn-edge",
    "remove ipset:partner-net"
  ],
    "ipset:cdn-edge": ["8.21.9.6", "8.21.9.7", "8.21.9.13", "8.21.9.14"],
    "ipset:partner-net": ["52.23.40.0/24"]
  }
  "grants": [
  {
    "src": ["group:sea"],
    "dst": ["ipset:internet"],
    "ip":  ["*"],
    "via": ["tag:officerouter-sea"],
  },
  {
    "src": ["group:lhr"],
    "dst": ["ipset:internet"],
    "ip":  ["*"],
    "via": ["tag:officerouter-lhr"],
  }
]