Tailnet policy file
The tailnet policy file is a centralized human JSON (HuJSON) configuration file that stores parameters, policies, and settings for your Tailscale network (known as a tailnet). Owners, Admins, and Network admins can manage your tailnet policy file from the Tailscale admin console. You can also manage the tailnet policy file with GitOps using GitHub, GitLab, or Bitbucket.
The tailnet policy file is organized into multiple top-level sections, each offering different functionality. You can use the various sections of the tailnet policy file to:
- Define named groupings of users, devices, and network segments with tags, groups, and IP sets.
- Define access control policies at the network layer using ACLs.
- Define access control policies at the network layer and application layer using grants.
- Assign aliases to IP addresses and subnets (using the
hostssection). - Define device posture rules.
- Specify who can use Tailscale SSH.
- Specify who can use which tags to authenticate devices.
- Specify who can bypass the approval process to advertise subnet routers and exit nodes.
- Apply additional attributes called node attributes to devices and users.
- Write tests to make assertions about access policies (ACLs and Tailscale SSH) that should not change.
- Define tailnet-wide policy options (such as disabling IPv4).
Using the different sections of the tailnet policy file in unison lets you manage your tailnet in a modular and fine-grained manner. For example, you can define a custom group of users, then create an access control policy to specify how the users in that group can traverse the resources in your tailnet.
Sections
The following table provides an overview of each top-level section of the tailnet policy file.
| Section | Name | What it’s for | Resources |
|---|---|---|---|
acls | Access control lists (ACLs) | Create network-level access control policies. | Syntax reference → |
autoApprovers | Auto approvers | Specify who can bypass the approval process to advertise subnet routers, and exit nodes, and app connectors. | Syntax reference → |
grants | Grants | Define network-level and application-level access control policies. | Syntax reference → |
groups | Groups | Define named groups of users, devices, and subnets to target in access control policies and other definitions. | Syntax reference → |
hosts | Hosts | Define named aliases for devices and subnets. | Syntax reference → |
ipsets | IP sets | Define named network segments to target in access control policies and other definitions. | Syntax reference → |
nodeAttr | Node attributes | Apply additional attributes to devices and users. | Syntax reference → |
postures | Device posture policies | Define device posture rules to target in access control policies. | Syntax reference → |
ssh | Tailscale SSH | Specify who can use Tailscale SSH. | Syntax reference → |
sshTests | Tailscale SSH tests | Write tests to make assertions about Tailscale SSH that should not change. | Syntax reference → |
tagOwners | Tag owners | Define who can assign which tags to devices in your tailnet. | Syntax reference → |
tests | Access control tests | Write tests to make assertions about access policies (ACLs and network-level grants) that should not change. | Syntax reference → |
There's also additional sections for network policy options, such as disabling IPv4 and customizing the DERP map. In most cases, these settings are unnecessary.
| Section | What it’s for | Resources |
|---|---|---|
derpMap | Customize the DERP servers that a tailnet uses. | Syntax reference → |
disableIPv4 | Disable using IPv4 in a tailnet. | Syntax reference → |
OneCGNATRoute | Modify the routes the Tailscale clients generate. | Syntax reference → |
randomizeClientPort | Control whether devices prefer a random port number or the default 41641 for WireGuard traffic. | Syntax reference → |