{"slug":"edit-access-control-policies-in-your-tailnet-policy-file","title":"Edit access control policies in your tailnet policy file","tags":["tailscale","access-control","file-sharing"],"agent_summary":"Last validated: Mar 13, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# Edit access control policies in your tailnet policy file\r\n\r\nLast validated: Mar 13, 2026\r\n\r\nYou can edit [access control policies](https://tailscale.com/docs/features/access-control/acls) in your [tailnet policy file](https://tailscale.com/docs/reference/glossary#tailnet-policy-file) by using the [Access controls](https://login.tailscale.com/admin/acls) page of the admin console, [GitOps for Tailscale](https://tailscale.com/docs/gitops), or the [Tailscale API](https://tailscale.com/docs/reference/tailscale-api). Refer to [tailnet policy syntax](https://tailscale.com/docs/reference/syntax/policy-file).\r\n\r\nYou must be an [Owner, Admin, or Network admin](https://tailscale.com/docs/reference/user-roles) to edit the tailnet policy file.\r\n\r\n## [Convert ACLs to grants](https://tailscale.com/docs/features/tailnet-policy-file/manage-tailnet-policies\\#convert-acls-to-grants)\r\n\r\nThe JSON editor includes a **Convert to grants** button that automatically converts the entire `acls` section in your tailnet policy file to equivalent [grants](https://tailscale.com/docs/features/access-control/grants). The button is always visible but is disabled when there is no `acls` section present. Refer to [Migrate from ACLs to grants](https://tailscale.com/docs/reference/migrate-acls-grants) for more information.\r\n\r\n## [Preview changes](https://tailscale.com/docs/features/tailnet-policy-file/manage-tailnet-policies\\#preview-changes)\r\n\r\nYou can preview user permissions while editing the access control policies in the tailnet policy file.\r\n\r\n1. Go to the [Access controls](https://login.tailscale.com/admin/acls) page of the admin console.\r\n2. Open the **Preview rules** tab.\r\n3. Select a user to access a list of destinations (one per line) accessible to the specified user.\r\n\r\nThe list also shows the line number that defines that rule and any other users or groups that can access that destination (due to that rule).\r\n\r\nYou can also define [access control policy tests](https://tailscale.com/docs/reference/syntax/policy-file#tests) to ensure changes don't accidentally remove access to an important system or unintentionally allow access to resources.\r\n\r\n## [Debug access control policies](https://tailscale.com/docs/features/tailnet-policy-file/manage-tailnet-policies\\#debug-access-control-policies)\r\n\r\nYou can use the [`tailscale ping` command](https://tailscale.com/docs/reference/tailscale-cli#ping) to debug access control policies by testing the connections between devices. The `tailscale ping` supports TSMP pings and ICMP pings.\r\n\r\nTSMP pings check whether two devices can establish a network connection but stop before the access control policy check. Use `tailscale ping --tsmp` to send a TSMP ping.\r\n\r\n```shell\r\ntailscale ping --tsmp\r\n```\r\n\r\nICMP pings check the end-to-end connectivity between devices, including access control policies. Use `tailscale ping --icmp` or regular `ping` to send an ICMP ping.\r\n\r\n```shell\r\ntailscale ping\r\n```\r\n\r\nIf TSMP ping succeeds, but ICMP ping fails, connections between devices are likely blocked by access control policies. If TSMP ping fails, devices cannot establish a network connection, even though access control policies might allow connections. If both TSMP and ICMP pings succeed, but connections still fail, check the port numbers in your access control policies and services you are trying to connect to.\r\n\r\nIn addition to manual testing, you can create built-in access control policy [tests](https://tailscale.com/docs/reference/syntax/policy-file#tests) to ensure that specific connections are allowed and prevent access control policy changes from accidentally breaking these connections.\r\n\r\n## [Revert changes](https://tailscale.com/docs/features/tailnet-policy-file/manage-tailnet-policies\\#revert-changes)\r\n\r\nYou can revert your [tailnet policy file](https://tailscale.com/docs/reference/glossary#tailnet-policy-file) to a previous date and time from the [Configuration logs](https://login.tailscale.com/admin/logs) page of the admin console. Refer to [Reverting access control policies from audit logs](https://tailscale.com/docs/features/logging/audit-logging#reverting-acls-from-audit-logs) for instructions.\r\n\r\nYou cannot revert the tailnet policy file if you are using [GitOps for Tailscale](https://tailscale.com/docs/gitops).\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

Edit access control policies in your tailnet policy file

\n

Last validated: Mar 13, 2026

\n

You can edit access control policies in your tailnet policy file by using the Access controls page of the admin console, GitOps for Tailscale, or the Tailscale API. Refer to tailnet policy syntax.

\n

You must be an Owner, Admin, or Network admin to edit the tailnet policy file.

\n

Convert ACLs to grants

\n

The JSON editor includes a Convert to grants button that automatically converts the entire acls section in your tailnet policy file to equivalent grants. The button is always visible but is disabled when there is no acls section present. Refer to Migrate from ACLs to grants for more information.

\n

Preview changes

\n

You can preview user permissions while editing the access control policies in the tailnet policy file.

\n
    \n
  1. Go to the Access controls page of the admin console.
    2. \n
  2. Open the Preview rules tab.
    3. \n
  3. Select a user to access a list of destinations (one per line) accessible to the specified user.
    4. \n
\n

The list also shows the line number that defines that rule and any other users or groups that can access that destination (due to that rule).

\n

You can also define access control policy tests to ensure changes don't accidentally remove access to an important system or unintentionally allow access to resources.

\n

Debug access control policies

\n

You can use the tailscale ping command to debug access control policies by testing the connections between devices. The tailscale ping supports TSMP pings and ICMP pings.

\n

TSMP pings check whether two devices can establish a network connection but stop before the access control policy check. Use tailscale ping --tsmp to send a TSMP ping.

\n
tailscale ping --tsmp\n
\n

ICMP pings check the end-to-end connectivity between devices, including access control policies. Use tailscale ping --icmp or regular ping to send an ICMP ping.

\n
tailscale ping\n
\n

If TSMP ping succeeds, but ICMP ping fails, connections between devices are likely blocked by access control policies. If TSMP ping fails, devices cannot establish a network connection, even though access control policies might allow connections. If both TSMP and ICMP pings succeed, but connections still fail, check the port numbers in your access control policies and services you are trying to connect to.

\n

In addition to manual testing, you can create built-in access control policy tests to ensure that specific connections are allowed and prevent access control policy changes from accidentally breaking these connections.

\n

Revert changes

\n

You can revert your tailnet policy file to a previous date and time from the Configuration logs page of the admin console. Refer to Reverting access control policies from audit logs for instructions.

\n

You cannot revert the tailnet policy file if you are using GitOps for Tailscale.

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}