<!doctype html><htmllang=enclass=no-js><head><metacharset=utf-8><metaname=viewportcontent="width=device-width,initial-scale=1"><metaname=descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaname=authorcontent="Headscale authors"><linkhref=https://juanfont.github.io/headscale/development/ref/acls/rel=canonical><linkhref=../tls/rel=prev><linkhref=../dns/rel=next><linkrel=iconhref=../../assets/favicon.png><metaname=generatorcontent="mkdocs-1.6.1, mkdocs-material-9.7.0"><title>ACLs - Headscale</title><linkrel=stylesheethref=../../assets/stylesheets/main.618322db.min.css><linkrel=stylesheethref=../../assets/stylesheets/palette.ab4e12ef.min.css><linkrel=preconnecthref=https://fonts.gstatic.comcrossorigin><linkrel=stylesheethref="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback"><style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style><script>__md_scope=newURL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script><metaproperty=og:typecontent=website><metaproperty=og:titlecontent="ACLs - Headscale"><metaproperty=og:descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaproperty=og:imagecontent=https://juanfont.github.io/headscale/development/assets/images/social/ref/acls.png><metaproperty=og:image:typecontent=image/png><metaproperty=og:image:widthcontent=1200><metaproperty=og:image:heightcontent=630><metacontent=https://juanfont.github.io/headscale/development/ref/acls/property=og:url><metaproperty=twitter:cardcontent=summary_large_image><metaproperty=twitter:titlecontent="ACLs - Headscale"><metaproperty=twitter:descriptioncontent="An open source, self-hosted implementation of the Tailscale control server."><metaproperty=twitter:imagecontent=https://juanfont.github.io/headscale/development/assets/images/social/ref/acls.png></head><bodydir=ltrdata-md-color-scheme=defaultdata-md-color-primary=whitedata-md-color-accent=indigo><inputclass=md-toggledata-md-toggle=drawertype=checkboxid=__drawerautocomplete=off><inputclass=md-toggledata-md-toggle=searchtype=checkboxid=__searchautocomplete=off><labelclass=md-overlayfor=__drawer></label><divdata-md-component=skip><ahref=#acl-setupclass=md-skip> Skip to content </a></div><divdata-md-component=announce></div><divdata-md-color-scheme=defaultdata-md-component=outdatedhidden></div><headerclass=md-headerdata-md-component=header><navclass="md-header__inner md-grid"aria-label=Header><ahref=../..title=Headscaleclass="md-header__button md-logo"aria-label=Headscaledata-md-component=logo><imgsrc=../../logo/headscale3-dots.svgalt=logo></a><labelclass="md-header__button md-icon"for=__drawer><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg></label><divclass=md-header__titledata-md-component=header-title><divclass=md-header__ellipsis><divclass=md-header__topic><spanclass=md-ellipsis> Headscale </span></div><divclass=md-header__topicdata-md-component=header-topic><spanclass=md-ellipsis> ACLs </span></div></div></div><formclass=md-header__optiondata-md-component=palette><inputclass=md-optiondata-md-color-mediadata-md-color-scheme=defaultdata-md-color-primary=whitedata-md-color-accent=indigoaria-label="Switch to dark mode"type=radioname=__paletteid=__palette_0><labelclass="md-header__button md-icon"title="Switch to dark mode"for=__palette_1hidden><svgxmlns=http://www.w3.org/2000/svgviewbox="0 0 24 24"><pathd="M128a44000-444400044440004-444000-4-4m010a66001-6-6660016-6660016666001-66m8-9.31V4h-4.69L12.698.694H4v4.69L.6912415.31V20h4.69L1223
</span></code></pre></div></li><li><p><ahref=https://tailscale.com/kb/1192/acl-samples#deny-all><strong>Deny All</strong></a>: To prevent all communication within your tailnet, you can include an empty array for the <code>"acls"</code> field in your policy file.</p><divclass="language-json highlight"><pre><span></span><code><spanid=__span-1-1><aid=__codelineno-1-1name=__codelineno-1-1href=#__codelineno-1-1></a><spanclass=p>{</span>
</span></code></pre></div></li></ul><h2id=complex-example>Complex Example<aclass=headerlinkhref=#complex-exampletitle="Permanent link">¶</a></h2><p>Let's build a more complex example use case for a small business (It may be the place where ACL's are the most useful).</p><p>We have a small company with a boss, an admin, two developers and an intern.</p><p>The boss should have access to all servers but not to the user's hosts. Admin should also have access to all hosts except that their permissions should be limited to maintaining the hosts (for example purposes). The developers can do anything they want on dev hosts but only watch on productions hosts. Intern can only interact with the development servers.</p><p>There's an additional server that acts as a router, connecting the VPN users to an internal network <code>10.20.0.0/16</code>. Developers must have access to those internal resources.</p><p>Each user have at least a device connected to the network and we have some servers.</p><ul><li>database.prod</li><li>database.dev</li><li>app-server1.prod</li><li>app-server1.dev</li><li>billing.internal</li><li>router.internal</li></ul><p><imgalt="ACL implementation example"src=../../images/headscale-acl-network.png></p><p>When <ahref=../../usage/getting-started/#register-a-node>registering the servers</a> we will need to add the flag <code>--advertise-tags=tag:<tag1>,tag:<tag2></code>, and the user that is registering the server should be allowed to do it. Since anyone can add tags to a server they can register, the check of the tags is done on headscale server and only valid tags are applied. A tag is valid if the user that is registering it is allowed to do it.</p><p>Here are the ACL's to implement the same permissions as above:</p><divclass="language-json highlight"><spanclass=filename>acl.json</span><pre><span></span><code><spanid=__span-2-1><aid=__codelineno-2-1name=__codelineno-2-1href=#__codelineno-2-1></a><spanclass=p>{</span>
</span><spanid=__span-2-2><aid=__codelineno-2-2name=__codelineno-2-2href=#__codelineno-2-2></a><spanclass=w></span><spanclass=c1>// groups are collections of users having a common scope. A user can be in multiple groups</span>
</span><spanid=__span-2-3><aid=__codelineno-2-3name=__codelineno-2-3href=#__codelineno-2-3></a><spanclass=w></span><spanclass=c1>// groups cannot be composed of groups</span>
</span><spanid=__span-2-10><aid=__codelineno-2-10name=__codelineno-2-10href=#__codelineno-2-10></a><spanclass=w></span><spanclass=c1>// tagOwners in tailscale is an association between a TAG and the people allowed to set this TAG on a server.</span>
</span><spanid=__span-2-11><aid=__codelineno-2-11name=__codelineno-2-11href=#__codelineno-2-11></a><spanclass=w></span><spanclass=c1>// This is documented [here](https://tailscale.com/kb/1068/acl-tags#defining-a-tag)</span>
</span><spanid=__span-2-12><aid=__codelineno-2-12name=__codelineno-2-12href=#__codelineno-2-12></a><spanclass=w></span><spanclass=c1>// and explained [here](https://tailscale.com/blog/rbac-like-it-was-meant-to-be/)</span>
</span><spanid=__span-2-14><aid=__codelineno-2-14name=__codelineno-2-14href=#__codelineno-2-14></a><spanclass=w></span><spanclass=c1>// the administrators can add servers in production</span>
</span><spanid=__span-2-18><aid=__codelineno-2-18name=__codelineno-2-18href=#__codelineno-2-18></a><spanclass=w></span><spanclass=c1>// the boss can tag any server as internal</span>
</span><spanid=__span-2-21><aid=__codelineno-2-21name=__codelineno-2-21href=#__codelineno-2-21></a><spanclass=w></span><spanclass=c1>// dev can add servers for dev purposes as well as admins</span>
</span><spanid=__span-2-27><aid=__codelineno-2-27name=__codelineno-2-27href=#__codelineno-2-27></a><spanclass=w></span><spanclass=c1>// hosts should be defined using its IP addresses and a subnet mask.</span>
</span><spanid=__span-2-28><aid=__codelineno-2-28name=__codelineno-2-28href=#__codelineno-2-28></a><spanclass=w></span><spanclass=c1>// to define a single host, use a /32 mask. You cannot use DNS entries here,</span>
</span><spanid=__span-2-29><aid=__codelineno-2-29name=__codelineno-2-29href=#__codelineno-2-29></a><spanclass=w></span><spanclass=c1>// as they're prone to be hijacked by replacing their IP addresses.</span>
</span><spanid=__span-2-30><aid=__codelineno-2-30name=__codelineno-2-30href=#__codelineno-2-30></a><spanclass=w></span><spanclass=c1>// see https://github.com/tailscale/tailscale/issues/3800 for more information.</span>
</span><spanid=__span-2-36><aid=__codelineno-2-36name=__codelineno-2-36href=#__codelineno-2-36></a><spanclass=w></span><spanclass=c1>// boss have access to all servers</span>
</span><spanid=__span-2-49><aid=__codelineno-2-49name=__codelineno-2-49href=#__codelineno-2-49></a><spanclass=w></span><spanclass=c1>// admin have only access to administrative ports of the servers, in tcp/22</span>
</span><spanid=__span-2-63><aid=__codelineno-2-63name=__codelineno-2-63href=#__codelineno-2-63></a><spanclass=w></span><spanclass=c1>// we also allow admin to ping the servers</span>
</span><spanid=__span-2-77><aid=__codelineno-2-77name=__codelineno-2-77href=#__codelineno-2-77></a><spanclass=w></span><spanclass=c1>// developers have access to databases servers and application servers on all ports</span>
</span><spanid=__span-2-78><aid=__codelineno-2-78name=__codelineno-2-78href=#__codelineno-2-78></a><spanclass=w></span><spanclass=c1>// they can only view the applications servers in prod and have no access to databases servers in production</span>
</span><spanid=__span-2-88><aid=__codelineno-2-88name=__codelineno-2-88href=#__codelineno-2-88></a><spanclass=w></span><spanclass=c1>// developers have access to the internal network through the router.</span>
</span><spanid=__span-2-89><aid=__codelineno-2-89name=__codelineno-2-89href=#__codelineno-2-89></a><spanclass=w></span><spanclass=c1>// the internal network is composed of HTTPS endpoints and Postgresql</span>
</span><spanid=__span-2-97><aid=__codelineno-2-97name=__codelineno-2-97href=#__codelineno-2-97></a><spanclass=w></span><spanclass=c1>// servers should be able to talk to database in tcp/5432. Database should not be able to initiate connections to</span>
</span><spanid=__span-2-111><aid=__codelineno-2-111name=__codelineno-2-111href=#__codelineno-2-111></a><spanclass=w></span><spanclass=c1>// interns have access to dev-app-servers only in reading mode</span>
</span><spanid=__span-2-118><aid=__codelineno-2-118name=__codelineno-2-118href=#__codelineno-2-118></a><spanclass=w></span><spanclass=c1>// Allow users to access their own devices using autogroup:self (see below for more details about performance impact)</span>
</span></code></pre></div><h2id=autogroups>Autogroups<aclass=headerlinkhref=#autogroupstitle="Permanent link">¶</a></h2><p>Headscale supports several autogroups that automatically include users, destinations, or devices with specific properties. Autogroups provide a convenient way to write ACL rules without manually listing individual users or devices.</p><h3id=autogroupinternet><code>autogroup:internet</code><aclass=headerlinkhref=#autogroupinternettitle="Permanent link">¶</a></h3><p>Allows access to the internet through <ahref=../routes/#exit-node>exit nodes</a>. Can only be used in ACL destinations.</p><divclass="language-json highlight"><pre><span></span><code><spanid=__span-3-1><aid=__codelineno-3-1name=__codelineno-3-1href=#__codelineno-3-1></a><spanclass=p>{</span>
</span></code></pre></div><h3id=autogroupmember><code>autogroup:member</code><aclass=headerlinkhref=#autogroupmembertitle="Permanent link">¶</a></h3><p>Includes all users who are direct members of the tailnet. Does not include users from shared devices.</p><divclass="language-json highlight"><pre><span></span><code><spanid=__span-4-1><aid=__codelineno-4-1name=__codelineno-4-1href=#__codelineno-4-1></a><spanclass=p>{</span>
</span></code></pre></div><h3id=autogrouptagged><code>autogroup:tagged</code><aclass=headerlinkhref=#autogrouptaggedtitle="Permanent link">¶</a></h3><p>Includes all devices that have at least one tag.</p><divclass="language-json highlight"><pre><span></span><code><spanid=__span-5-1><aid=__codelineno-5-1name=__codelineno-5-1href=#__codelineno-5-1></a><spanclass=p>{</span>
</span></code></pre></div><h3id=autogroupself><code>autogroup:self</code><aclass=headerlinkhref=#autogroupselftitle="Permanent link">¶</a></h3><p><strong>(EXPERIMENTAL)</strong></p><divclass="admonition warning"><pclass=admonition-title>The current implementation of <code>autogroup:self</code> is inefficient</p></div><p>Includes devices where the same user is authenticated on both the source and destination. Does not include tagged devices. Can only be used in ACL destinations.</p><p><divclass="language-json highlight"><pre><span></span><code><spanid=__span-6-1><aid=__codelineno-6-1name=__codelineno-6-1href=#__codelineno-6-1></a><spanclass=p>{</span>
</span></code></pre></div><em>Using <code>autogroup:self</code> may cause performance degradation on the Headscale coordinator server in large deployments, as filter rules must be compiled per-node rather than globally and the current implementation is not very efficient.</em></p><p>If you experience performance issues, consider using more specific ACL rules or limiting the use of <code>autogroup:self</code>. <divclass="language-json highlight"><pre><span></span><code><spanid=__span-7-1><aid=__codelineno-7-1name=__codelineno-7-1href=#__codelineno-7-1></a><spanclass=p>{</span>
</span><spanid=__span-7-2><aid=__codelineno-7-2name=__codelineno-7-2href=#__codelineno-7-2></a><spanclass=w></span><spanclass=c1>// The following rules allow internal users to communicate with their</span>
</span><spanid=__span-7-3><aid=__codelineno-7-3name=__codelineno-7-3href=#__codelineno-7-3></a><spanclass=w></span><spanclass=c1>// own nodes in case autogroup:self is causing performance issues.</span>
</span></code></pre></div></p><h3id=autogroupnonroot><code>autogroup:nonroot</code><aclass=headerlinkhref=#autogroupnonroottitle="Permanent link">¶</a></h3><p>Used in Tailscale SSH rules to allow access to any user except root. Can only be used in the <code>users</code> field of SSH rules.</p><divclass="language-json highlight"><pre><span></span><code><spanid=__span-8-1><aid=__codelineno-8-1name=__codelineno-8-1href=#__codelineno-8-1></a><spanclass=p>{</span>
