mirror of
https://github.com/juanfont/headscale.git
synced 2026-10-24 23:36:49 +09:00
Deployed 63123196 to development with ProperDocs 1.6.7 and mike 2.2.0
This commit is contained in:
1 parent
d65ca4e07d
commit
aeb5e8767c
20 files changed
+195
-195
No files matched your search
@@ -1 +1 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/about/contributing/ rel=canonical><link href=../releases/ rel=prev><link href=../sponsor/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Contributing - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="Contributing - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/about/contributing.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/about/contributing/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Contributing - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/about/contributing.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#contributing class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Contributing </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <Line truncated
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/about/contributing/ rel=canonical><link href=../releases/ rel=prev><link href=../sponsor/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Contributing - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="Contributing - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/about/contributing.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/about/contributing/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Contributing - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/about/contributing.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#contributing class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Contributing </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <Line truncated
|
||||
@@ -2,6 +2,6 @@
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=w> </span><span class=nt>v4</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">100.64.0.0/10</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=w> </span><span class=nt>v6</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">fd7a:115c:a1e0::/48</span>
|
||||
</span></code></pre></div></li> <li>Update the <code>nodes.ipv4</code> and <code>nodes.ipv6</code> columns in the database and assign each node a unique IPv4 and IPv6 address. The following SQL statement assigns IP addresses based on the node ID: <div class="language-sql highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=k>UPDATE</span><span class=w> </span><span class=n>nodes</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=k>SET</span><span class=w> </span><span class=n>ipv4</span><span class=o>=</span><span class=n>concat</span><span class=p>(</span><span class=s1>'100.64.'</span><span class=p>,</span><span class=w> </span><span class=n>id</span><span class=o>/</span><span class=mi>256</span><span class=p>,</span><span class=w> </span><span class=s1>'.'</span><span class=p>,</span><span class=w> </span><span class=n>id</span><span class=o>%</span><span class=mi>256</span><span class=p>),</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span><span class=n>ipv6</span><span class=o>=</span><span class=n>concat</span><span class=p>(</span><span class=s1>'fd7a:115c:a1e0::'</span><span class=p>,</span><span class=w> </span><span class=n>format</span><span class=p>(</span><span class=s1>'%x'</span><span class=p>,</span><span class=w> </span><span class=n>id</span><span class=p>));</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=k>SET</span><span class=w> </span><span class=n>ipv4</span><span class=o>=</span><span class=n>concat</span><span class=p>(</span><span class=s1>'100.64.'</span><span class=p>,</span><span class=w> </span><span class=n>id</span><span class=o>/</span><span class=mi>256</span><span class=p>,</span><span class=w> </span><span class=s1>'.'</span><span class=p>,</span><span class=w> </span><span class=n>id</span><span class=o>%</span><span class=mi>256</span><span class=p>),</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span><span class=n>ipv6</span><span class=o>=</span><span class=n>concat</span><span class=p>(</span><span class=s1>'fd7a:115c:a1e0::'</span><span class=p>,</span><span class=w> </span><span class=n>format</span><span class=p>(</span><span class=s1>'%x'</span><span class=p>,</span><span class=w> </span><span class=n>id</span><span class=p>));</span>
|
||||
</span></code></pre></div></li> <li>Update the <a href=../../ref/policy/ >policy</a> to reflect the IP address changes (if any)</li> <li>Start Headscale</li> </ul> <p>Nodes should reconnect within a few seconds and pickup their newly assigned IP addresses.</p> <h2 id=how-can-i-avoid-to-send-logs-to-tailscale-inc>How can I avoid to send logs to Tailscale Inc?<a class=headerlink href=#how-can-i-avoid-to-send-logs-to-tailscale-inc title="Permanent link">¶</a></h2> <p>A Tailscale client <a href=https://tailscale.com/docs/features/logging#client-logs>collects logs about its operation and connection attempts with other clients</a> and sends them to a central log service operated by Tailscale Inc.</p> <p>Headscale, by default, instructs clients to disable log submission to the central log service. This configuration is applied by a client once it successfully connected with Headscale. See the configuration option <code>logtail.enabled</code> in the <a href=../../ref/configuration/ >configuration file</a> for details.</p> <p>Alternatively, logging can also be disabled on the client side. This is independent of Headscale and opting out of client logging disables log submission early during client startup. The configuration is operating system specific and is usually achieved by setting the environment variable <code>TS_NO_LOGS_NO_SUPPORT=true</code> or by passing the flag <code>--no-logs-no-support</code> to <code>tailscaled</code>. See <a href=https://tailscale.com/docs/features/logging#opt-out-of-client-logging>https://tailscale.com/docs/features/logging#opt-out-of-client-logging</a> for details.</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <div class=md-top data-md-component=top hidden> <div class=md-top__center> <button type=button class="md-top__button md-top__button--main" data-md-action=top> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> <span>Back to top</span> </button> <label class="md-top__button md-top__side md-top__side--nav" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-left" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M9 3v18"/></svg> </label> <label class="md-top__button md-top__side md-top__side--toc" for=__toc> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-right" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M15 3v18"/></svg> </label> </div> </div> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../.. class="md-footer__link md-footer__link--prev" aria-label="Previous: Welcome"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Welcome </div> </div> </a> <a href=../features/ class="md-footer__link md-footer__link--next" aria-label="Next: Features"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Features </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2026 Headscale authors </div> Made with <a href=https://jaywhj.github.io/mkdocs-materialx/ target=_blank rel=noopener> MaterialX </a> </div> <div class=md-social> <a href=https://github.com/juanfont/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.Line truncated
|
||||
@@ -1,17 +1,17 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/ref/api/ rel=canonical><link href=../derp/ rel=prev><link href=../tags/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>API - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="API - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/api.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/ref/api/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="API - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/api.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#api class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> API </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slLine truncated
|
||||
</span></code></pre></div> <p>Copy the output of the command and save it for later. Please note that you can not retrieve an API key again. If the API key is lost, expire the old one, and create a new one.</p> <p>To list the API keys currently associated with the server:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a>headscale<span class=w> </span>apikeys<span class=w> </span>list
|
||||
</span></code></pre></div> <p>and to expire an API key:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a>headscale<span class=w> </span>apikeys<span class=w> </span>expire<span class=w> </span>--prefix<span class=w> </span><PREFIX>
|
||||
</span></code></pre></div> <h2 id=rest-api>REST API<a class=headerlink href=#rest-api title="Permanent link">¶</a></h2> <ul> <li>API endpoint: <code>/api/v1</code>, e.g. <code>https://headscale.example.com/api/v1</code></li> <li>Documentation: <code>/api/v1/docs</code>, e.g. <code>https://headscale.example.com/api/v1/docs</code></li> <li>Headscale Version: <code>/version</code>, e.g. <code>https://headscale.example.com/version</code></li> <li>Authenticate using HTTP Bearer authentication by sending the <a href=#api>API key</a> with the HTTP <code>Authorization: Bearer <API_KEY></code> header.</li> </ul> <p>Start by <a href=#api>creating an API key</a> and test it with the examples below. Read the API documentation provided by your Headscale server at <code>/api/v1/docs</code> for details.</p> <div class="tabbed-set tabbed-alternate" data-tabs=1:3><input checked=checked id=__tabbed_1_1 name=__tabbed_1 type=radio><input id=__tabbed_1_2 name=__tabbed_1 type=radio><input id=__tabbed_1_3 name=__tabbed_1 type=radio><div class=tabbed-labels><label for=__tabbed_1_1>Get details for all users</label><label for=__tabbed_1_2>Get details for user 'bob'</label><label for=__tabbed_1_3>Register a node</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-console highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=go>curl -H "Authorization: Bearer <API_KEY>" \</span>
|
||||
</span></code></pre></div> <h2 id=rest-api>REST API<a class=headerlink href=#rest-api title="Permanent link">¶</a></h2> <ul> <li>API endpoint: <code>/api/v1</code>, e.g. <code>https://headscale.example.com/api/v1</code></li> <li>Documentation: <code>/api/v1/docs</code>, e.g. <code>https://headscale.example.com/api/v1/docs</code></li> <li>Headscale Version: <code>/version</code>, e.g. <code>https://headscale.example.com/version</code></li> <li>Authenticate using HTTP Bearer authentication by sending the <a href=#api>API key</a> with the HTTP <code>Authorization: Bearer <API_KEY></code> header.</li> </ul> <p>Start by <a href=#api>creating an API key</a> and test it with the examples below. Read the API documentation provided by your Headscale server at <code>/api/v1/docs</code> for details.</p> <div class="tabbed-set tabbed-alternate" data-tabs=1:3><input checked=checked id=__tabbed_1_1 name=__tabbed_1 type=radio><input id=__tabbed_1_2 name=__tabbed_1 type=radio><input id=__tabbed_1_3 name=__tabbed_1 type=radio><div class=tabbed-labels><label for=__tabbed_1_1>Get details for all users</label><label for=__tabbed_1_2>Get details for user 'bob'</label><label for=__tabbed_1_3>Register a node</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-console highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=go>curl -H "Authorization: Bearer <API_KEY>" \</span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=go> https://headscale.example.com/api/v1/user</span>
|
||||
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-console highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a><span class=go>curl -H "Authorization: Bearer <API_KEY>" \</span>
|
||||
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-console highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a><span class=go>curl -H "Authorization: Bearer <API_KEY>" \</span>
|
||||
</span><span id=__span-4-2><a id=__codelineno-4-2 name=__codelineno-4-2 href=#__codelineno-4-2></a><span class=go> https://headscale.example.com/api/v1/user?name=bob</span>
|
||||
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-console highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a><span class=go>curl -H "Authorization: Bearer <API_KEY>" \</span>
|
||||
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=go> --json '{"user": "<USER>", "authId": "<AUTH_ID>"}' \</span>
|
||||
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-console highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a><span class=go>curl -H "Authorization: Bearer <API_KEY>" \</span>
|
||||
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=go> --json '{"user": "<USER>", "authId": "<AUTH_ID>"}' \</span>
|
||||
</span><span id=__span-5-3><a id=__codelineno-5-3 name=__codelineno-5-3 href=#__codelineno-5-3></a><span class=go> https://headscale.example.com/api/v1/auth/register</span>
|
||||
</span></code></pre></div> </div> </div> </div> <h2 id=remote-control>Remote control<a class=headerlink href=#remote-control title="Permanent link">¶</a></h2> <p>The <code>headscale</code> binary can control a Headscale instance from a remote machine over the HTTP API.</p> <h3 id=prerequisite>Prerequisite<a class=headerlink href=#prerequisite title="Permanent link">¶</a></h3> <ul> <li>A workstation to run <code>headscale</code> (any supported platform, e.g. Linux).</li> <li>The Headscale server reachable over HTTP(S).</li> <li>An <a href=#api>API key</a> to authenticate with the Headscale server.</li> </ul> <h3 id=setup-remote-control>Setup remote control<a class=headerlink href=#setup-remote-control title="Permanent link">¶</a></h3> <ol> <li> <p>Download the <a href=https://github.com/juanfont/headscale/releases><code>headscale</code> binary from GitHub's release page</a>. Make sure to use the same version as on the server.</p> </li> <li> <p>Put the binary somewhere in your <code>PATH</code>, e.g. <code>/usr/local/bin/headscale</code></p> </li> <li> <p>Make <code>headscale</code> executable: <code>chmod +x /usr/local/bin/headscale</code></p> </li> <li> <p><a href=#api>Create an API key</a> on the Headscale server.</p> </li> <li> <p>Provide the connection parameters for the remote Headscale server either via a minimal YAML configuration file or via environment variables:</p> <div class="tabbed-set tabbed-alternate" data-tabs=2:2><input checked=checked id=__tabbed_2_1 name=__tabbed_2 type=radio><input id=__tabbed_2_2 name=__tabbed_2 type=radio><div class=tabbed-labels><label for=__tabbed_2_1>Minimal YAML configuration file</label><label for=__tabbed_2_2>Environment variables</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><span class=filename>config.yaml</span><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=nt>cli</span><span class=p>:</span>
|
||||
</span><span id=__span-6-2><a id=__codelineno-6-2 name=__codelineno-6-2 href=#__codelineno-6-2></a><span class=w> </span><span class=nt>address</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain"><HEADSCALE_URL></span>
|
||||
</span><span id=__span-6-3><a id=__codelineno-6-3 name=__codelineno-6-3 href=#__codelineno-6-3></a><span class=w> </span><span class=nt>api_key</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain"><API_KEY></span>
|
||||
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_CLI_ADDRESS</span><span class=o>=</span><span class=s2>"<HEADSCALE_URL>"</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_CLI_API_KEY</span><span class=o>=</span><span class=s2>"<API_KEY>"</span>
|
||||
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_CLI_ADDRESS</span><span class=o>=</span><span class=s2>"<HEADSCALE_URL>"</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_CLI_API_KEY</span><span class=o>=</span><span class=s2>"<API_KEY>"</span>
|
||||
</span></code></pre></div> </div> </div> </div> <p>This instructs the <code>headscale</code> binary to connect to a remote instance at <code><HEADSCALE_URL></code> (e.g. <code>https://headscale.example.com</code>), instead of connecting to the local instance. A bare host without a scheme is assumed to be <code>https</code>.</p> </li> <li> <p>Test the connection by listing all nodes:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-8-1><a id=__codelineno-8-1 name=__codelineno-8-1 href=#__codelineno-8-1></a>headscale<span class=w> </span>nodes<span class=w> </span>list
|
||||
</span></code></pre></div> <p>You should now be able to see a list of your nodes from your workstation, and you can now control the Headscale server from your workstation.</p> </li> </ol> <h3 id=behind-a-proxy>Behind a proxy<a class=headerlink href=#behind-a-proxy title="Permanent link">¶</a></h3> <p>The remote CLI uses the same HTTP API as everything else, so it works through the reverse proxy already in front of Headscale with no extra setup.</p> <h3 id=troubleshooting>Troubleshooting<a class=headerlink href=#troubleshooting title="Permanent link">¶</a></h3> <ul> <li>Make sure you have the <em>same</em> Headscale version on your server and workstation.</li> <li>Verify that your TLS certificate is valid and trusted.</li> <li>If you don't have access to a trusted certificate (e.g. from Let's Encrypt), either:<ul> <li>Add your self-signed certificate to the trust store of your OS <em>or</em></li> <li>Disable certificate verification by either setting <code>cli.insecure: true</code> in the configuration file or by setting <code>HEADSCALE_CLI_INSECURE=1</code> via an environment variable. We do <strong>not</strong> recommend to disable certificate validation.</li> </ul> </li> </ul> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <div class=md-top data-md-component=top hidden> <div class=md-top__center> <button type=button class="md-top__button md-top__button--main" data-md-action=top> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> <span>Back to top</span> </button> <label class="md-top__button md-top__side md-top__side--nav" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-left" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M9 3v18"/></svg> </label> <label class="md-top__button md-top__side md-top__side--toc" for=__toc> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-right" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M15 3v18"/></svg> </label> </div> </div> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../derp/ class="md-footer__link md-footer__link--prev" aria-label="Previous: DERP"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> DERP </div> </div> </a> <a href=../tags/ class="md-footer__link md-footer__link--next" aria-label="Next: Tags"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Tags </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2026 Headscale authors </div> Made with <a href=https://jaywhj.github.io/mkdocs-materialx/ target=_blank rel=noopener> MaterialX </a> </div> <div class=md-social> <a href=https://github.com/juanfont/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.Line truncated
|
||||
@@ -2,7 +2,7 @@
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=w> </span><span class=c1># Valid log levels: panic, fatal, error, warn, info, debug, trace</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=hll><span class=w> </span><span class=nt>level</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">debug</span>
|
||||
</span></span></code></pre></div> <h3 id=database-logging>Database logging<a class=headerlink href=#database-logging title="Permanent link">¶</a></h3> <p>The database debug mode logs all database queries. Enable it to see how Headscale interacts with its database. This also requires the application log level to be set to either <code>debug</code> or <code>trace</code>.</p> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=nt>database</span><span class=p>:</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class=c1># Enable debug mode. This setting requires the log.level to be set to "debug" or "trace".</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class=c1># Enable debug mode. This setting requires the log.level to be set to "debug" or "trace".</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=hll><span class=w> </span><span class=nt>debug</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
||||
</span></span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a>
|
||||
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a><span class=nt>log</span><span class=p>:</span>
|
||||
|
||||
@@ -1,24 +1,24 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/ref/dns/ rel=canonical><link href=../policy/ rel=prev><link href=../derp/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>DNS - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="DNS - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/dns.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/ref/dns/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="DNS - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/dns.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#dns class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> DNS </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=Line truncated
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">extra_records</span><span class="p p-Indicator">:</span>
|
||||
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>name</span><span class=p>:</span><span class=w> </span><span class=s>"grafana.myvpn.example.com"</span>
|
||||
</span><span id=__span-0-5><a id=__codelineno-0-5 name=__codelineno-0-5 href=#__codelineno-0-5></a><span class=w> </span><span class=nt>type</span><span class=p>:</span><span class=w> </span><span class=s>"A"</span>
|
||||
</span><span id=__span-0-6><a id=__codelineno-0-6 name=__codelineno-0-6 href=#__codelineno-0-6></a><span class=w> </span><span class=nt>value</span><span class=p>:</span><span class=w> </span><span class=s>"100.64.0.3"</span>
|
||||
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>name</span><span class=p>:</span><span class=w> </span><span class=s>"grafana.myvpn.example.com"</span>
|
||||
</span><span id=__span-0-5><a id=__codelineno-0-5 name=__codelineno-0-5 href=#__codelineno-0-5></a><span class=w> </span><span class=nt>type</span><span class=p>:</span><span class=w> </span><span class=s>"A"</span>
|
||||
</span><span id=__span-0-6><a id=__codelineno-0-6 name=__codelineno-0-6 href=#__codelineno-0-6></a><span class=w> </span><span class=nt>value</span><span class=p>:</span><span class=w> </span><span class=s>"100.64.0.3"</span>
|
||||
</span><span id=__span-0-7><a id=__codelineno-0-7 name=__codelineno-0-7 href=#__codelineno-0-7></a>
|
||||
</span><span id=__span-0-8><a id=__codelineno-0-8 name=__codelineno-0-8 href=#__codelineno-0-8></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>name</span><span class=p>:</span><span class=w> </span><span class=s>"prometheus.myvpn.example.com"</span>
|
||||
</span><span id=__span-0-9><a id=__codelineno-0-9 name=__codelineno-0-9 href=#__codelineno-0-9></a><span class=w> </span><span class=nt>type</span><span class=p>:</span><span class=w> </span><span class=s>"A"</span>
|
||||
</span><span id=__span-0-10><a id=__codelineno-0-10 name=__codelineno-0-10 href=#__codelineno-0-10></a><span class=w> </span><span class=nt>value</span><span class=p>:</span><span class=w> </span><span class=s>"100.64.0.3"</span>
|
||||
</span><span id=__span-0-8><a id=__codelineno-0-8 name=__codelineno-0-8 href=#__codelineno-0-8></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>name</span><span class=p>:</span><span class=w> </span><span class=s>"prometheus.myvpn.example.com"</span>
|
||||
</span><span id=__span-0-9><a id=__codelineno-0-9 name=__codelineno-0-9 href=#__codelineno-0-9></a><span class=w> </span><span class=nt>type</span><span class=p>:</span><span class=w> </span><span class=s>"A"</span>
|
||||
</span><span id=__span-0-10><a id=__codelineno-0-10 name=__codelineno-0-10 href=#__codelineno-0-10></a><span class=w> </span><span class=nt>value</span><span class=p>:</span><span class=w> </span><span class=s>"100.64.0.3"</span>
|
||||
</span><span id=__span-0-11><a id=__codelineno-0-11 name=__codelineno-0-11 href=#__codelineno-0-11></a><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">...</span>
|
||||
</span></code></pre></div> <p>Restart your headscale instance.</p> </div> <div class=tabbed-block> <div class="language-json highlight"><span class=filename>extra-records.json</span><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=p>[</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"grafana.myvpn.example.com"</span><span class=p>,</span>
|
||||
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a><span class=w> </span><span class=nt>"type"</span><span class=p>:</span><span class=w> </span><span class=s2>"A"</span><span class=p>,</span>
|
||||
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a><span class=w> </span><span class=nt>"value"</span><span class=p>:</span><span class=w> </span><span class=s2>"100.64.0.3"</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"grafana.myvpn.example.com"</span><span class=p>,</span>
|
||||
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a><span class=w> </span><span class=nt>"type"</span><span class=p>:</span><span class=w> </span><span class=s2>"A"</span><span class=p>,</span>
|
||||
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a><span class=w> </span><span class=nt>"value"</span><span class=p>:</span><span class=w> </span><span class=s2>"100.64.0.3"</span>
|
||||
</span><span id=__span-1-6><a id=__codelineno-1-6 name=__codelineno-1-6 href=#__codelineno-1-6></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-1-7><a id=__codelineno-1-7 name=__codelineno-1-7 href=#__codelineno-1-7></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-1-8><a id=__codelineno-1-8 name=__codelineno-1-8 href=#__codelineno-1-8></a><span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"prometheus.myvpn.example.com"</span><span class=p>,</span>
|
||||
</span><span id=__span-1-9><a id=__codelineno-1-9 name=__codelineno-1-9 href=#__codelineno-1-9></a><span class=w> </span><span class=nt>"type"</span><span class=p>:</span><span class=w> </span><span class=s2>"A"</span><span class=p>,</span>
|
||||
</span><span id=__span-1-10><a id=__codelineno-1-10 name=__codelineno-1-10 href=#__codelineno-1-10></a><span class=w> </span><span class=nt>"value"</span><span class=p>:</span><span class=w> </span><span class=s2>"100.64.0.3"</span>
|
||||
</span><span id=__span-1-8><a id=__codelineno-1-8 name=__codelineno-1-8 href=#__codelineno-1-8></a><span class=w> </span><span class=nt>"name"</span><span class=p>:</span><span class=w> </span><span class=s2>"prometheus.myvpn.example.com"</span><span class=p>,</span>
|
||||
</span><span id=__span-1-9><a id=__codelineno-1-9 name=__codelineno-1-9 href=#__codelineno-1-9></a><span class=w> </span><span class=nt>"type"</span><span class=p>:</span><span class=w> </span><span class=s2>"A"</span><span class=p>,</span>
|
||||
</span><span id=__span-1-10><a id=__codelineno-1-10 name=__codelineno-1-10 href=#__codelineno-1-10></a><span class=w> </span><span class=nt>"value"</span><span class=p>:</span><span class=w> </span><span class=s2>"100.64.0.3"</span>
|
||||
</span><span id=__span-1-11><a id=__codelineno-1-11 name=__codelineno-1-11 href=#__codelineno-1-11></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-1-12><a id=__codelineno-1-12 name=__codelineno-1-12 href=#__codelineno-1-12></a><span class=p>]</span>
|
||||
</span></code></pre></div> <p>Headscale picks up changes to the above JSON file automatically.</p> <div class="admonition tip"> <p class=admonition-title>Good to know</p> <ul> <li>The <code>dns.extra_records_path</code> option in the <a href=../configuration/ >configuration file</a> needs to reference the JSON file containing extra DNS records.</li> <li>Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script. Headscale uses a checksum to detect changes to the file and a stable output avoids unnecessary processing.</li> </ul> </div> </div> </div> </div> </li> <li> <p>Verify that DNS records are properly set using the DNS querying tool of your choice:</p> <div class="tabbed-set tabbed-alternate" data-tabs=2:2><input checked=checked id=__tabbed_2_1 name=__tabbed_2 type=radio><input id=__tabbed_2_2 name=__tabbed_2 type=radio><div class=tabbed-labels><label for=__tabbed_2_1>Query with dig</label><label for=__tabbed_2_2>Query with drill</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-console highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a><span class=go>dig +short grafana.myvpn.example.com</span>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/ref/integration/reverse-proxy/ rel=canonical><link href=../../debug/ rel=prev><link href=../web-ui/ rel=next><link rel=icon href=../../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Reverse proxy - Headscale</title><link rel=stylesheet href=../../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../../..",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><meta property=og:type content=website><meta property=og:title content="Reverse proxy - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/integration/reverse-proxy.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/ref/integration/reverse-proxy/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Reverse proxy - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/integration/reverse-proxy.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#running-headscale-behind-a-reverse-proxy class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Reverse proxy </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 Line truncated
|
||||
</span></span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=nt>tls_cert_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=nt>tls_key_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span></span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=nt>tls_cert_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=nt>tls_key_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span></code></pre></div> <p>Headscale logs <code>WRN listening without TLS but ServerURL does not start with http://</code> during startup. This is expected and indicates that the reverse proxy is in charge of terminating TLS.</p> <h3 id=trusted-proxies>Trusted proxies<a class=headerlink href=#trusted-proxies title="Permanent link">¶</a></h3> <p>Headscale ignores <code>True-Client-IP</code>, <code>X-Real-IP</code> and <code>X-Forwarded-For</code> headers unless the request's TCP peer matches the <code>trusted_proxies</code> configuration option. Set this to the CIDR(s) your reverse proxy connects from so the real client IP appears in access logs.</p> <div class="language-yaml highlight"><span class=filename>config.yaml</span><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=nt>trusted_proxies</span><span class=p>:</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">127.0.0.1/32</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">::1/128</span>
|
||||
@@ -10,15 +10,15 @@
|
||||
</span><span id=__span-2-4><a id=__codelineno-2-4 name=__codelineno-2-4 href=#__codelineno-2-4></a><span class=nt>trusted_proxies</span><span class=p>:</span>
|
||||
</span><span id=__span-2-5><a id=__codelineno-2-5 name=__codelineno-2-5 href=#__codelineno-2-5></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">127.0.0.1/32</span>
|
||||
</span><span id=__span-2-6><a id=__codelineno-2-6 name=__codelineno-2-6 href=#__codelineno-2-6></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">::1/128</span>
|
||||
</span><span id=__span-2-7><a id=__codelineno-2-7 name=__codelineno-2-7 href=#__codelineno-2-7></a><span class=nt>tls_cert_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span><span id=__span-2-8><a id=__codelineno-2-8 name=__codelineno-2-8 href=#__codelineno-2-8></a><span class=nt>tls_key_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span><span id=__span-2-7><a id=__codelineno-2-7 name=__codelineno-2-7 href=#__codelineno-2-7></a><span class=nt>tls_cert_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span><span id=__span-2-8><a id=__codelineno-2-8 name=__codelineno-2-8 href=#__codelineno-2-8></a><span class=nt>tls_key_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span></code></pre></div> <h3 id=apache>Apache<a class=headerlink href=#apache title="Permanent link">¶</a></h3> <p>The following basic Apache configuration works with the Headscale configuration <a href=#reverse-proxy-specific-configuration>as shown above</a>. Substitute placeholders and adjust the configuration as needed:</p> <ul> <li><code><SERVER_NAME></code>: The server name for your instance, e.g. <code>headscale.example.com</code></li> <li><code><PATH_TO_TLS_CERT></code>: Absolute path to your TLS certificate</li> <li><code><PATH_TO_TLS_KEY></code>: Absolute path to your TLS private key</li> </ul> <div class="language-apache highlight"><span class=filename>apache.conf</span><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=nt><VirtualHost</span><span class=w> </span><span class=s>*:80</span><span class=nt>></span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=hll><span class=w> </span><span class=nb>ServerName</span><span class=w> </span><SERVER_NAME>
|
||||
</span></span><span id=__span-3-3><a id=__codelineno-3-3 name=__codelineno-3-3 href=#__codelineno-3-3></a>
|
||||
</span><span id=__span-3-4><a id=__codelineno-3-4 name=__codelineno-3-4 href=#__codelineno-3-4></a><span class=w> </span><span class=c># Tailscale captive portal detection</span>
|
||||
</span><span id=__span-3-5><a id=__codelineno-3-5 name=__codelineno-3-5 href=#__codelineno-3-5></a><span class=w> </span><span class=nb>RedirectMatch</span><span class=w> </span><span class=m>204</span><span class=w> </span>^/generate_204$
|
||||
</span><span id=__span-3-6><a id=__codelineno-3-6 name=__codelineno-3-6 href=#__codelineno-3-6></a>
|
||||
</span><span id=__span-3-7><a id=__codelineno-3-7 name=__codelineno-3-7 href=#__codelineno-3-7></a><span class=hll><span class=w> </span><span class=nb>RedirectMatch</span><span class=w> </span>permanent<span class=w> </span><span class=s2>"^/(.*)$"</span><span class=w> </span><span class=s2>"https://<SERVER_NAME>/$1"</span>
|
||||
</span><span id=__span-3-7><a id=__codelineno-3-7 name=__codelineno-3-7 href=#__codelineno-3-7></a><span class=hll><span class=w> </span><span class=nb>RedirectMatch</span><span class=w> </span>permanent<span class=w> </span><span class=s2>"^/(.*)$"</span><span class=w> </span><span class=s2>"https://<SERVER_NAME>/$1"</span>
|
||||
</span></span><span id=__span-3-8><a id=__codelineno-3-8 name=__codelineno-3-8 href=#__codelineno-3-8></a><span class=nt></VirtualHost></span>
|
||||
</span><span id=__span-3-9><a id=__codelineno-3-9 name=__codelineno-3-9 href=#__codelineno-3-9></a>
|
||||
</span><span id=__span-3-10><a id=__codelineno-3-10 name=__codelineno-3-10 href=#__codelineno-3-10></a><span class=nt><VirtualHost</span><span class=w> </span><span class=s>*:443</span><span class=nt>></span>
|
||||
@@ -28,8 +28,8 @@
|
||||
</span><span id=__span-3-14><a id=__codelineno-3-14 name=__codelineno-3-14 href=#__codelineno-3-14></a><span class=hll><span class=w> </span><span class=nb>SSLCertificateFile</span><span class=w> </span><PATH_TO_TLS_CERT>
|
||||
</span></span><span id=__span-3-15><a id=__codelineno-3-15 name=__codelineno-3-15 href=#__codelineno-3-15></a><span class=hll><span class=w> </span><span class=nb>SSLCertificateKeyFile</span><span class=w> </span><PATH_TO_TLS_KEY>
|
||||
</span></span><span id=__span-3-16><a id=__codelineno-3-16 name=__codelineno-3-16 href=#__codelineno-3-16></a>
|
||||
</span><span id=__span-3-17><a id=__codelineno-3-17 name=__codelineno-3-17 href=#__codelineno-3-17></a><span class=w> </span><span class=nb>RequestHeader</span><span class=w> </span>set<span class=w> </span>True-Client-IP<span class=w> </span><span class=s2>"%{REMOTE_ADDR}s"</span>
|
||||
</span><span id=__span-3-18><a id=__codelineno-3-18 name=__codelineno-3-18 href=#__codelineno-3-18></a><span class=w> </span><span class=nb>RequestHeader</span><span class=w> </span>set<span class=w> </span>X-Real-IP<span class=w> </span><span class=s2>"%{REMOTE_ADDR}s"</span>
|
||||
</span><span id=__span-3-17><a id=__codelineno-3-17 name=__codelineno-3-17 href=#__codelineno-3-17></a><span class=w> </span><span class=nb>RequestHeader</span><span class=w> </span>set<span class=w> </span>True-Client-IP<span class=w> </span><span class=s2>"%{REMOTE_ADDR}s"</span>
|
||||
</span><span id=__span-3-18><a id=__codelineno-3-18 name=__codelineno-3-18 href=#__codelineno-3-18></a><span class=w> </span><span class=nb>RequestHeader</span><span class=w> </span>set<span class=w> </span>X-Real-IP<span class=w> </span><span class=s2>"%{REMOTE_ADDR}s"</span>
|
||||
</span><span id=__span-3-19><a id=__codelineno-3-19 name=__codelineno-3-19 href=#__codelineno-3-19></a>
|
||||
</span><span id=__span-3-20><a id=__codelineno-3-20 name=__codelineno-3-20 href=#__codelineno-3-20></a><span class=w> </span><span class=nb>ProxyPreserveHost</span><span class=w> </span><span class=k>On</span>
|
||||
</span><span id=__span-3-21><a id=__codelineno-3-21 name=__codelineno-3-21 href=#__codelineno-3-21></a><span class=w> </span><span class=nb>ProxyPass</span><span class=w> </span>/<span class=w> </span>http://127.0.0.1:8080/<span class=w> </span>upgrade=any
|
||||
@@ -68,7 +68,7 @@
|
||||
</span><span id=__span-5-15><a id=__codelineno-5-15 name=__codelineno-5-15 href=#__codelineno-5-15></a><span class=w> </span><span class=nt>operation</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">MERGE</span>
|
||||
</span><span id=__span-5-16><a id=__codelineno-5-16 name=__codelineno-5-16 href=#__codelineno-5-16></a><span class=w> </span><span class=nt>value</span><span class=p>:</span>
|
||||
</span><span id=__span-5-17><a id=__codelineno-5-17 name=__codelineno-5-17 href=#__codelineno-5-17></a><span class=w> </span><span class=nt>typed_config</span><span class=p>:</span>
|
||||
</span><span id=__span-5-18><a id=__codelineno-5-18 name=__codelineno-5-18 href=#__codelineno-5-18></a><span class=w> </span><span class=s>"@type"</span><span class="p p-Indicator">:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager</span>
|
||||
</span><span id=__span-5-18><a id=__codelineno-5-18 name=__codelineno-5-18 href=#__codelineno-5-18></a><span class=w> </span><span class=s>"@type"</span><span class="p p-Indicator">:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager</span>
|
||||
</span><span id=__span-5-19><a id=__codelineno-5-19 name=__codelineno-5-19 href=#__codelineno-5-19></a><span class=w> </span><span class=nt>upgrade_configs</span><span class=p>:</span>
|
||||
</span><span id=__span-5-20><a id=__codelineno-5-20 name=__codelineno-5-20 href=#__codelineno-5-20></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=nt>upgrade_type</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">tailscale-control-protocol</span>
|
||||
</span></code></pre></div> <h3 id=nginx>Nginx<a class=headerlink href=#nginx title="Permanent link">¶</a></h3> <p>The following basic Nginx configuration works with the Headscale configuration <a href=#reverse-proxy-specific-configuration>as shown above</a>. Substitute placeholders and adjust the configuration as needed:</p> <ul> <li><code><SERVER_NAME></code>: The server name for your instance, e.g. <code>headscale.example.com</code></li> <li><code><PATH_TO_TLS_CERT></code>: Absolute path to your TLS certificate</li> <li><code><PATH_TO_TLS_KEY></code>: Absolute path to your TLS private key</li> </ul> <div class="language-nginx highlight"><span class=filename>nginx.conf</span><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=c1># headscale</span>
|
||||
@@ -81,7 +81,7 @@
|
||||
</span><span id=__span-6-8><a id=__codelineno-6-8 name=__codelineno-6-8 href=#__codelineno-6-8></a><span class=c1># websocket</span>
|
||||
</span><span id=__span-6-9><a id=__codelineno-6-9 name=__codelineno-6-9 href=#__codelineno-6-9></a><span class=k>map</span><span class=w> </span><span class=nv>$http_upgrade</span><span class=w> </span><span class=nv>$connection_upgrade</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-6-10><a id=__codelineno-6-10 name=__codelineno-6-10 href=#__codelineno-6-10></a><span class=w> </span><span class=kn>default</span><span class=w> </span><span class=s>keep-alive</span><span class=p>;</span>
|
||||
</span><span id=__span-6-11><a id=__codelineno-6-11 name=__codelineno-6-11 href=#__codelineno-6-11></a><span class=w> </span><span class=kn>''</span><span class=w> </span><span class=s>close</span><span class=p>;</span>
|
||||
</span><span id=__span-6-11><a id=__codelineno-6-11 name=__codelineno-6-11 href=#__codelineno-6-11></a><span class=w> </span><span class=kn>''</span><span class=w> </span><span class=s>close</span><span class=p>;</span>
|
||||
</span><span id=__span-6-12><a id=__codelineno-6-12 name=__codelineno-6-12 href=#__codelineno-6-12></a><span class=p>}</span>
|
||||
</span><span id=__span-6-13><a id=__codelineno-6-13 name=__codelineno-6-13 href=#__codelineno-6-13></a>
|
||||
</span><span id=__span-6-14><a id=__codelineno-6-14 name=__codelineno-6-14 href=#__codelineno-6-14></a><span class=c1># http</span>
|
||||
|
||||
@@ -1,61 +1,61 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/ref/oidc/ rel=canonical><link href=../registration/ rel=prev><link href=../routes/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>OpenID Connect - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="OpenID Connect - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/oidc.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/ref/oidc/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="OpenID Connect - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/oidc.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#openid-connect class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> OpenID Connect </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-Line truncated
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span></code></pre></div> </div> <div class=tabbed-block> <ul> <li>Create a new confidential client (<code>Client ID</code>, <code>Client secret</code>)</li> <li>Add Headscale's OIDC callback URL as valid redirect URL: <code>https://headscale.example.com/oidc/callback</code></li> <li>Configure additional parameters to improve user experience such as: name, description, logo, …</li> </ul> </div> </div> </div> <h3 id=enable-pkce-recommended>Enable PKCE (recommended)<a class=headerlink href=#enable-pkce-recommended title="Permanent link">¶</a></h3> <p>Proof Key for Code Exchange (PKCE) adds an additional layer of security to the OAuth 2.0 authorization code flow by preventing authorization code interception attacks, see: <a href=https://datatracker.ietf.org/doc/html/rfc7636>https://datatracker.ietf.org/doc/html/rfc7636</a>. PKCE is recommended and needs to be configured for Headscale and the identity provider alike:</p> <div class="tabbed-set tabbed-alternate" data-tabs=2:2><input checked=checked id=__tabbed_2_1 name=__tabbed_2 type=radio><input id=__tabbed_2_2 name=__tabbed_2 type=radio><div class=tabbed-labels><label for=__tabbed_2_1>Headscale</label><label for=__tabbed_2_2>Identity provider</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a><span class=hll><span class=w> </span><span class=nt>pkce</span><span class=p>:</span>
|
||||
</span></span><span id=__span-1-6><a id=__codelineno-1-6 name=__codelineno-1-6 href=#__codelineno-1-6></a><span class=hll><span class=w> </span><span class=nt>enabled</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span></span></code></pre></div> </div> <div class=tabbed-block> <ul> <li>Enable PKCE for the headscale client</li> <li>Set the PKCE challenge method to "S256"</li> </ul> </div> </div> </div> <h3 id=authorize-users-with-filters>Authorize users with filters<a class=headerlink href=#authorize-users-with-filters title="Permanent link">¶</a></h3> <p>Headscale allows to filter for allowed users based on their domain, email address or group membership. These filters can be helpful to apply additional restrictions and control which users are allowed to join. Filters are disabled by default, users are allowed to join once the authentication with the identity provider succeeds. In case multiple filters are configured, a user needs to pass all of them.</p> <div class="tabbed-set tabbed-alternate" data-tabs=3:3><input checked=checked id=__tabbed_3_1 name=__tabbed_3 type=radio><input id=__tabbed_3_2 name=__tabbed_3 type=radio><input id=__tabbed_3_3 name=__tabbed_3 type=radio><div class=tabbed-labels><label for=__tabbed_3_1>Allowed domains</label><label for=__tabbed_3_2>Allowed users/emails</label><label for=__tabbed_3_3>Allowed groups</label></div> <div class=tabbed-content> <div class=tabbed-block> <ul> <li>Check the email domain of each authenticating user against the list of allowed domains and only authorize users whose email domain matches <code>example.com</code>.</li> <li>A verified email address is required <a href=#control-email-verification>unless email verification is disabled</a>.</li> <li>Access allowed: <code>alice@example.com</code></li> <li>Access denied: <code>bob@example.net</code></li> </ul> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-2-2><a id=__codelineno-2-2 name=__codelineno-2-2 href=#__codelineno-2-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-2-3><a id=__codelineno-2-3 name=__codelineno-2-3 href=#__codelineno-2-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-2-4><a id=__codelineno-2-4 name=__codelineno-2-4 href=#__codelineno-2-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-2-2><a id=__codelineno-2-2 name=__codelineno-2-2 href=#__codelineno-2-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-2-3><a id=__codelineno-2-3 name=__codelineno-2-3 href=#__codelineno-2-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-2-4><a id=__codelineno-2-4 name=__codelineno-2-4 href=#__codelineno-2-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-2-5><a id=__codelineno-2-5 name=__codelineno-2-5 href=#__codelineno-2-5></a><span class=hll><span class=w> </span><span class=nt>allowed_domains</span><span class=p>:</span>
|
||||
</span></span><span id=__span-2-6><a id=__codelineno-2-6 name=__codelineno-2-6 href=#__codelineno-2-6></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"example.com"</span>
|
||||
</span></span><span id=__span-2-6><a id=__codelineno-2-6 name=__codelineno-2-6 href=#__codelineno-2-6></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"example.com"</span>
|
||||
</span></span></code></pre></div> </div> <div class=tabbed-block> <ul> <li>Check the email address of each authenticating user against the list of allowed email addresses and only authorize users whose email is part of the <code>allowed_users</code> list.</li> <li>A verified email address is required <a href=#control-email-verification>unless email verification is disabled</a>.</li> <li>Access allowed: <code>alice@example.com</code>, <code>bob@example.net</code></li> <li>Access denied: <code>mallory@example.net</code></li> </ul> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-3-3><a id=__codelineno-3-3 name=__codelineno-3-3 href=#__codelineno-3-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-3-4><a id=__codelineno-3-4 name=__codelineno-3-4 href=#__codelineno-3-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-3-3><a id=__codelineno-3-3 name=__codelineno-3-3 href=#__codelineno-3-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-3-4><a id=__codelineno-3-4 name=__codelineno-3-4 href=#__codelineno-3-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-3-5><a id=__codelineno-3-5 name=__codelineno-3-5 href=#__codelineno-3-5></a><span class=hll><span class=w> </span><span class=nt>allowed_users</span><span class=p>:</span>
|
||||
</span></span><span id=__span-3-6><a id=__codelineno-3-6 name=__codelineno-3-6 href=#__codelineno-3-6></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"alice@example.com"</span>
|
||||
</span></span><span id=__span-3-7><a id=__codelineno-3-7 name=__codelineno-3-7 href=#__codelineno-3-7></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"bob@example.net"</span>
|
||||
</span></span><span id=__span-3-6><a id=__codelineno-3-6 name=__codelineno-3-6 href=#__codelineno-3-6></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"alice@example.com"</span>
|
||||
</span></span><span id=__span-3-7><a id=__codelineno-3-7 name=__codelineno-3-7 href=#__codelineno-3-7></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"bob@example.net"</span>
|
||||
</span></span></code></pre></div> </div> <div class=tabbed-block> <ul> <li>Use the OIDC <code>groups</code> claim of each authenticating user to get their group membership and only authorize users which are members in at least one of the referenced groups.</li> <li>Access allowed: users in the <code>headscale_users</code> group</li> <li>Access denied: users without groups, users with other groups</li> </ul> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-4-2><a id=__codelineno-4-2 name=__codelineno-4-2 href=#__codelineno-4-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-4-3><a id=__codelineno-4-3 name=__codelineno-4-3 href=#__codelineno-4-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-4-4><a id=__codelineno-4-4 name=__codelineno-4-4 href=#__codelineno-4-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-4-5><a id=__codelineno-4-5 name=__codelineno-4-5 href=#__codelineno-4-5></a><span class=hll><span class=w> </span><span class=nt>scope</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[</span><span class=s>"openid"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"profile"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"email"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"groups"</span><span class="p p-Indicator">]</span>
|
||||
</span><span id=__span-4-2><a id=__codelineno-4-2 name=__codelineno-4-2 href=#__codelineno-4-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-4-3><a id=__codelineno-4-3 name=__codelineno-4-3 href=#__codelineno-4-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-4-4><a id=__codelineno-4-4 name=__codelineno-4-4 href=#__codelineno-4-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-4-5><a id=__codelineno-4-5 name=__codelineno-4-5 href=#__codelineno-4-5></a><span class=hll><span class=w> </span><span class=nt>scope</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[</span><span class=s>"openid"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"profile"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"email"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"groups"</span><span class="p p-Indicator">]</span>
|
||||
</span></span><span id=__span-4-6><a id=__codelineno-4-6 name=__codelineno-4-6 href=#__codelineno-4-6></a><span class=hll><span class=w> </span><span class=nt>allowed_groups</span><span class=p>:</span>
|
||||
</span></span><span id=__span-4-7><a id=__codelineno-4-7 name=__codelineno-4-7 href=#__codelineno-4-7></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"headscale_users"</span>
|
||||
</span></span><span id=__span-4-7><a id=__codelineno-4-7 name=__codelineno-4-7 href=#__codelineno-4-7></a><span class=hll><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"headscale_users"</span>
|
||||
</span></span></code></pre></div> </div> </div> </div> <h3 id=control-email-verification>Control email verification<a class=headerlink href=#control-email-verification title="Permanent link">¶</a></h3> <p>Headscale uses the <code>email</code> claim from the identity provider to synchronize the email address to its user profile. By default, a user's email address is only synchronized when the identity provider reports the email address as verified via the <code>email_verified: true</code> claim.</p> <p>Unverified emails may be allowed in case an identity provider does not send the <code>email_verified</code> claim or email verification is not required. In that case, a user's email address is always synchronized to the user profile.</p> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-5-3><a id=__codelineno-5-3 name=__codelineno-5-3 href=#__codelineno-5-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-5-4><a id=__codelineno-5-4 name=__codelineno-5-4 href=#__codelineno-5-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-5-3><a id=__codelineno-5-3 name=__codelineno-5-3 href=#__codelineno-5-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-5-4><a id=__codelineno-5-4 name=__codelineno-5-4 href=#__codelineno-5-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-5-5><a id=__codelineno-5-5 name=__codelineno-5-5 href=#__codelineno-5-5></a><span class=hll><span class=w> </span><span class=nt>email_verified_required</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
||||
</span></span></code></pre></div> <h3 id=customize-node-expiration>Customize node expiration<a class=headerlink href=#customize-node-expiration title="Permanent link">¶</a></h3> <p>The node expiration is the amount of time a node is authenticated with OpenID Connect until it expires and needs to reauthenticate. The default node expiration can be configured via the top-level <code>node.expiry</code> setting.</p> <div class="tabbed-set tabbed-alternate" data-tabs=4:2><input checked=checked id=__tabbed_4_1 name=__tabbed_4 type=radio><input id=__tabbed_4_2 name=__tabbed_4 type=radio><div class=tabbed-labels><label for=__tabbed_4_1>Customize node expiration</label><label for=__tabbed_4_2>Use expiration from Access Token</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=nt>node</span><span class=p>:</span>
|
||||
</span><span id=__span-6-2><a id=__codelineno-6-2 name=__codelineno-6-2 href=#__codelineno-6-2></a><span class=hll><span class=w> </span><span class=nt>expiry</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">30d</span><span class=w> </span><span class=c1># Use 0 to disable node expiration</span>
|
||||
</span></span></code></pre></div> </div> <div class=tabbed-block> <p>Please keep in mind that the Access Token is typically a short-lived token that expires within a few minutes. You will have to configure token expiration in your identity provider to avoid frequent re-authentication.</p> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-7-3><a id=__codelineno-7-3 name=__codelineno-7-3 href=#__codelineno-7-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-7-4><a id=__codelineno-7-4 name=__codelineno-7-4 href=#__codelineno-7-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>"https://sso.example.com"</span>
|
||||
</span><span id=__span-7-3><a id=__codelineno-7-3 name=__codelineno-7-3 href=#__codelineno-7-3></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>"headscale"</span>
|
||||
</span><span id=__span-7-4><a id=__codelineno-7-4 name=__codelineno-7-4 href=#__codelineno-7-4></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>"generated-secret"</span>
|
||||
</span><span id=__span-7-5><a id=__codelineno-7-5 name=__codelineno-7-5 href=#__codelineno-7-5></a><span class=hll><span class=w> </span><span class=nt>use_expiry_from_token</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
||||
</span></span></code></pre></div> </div> </div> </div> <div class="admonition tip"> <p class=admonition-title>Expire a node and force re-authentication</p> <p>A node can be expired immediately via:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-8-1><a id=__codelineno-8-1 name=__codelineno-8-1 href=#__codelineno-8-1></a><span class=go>headscale node expire -i <NODE_ID></span>
|
||||
</span></code></pre></div> </div> <h3 id=reference-a-user-in-the-policy>Reference a user in the policy<a class=headerlink href=#reference-a-user-in-the-policy title="Permanent link">¶</a></h3> <p>You may refer to users in the Headscale policy via:</p> <ul> <li>Email address</li> <li>Username</li> <li>Provider identifier (this value is currently only available from the <a href=../api/ >API</a>, database or directly from your identity provider)</li> </ul> <div class="admonition note"> <p class=admonition-title>A user identifier in the policy must contain a single <code>@</code></p> <p>The Headscale policy requires a single <code>@</code> to reference a user. If the username or provider identifier doesn't already contain a single <code>@</code>, it needs to be appended at the end. For example: the Headscale username <code>ssmith</code> has to be written as <code>ssmith@</code> to be correctly identified as user within the policy.</p> <p>Ensure that the Headscale username itself does not end with <code>@</code>.</p> </div> <div class="admonition warning"> <p class=admonition-title>Email address or username might be updated by users</p> <p>Many identity providers allow users to update their own profile. Depending on the identity provider and its configuration, the values for username or email address might change over time. This might have unexpected consequences for Headscale where a policy might no longer work or a user might obtain more access by hijacking an existing username or email address.</p> </div> <div class="admonition tip"> <p class=admonition-title>Howto use the provider identifier in the policy</p> <p>The provider identifier uniquely identifies an OIDC user and a well-behaving identity provider guarantees that this value never changes for a particular user. It is usually an opaque and long string and its value is currently only available from the <a href=../api/ >API</a>, database or directly from your identity provider).</p> <p>Use the <a href=../api/ >API</a> with the <code>/api/v1/user</code> endpoint to fetch the provider identifier (<code>providerId</code>). The value (be sure to append an <code>@</code> in case the provider identifier doesn't already contain an <code>@</code> somewhere) can be used directly to reference a user in the policy. To improve readability of the policy, one may use the <code>groups</code> section as an alias:</p> <div class="language-json highlight"><pre><span></span><code><span id=__span-9-1><a id=__codelineno-9-1 name=__codelineno-9-1 href=#__codelineno-9-1></a><span class=p>{</span>
|
||||
</span><span id=__span-9-2><a id=__codelineno-9-2 name=__codelineno-9-2 href=#__codelineno-9-2></a><span class=w> </span><span class=nt>"groups"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-9-3><a id=__codelineno-9-3 name=__codelineno-9-3 href=#__codelineno-9-3></a><span class=w> </span><span class=nt>"group:alice"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-9-4><a id=__codelineno-9-4 name=__codelineno-9-4 href=#__codelineno-9-4></a><span class=w> </span><span class=s2>"https://sso.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@"</span>
|
||||
</span><span id=__span-9-2><a id=__codelineno-9-2 name=__codelineno-9-2 href=#__codelineno-9-2></a><span class=w> </span><span class=nt>"groups"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-9-3><a id=__codelineno-9-3 name=__codelineno-9-3 href=#__codelineno-9-3></a><span class=w> </span><span class=nt>"group:alice"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-9-4><a id=__codelineno-9-4 name=__codelineno-9-4 href=#__codelineno-9-4></a><span class=w> </span><span class=s2>"https://sso.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@"</span>
|
||||
</span><span id=__span-9-5><a id=__codelineno-9-5 name=__codelineno-9-5 href=#__codelineno-9-5></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-9-6><a id=__codelineno-9-6 name=__codelineno-9-6 href=#__codelineno-9-6></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-9-7><a id=__codelineno-9-7 name=__codelineno-9-7 href=#__codelineno-9-7></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-9-7><a id=__codelineno-9-7 name=__codelineno-9-7 href=#__codelineno-9-7></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-9-8><a id=__codelineno-9-8 name=__codelineno-9-8 href=#__codelineno-9-8></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-9-9><a id=__codelineno-9-9 name=__codelineno-9-9 href=#__codelineno-9-9></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"group:alice"</span><span class=p>],</span>
|
||||
</span><span id=__span-9-10><a id=__codelineno-9-10 name=__codelineno-9-10 href=#__codelineno-9-10></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>],</span>
|
||||
</span><span id=__span-9-11><a id=__codelineno-9-11 name=__codelineno-9-11 href=#__codelineno-9-11></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-9-9><a id=__codelineno-9-9 name=__codelineno-9-9 href=#__codelineno-9-9></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"group:alice"</span><span class=p>],</span>
|
||||
</span><span id=__span-9-10><a id=__codelineno-9-10 name=__codelineno-9-10 href=#__codelineno-9-10></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>],</span>
|
||||
</span><span id=__span-9-11><a id=__codelineno-9-11 name=__codelineno-9-11 href=#__codelineno-9-11></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-9-12><a id=__codelineno-9-12 name=__codelineno-9-12 href=#__codelineno-9-12></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-9-13><a id=__codelineno-9-13 name=__codelineno-9-13 href=#__codelineno-9-13></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-9-14><a id=__codelineno-9-14 name=__codelineno-9-14 href=#__codelineno-9-14></a><span class=p>}</span>
|
||||
</span></code></pre></div> </div> <h2 id=supported-oidc-claims>Supported OIDC claims<a class=headerlink href=#supported-oidc-claims title="Permanent link">¶</a></h2> <p>Headscale uses <a href=https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims>the standard OIDC claims</a> to populate and update its local user profile on each login. OIDC claims are read from the ID Token and from the UserInfo endpoint.</p> <table> <thead> <tr> <th>Headscale profile</th> <th>OIDC claim</th> <th>Notes / examples</th> </tr> </thead> <tbody> <tr> <td>email address</td> <td><code>email</code></td> <td>Only verified emails are synchronized, unless <code>email_verified_required: false</code> is configured</td> </tr> <tr> <td>display name</td> <td><code>name</code></td> <td>eg: <code>Sam Smith</code></td> </tr> <tr> <td>username</td> <td><code>preferred_username</code></td> <td>Depends on identity provider, eg: <code>ssmith</code>, <code>ssmith@idp.example.com</code>, <code>\\example.com\ssmith</code></td> </tr> <tr> <td>profile picture</td> <td><code>picture</code></td> <td>URL to a profile picture or avatar</td> </tr> <tr> <td>provider identifier</td> <td><code>iss</code>, <code>sub</code></td> <td>A stable and unique identifier for a user, typically a combination of <code>iss</code> and <code>sub</code> OIDC claims</td> </tr> <tr> <td></td> <td><code>groups</code></td> <td><a href=#authorize-users-with-filters>Only used to filter for allowed groups</a></td> </tr> </tbody> </table> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="Permanent link">¶</a></h2> <ul> <li>Support for OpenID Connect aims to be generic and vendor independent. It offers only limited support for quirks of specific identity providers.</li> <li>OIDC groups cannot be used in policy rules.</li> <li>The username provided by the identity provider needs to adhere to this pattern:<ul> <li>The username must be at least two characters long.</li> <li>It must only contain letters, digits, hyphens, dots, underscores, and up to a single <code>@</code>.</li> <li>The username must start with a letter.</li> </ul> </li> </ul> <p>Please see the <a href=https://github.com/juanfont/headscale/labels/OIDC>GitHub label "OIDC"</a> for OIDC related issues.</p> <h2 id=identity-provider-specific-configuration>Identity provider specific configuration<a class=headerlink href=#identity-provider-specific-configuration title="Permanent link">¶</a></h2> <div class="admonition warning"> <p class=admonition-title>Third-party software and services</p> <p>This section of the documentation is specific for third-party software and services. We recommend users read the third-party documentation on how to configure and integrate an OIDC client. Please see the <a href=#configuration>Configuration section</a> for a description of Headscale's OIDC related configuration settings.</p> </div> <p>Any identity provider with OpenID Connect support should "just work" with Headscale. The following identity providers are known to work:</p> <ul> <li><a href=#authelia>Authelia</a></li> <li><a href=#authentik>Authentik</a></li> <li><a href=#kanidm>Kanidm</a></li> <li><a href=#keycloak>Keycloak</a></li> </ul> <h3 id=authelia>Authelia<a class=headerlink href=#authelia title="Permanent link">¶</a></h3> <p>Authelia is fully supported by Headscale.</p> <h3 id=authentik>Authentik<a class=headerlink href=#authentik title="Permanent link">¶</a></h3> <ul> <li>Authentik is fully supported by Headscale.</li> <li><a href=https://github.com/juanfont/headscale/issues/2446>Headscale does not support JSON Web Encryption</a>. Leave the field <code>Encryption Key</code> in the providers section unset.</li> <li>See Authentik's <a href=https://integrations.goauthentik.io/networking/headscale/ >Integrate with Headscale</a></li> </ul> <h3 id=google-oauth>Google OAuth<a class=headerlink href=#google-oauth title="Permanent link">¶</a></h3> <div class="admonition warning"> <p class=admonition-title>No username due to missing preferred_username claim</p> <p>Google OAuth does not send the <code>preferred_username</code> claim when the <code>profile</code> scope is requested. The username in Headscale will be blank/not set.</p> </div> <p>In order to integrate Headscale with Google, you'll need to have a <a href=https://console.cloud.google.com>Google Cloud Console</a> account.</p> <p>Google OAuth has a <a href="https://support.google.com/cloud/answer/9110914?hl=en">verification process</a> if you need to have users authenticate who are outside of your domain. If you only need to authenticate users from your domain name (ie <code>@example.com</code>), you don't need to go through the verification process.</p> <p>However if you don't have a domain, or need to add users outside of your domain, you can manually add emails via Google Console.</p> <h4 id=steps>Steps<a class=headerlink href=#steps title="Permanent link">¶</a></h4> <ol> <li>Go to <a href=https://console.cLine truncated
|
||||
</span></code></pre></div> Once configured, the short username in Headscale will be <code>alice</code> and can be referred to as <code>alice@</code> in the policy.</li> </ul> <h3 id=keycloak>Keycloak<a class=headerlink href=#keycloak title="Permanent link">¶</a></h3> <p>Keycloak is fully supported by Headscale.</p> <h4 id=additional-configuration-to-use-the-allowed-groups-filter>Additional configuration to use the allowed groups filter<a class=headerlink href=#additional-configuration-to-use-the-allowed-groups-filter title="Permanent link">¶</a></h4> <p>Keycloak has no built-in client scope for the OIDC <code>groups</code> claim. This extra configuration step is <strong>only</strong> needed if you need to <a href=#authorize-users-with-filters>authorize access based on group membership</a>.</p> <ul> <li>Create a new client scope <code>groups</code> for OpenID Connect:<ul> <li>Configure a <code>Group Membership</code> mapper with name <code>groups</code> and the token claim name <code>groups</code>.</li> <li>Add the mapper to at least the UserInfo endpoint.</li> </ul> </li> <li>Configure the new client scope for your Headscale client:<ul> <li>Edit the Headscale client.</li> <li>Search for the client scope <code>group</code>.</li> <li>Add it with assigned type <code>Default</code>.</li> </ul> </li> <li><a href=#authorize-users-with-filters>Configure the allowed groups in Headscale</a>. How groups need to be specified depends on Keycloak's <code>Full group path</code> option:<ul> <li><code>Full group path</code> is enabled: groups contain their full path, e.g. <code>/top/group1</code></li> <li><code>Full group path</code> is disabled: only the name of the group is used, e.g. <code>group1</code></li> </ul> </li> </ul> <h3 id=microsoft-entra-id>Microsoft Entra ID<a class=headerlink href=#microsoft-entra-id title="Permanent link">¶</a></h3> <p>In order to integrate Headscale with Microsoft Entra ID, you'll need to provision an App Registration with the correct scopes and redirect URI.</p> <p><a href=#basic-configuration>Configure Headscale following the "Basic configuration" steps</a>. The issuer URL for Microsoft Entra ID is: <code>https://login.microsoftonline.com/<tenant-UUID>/v2.0</code>. The following <code>extra_params</code> might be useful:</p> <ul> <li><code>domain_hint: example.com</code> to use your own domain</li> <li><code>prompt: select_account</code> to force an account picker during login</li> </ul> <p>When using Microsoft Entra ID together with the <a href=#authorize-users-with-filters>allowed groups filter</a>, configure the Headscale OIDC scope without the <code>groups</code> claim, for example:</p> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-11-1><a id=__codelineno-11-1 name=__codelineno-11-1 href=#__codelineno-11-1></a><span class=nt>oidc</span><span class=p>:</span>
|
||||
</span><span id=__span-11-2><a id=__codelineno-11-2 name=__codelineno-11-2 href=#__codelineno-11-2></a><span class=w> </span><span class=nt>scope</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[</span><span class=s>"openid"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"profile"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"email"</span><span class="p p-Indicator">]</span>
|
||||
</span><span id=__span-11-2><a id=__codelineno-11-2 name=__codelineno-11-2 href=#__codelineno-11-2></a><span class=w> </span><span class=nt>scope</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[</span><span class=s>"openid"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"profile"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"email"</span><span class="p p-Indicator">]</span>
|
||||
</span></code></pre></div> <p>Groups for the <a href=#authorize-users-with-filters>allowed groups filter</a> need to be specified with their group ID(UUID) instead of the group name.</p> <h2 id=switching-oidc-providers>Switching OIDC providers<a class=headerlink href=#switching-oidc-providers title="Permanent link">¶</a></h2> <p>Headscale only supports a single OIDC provider in its configuration, but it does store the provider identifier of each user. When switching providers, this might lead to issues with existing users: all user details (name, email, groups) might be identical with the new provider, but the identifier will differ. Headscale will be unable to create a new user as the name and email will already be in use for the existing users.</p> <p>At this time, you will need to manually update the <code>provider_identifier</code> column in the <code>users</code> table for each user with the appropriate value for the new provider. The identifier is built from the <code>iss</code> and <code>sub</code> claims of the OIDC ID token, for example <code>https://id.example.com/12340987</code>.</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <div class=md-top data-md-component=top hidden> <div class=md-top__center> <button type=button class="md-top__button md-top__button--main" data-md-action=top> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> <span>Back to top</span> </button> <label class="md-top__button md-top__side md-top__side--nav" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-left" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M9 3v18"/></svg> </label> <label class="md-top__button md-top__side md-top__side--toc" for=__toc> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-right" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M15 3v18"/></svg> </label> </div> </div> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../registration/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Registration methods"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Registration methods </div> </div> </a> <a href=../routes/ class="md-footer__link md-footer__link--next" aria-label="Next: Routes"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Routes </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2026 Headscale authors </div> Made with <a href=https://jaywhj.github.io/mkdocs-materialx/ target=_blank rel=noopener> MaterialX </a> </div> <div class=md-social> <a href=https://github.com/juanfont/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2Line truncated
|
||||
@@ -1,85 +1,85 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/ref/policy/ rel=canonical><link href=../tls/ rel=prev><link href=../dns/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Policy - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="Policy - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/policy.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/ref/policy/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Policy - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/policy.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#policy class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Policy </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)Line truncated
|
||||
</span></code></pre></div> <h3 id=deny-all>Deny All<a class=headerlink href=#deny-all title="Permanent link">¶</a></h3> <p>To <a href=https://tailscale.com/docs/reference/examples/acls#deny-all>prevent all communication within your tailnet</a>, you can include an empty array for the <code>"grants"</code> section in your policy file.</p> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=p>{</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[]</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[]</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h3 id=more-examples>More examples<a class=headerlink href=#more-examples title="Permanent link">¶</a></h3> <ul> <li>See our documentation on <a href=../routes/#subnet-router>subnet routers</a> and <a href=../routes/#exit-node>exit nodes</a> to learn how to restrict their use or how to automatically approve them.</li> <li>The Tailscale documentation provides a large collection of configuration examples:<ul> <li><a href=https://tailscale.com/docs/reference/examples/acls>ACL examples</a></li> <li><a href=https://tailscale.com/docs/reference/examples/grants>Grants examples</a></li> <li><a href=https://tailscale.com/docs/features/tailscale-ssh#configure-tailscale-ssh>SSH configuration</a></li> <li><a href=https://tailscale.com/docs/features/tags#define-a-tag>Define a tag</a></li> </ul> </li> </ul> <hr> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="Permanent link">¶</a></h2> <ul> <li><a href=https://tailscale.com/docs/features/device-posture>Device postures</a> and the related sections such as <code>postures</code> or <code>srcPosture</code> aren't supported.</li> <li><a href=https://tailscale.com/docs/features/tailnet-policy-file/ip-sets>IP sets</a> aren't supported.</li> <li>A subset of <a href=#autogroups>Autogroups</a> are available.</li> </ul> <h2 id=autogroups>Autogroups<a class=headerlink href=#autogroups title="Permanent link">¶</a></h2> <p>Headscale supports several <a href=https://tailscale.com/docs/reference/targets-and-selectors#autogroups>Autogroups</a> that automatically include users, destinations, or devices with specific properties. Autogroups provide a convenient way to write policy rules without manually listing individual users or devices.</p> <h3 id=autogroupinternet><a href=https://tailscale.com/docs/reference/targets-and-selectors#autogroupinternet><code>autogroup:internet</code></a><a class=headerlink href=#autogroupinternet title="Permanent link">¶</a></h3> <p>Allows access to the internet through <a href=../routes/#exit-node>exit nodes</a>. Can only be used in policy destinations.</p> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a><span class=p>{</span>
|
||||
</span><span id=__span-2-2><a id=__codelineno-2-2 name=__codelineno-2-2 href=#__codelineno-2-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-2-2><a id=__codelineno-2-2 name=__codelineno-2-2 href=#__codelineno-2-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-2-3><a id=__codelineno-2-3 name=__codelineno-2-3 href=#__codelineno-2-3></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-2-4><a id=__codelineno-2-4 name=__codelineno-2-4 href=#__codelineno-2-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>],</span>
|
||||
</span><span id=__span-2-5><a id=__codelineno-2-5 name=__codelineno-2-5 href=#__codelineno-2-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:internet"</span><span class=p>],</span>
|
||||
</span><span id=__span-2-6><a id=__codelineno-2-6 name=__codelineno-2-6 href=#__codelineno-2-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-2-4><a id=__codelineno-2-4 name=__codelineno-2-4 href=#__codelineno-2-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>],</span>
|
||||
</span><span id=__span-2-5><a id=__codelineno-2-5 name=__codelineno-2-5 href=#__codelineno-2-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:internet"</span><span class=p>],</span>
|
||||
</span><span id=__span-2-6><a id=__codelineno-2-6 name=__codelineno-2-6 href=#__codelineno-2-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-2-7><a id=__codelineno-2-7 name=__codelineno-2-7 href=#__codelineno-2-7></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-2-8><a id=__codelineno-2-8 name=__codelineno-2-8 href=#__codelineno-2-8></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-2-9><a id=__codelineno-2-9 name=__codelineno-2-9 href=#__codelineno-2-9></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h3 id=autogroupmember><a href=https://tailscale.com/docs/reference/targets-and-selectors#autogrouprole><code>autogroup:member</code></a><a class=headerlink href=#autogroupmember title="Permanent link">¶</a></h3> <p>Includes all <a href=../registration/#identity-model>personal (untagged) devices</a>.</p> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=p>{</span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-3-3><a id=__codelineno-3-3 name=__codelineno-3-3 href=#__codelineno-3-3></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-3-4><a id=__codelineno-3-4 name=__codelineno-3-4 href=#__codelineno-3-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:member"</span><span class=p>],</span>
|
||||
</span><span id=__span-3-5><a id=__codelineno-3-5 name=__codelineno-3-5 href=#__codelineno-3-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:prod-app-servers"</span><span class=p>],</span>
|
||||
</span><span id=__span-3-6><a id=__codelineno-3-6 name=__codelineno-3-6 href=#__codelineno-3-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"80,443"</span><span class=p>]</span>
|
||||
</span><span id=__span-3-4><a id=__codelineno-3-4 name=__codelineno-3-4 href=#__codelineno-3-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:member"</span><span class=p>],</span>
|
||||
</span><span id=__span-3-5><a id=__codelineno-3-5 name=__codelineno-3-5 href=#__codelineno-3-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:prod-app-servers"</span><span class=p>],</span>
|
||||
</span><span id=__span-3-6><a id=__codelineno-3-6 name=__codelineno-3-6 href=#__codelineno-3-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"80,443"</span><span class=p>]</span>
|
||||
</span><span id=__span-3-7><a id=__codelineno-3-7 name=__codelineno-3-7 href=#__codelineno-3-7></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-3-8><a id=__codelineno-3-8 name=__codelineno-3-8 href=#__codelineno-3-8></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-3-9><a id=__codelineno-3-9 name=__codelineno-3-9 href=#__codelineno-3-9></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h3 id=autogrouptagged><a href=https://tailscale.com/docs/reference/targets-and-selectors#autogrouptagged><code>autogroup:tagged</code></a><a class=headerlink href=#autogrouptagged title="Permanent link">¶</a></h3> <p>Includes all devices that <a href=../registration/#identity-model>have at least one tag</a>.</p> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a><span class=p>{</span>
|
||||
</span><span id=__span-4-2><a id=__codelineno-4-2 name=__codelineno-4-2 href=#__codelineno-4-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-4-2><a id=__codelineno-4-2 name=__codelineno-4-2 href=#__codelineno-4-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-4-3><a id=__codelineno-4-3 name=__codelineno-4-3 href=#__codelineno-4-3></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-4-4><a id=__codelineno-4-4 name=__codelineno-4-4 href=#__codelineno-4-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:tagged"</span><span class=p>],</span>
|
||||
</span><span id=__span-4-5><a id=__codelineno-4-5 name=__codelineno-4-5 href=#__codelineno-4-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:monitoring"</span><span class=p>],</span>
|
||||
</span><span id=__span-4-6><a id=__codelineno-4-6 name=__codelineno-4-6 href=#__codelineno-4-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"9090"</span><span class=p>]</span>
|
||||
</span><span id=__span-4-4><a id=__codelineno-4-4 name=__codelineno-4-4 href=#__codelineno-4-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:tagged"</span><span class=p>],</span>
|
||||
</span><span id=__span-4-5><a id=__codelineno-4-5 name=__codelineno-4-5 href=#__codelineno-4-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:monitoring"</span><span class=p>],</span>
|
||||
</span><span id=__span-4-6><a id=__codelineno-4-6 name=__codelineno-4-6 href=#__codelineno-4-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"9090"</span><span class=p>]</span>
|
||||
</span><span id=__span-4-7><a id=__codelineno-4-7 name=__codelineno-4-7 href=#__codelineno-4-7></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-4-8><a id=__codelineno-4-8 name=__codelineno-4-8 href=#__codelineno-4-8></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-4-9><a id=__codelineno-4-9 name=__codelineno-4-9 href=#__codelineno-4-9></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h3 id=autogroupself><a href=https://tailscale.com/docs/reference/targets-and-selectors#autogroupself><code>autogroup:self</code></a><a class=headerlink href=#autogroupself title="Permanent link">¶</a></h3> <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 policy destinations.</p> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a><span class=p>{</span>
|
||||
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-5-3><a id=__codelineno-5-3 name=__codelineno-5-3 href=#__codelineno-5-3></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-5-4><a id=__codelineno-5-4 name=__codelineno-5-4 href=#__codelineno-5-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:member"</span><span class=p>],</span>
|
||||
</span><span id=__span-5-5><a id=__codelineno-5-5 name=__codelineno-5-5 href=#__codelineno-5-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:self"</span><span class=p>],</span>
|
||||
</span><span id=__span-5-6><a id=__codelineno-5-6 name=__codelineno-5-6 href=#__codelineno-5-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-5-4><a id=__codelineno-5-4 name=__codelineno-5-4 href=#__codelineno-5-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:member"</span><span class=p>],</span>
|
||||
</span><span id=__span-5-5><a id=__codelineno-5-5 name=__codelineno-5-5 href=#__codelineno-5-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:self"</span><span class=p>],</span>
|
||||
</span><span id=__span-5-6><a id=__codelineno-5-6 name=__codelineno-5-6 href=#__codelineno-5-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-5-7><a id=__codelineno-5-7 name=__codelineno-5-7 href=#__codelineno-5-7></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-5-8><a id=__codelineno-5-8 name=__codelineno-5-8 href=#__codelineno-5-8></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-5-9><a id=__codelineno-5-9 name=__codelineno-5-9 href=#__codelineno-5-9></a><span class=p>}</span>
|
||||
</span></code></pre></div> <div class="admonition warning"> <p class=admonition-title>The current implementation of <code>autogroup:self</code> is inefficient</p> <p>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.</p> <p>If you experience performance issues, consider using more specific policy rules or limiting the use of <code>autogroup:self</code>.</p> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=p>{</span>
|
||||
</span><span id=__span-6-2><a id=__codelineno-6-2 name=__codelineno-6-2 href=#__codelineno-6-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-6-2><a id=__codelineno-6-2 name=__codelineno-6-2 href=#__codelineno-6-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-6-3><a id=__codelineno-6-3 name=__codelineno-6-3 href=#__codelineno-6-3></a><span class=w> </span><span class=c1>// The following rules allow internal users to communicate with their</span>
|
||||
</span><span id=__span-6-4><a id=__codelineno-6-4 name=__codelineno-6-4 href=#__codelineno-6-4></a><span class=w> </span><span class=c1>// own nodes in case autogroup:self is causing performance issues.</span>
|
||||
</span><span id=__span-6-5><a id=__codelineno-6-5 name=__codelineno-6-5 href=#__codelineno-6-5></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-6-6><a id=__codelineno-6-6 name=__codelineno-6-6 href=#__codelineno-6-6></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"boss@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-7><a id=__codelineno-6-7 name=__codelineno-6-7 href=#__codelineno-6-7></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"boss@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-8><a id=__codelineno-6-8 name=__codelineno-6-8 href=#__codelineno-6-8></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-6-6><a id=__codelineno-6-6 name=__codelineno-6-6 href=#__codelineno-6-6></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"boss@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-7><a id=__codelineno-6-7 name=__codelineno-6-7 href=#__codelineno-6-7></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"boss@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-8><a id=__codelineno-6-8 name=__codelineno-6-8 href=#__codelineno-6-8></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-6-9><a id=__codelineno-6-9 name=__codelineno-6-9 href=#__codelineno-6-9></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-6-10><a id=__codelineno-6-10 name=__codelineno-6-10 href=#__codelineno-6-10></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-6-11><a id=__codelineno-6-11 name=__codelineno-6-11 href=#__codelineno-6-11></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"dev1@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-12><a id=__codelineno-6-12 name=__codelineno-6-12 href=#__codelineno-6-12></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"dev1@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-13><a id=__codelineno-6-13 name=__codelineno-6-13 href=#__codelineno-6-13></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-6-11><a id=__codelineno-6-11 name=__codelineno-6-11 href=#__codelineno-6-11></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"dev1@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-12><a id=__codelineno-6-12 name=__codelineno-6-12 href=#__codelineno-6-12></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"dev1@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-13><a id=__codelineno-6-13 name=__codelineno-6-13 href=#__codelineno-6-13></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-6-14><a id=__codelineno-6-14 name=__codelineno-6-14 href=#__codelineno-6-14></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-6-15><a id=__codelineno-6-15 name=__codelineno-6-15 href=#__codelineno-6-15></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-6-16><a id=__codelineno-6-16 name=__codelineno-6-16 href=#__codelineno-6-16></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"intern1@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-17><a id=__codelineno-6-17 name=__codelineno-6-17 href=#__codelineno-6-17></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"intern1@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-18><a id=__codelineno-6-18 name=__codelineno-6-18 href=#__codelineno-6-18></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-6-16><a id=__codelineno-6-16 name=__codelineno-6-16 href=#__codelineno-6-16></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"intern1@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-17><a id=__codelineno-6-17 name=__codelineno-6-17 href=#__codelineno-6-17></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"intern1@"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-18><a id=__codelineno-6-18 name=__codelineno-6-18 href=#__codelineno-6-18></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-6-19><a id=__codelineno-6-19 name=__codelineno-6-19 href=#__codelineno-6-19></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-6-20><a id=__codelineno-6-20 name=__codelineno-6-20 href=#__codelineno-6-20></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-6-21><a id=__codelineno-6-21 name=__codelineno-6-21 href=#__codelineno-6-21></a><span class=p>}</span>
|
||||
</span></code></pre></div> </div> <h3 id=autogroupnonroot><a href=https://tailscale.com/docs/reference/targets-and-selectors#other-built-in-targets><code>autogroup:nonroot</code></a><a class=headerlink href=#autogroupnonroot title="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> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a><span class=p>{</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=w> </span><span class=nt>"ssh"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=w> </span><span class=nt>"ssh"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-7-3><a id=__codelineno-7-3 name=__codelineno-7-3 href=#__codelineno-7-3></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-7-4><a id=__codelineno-7-4 name=__codelineno-7-4 href=#__codelineno-7-4></a><span class=w> </span><span class=nt>"action"</span><span class=p>:</span><span class=w> </span><span class=s2>"accept"</span><span class=p>,</span>
|
||||
</span><span id=__span-7-5><a id=__codelineno-7-5 name=__codelineno-7-5 href=#__codelineno-7-5></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:member"</span><span class=p>],</span>
|
||||
</span><span id=__span-7-6><a id=__codelineno-7-6 name=__codelineno-7-6 href=#__codelineno-7-6></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:self"</span><span class=p>],</span>
|
||||
</span><span id=__span-7-7><a id=__codelineno-7-7 name=__codelineno-7-7 href=#__codelineno-7-7></a><span class=w> </span><span class=nt>"users"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:nonroot"</span><span class=p>]</span>
|
||||
</span><span id=__span-7-4><a id=__codelineno-7-4 name=__codelineno-7-4 href=#__codelineno-7-4></a><span class=w> </span><span class=nt>"action"</span><span class=p>:</span><span class=w> </span><span class=s2>"accept"</span><span class=p>,</span>
|
||||
</span><span id=__span-7-5><a id=__codelineno-7-5 name=__codelineno-7-5 href=#__codelineno-7-5></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:member"</span><span class=p>],</span>
|
||||
</span><span id=__span-7-6><a id=__codelineno-7-6 name=__codelineno-7-6 href=#__codelineno-7-6></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:self"</span><span class=p>],</span>
|
||||
</span><span id=__span-7-7><a id=__codelineno-7-7 name=__codelineno-7-7 href=#__codelineno-7-7></a><span class=w> </span><span class=nt>"users"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:nonroot"</span><span class=p>]</span>
|
||||
</span><span id=__span-7-8><a id=__codelineno-7-8 name=__codelineno-7-8 href=#__codelineno-7-8></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-7-9><a id=__codelineno-7-9 name=__codelineno-7-9 href=#__codelineno-7-9></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-7-10><a id=__codelineno-7-10 name=__codelineno-7-10 href=#__codelineno-7-10></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h3 id=autogroupdanger-all><a href=https://tailscale.com/docs/reference/targets-and-selectors#autogroupdanger-all><code>autogroup:danger-all</code></a><a class=headerlink href=#autogroupdanger-all title="Permanent link">¶</a></h3> <p>This autogroup resolves to all IP addresses (<code>0.0.0.0/0</code> and <code>::/0</code>) which also includes all IP addresses outside the standard Tailscale IP ranges. This autogroup can only be used as source.</p> <h2 id=node-attributes>Node Attributes<a class=headerlink href=#node-attributes title="Permanent link">¶</a></h2> <p><a href=https://tailscale.com/docs/reference/syntax/policy-file#node-attributes>Node attributes</a> allow for device-specific configuration and attributes. At least the following node attributes are currently supported by Headscale<sup id=fnref:2><a class=footnote-ref href=#fn:2>2</a></sup>:</p> <ul> <li><code>drive:access</code>, <code>drive:share</code>: <a href=https://tailscale.com/docs/features/taildrive>Taildrive support</a>.</li> <li><code>nextdns:<profile></code>, <code>nextdns:no-device-info</code>: <a href=https://tailscale.com/docs/integrations/nextdns>NextDNS integration</a>. Be sure to set NextDNS as global resolver in the <a href=../configuration/ >configuration</a>.</li> <li><code>magicdns-aaaa</code>: Respond to AAAA queries on the local <a href=https://tailscale.com/docs/features/magicdns>MagicDNS</a> resolver at 100.100.100.100.</li> <li><code>disable-ipv4</code>: Selectively disable IPv4 for specfic nodes. This is may be useful to workaround <a href=https://tailscale.com/docs/reference/troubleshooting/network-configuration/cgnat-conflicts>CGNat conflicts</a>.</li> <li><code>randomize-client-port</code>: Allocate a <a href=https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport>random port for WireGuard traffic</a> instead of the static default port 41641.</li> <li><code>disable-captive-portal-detection</code>: <a href=https://tailscale.com/docs/integrations/captive-portals#disable-captive-portal-detection>Disable automatic captive portal detection</a>.</li> </ul> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-8-1><a id=__codelineno-8-1 name=__codelineno-8-1 href=#__codelineno-8-1></a><span class=p>{</span>
|
||||
</span><span id=__span-8-2><a id=__codelineno-8-2 name=__codelineno-8-2 href=#__codelineno-8-2></a><span class=w> </span><span class=nt>"nodeAttrs"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-8-2><a id=__codelineno-8-2 name=__codelineno-8-2 href=#__codelineno-8-2></a><span class=w> </span><span class=nt>"nodeAttrs"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-8-3><a id=__codelineno-8-3 name=__codelineno-8-3 href=#__codelineno-8-3></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-8-4><a id=__codelineno-8-4 name=__codelineno-8-4 href=#__codelineno-8-4></a><span class=w> </span><span class=c1>// Enable MagicDNS AAAA records for all nodes</span>
|
||||
</span><span id=__span-8-5><a id=__codelineno-8-5 name=__codelineno-8-5 href=#__codelineno-8-5></a><span class=w> </span><span class=nt>"target"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-8-6><a id=__codelineno-8-6 name=__codelineno-8-6 href=#__codelineno-8-6></a><span class=w> </span><span class=nt>"attr"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"magicdns-aaaa"</span><span class=p>]</span>
|
||||
</span><span id=__span-8-5><a id=__codelineno-8-5 name=__codelineno-8-5 href=#__codelineno-8-5></a><span class=w> </span><span class=nt>"target"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-8-6><a id=__codelineno-8-6 name=__codelineno-8-6 href=#__codelineno-8-6></a><span class=w> </span><span class=nt>"attr"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"magicdns-aaaa"</span><span class=p>]</span>
|
||||
</span><span id=__span-8-7><a id=__codelineno-8-7 name=__codelineno-8-7 href=#__codelineno-8-7></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-8-8><a id=__codelineno-8-8 name=__codelineno-8-8 href=#__codelineno-8-8></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-8-9><a id=__codelineno-8-9 name=__codelineno-8-9 href=#__codelineno-8-9></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h2 id=network-wide-policy-options>Network-wide policy options<a class=headerlink href=#network-wide-policy-options title="Permanent link">¶</a></h2> <p>The following options are applied for the entire tailnet. Consider <a href=#node-attributes>node attributes</a> for a more fine-grained configuration instead.</p> <ul> <li><code>randomizeClientPort</code>: Allocate a <a href=https://tailscale.com/docs/reference/syntax/policy-file#randomizeclientport>random port for WireGuard traffic</a> instead of the static default port 41641.</li> </ul> <div class="language-json highlight"><span class=filename>policy.json</span><pre><span></span><code><span id=__span-9-1><a id=__codelineno-9-1 name=__codelineno-9-1 href=#__codelineno-9-1></a><span class=p>{</span>
|
||||
</span><span id=__span-9-2><a id=__codelineno-9-2 name=__codelineno-9-2 href=#__codelineno-9-2></a><span class=w> </span><span class=c1>// Use a random WireGuard port for the entire tailnet</span>
|
||||
</span><span id=__span-9-3><a id=__codelineno-9-3 name=__codelineno-9-3 href=#__codelineno-9-3></a><span class=w> </span><span class=nt>"randomizeClientPort"</span><span class=p>:</span><span class=w> </span><span class=kc>true</span>
|
||||
</span><span id=__span-9-3><a id=__codelineno-9-3 name=__codelineno-9-3 href=#__codelineno-9-3></a><span class=w> </span><span class=nt>"randomizeClientPort"</span><span class=p>:</span><span class=w> </span><span class=kc>true</span>
|
||||
</span><span id=__span-9-4><a id=__codelineno-9-4 name=__codelineno-9-4 href=#__codelineno-9-4></a><span class=p>}</span>
|
||||
</span></code></pre></div> <div class=footnote> <hr> <ol> <li id=fn:1> <p>Headscale also allows to store the policy in the database. This is typically only required in case a <a href=../integration/web-ui/ >web interface</a> is used. <a class=footnote-backref href=#fnref:1 title="Jump back to footnote 1 in the text">↩</a></p> </li> <li id=fn:2> <p>Other key-only node attributes can be used as well. Find them in the client source code with <code>grep -E '^\s+NodeAttr\w+' tailcfg/tailcfg.go</code> or by using <a href="https://github.com/search?q=repo%3Atailscale%2Ftailscale%20language%3Ago%20path%3Atailcfg%2Ftailcfg.go%20symbol%3A%2FNodeAttr%5Cw%2B%2F&type=code">GitHub code search (requires login)</a>. <a class=footnote-backref href=#fnref:2 title="Jump back to footnote 2 in the text">↩</a></p> </li> </ol> </div> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <div class=md-top data-md-component=top hidden> <div class=md-top__center> <button type=button class="md-top__button md-top__button--main" data-md-action=top> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> <span>Back to top</span> </button> <label class="md-top__button md-top__side md-top__side--nav" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-left" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M9 3v18"/></svg> </label> <label class="md-top__button md-top__side md-top__side--toc" for=__toc> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-right" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M15 3v18"/></svg> </label> </div> </div> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../tls/ class="md-footer__link md-footer__link--prev" aria-label="Previous: TLS"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> TLS </div> </div> </a> <a href=../dns/ class="md-footer__link md-footer__link--next" aria-label="Next: DNS"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> DNS </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2026 Headscale authors </div> Made with <a href=https://jaywhj.github.io/mkdocs-materialx/ target=_blank rel=noopener> MaterialX </a> </div> <div class=md-social> <a href=https://github.com/juanfont/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href=https://ko-fi.com/headscale target=_blank rel=noLine truncated
|
||||
@@ -2,8 +2,8 @@
|
||||
</span></code></pre></div> <div class="tabbed-set tabbed-alternate" data-tabs=1:2><input checked=checked id=__tabbed_1_1 name=__tabbed_1 type=radio><input id=__tabbed_1_2 name=__tabbed_1 type=radio><div class=tabbed-labels><label for=__tabbed_1_1>Personal devices</label><label for=__tabbed_1_2>Tagged devices</label></div> <div class=tabbed-content> <div class=tabbed-block> <p>Run <code>tailscale up</code> to login your personal device:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=go>tailscale up --login-server <YOUR_HEADSCALE_URL></span>
|
||||
</span></code></pre></div> <p>Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your Headscale server and it also prints the Auth ID required to approve the node:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a><span class=go>headscale auth register --user <USER> --auth-id <AUTH_ID></span>
|
||||
</span></code></pre></div> <p>Congrations, the registration of your personal node is complete and it should be listed as "online" in the output of <code>headscale nodes list</code>. The "User" column displays <code><USER></code> as the owner of the node.</p> </div> <div class=tabbed-block> <p>Your Headscale user needs to be authorized to register tagged devices. This authorization is specified in the <a href=https://tailscale.com/docs/reference/syntax/policy-file#tag-owners><code>tagOwners</code></a> section of the <a href=../policy/ >policy</a>. A simple example looks like this:</p> <div class="language-json highlight"><span class=filename>The user alice can register nodes tagged with tag:server</span><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=p>{</span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=w> </span><span class=nt>"tagOwners"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-3-3><a id=__codelineno-3-3 name=__codelineno-3-3 href=#__codelineno-3-3></a><span class=w> </span><span class=nt>"tag:server"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>]</span>
|
||||
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=w> </span><span class=nt>"tagOwners"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-3-3><a id=__codelineno-3-3 name=__codelineno-3-3 href=#__codelineno-3-3></a><span class=w> </span><span class=nt>"tag:server"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>]</span>
|
||||
</span><span id=__span-3-4><a id=__codelineno-3-4 name=__codelineno-3-4 href=#__codelineno-3-4></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-3-5><a id=__codelineno-3-5 name=__codelineno-3-5 href=#__codelineno-3-5></a><span class=w> </span><span class=c1>// more rules</span>
|
||||
</span><span id=__span-3-6><a id=__codelineno-3-6 name=__codelineno-3-6 href=#__codelineno-3-6></a><span class=p>}</span>
|
||||
|
||||
@@ -12,30 +12,30 @@
|
||||
</span><span id=__span-4-4><a id=__codelineno-4-4 name=__codelineno-4-4 href=#__codelineno-4-4></a><span class=go> | | 192.168.0.0/24 | 192.168.0.0/24 | 192.168.0.0/24</span>
|
||||
</span></code></pre></div> <h4 id=use-the-subnet-router>Use the subnet router<a class=headerlink href=#use-the-subnet-router title="Permanent link">¶</a></h4> <p>To accept routes advertised by a subnet router on a node:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a><span class=gp>$ </span>sudo<span class=w> </span>tailscale<span class=w> </span><span class=nb>set</span><span class=w> </span>--accept-routes
|
||||
</span></code></pre></div> <p>Please refer to the official <a href=https://tailscale.com/docs/features/subnet-routers#use-your-subnet-routes-from-other-devices>Tailscale documentation</a> for how to use a subnet router on different operating systems.</p> <h3 id=restrict-the-use-of-a-subnet-router-with-a-policy>Restrict the use of a subnet router with a policy<a class=headerlink href=#restrict-the-use-of-a-subnet-router-with-a-policy title="Permanent link">¶</a></h3> <p>The routes announced by subnet routers are available to the nodes in a tailnet. By default, without a policy enabled, all nodes can accept and use such routes. Configure a policy to explicitly manage who can use routes.</p> <p>The policy snippet below defines three hosts, a subnet router <code>router</code>, a regular node <code>node</code> and <code>service.example.net</code> as internal service that can be reached via a route on the subnet router <code>router</code>. It allows the node <code>node</code> to access <code>service.example.net</code> on port 80 and 443 which is reachable via the subnet router. Access to the subnet router itself is denied.</p> <div class="language-json highlight"><span class=filename>Access the routes of a subnet router without the subnet router itself</span><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=p>{</span>
|
||||
</span><span id=__span-6-2><a id=__codelineno-6-2 name=__codelineno-6-2 href=#__codelineno-6-2></a><span class=w> </span><span class=nt>"hosts"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-6-2><a id=__codelineno-6-2 name=__codelineno-6-2 href=#__codelineno-6-2></a><span class=w> </span><span class=nt>"hosts"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-6-3><a id=__codelineno-6-3 name=__codelineno-6-3 href=#__codelineno-6-3></a><span class=w> </span><span class=c1>// the router is not referenced but announces 192.168.0.0/24</span>
|
||||
</span><span id=__span-6-4><a id=__codelineno-6-4 name=__codelineno-6-4 href=#__codelineno-6-4></a><span class=w> </span><span class=nt>"router"</span><span class=p>:</span><span class=w> </span><span class=s2>"100.64.0.1/32"</span><span class=p>,</span>
|
||||
</span><span id=__span-6-5><a id=__codelineno-6-5 name=__codelineno-6-5 href=#__codelineno-6-5></a><span class=w> </span><span class=nt>"node"</span><span class=p>:</span><span class=w> </span><span class=s2>"100.64.0.2/32"</span><span class=p>,</span>
|
||||
</span><span id=__span-6-6><a id=__codelineno-6-6 name=__codelineno-6-6 href=#__codelineno-6-6></a><span class=w> </span><span class=nt>"service.example.net"</span><span class=p>:</span><span class=w> </span><span class=s2>"192.168.0.1/32"</span>
|
||||
</span><span id=__span-6-4><a id=__codelineno-6-4 name=__codelineno-6-4 href=#__codelineno-6-4></a><span class=w> </span><span class=nt>"router"</span><span class=p>:</span><span class=w> </span><span class=s2>"100.64.0.1/32"</span><span class=p>,</span>
|
||||
</span><span id=__span-6-5><a id=__codelineno-6-5 name=__codelineno-6-5 href=#__codelineno-6-5></a><span class=w> </span><span class=nt>"node"</span><span class=p>:</span><span class=w> </span><span class=s2>"100.64.0.2/32"</span><span class=p>,</span>
|
||||
</span><span id=__span-6-6><a id=__codelineno-6-6 name=__codelineno-6-6 href=#__codelineno-6-6></a><span class=w> </span><span class=nt>"service.example.net"</span><span class=p>:</span><span class=w> </span><span class=s2>"192.168.0.1/32"</span>
|
||||
</span><span id=__span-6-7><a id=__codelineno-6-7 name=__codelineno-6-7 href=#__codelineno-6-7></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-6-8><a id=__codelineno-6-8 name=__codelineno-6-8 href=#__codelineno-6-8></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-6-8><a id=__codelineno-6-8 name=__codelineno-6-8 href=#__codelineno-6-8></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-6-9><a id=__codelineno-6-9 name=__codelineno-6-9 href=#__codelineno-6-9></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-6-10><a id=__codelineno-6-10 name=__codelineno-6-10 href=#__codelineno-6-10></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"node"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-11><a id=__codelineno-6-11 name=__codelineno-6-11 href=#__codelineno-6-11></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"service.example.net"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-12><a id=__codelineno-6-12 name=__codelineno-6-12 href=#__codelineno-6-12></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"80,443"</span><span class=p>]</span>
|
||||
</span><span id=__span-6-10><a id=__codelineno-6-10 name=__codelineno-6-10 href=#__codelineno-6-10></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"node"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-11><a id=__codelineno-6-11 name=__codelineno-6-11 href=#__codelineno-6-11></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"service.example.net"</span><span class=p>],</span>
|
||||
</span><span id=__span-6-12><a id=__codelineno-6-12 name=__codelineno-6-12 href=#__codelineno-6-12></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"80,443"</span><span class=p>]</span>
|
||||
</span><span id=__span-6-13><a id=__codelineno-6-13 name=__codelineno-6-13 href=#__codelineno-6-13></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-6-14><a id=__codelineno-6-14 name=__codelineno-6-14 href=#__codelineno-6-14></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-6-15><a id=__codelineno-6-15 name=__codelineno-6-15 href=#__codelineno-6-15></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h3 id=automatically-approve-routes-of-a-subnet-router>Automatically approve routes of a subnet router<a class=headerlink href=#automatically-approve-routes-of-a-subnet-router title="Permanent link">¶</a></h3> <p>The initial setup of a subnet router usually requires manual approval of their announced routes on the control server before they can be used by a node in a tailnet. Headscale supports the <code>autoApprovers</code> section in a policy to automate the approval of routes served with a subnet router.</p> <p>The policy snippet below defines the tag <code>tag:router</code> owned by the user <code>alice</code>. This tag is used for <code>routes</code> in the <code>autoApprovers</code> section. The IPv4 route <code>192.168.0.0/24</code> is automatically approved once announced by a subnet router that advertises the tag <code>tag:router</code>.</p> <div class="language-json highlight"><span class=filename>Subnet routers tagged with tag:router are automatically approved</span><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a><span class=p>{</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=w> </span><span class=nt>"tagOwners"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-7-3><a id=__codelineno-7-3 name=__codelineno-7-3 href=#__codelineno-7-3></a><span class=w> </span><span class=nt>"tag:router"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>]</span>
|
||||
</span><span id=__span-7-2><a id=__codelineno-7-2 name=__codelineno-7-2 href=#__codelineno-7-2></a><span class=w> </span><span class=nt>"tagOwners"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-7-3><a id=__codelineno-7-3 name=__codelineno-7-3 href=#__codelineno-7-3></a><span class=w> </span><span class=nt>"tag:router"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>]</span>
|
||||
</span><span id=__span-7-4><a id=__codelineno-7-4 name=__codelineno-7-4 href=#__codelineno-7-4></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-7-5><a id=__codelineno-7-5 name=__codelineno-7-5 href=#__codelineno-7-5></a><span class=w> </span><span class=nt>"autoApprovers"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-7-6><a id=__codelineno-7-6 name=__codelineno-7-6 href=#__codelineno-7-6></a><span class=w> </span><span class=nt>"routes"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-7-7><a id=__codelineno-7-7 name=__codelineno-7-7 href=#__codelineno-7-7></a><span class=w> </span><span class=nt>"192.168.0.0/24"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:router"</span><span class=p>]</span>
|
||||
</span><span id=__span-7-5><a id=__codelineno-7-5 name=__codelineno-7-5 href=#__codelineno-7-5></a><span class=w> </span><span class=nt>"autoApprovers"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-7-6><a id=__codelineno-7-6 name=__codelineno-7-6 href=#__codelineno-7-6></a><span class=w> </span><span class=nt>"routes"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-7-7><a id=__codelineno-7-7 name=__codelineno-7-7 href=#__codelineno-7-7></a><span class=w> </span><span class=nt>"192.168.0.0/24"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:router"</span><span class=p>]</span>
|
||||
</span><span id=__span-7-8><a id=__codelineno-7-8 name=__codelineno-7-8 href=#__codelineno-7-8></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-7-9><a id=__codelineno-7-9 name=__codelineno-7-9 href=#__codelineno-7-9></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-7-10><a id=__codelineno-7-10 name=__codelineno-7-10 href=#__codelineno-7-10></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-7-10><a id=__codelineno-7-10 name=__codelineno-7-10 href=#__codelineno-7-10></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-7-11><a id=__codelineno-7-11 name=__codelineno-7-11 href=#__codelineno-7-11></a><span class=w> </span><span class=c1>// more rules</span>
|
||||
</span><span id=__span-7-12><a id=__codelineno-7-12 name=__codelineno-7-12 href=#__codelineno-7-12></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-7-13><a id=__codelineno-7-13 name=__codelineno-7-13 href=#__codelineno-7-13></a><span class=p>}</span>
|
||||
@@ -54,42 +54,42 @@
|
||||
</span><span id=__span-13-4><a id=__codelineno-13-4 name=__codelineno-13-4 href=#__codelineno-13-4></a><span class=go> | | ::/0 | ::/0 | ::/0</span>
|
||||
</span></code></pre></div> <h4 id=use-the-exit-node>Use the exit node<a class=headerlink href=#use-the-exit-node title="Permanent link">¶</a></h4> <p>The exit node can now be used on a node with:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-14-1><a id=__codelineno-14-1 name=__codelineno-14-1 href=#__codelineno-14-1></a><span class=gp>$ </span>sudo<span class=w> </span>tailscale<span class=w> </span><span class=nb>set</span><span class=w> </span>--exit-node<span class=w> </span>myexit
|
||||
</span></code></pre></div> <p>Please refer to the official <a href=https://tailscale.com/docs/features/exit-nodes#use-the-exit-node>Tailscale documentation</a> for how to use an exit node on different operating systems.</p> <h3 id=restrict-the-use-of-an-exit-node-with-a-policy>Restrict the use of an exit node with a policy<a class=headerlink href=#restrict-the-use-of-an-exit-node-with-a-policy title="Permanent link">¶</a></h3> <p>An exit node is offered to all nodes in a tailnet. By default, without a policy enabled, all nodes in a tailnet can select and use an exit node. Configure <code>autogroup:internet</code> in a policy rule to restrict who can use <em>any</em> of the available exit nodes.</p> <div class="language-json highlight"><span class=filename>Example use of autogroup:internet</span><pre><span></span><code><span id=__span-15-1><a id=__codelineno-15-1 name=__codelineno-15-1 href=#__codelineno-15-1></a><span class=p>{</span>
|
||||
</span><span id=__span-15-2><a id=__codelineno-15-2 name=__codelineno-15-2 href=#__codelineno-15-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-15-2><a id=__codelineno-15-2 name=__codelineno-15-2 href=#__codelineno-15-2></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-15-3><a id=__codelineno-15-3 name=__codelineno-15-3 href=#__codelineno-15-3></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-15-4><a id=__codelineno-15-4 name=__codelineno-15-4 href=#__codelineno-15-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"..."</span><span class=p>],</span>
|
||||
</span><span id=__span-15-5><a id=__codelineno-15-5 name=__codelineno-15-5 href=#__codelineno-15-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:internet"</span><span class=p>],</span>
|
||||
</span><span id=__span-15-6><a id=__codelineno-15-6 name=__codelineno-15-6 href=#__codelineno-15-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-15-4><a id=__codelineno-15-4 name=__codelineno-15-4 href=#__codelineno-15-4></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"..."</span><span class=p>],</span>
|
||||
</span><span id=__span-15-5><a id=__codelineno-15-5 name=__codelineno-15-5 href=#__codelineno-15-5></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:internet"</span><span class=p>],</span>
|
||||
</span><span id=__span-15-6><a id=__codelineno-15-6 name=__codelineno-15-6 href=#__codelineno-15-6></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-15-7><a id=__codelineno-15-7 name=__codelineno-15-7 href=#__codelineno-15-7></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-15-8><a id=__codelineno-15-8 name=__codelineno-15-8 href=#__codelineno-15-8></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-15-9><a id=__codelineno-15-9 name=__codelineno-15-9 href=#__codelineno-15-9></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h3 id=restrict-access-to-exit-nodes-per-user-or-group>Restrict access to exit nodes per user or group<a class=headerlink href=#restrict-access-to-exit-nodes-per-user-or-group title="Permanent link">¶</a></h3> <p>A user can use <em>any</em> of the available exit nodes with <code>autogroup:internet</code>. Alternatively, the policy snippet below assigns each user a specific exit node while hiding all other exit nodes. The user <code>alice</code> can only use an exit node tagged with <code>tag:exit1</code> while user <code>bob</code> can only use an exit node tagged with <code>tag:exit2</code>.</p> <div class="language-json highlight"><span class=filename>Assign each user a dedicated exit node</span><pre><span></span><code><span id=__span-16-1><a id=__codelineno-16-1 name=__codelineno-16-1 href=#__codelineno-16-1></a><span class=p>{</span>
|
||||
</span><span id=__span-16-2><a id=__codelineno-16-2 name=__codelineno-16-2 href=#__codelineno-16-2></a><span class=w> </span><span class=nt>"tagOwners"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-16-3><a id=__codelineno-16-3 name=__codelineno-16-3 href=#__codelineno-16-3></a><span class=w> </span><span class=nt>"tag:exit1"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-4><a id=__codelineno-16-4 name=__codelineno-16-4 href=#__codelineno-16-4></a><span class=w> </span><span class=nt>"tag:exit2"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"bob@"</span><span class=p>]</span>
|
||||
</span><span id=__span-16-2><a id=__codelineno-16-2 name=__codelineno-16-2 href=#__codelineno-16-2></a><span class=w> </span><span class=nt>"tagOwners"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-16-3><a id=__codelineno-16-3 name=__codelineno-16-3 href=#__codelineno-16-3></a><span class=w> </span><span class=nt>"tag:exit1"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-4><a id=__codelineno-16-4 name=__codelineno-16-4 href=#__codelineno-16-4></a><span class=w> </span><span class=nt>"tag:exit2"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"bob@"</span><span class=p>]</span>
|
||||
</span><span id=__span-16-5><a id=__codelineno-16-5 name=__codelineno-16-5 href=#__codelineno-16-5></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-16-6><a id=__codelineno-16-6 name=__codelineno-16-6 href=#__codelineno-16-6></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-16-6><a id=__codelineno-16-6 name=__codelineno-16-6 href=#__codelineno-16-6></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-16-7><a id=__codelineno-16-7 name=__codelineno-16-7 href=#__codelineno-16-7></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-16-8><a id=__codelineno-16-8 name=__codelineno-16-8 href=#__codelineno-16-8></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-9><a id=__codelineno-16-9 name=__codelineno-16-9 href=#__codelineno-16-9></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:internet"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-10><a id=__codelineno-16-10 name=__codelineno-16-10 href=#__codelineno-16-10></a><span class=w> </span><span class=nt>"via"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:exit1"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-11><a id=__codelineno-16-11 name=__codelineno-16-11 href=#__codelineno-16-11></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-16-8><a id=__codelineno-16-8 name=__codelineno-16-8 href=#__codelineno-16-8></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-9><a id=__codelineno-16-9 name=__codelineno-16-9 href=#__codelineno-16-9></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:internet"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-10><a id=__codelineno-16-10 name=__codelineno-16-10 href=#__codelineno-16-10></a><span class=w> </span><span class=nt>"via"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:exit1"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-11><a id=__codelineno-16-11 name=__codelineno-16-11 href=#__codelineno-16-11></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-16-12><a id=__codelineno-16-12 name=__codelineno-16-12 href=#__codelineno-16-12></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-16-13><a id=__codelineno-16-13 name=__codelineno-16-13 href=#__codelineno-16-13></a><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-16-14><a id=__codelineno-16-14 name=__codelineno-16-14 href=#__codelineno-16-14></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"bob@"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-15><a id=__codelineno-16-15 name=__codelineno-16-15 href=#__codelineno-16-15></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:internet"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-16><a id=__codelineno-16-16 name=__codelineno-16-16 href=#__codelineno-16-16></a><span class=w> </span><span class=nt>"via"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:exit2"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-17><a id=__codelineno-16-17 name=__codelineno-16-17 href=#__codelineno-16-17></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-16-14><a id=__codelineno-16-14 name=__codelineno-16-14 href=#__codelineno-16-14></a><span class=w> </span><span class=nt>"src"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"bob@"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-15><a id=__codelineno-16-15 name=__codelineno-16-15 href=#__codelineno-16-15></a><span class=w> </span><span class=nt>"dst"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"autogroup:internet"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-16><a id=__codelineno-16-16 name=__codelineno-16-16 href=#__codelineno-16-16></a><span class=w> </span><span class=nt>"via"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:exit2"</span><span class=p>],</span>
|
||||
</span><span id=__span-16-17><a id=__codelineno-16-17 name=__codelineno-16-17 href=#__codelineno-16-17></a><span class=w> </span><span class=nt>"ip"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"*"</span><span class=p>]</span>
|
||||
</span><span id=__span-16-18><a id=__codelineno-16-18 name=__codelineno-16-18 href=#__codelineno-16-18></a><span class=w> </span><span class=p>}</span>
|
||||
</span><span id=__span-16-19><a id=__codelineno-16-19 name=__codelineno-16-19 href=#__codelineno-16-19></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-16-20><a id=__codelineno-16-20 name=__codelineno-16-20 href=#__codelineno-16-20></a><span class=p>}</span>
|
||||
</span></code></pre></div> <h3 id=automatically-approve-an-exit-node-with-auto-approvers>Automatically approve an exit node with auto approvers<a class=headerlink href=#automatically-approve-an-exit-node-with-auto-approvers title="Permanent link">¶</a></h3> <p>The initial setup of an exit node usually requires manual approval on the control server before it can be used by a node in a tailnet. Headscale supports the <code>autoApprovers</code> section in a policy to automate the approval of a new exit node as soon as it joins the tailnet.</p> <p>The policy snippet below defines the tag <code>tag:exit</code> owned by the user <code>alice</code>. This tag is used for the <code>exitNode</code> entry in the <code>autoApprovers</code> section. A new exit node that advertises the tag <code>tag:exit</code> is automatically approved:</p> <div class="language-json highlight"><span class=filename>Exit nodes tagged with tag:exit are automatically approved</span><pre><span></span><code><span id=__span-17-1><a id=__codelineno-17-1 name=__codelineno-17-1 href=#__codelineno-17-1></a><span class=p>{</span>
|
||||
</span><span id=__span-17-2><a id=__codelineno-17-2 name=__codelineno-17-2 href=#__codelineno-17-2></a><span class=w> </span><span class=nt>"tagOwners"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-17-3><a id=__codelineno-17-3 name=__codelineno-17-3 href=#__codelineno-17-3></a><span class=w> </span><span class=nt>"tag:exit"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>]</span>
|
||||
</span><span id=__span-17-2><a id=__codelineno-17-2 name=__codelineno-17-2 href=#__codelineno-17-2></a><span class=w> </span><span class=nt>"tagOwners"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-17-3><a id=__codelineno-17-3 name=__codelineno-17-3 href=#__codelineno-17-3></a><span class=w> </span><span class=nt>"tag:exit"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"alice@"</span><span class=p>]</span>
|
||||
</span><span id=__span-17-4><a id=__codelineno-17-4 name=__codelineno-17-4 href=#__codelineno-17-4></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-17-5><a id=__codelineno-17-5 name=__codelineno-17-5 href=#__codelineno-17-5></a><span class=w> </span><span class=nt>"autoApprovers"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-17-6><a id=__codelineno-17-6 name=__codelineno-17-6 href=#__codelineno-17-6></a><span class=w> </span><span class=nt>"exitNode"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:exit"</span><span class=p>]</span>
|
||||
</span><span id=__span-17-5><a id=__codelineno-17-5 name=__codelineno-17-5 href=#__codelineno-17-5></a><span class=w> </span><span class=nt>"autoApprovers"</span><span class=p>:</span><span class=w> </span><span class=p>{</span>
|
||||
</span><span id=__span-17-6><a id=__codelineno-17-6 name=__codelineno-17-6 href=#__codelineno-17-6></a><span class=w> </span><span class=nt>"exitNode"</span><span class=p>:</span><span class=w> </span><span class=p>[</span><span class=s2>"tag:exit"</span><span class=p>]</span>
|
||||
</span><span id=__span-17-7><a id=__codelineno-17-7 name=__codelineno-17-7 href=#__codelineno-17-7></a><span class=w> </span><span class=p>},</span>
|
||||
</span><span id=__span-17-8><a id=__codelineno-17-8 name=__codelineno-17-8 href=#__codelineno-17-8></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-17-8><a id=__codelineno-17-8 name=__codelineno-17-8 href=#__codelineno-17-8></a><span class=w> </span><span class=nt>"grants"</span><span class=p>:</span><span class=w> </span><span class=p>[</span>
|
||||
</span><span id=__span-17-9><a id=__codelineno-17-9 name=__codelineno-17-9 href=#__codelineno-17-9></a><span class=w> </span><span class=c1>// more rules</span>
|
||||
</span><span id=__span-17-10><a id=__codelineno-17-10 name=__codelineno-17-10 href=#__codelineno-17-10></a><span class=w> </span><span class=p>]</span>
|
||||
</span><span id=__span-17-11><a id=__codelineno-17-11 name=__codelineno-17-11 href=#__codelineno-17-11></a><span class=p>}</span>
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/ref/tls/ rel=canonical><link href=../routes/ rel=prev><link href=../policy/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>TLS - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="TLS - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/tls.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/ref/tls/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="TLS - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/tls.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#running-the-service-via-tls-optional class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> TLS </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-sLine truncated
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=nt>tls_key_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span></code></pre></div> <p>The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it.</p> <h2 id=lets-encrypt-acme>Let's Encrypt / ACME<a class=headerlink href=#lets-encrypt-acme title="Permanent link">¶</a></h2> <p>To get a certificate automatically via <a href=https://letsencrypt.org/ >Let's Encrypt</a>, set <code>tls_letsencrypt_hostname</code> to the desired certificate hostname. This name must resolve to the IP address(es) headscale is reachable on (i.e., it must correspond to the <code>server_url</code> configuration parameter). The certificate and Let's Encrypt account credentials will be stored in the directory configured in <code>tls_letsencrypt_cache_dir</code>. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.</p> <div class="language-yaml highlight"><span class=filename>config.yaml</span><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=nt>tls_letsencrypt_hostname</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=nt>tls_letsencrypt_listen</span><span class=p>:</span><span class=w> </span><span class=s>":http"</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=nt>tls_letsencrypt_cache_dir</span><span class=p>:</span><span class=w> </span><span class=s>".cache"</span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/ref/tls/ rel=canonical><link href=../routes/ rel=prev><link href=../policy/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>TLS - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../..",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><meta property=og:type content=website><meta property=og:title content="TLS - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/tls.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/ref/tls/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="TLS - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/ref/tls.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#running-the-service-via-tls-optional class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> TLS </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-sLine truncated
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=nt>tls_key_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span></code></pre></div> <p>The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it.</p> <h2 id=lets-encrypt-acme>Let's Encrypt / ACME<a class=headerlink href=#lets-encrypt-acme title="Permanent link">¶</a></h2> <p>To get a certificate automatically via <a href=https://letsencrypt.org/ >Let's Encrypt</a>, set <code>tls_letsencrypt_hostname</code> to the desired certificate hostname. This name must resolve to the IP address(es) headscale is reachable on (i.e., it must correspond to the <code>server_url</code> configuration parameter). The certificate and Let's Encrypt account credentials will be stored in the directory configured in <code>tls_letsencrypt_cache_dir</code>. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.</p> <div class="language-yaml highlight"><span class=filename>config.yaml</span><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=nt>tls_letsencrypt_hostname</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=nt>tls_letsencrypt_listen</span><span class=p>:</span><span class=w> </span><span class=s>":http"</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=nt>tls_letsencrypt_cache_dir</span><span class=p>:</span><span class=w> </span><span class=s>".cache"</span>
|
||||
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a><span class=nt>tls_letsencrypt_challenge_type</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">HTTP-01</span>
|
||||
</span></code></pre></div> <h3 id=challenge-types>Challenge types<a class=headerlink href=#challenge-types title="Permanent link">¶</a></h3> <p>Headscale only supports two values for <code>tls_letsencrypt_challenge_type</code>: <code>HTTP-01</code> (default) and <code>TLS-ALPN-01</code>.</p> <h4 id=http-01>HTTP-01<a class=headerlink href=#http-01 title="Permanent link">¶</a></h4> <p>For <code>HTTP-01</code>, headscale must be reachable on port 80 for the Let's Encrypt automated validation, in addition to whatever port is configured in <code>listen_addr</code>. By default, headscale listens on port 80 on all local IPs for Let's Encrypt automated validation.</p> <p>If you need to change the ip and/or port used by headscale for the Let's Encrypt validation process, set <code>tls_letsencrypt_listen</code> to the appropriate value. This can be handy if you are running headscale as a non-root user (or can't run <code>setcap</code>). Keep in mind, however, that Let's Encrypt will <em>only</em> connect to port 80 for the validation callback, so if you change <code>tls_letsencrypt_listen</code> you will also need to configure something else (e.g. a firewall rule) to forward the traffic from port 80 to the ip:port combination specified in <code>tls_letsencrypt_listen</code>.</p> <h4 id=tls-alpn-01>TLS-ALPN-01<a class=headerlink href=#tls-alpn-01 title="Permanent link">¶</a></h4> <p>For <code>TLS-ALPN-01</code>, headscale listens on the ip:port combination defined in <code>listen_addr</code>. Let's Encrypt will <em>only</em> connect to port 443 for the validation callback, so if <code>listen_addr</code> is not set to port 443, something else (e.g. a firewall rule) will be required to forward the traffic from port 443 to the ip:port combination specified in <code>listen_addr</code>.</p> <h3 id=technical-description>Technical description<a class=headerlink href=#technical-description title="Permanent link">¶</a></h3> <p>Headscale uses <a href=https://pkg.go.dev/golang.org/x/crypto/acme/autocert>autocert</a>, a Golang library providing <a href=https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment>ACME protocol</a> verification, to facilitate certificate renewals via <a href=https://letsencrypt.org/about/ >Let's Encrypt</a>. Certificates will be renewed automatically, and the following can be expected:</p> <ul> <li>Certificates provided from Let's Encrypt have a validity of 3 months from date issued.</li> <li>Renewals are only attempted by headscale when 30 days or less remains until certificate expiry.</li> <li>Renewal attempts by autocert are triggered at a random interval of 30-60 minutes.</li> <li>No log output is generated when renewals are skipped, or successful.</li> </ul> <h4 id=checking-certificate-expiry>Checking certificate expiry<a class=headerlink href=#checking-certificate-expiry title="Permanent link">¶</a></h4> <p>If you want to validate that certificate renewal completed successfully, this can be done either manually, or through external monitoring software. Two examples of doing this manually:</p> <ol> <li>Open the URL for your headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.</li> <li>Or, check remotely from CLI using <code>openssl</code>:</li> </ol> <div class="language-console highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a><span class=gp>$ </span>openssl<span class=w> </span>s_client<span class=w> </span>-servername<span class=w> </span><span class=o>[</span>hostname<span class=o>]</span><span class=w> </span>-connect<span class=w> </span><span class=o>[</span>hostname<span class=o>]</span>:443<span class=w> </span><span class=p>|</span><span class=w> </span>openssl<span class=w> </span>x509<span class=w> </span>-noout<span class=w> </span>-dates
|
||||
</span><span id=__span-2-2><a id=__codelineno-2-2 name=__codelineno-2-2 href=#__codelineno-2-2></a><span class="gp gp-VirtualEnv">(...)</span>
|
||||
</span><span id=__span-2-3><a id=__codelineno-2-3 name=__codelineno-2-3 href=#__codelineno-2-3></a><span class=go>notBefore=Feb 8 09:48:26 2024 GMT</span>
|
||||
</span><span id=__span-2-4><a id=__codelineno-2-4 name=__codelineno-2-4 href=#__codelineno-2-4></a><span class=go>notAfter=May 8 09:48:25 2024 GMT</span>
|
||||
</span></code></pre></div> <h4 id=log-output-from-the-autocert-library>Log output from the autocert library<a class=headerlink href=#log-output-from-the-autocert-library title="Permanent link">¶</a></h4> <p>As these log lines are from the autocert library, they are not strictly generated by headscale itself.</p> <div class="language-text highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a>acme/autocert: missing server name
|
||||
</span></code></pre></div> <p>Likely caused by an incoming connection that does not specify a hostname, for example a <code>curl</code> request directly against the IP of the server, or an unexpected hostname.</p> <div class="language-text highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a>acme/autocert: host "[foo]" not configured in HostWhitelist
|
||||
</span></code></pre></div> <p>Likely caused by an incoming connection that does not specify a hostname, for example a <code>curl</code> request directly against the IP of the server, or an unexpected hostname.</p> <div class="language-text highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a>acme/autocert: host "[foo]" not configured in HostWhitelist
|
||||
</span></code></pre></div> <p>Similarly to the above, this likely indicates an invalid incoming request for an incorrect hostname, commonly just the IP itself.</p> <p>The source code for autocert can be found <a href=https://cs.opensource.google/go/x/crypto/+/refs/tags/v0.19.0:acme/autocert/autocert.go>here</a></p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <div class=md-top data-md-component=top hidden> <div class=md-top__center> <button type=button class="md-top__button md-top__button--main" data-md-action=top> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> <span>Back to top</span> </button> <label class="md-top__button md-top__side md-top__side--nav" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-left" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M9 3v18"/></svg> </label> <label class="md-top__button md-top__side md-top__side--toc" for=__toc> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-right" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M15 3v18"/></svg> </label> </div> </div> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../routes/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Routes"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Routes </div> </div> </a> <a href=../policy/ class="md-footer__link md-footer__link--next" aria-label="Next: Policy"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Policy </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2026 Headscale authors </div> Made with <a href=https://jaywhj.github.io/mkdocs-materialx/ target=_blank rel=noopener> MaterialX </a> </div> <div class=md-social> <a href=https://github.com/juanfont/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href=https://ko-fi.com/headscale target=_blank rel=noopener title=ko-fi.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M2 21h18v-2H2M20 8h-2V5h2m0-2H4v10a4 4 0 0 0 4 4h6a4 4 0 0 0 4-4v-3h2a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2"/></svg> </a> <a href=https://github.com/juanfont/headscale/pkgs/container/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 640 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - httpLine truncated
|
||||
@@ -1 +1 @@
|
||||
{"config":{"lang":["en"],"separator":"[\\s\\-,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to headscale","text":"<p>Headscale is an open source, self-hosted implementation of the Tailscale control server.</p> <p>This page contains the documentation for the latest version of headscale. Please also check our FAQ.</p> <p>Join our Discord server for a chat and community support.</p>"},{"location":"#design-goal","title":"Design goal","text":"<p>Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailscale network (tailnet), suitable for a personal use, or a small open-source organisation.</p>"},{"location":"#supporting-headscale","title":"Supporting headscale","text":"<p>Please see Sponsor for more information.</p>"},{"location":"#contributing","title":"Contributing","text":"<p>Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the Maintainers before being submitted.</p> <p>Please see Contributing for more information.</p>"},{"location":"#about","title":"About","text":"<p>Headscale is maintained by Kristoffer Dalby and Juan Font.</p>"},{"location":"about/clients/","title":"Client and operating system support","text":"<p>We aim to support the last 10 releases of the Tailscale client on all provided operating systems and platforms. Some platforms might require additional configuration to connect with headscale.</p> OS Supports headscale Linux Yes OpenBSD Yes FreeBSD Yes Windows Yes (see docs and <code>/windows</code> on your headscale for more information) Android Yes (see docs for more information) macOS Yes (see docs and <code>/apple</code> on your headscale for more information) iOS Yes (see docs and <code>/apple</code> on your headscale for more information) tvOS Yes (see docs and <code>/apple</code> on your headscale for more information)"},{"location":"about/contributing/","title":"Contributing","text":"<p>Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the maintainers before being added to the project. This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code.</p>"},{"location":"about/contributing/#why-do-we-have-this-model","title":"Why do we have this model?","text":"<p>Headscale has a small maintainer team that tries to balance working on the project, fixing bugs and reviewing contributions.</p> <p>When we work on issues ourselves, we develop first hand knowledge of the code and it makes it possible for us to maintain and own the code as the project develops.</p> <p>Code contributions are seen as a positive thing. People enjoy and engage with our project, but it also comes with some challenges; we have to understand the code, we have to understand the feature, we might have to become familiar with external libraries or services and we think about security implications. All those steps are required during the reviewing process. After the code has been merged, the feature has to be maintained. Any changes reliant on external services must be updated and expanded accordingly.</p> <p>The review and day-1 maintenance adds a significant burden on the maintainers. Often we hope that the contributor will help out, but we found that most of the time, they disappear after their new feature was added.</p> <p>This means that when someone contributes, we are mostly happy about it, but we do have to run it through a series of checks to establish if we actually can maintain this feature.</p>"},{"location":"about/contributing/#what-do-we-require","title":"What do we require?","text":"<p>A general description is provided here and an explicit list is provided in our pull request template.</p> <p>All new features have to start out with a design document, which should be discussed on the issue tracker (not discord). It should include a use case for the feature, how it can be implemented, who will implement it and a plan for maintaining it.</p> <p>All features have to be end-to-end tested (integration tests) and have good unit test coverage to ensure that they work as expected. This will also ensure that the feature continues to work as expected over time. If a change cannot be tested, a strong case for why this is not possible needs to be presented.</p> <p>The contributor should help to maintain the feature over time. In case the feature is not maintained probably, the maintainers reserve themselves the right to remove features they redeem as unmaintainable. This should help to improve the quality of the software and keep it iLine truncated
|
||||
{"config":{"lang":["en"],"separator":"[\\s\\-,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to headscale","text":"<p>Headscale is an open source, self-hosted implementation of the Tailscale control server.</p> <p>This page contains the documentation for the latest version of headscale. Please also check our FAQ.</p> <p>Join our Discord server for a chat and community support.</p>"},{"location":"#design-goal","title":"Design goal","text":"<p>Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailscale network (tailnet), suitable for a personal use, or a small open-source organisation.</p>"},{"location":"#supporting-headscale","title":"Supporting headscale","text":"<p>Please see Sponsor for more information.</p>"},{"location":"#contributing","title":"Contributing","text":"<p>Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the Maintainers before being submitted.</p> <p>Please see Contributing for more information.</p>"},{"location":"#about","title":"About","text":"<p>Headscale is maintained by Kristoffer Dalby and Juan Font.</p>"},{"location":"about/clients/","title":"Client and operating system support","text":"<p>We aim to support the last 10 releases of the Tailscale client on all provided operating systems and platforms. Some platforms might require additional configuration to connect with headscale.</p> OS Supports headscale Linux Yes OpenBSD Yes FreeBSD Yes Windows Yes (see docs and <code>/windows</code> on your headscale for more information) Android Yes (see docs for more information) macOS Yes (see docs and <code>/apple</code> on your headscale for more information) iOS Yes (see docs and <code>/apple</code> on your headscale for more information) tvOS Yes (see docs and <code>/apple</code> on your headscale for more information)"},{"location":"about/contributing/","title":"Contributing","text":"<p>Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the maintainers before being added to the project. This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code.</p>"},{"location":"about/contributing/#why-do-we-have-this-model","title":"Why do we have this model?","text":"<p>Headscale has a small maintainer team that tries to balance working on the project, fixing bugs and reviewing contributions.</p> <p>When we work on issues ourselves, we develop first hand knowledge of the code and it makes it possible for us to maintain and own the code as the project develops.</p> <p>Code contributions are seen as a positive thing. People enjoy and engage with our project, but it also comes with some challenges; we have to understand the code, we have to understand the feature, we might have to become familiar with external libraries or services and we think about security implications. All those steps are required during the reviewing process. After the code has been merged, the feature has to be maintained. Any changes reliant on external services must be updated and expanded accordingly.</p> <p>The review and day-1 maintenance adds a significant burden on the maintainers. Often we hope that the contributor will help out, but we found that most of the time, they disappear after their new feature was added.</p> <p>This means that when someone contributes, we are mostly happy about it, but we do have to run it through a series of checks to establish if we actually can maintain this feature.</p>"},{"location":"about/contributing/#what-do-we-require","title":"What do we require?","text":"<p>A general description is provided here and an explicit list is provided in our pull request template.</p> <p>All new features have to start out with a design document, which should be discussed on the issue tracker (not discord). It should include a use case for the feature, how it can be implemented, who will implement it and a plan for maintaining it.</p> <p>All features have to be end-to-end tested (integration tests) and have good unit test coverage to ensure that they work as expected. This will also ensure that the feature continues to work as expected over time. If a change cannot be tested, a strong case for why this is not possible needs to be presented.</p> <p>The contributor should help to maintain the feature over time. In case the feature is not maintained probably, the maintainers reserve themselves the right to remove features they redeem as unmaintainable. This should help to improve the quality of the software and keep it iLine truncated
|
||||
@@ -5,11 +5,11 @@
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=w> </span>--detach<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a><span class=w> </span>--read-only<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a><span class=w> </span>--tmpfs<span class=w> </span>/var/run/headscale<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-6><a id=__codelineno-1-6 name=__codelineno-1-6 href=#__codelineno-1-6></a><span class=w> </span>--volume<span class=w> </span><span class=s2>"</span><span class=k>$(</span><span class=nb>pwd</span><span class=k>)</span><span class=s2>/config:/etc/headscale:ro"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-7><a id=__codelineno-1-7 name=__codelineno-1-7 href=#__codelineno-1-7></a><span class=w> </span>--volume<span class=w> </span><span class=s2>"</span><span class=k>$(</span><span class=nb>pwd</span><span class=k>)</span><span class=s2>/lib:/var/lib/headscale"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-6><a id=__codelineno-1-6 name=__codelineno-1-6 href=#__codelineno-1-6></a><span class=w> </span>--volume<span class=w> </span><span class=s2>"</span><span class=k>$(</span><span class=nb>pwd</span><span class=k>)</span><span class=s2>/config:/etc/headscale:ro"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-7><a id=__codelineno-1-7 name=__codelineno-1-7 href=#__codelineno-1-7></a><span class=w> </span>--volume<span class=w> </span><span class=s2>"</span><span class=k>$(</span><span class=nb>pwd</span><span class=k>)</span><span class=s2>/lib:/var/lib/headscale"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-8><a id=__codelineno-1-8 name=__codelineno-1-8 href=#__codelineno-1-8></a><span class=w> </span>--publish<span class=w> </span><span class=m>127</span>.0.0.1:8080:8080<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-9><a id=__codelineno-1-9 name=__codelineno-1-9 href=#__codelineno-1-9></a><span class=w> </span>--publish<span class=w> </span><span class=m>127</span>.0.0.1:9090:9090<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-10><a id=__codelineno-1-10 name=__codelineno-1-10 href=#__codelineno-1-10></a><span class=w> </span>--health-cmd<span class=w> </span><span class=s2>"CMD headscale health"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-10><a id=__codelineno-1-10 name=__codelineno-1-10 href=#__codelineno-1-10></a><span class=w> </span>--health-cmd<span class=w> </span><span class=s2>"CMD headscale health"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-11><a id=__codelineno-1-11 name=__codelineno-1-11 href=#__codelineno-1-11></a><span class=w> </span>docker.io/headscale/headscale:<VERSION><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-1-12><a id=__codelineno-1-12 name=__codelineno-1-12 href=#__codelineno-1-12></a><span class=w> </span>serve
|
||||
</span></code></pre></div> <p>Note: use <code>0.0.0.0:8080:8080</code> instead of <code>127.0.0.1:8080:8080</code> if you want to expose the container externally.</p> <p>This command mounts the local directories inside the container, forwards port 8080 and 9090 out of the container so the headscale instance becomes available and then detaches so headscale runs in the background.</p> <p>A similar configuration for <code>docker-compose</code>:</p> <div class="language-yaml highlight"><span class=filename>docker-compose.yaml</span><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a><span class=nt>services</span><span class=p>:</span>
|
||||
@@ -21,8 +21,8 @@
|
||||
</span><span id=__span-2-7><a id=__codelineno-2-7 name=__codelineno-2-7 href=#__codelineno-2-7></a><span class=w> </span><span class=nt>tmpfs</span><span class=p>:</span>
|
||||
</span><span id=__span-2-8><a id=__codelineno-2-8 name=__codelineno-2-8 href=#__codelineno-2-8></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/var/run/headscale</span>
|
||||
</span><span id=__span-2-9><a id=__codelineno-2-9 name=__codelineno-2-9 href=#__codelineno-2-9></a><span class=w> </span><span class=nt>ports</span><span class=p>:</span>
|
||||
</span><span id=__span-2-10><a id=__codelineno-2-10 name=__codelineno-2-10 href=#__codelineno-2-10></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"127.0.0.1:8080:8080"</span>
|
||||
</span><span id=__span-2-11><a id=__codelineno-2-11 name=__codelineno-2-11 href=#__codelineno-2-11></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"127.0.0.1:9090:9090"</span>
|
||||
</span><span id=__span-2-10><a id=__codelineno-2-10 name=__codelineno-2-10 href=#__codelineno-2-10></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"127.0.0.1:8080:8080"</span>
|
||||
</span><span id=__span-2-11><a id=__codelineno-2-11 name=__codelineno-2-11 href=#__codelineno-2-11></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>"127.0.0.1:9090:9090"</span>
|
||||
</span><span id=__span-2-12><a id=__codelineno-2-12 name=__codelineno-2-12 href=#__codelineno-2-12></a><span class=w> </span><span class=nt>volumes</span><span class=p>:</span>
|
||||
</span><span id=__span-2-13><a id=__codelineno-2-13 name=__codelineno-2-13 href=#__codelineno-2-13></a><span class=w> </span><span class=c1># Please set <HEADSCALE_PATH> to the absolute path</span>
|
||||
</span><span id=__span-2-14><a id=__codelineno-2-14 name=__codelineno-2-14 href=#__codelineno-2-14></a><span class=w> </span><span class=c1># of the previously created headscale directory.</span>
|
||||
@@ -30,7 +30,7 @@
|
||||
</span><span id=__span-2-16><a id=__codelineno-2-16 name=__codelineno-2-16 href=#__codelineno-2-16></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain"><HEADSCALE_PATH>/lib:/var/lib/headscale</span>
|
||||
</span><span id=__span-2-17><a id=__codelineno-2-17 name=__codelineno-2-17 href=#__codelineno-2-17></a><span class=w> </span><span class=nt>command</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">serve</span>
|
||||
</span><span id=__span-2-18><a id=__codelineno-2-18 name=__codelineno-2-18 href=#__codelineno-2-18></a><span class=w> </span><span class=nt>healthcheck</span><span class=p>:</span>
|
||||
</span><span id=__span-2-19><a id=__codelineno-2-19 name=__codelineno-2-19 href=#__codelineno-2-19></a><span class=w> </span><span class=nt>test</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[</span><span class=s>"CMD"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"headscale"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"health"</span><span class="p p-Indicator">]</span>
|
||||
</span><span id=__span-2-19><a id=__codelineno-2-19 name=__codelineno-2-19 href=#__codelineno-2-19></a><span class=w> </span><span class=nt>test</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[</span><span class=s>"CMD"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"headscale"</span><span class="p p-Indicator">,</span><span class=w> </span><span class=s>"health"</span><span class="p p-Indicator">]</span>
|
||||
</span></code></pre></div> </li> <li> <p>Verify headscale is running:</p> <p>Follow the container logs:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a>docker<span class=w> </span>logs<span class=w> </span>--follow<span class=w> </span>headscale
|
||||
</span></code></pre></div> <p>Verify running containers:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a>docker<span class=w> </span>ps
|
||||
</span></code></pre></div> <p>Verify headscale is available:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a>curl<span class=w> </span>http://127.0.0.1:8080/health
|
||||
|
||||
@@ -3,11 +3,11 @@
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a><span class=w> </span>--detach<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=w> </span>--read-only<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-5><a id=__codelineno-0-5 name=__codelineno-0-5 href=#__codelineno-0-5></a><span class=w> </span>--tmpfs<span class=w> </span>/var/run/headscale<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-6><a id=__codelineno-0-6 name=__codelineno-0-6 href=#__codelineno-0-6></a><span class=w> </span>--volume<span class=w> </span><span class=s2>"</span><span class=k>$(</span><span class=nb>pwd</span><span class=k>)</span><span class=s2>/config:/etc/headscale:ro"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-7><a id=__codelineno-0-7 name=__codelineno-0-7 href=#__codelineno-0-7></a><span class=w> </span>--volume<span class=w> </span><span class=s2>"</span><span class=k>$(</span><span class=nb>pwd</span><span class=k>)</span><span class=s2>/lib:/var/lib/headscale"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-6><a id=__codelineno-0-6 name=__codelineno-0-6 href=#__codelineno-0-6></a><span class=w> </span>--volume<span class=w> </span><span class=s2>"</span><span class=k>$(</span><span class=nb>pwd</span><span class=k>)</span><span class=s2>/config:/etc/headscale:ro"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-7><a id=__codelineno-0-7 name=__codelineno-0-7 href=#__codelineno-0-7></a><span class=w> </span>--volume<span class=w> </span><span class=s2>"</span><span class=k>$(</span><span class=nb>pwd</span><span class=k>)</span><span class=s2>/lib:/var/lib/headscale"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-8><a id=__codelineno-0-8 name=__codelineno-0-8 href=#__codelineno-0-8></a><span class=w> </span>--publish<span class=w> </span><span class=m>127</span>.0.0.1:8080:8080<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-9><a id=__codelineno-0-9 name=__codelineno-0-9 href=#__codelineno-0-9></a><span class=w> </span>--publish<span class=w> </span><span class=m>127</span>.0.0.1:9090:9090<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-10><a id=__codelineno-0-10 name=__codelineno-0-10 href=#__codelineno-0-10></a><span class=w> </span>--health-cmd<span class=w> </span><span class=s2>"CMD headscale health"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-10><a id=__codelineno-0-10 name=__codelineno-0-10 href=#__codelineno-0-10></a><span class=w> </span>--health-cmd<span class=w> </span><span class=s2>"CMD headscale health"</span><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-11><a id=__codelineno-0-11 name=__codelineno-0-11 href=#__codelineno-0-11></a><span class=w> </span>docker.io/headscale/headscale:main-<sha><span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-12><a id=__codelineno-0-12 name=__codelineno-0-12 href=#__codelineno-0-12></a><span class=w> </span>serve
|
||||
</span></code></pre></div> <p>See <a href=../container/ >Running headscale in a container</a> for full container setup instructions.</p> <h2 id=binaries>Binaries<a class=headerlink href=#binaries title="Permanent link">¶</a></h2> <p>Pre-built binaries from the latest successful build on <code>main</code> are available via <a href=https://nightly.link/juanfont/headscale/workflows/container-main/main>nightly.link</a>:</p> <table> <thead> <tr> <th>OS</th> <th>Arch</th> <th>Download</th> </tr> </thead> <tbody> <tr> <td>Linux</td> <td>amd64</td> <td><a href=https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-linux-amd64.zip>headscale-linux-amd64</a></td> </tr> <tr> <td>Linux</td> <td>arm64</td> <td><a href=https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-linux-arm64.zip>headscale-linux-arm64</a></td> </tr> <tr> <td>macOS</td> <td>amd64</td> <td><a href=https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-darwin-amd64.zip>headscale-darwin-amd64</a></td> </tr> <tr> <td>macOS</td> <td>arm64</td> <td><a href=https://nightly.link/juanfont/headscale/workflows/container-main/main/headscale-darwin-arm64.zip>headscale-darwin-arm64</a></td> </tr> </tbody> </table> <p>After downloading and extracting the archive, make the binary executable and follow the <a href=../official/#using-standalone-binaries-advanced>standalone binary installation</a> instructions for setting up the service.</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <div class=md-top data-md-component=top hidden> <div class=md-top__center> <button type=button class="md-top__button md-top__button--main" data-md-action=top> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> <span>Back to top</span> </button> <label class="md-top__button md-top__side md-top__side--nav" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-left" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M9 3v18"/></svg> </label> <label class="md-top__button md-top__side md-top__side--toc" for=__toc> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-right" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M15 3v18"/></svg> </label> </div> </div> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../source/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Build from source"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Build from source </div> </div> </a> <a href=../../upgrade/ class="md-footer__link md-footer__link--next" aria-label="Next: Upgrade"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Upgrade </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2026 Headscale authors </div> Made with <a href=https://jaywhj.github.io/mkdocs-materialx/ target=_blank rel=noopener> MaterialX </a> </div> <div class=md-social> <a href=https://github.com/juanfont/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9Line truncated
|
||||
@@ -1,7 +1,7 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/setup/install/official/ rel=canonical><link href=../../requirements/ rel=prev><link href=../community/ rel=next><link rel=icon href=../../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Official releases - Headscale</title><link rel=stylesheet href=../../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../../..",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><meta property=og:type content=website><meta property=og:title content="Official releases - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/setup/install/official.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/setup/install/official/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Official releases - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/setup/install/official.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#official-releases class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Official releases </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15Line truncated
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=nv>HEADSCALE_ARCH</span><span class=o>=</span><span class=s2>""</span><span class=w> </span><span class=c1># Your system architecture, e.g. "amd64"</span>
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/setup/install/official/ rel=canonical><link href=../../requirements/ rel=prev><link href=../community/ rel=next><link rel=icon href=../../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Official releases - Headscale</title><link rel=stylesheet href=../../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../../..",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><meta property=og:type content=website><meta property=og:title content="Official releases - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/setup/install/official.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/setup/install/official/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Official releases - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/setup/install/official.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#official-releases class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Official releases </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15Line truncated
|
||||
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=nv>HEADSCALE_ARCH</span><span class=o>=</span><span class=s2>""</span><span class=w> </span><span class=c1># Your system architecture, e.g. "amd64"</span>
|
||||
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a>wget<span class=w> </span>--output-document<span class=o>=</span>headscale.deb<span class=w> </span><span class=se>\</span>
|
||||
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=w> </span><span class=s2>"https://github.com/juanfont/headscale/releases/download/v</span><span class=si>${</span><span class=nv>HEADSCALE_VERSION</span><span class=si>}</span><span class=s2>/headscale_</span><span class=si>${</span><span class=nv>HEADSCALE_VERSION</span><span class=si>}</span><span class=s2>_linux_</span><span class=si>${</span><span class=nv>HEADSCALE_ARCH</span><span class=si>}</span><span class=s2>.deb"</span>
|
||||
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=w> </span><span class=s2>"https://github.com/juanfont/headscale/releases/download/v</span><span class=si>${</span><span class=nv>HEADSCALE_VERSION</span><span class=si>}</span><span class=s2>/headscale_</span><span class=si>${</span><span class=nv>HEADSCALE_VERSION</span><span class=si>}</span><span class=s2>_linux_</span><span class=si>${</span><span class=nv>HEADSCALE_ARCH</span><span class=si>}</span><span class=s2>.deb"</span>
|
||||
</span></code></pre></div> </li> <li> <p>Install headscale:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a>sudo<span class=w> </span>apt<span class=w> </span>install<span class=w> </span>./headscale.deb
|
||||
</span></code></pre></div> </li> <li> <p><a href=../../../ref/configuration/ >Configure headscale by editing the configuration file</a>. An up-to date example configuration file is also available in <code>/usr/share/doc/headscale/examples/config-example.yaml</code>:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a>sudo<span class=w> </span>nano<span class=w> </span>/etc/headscale/config.yaml
|
||||
</span></code></pre></div> </li> <li> <p>Restart headscale to pick up configuration changes:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a>sudo<span class=w> </span>systemctl<span class=w> </span>restart<span class=w> </span>headscale
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
</span><span id=__span-0-12><a id=__codelineno-0-12 name=__codelineno-0-12 href=#__codelineno-0-12></a>
|
||||
</span><span id=__span-0-13><a id=__codelineno-0-13 name=__codelineno-0-13 href=#__codelineno-0-13></a>git<span class=w> </span>checkout<span class=w> </span><span class=nv>$latestTag</span>
|
||||
</span><span id=__span-0-14><a id=__codelineno-0-14 name=__codelineno-0-14 href=#__codelineno-0-14></a>
|
||||
</span><span id=__span-0-15><a id=__codelineno-0-15 name=__codelineno-0-15 href=#__codelineno-0-15></a>go<span class=w> </span>build<span class=w> </span>-ldflags<span class=o>=</span><span class=s2>"-s -w -X github.com/juanfont/headscale/hscontrol/types.Version=</span><span class=nv>$latestTag</span><span class=s2>"</span><span class=w> </span>-X<span class=w> </span>github.com/juanfont/headscale/hscontrol/types.GitCommitHash<span class=o>=</span>HASH<span class=s2>" github.com/juanfont/headscale</span>
|
||||
</span><span id=__span-0-15><a id=__codelineno-0-15 name=__codelineno-0-15 href=#__codelineno-0-15></a>go<span class=w> </span>build<span class=w> </span>-ldflags<span class=o>=</span><span class=s2>"-s -w -X github.com/juanfont/headscale/hscontrol/types.Version=</span><span class=nv>$latestTag</span><span class=s2>"</span><span class=w> </span>-X<span class=w> </span>github.com/juanfont/headscale/hscontrol/types.GitCommitHash<span class=o>=</span>HASH<span class=s2>" github.com/juanfont/headscale</span>
|
||||
</span><span id=__span-0-16><a id=__codelineno-0-16 name=__codelineno-0-16 href=#__codelineno-0-16></a>
|
||||
</span><span id=__span-0-17><a id=__codelineno-0-17 name=__codelineno-0-17 href=#__codelineno-0-17></a><span class=s2># make it executable</span>
|
||||
</span><span id=__span-0-18><a id=__codelineno-0-18 name=__codelineno-0-18 href=#__codelineno-0-18></a><span class=s2>chmod a+x headscale</span>
|
||||
@@ -20,7 +20,7 @@
|
||||
</span><span id=__span-0-20><a id=__codelineno-0-20 name=__codelineno-0-20 href=#__codelineno-0-20></a><span class=s2># copy it to /usr/local/sbin</span>
|
||||
</span><span id=__span-0-21><a id=__codelineno-0-21 name=__codelineno-0-21 href=#__codelineno-0-21></a><span class=s2>cp headscale /usr/local/sbin</span>
|
||||
</span></code></pre></div> <h3 id=install-from-source-via-cross-compile>Install from source via cross compile<a class=headerlink href=#install-from-source-via-cross-compile title="Permanent link">¶</a></h3> <div class="language-shell highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a><span class=c1># Install prerequisites</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=c1># 1. go v1.20+: headscale newer than 0.21 needs go 1.20+ to compile</span>
|
||||
</span><span id=__span-1-2><a id=__codelineno-1-2 name=__codelineno-1-2 href=#__codelineno-1-2></a><span class=c1># 1. go v1.27+: see the go directive in go.mod for the exact minimum</span>
|
||||
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=c1># 2. gmake: Makefile in the headscale repo is written in GNU make syntax</span>
|
||||
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a>
|
||||
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a>git<span class=w> </span>clone<span class=w> </span>https://github.com/juanfont/headscale.git
|
||||
|
||||
+33
-33
@@ -2,167 +2,167 @@
|
||||
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/about/clients/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/about/contributing/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/about/faq/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/about/features/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/about/help/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/about/releases/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/about/sponsor/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/api/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/configuration/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/debug/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/derp/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/dns/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/oidc/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/policy/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/registration/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/routes/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/tags/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/tls/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/integration/reverse-proxy/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/integration/tools/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/ref/integration/web-ui/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/setup/requirements/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/setup/upgrade/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/setup/install/community/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/setup/install/container/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/setup/install/main/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/setup/install/official/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/setup/install/source/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/usage/getting-started/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/usage/connect/android/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/usage/connect/apple/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
<url>
|
||||
<loc>https://juanfont.github.io/headscale/development/usage/connect/windows/</loc>
|
||||
<lastmod>2026-07-29</lastmod>
|
||||
<lastmod>2026-08-25</lastmod>
|
||||
<changefreq>daily</changefreq>
|
||||
</url>
|
||||
</urlset>
|
||||
Binary file not shown.
@@ -1,4 +1,4 @@
|
||||
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="An open source, self-hosted implementation of the Tailscale control server."><meta name=author content="Headscale authors"><link href=https://juanfont.github.io/headscale/development/usage/connect/windows/ rel=canonical><link href=../apple/ rel=prev><link href=../../../ref/configuration/ rel=next><link rel=icon href=../../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Windows - Headscale</title><link rel=stylesheet href=../../../assets/stylesheets/main.d7aee198.min.css><link rel=stylesheet href=../../../assets/stylesheets/palette.a45159b5.min.css><link rel=preconnect href=https://fonts.gstatic.com crossorigin><link rel=stylesheet href="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=new URL("../../..",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><meta property=og:type content=website><meta property=og:title content="Windows - Headscale"><meta property=og:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=og:image content=https://juanfont.github.io/headscale/development/assets/images/social/usage/connect/windows.png><meta property=og:image:type content=image/png><meta property=og:image:width content=1200><meta property=og:image:height content=630><meta content=https://juanfont.github.io/headscale/development/usage/connect/windows/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Windows - Headscale"><meta property=twitter:description content="An open source, self-hosted implementation of the Tailscale control server."><meta property=twitter:image content=https://juanfont.github.io/headscale/development/assets/images/social/usage/connect/windows.png></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo data-mx-topbar=glass> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=toc type=checkbox id=__toc autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <label class=md-overlay for=__toc></label> <div data-md-component=skip> <a href=#connecting-a-windows-client class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <div data-md-color-scheme=default data-md-component=outdated hidden> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../../.. title=Headscale class="md-header__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../../assets/logo/headscale3-dots.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> Headscale </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Windows </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media=(prefers-color-scheme) data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to light mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to dark mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_2 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20HLine truncated
|
||||
</span></code></pre></div> <p>Follow the instructions in the opened browser window to finish the configuration.</p> <h2 id=troubleshooting>Troubleshooting<a class=headerlink href=#troubleshooting title="Permanent link">¶</a></h2> <h3 id=unattended-mode>Unattended mode<a class=headerlink href=#unattended-mode title="Permanent link">¶</a></h3> <p>By default, Tailscale's Windows client is only running when the user is logged in. If you want to keep Tailscale running all the time, please enable "Unattended mode":</p> <ul> <li>Click on the Tailscale tray icon and select <code>Preferences</code></li> <li>Enable <code>Run unattended</code></li> <li>Confirm the "Unattended mode" message</li> </ul> <p>See also <a href=https://tailscale.com/docs/how-to/run-unattended>Keep Tailscale running when I'm not logged in to my computer</a>.</p> <h3 id=failing-node-registration>Failing node registration<a class=headerlink href=#failing-node-registration title="Permanent link">¶</a></h3> <p>If you are seeing repeated messages like:</p> <div class="language-text highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a>[GIN] 2022/02/10 - 16:39:34 | 200 | 1.105306ms | 127.0.0.1 | POST "/machine/redacted"
|
||||
</span></code></pre></div> <p>Follow the instructions in the opened browser window to finish the configuration.</p> <h2 id=troubleshooting>Troubleshooting<a class=headerlink href=#troubleshooting title="Permanent link">¶</a></h2> <h3 id=unattended-mode>Unattended mode<a class=headerlink href=#unattended-mode title="Permanent link">¶</a></h3> <p>By default, Tailscale's Windows client is only running when the user is logged in. If you want to keep Tailscale running all the time, please enable "Unattended mode":</p> <ul> <li>Click on the Tailscale tray icon and select <code>Preferences</code></li> <li>Enable <code>Run unattended</code></li> <li>Confirm the "Unattended mode" message</li> </ul> <p>See also <a href=https://tailscale.com/docs/how-to/run-unattended>Keep Tailscale running when I'm not logged in to my computer</a>.</p> <h3 id=failing-node-registration>Failing node registration<a class=headerlink href=#failing-node-registration title="Permanent link">¶</a></h3> <p>If you are seeing repeated messages like:</p> <div class="language-text highlight"><pre><span></span><code><span id=__span-1-1><a id=__codelineno-1-1 name=__codelineno-1-1 href=#__codelineno-1-1></a>[GIN] 2022/02/10 - 16:39:34 | 200 | 1.105306ms | 127.0.0.1 | POST "/machine/redacted"
|
||||
</span></code></pre></div> <p>in your headscale output, turn on <code>DEBUG</code> logging and look for:</p> <div class="language-text highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a>2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
|
||||
</span></code></pre></div> <p>This typically means that the registry keys above was not set appropriately.</p> <p>To reset and try again, it is important to do the following:</p> <ol> <li>Shut down the Tailscale service (or the client running in the tray)</li> <li>Delete Tailscale Application data folder, located at <code>C:\Users\<USERNAME>\AppData\Local\Tailscale</code> and try to connect again.</li> <li>Ensure the Windows node is deleted from headscale (to ensure fresh setup)</li> <li>Start Tailscale on the Windows machine and retry the login.</li> </ol> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <div class=md-top data-md-component=top hidden> <div class=md-top__center> <button type=button class="md-top__button md-top__button--main" data-md-action=top> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> <span>Back to top</span> </button> <label class="md-top__button md-top__side md-top__side--nav" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-left" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M9 3v18"/></svg> </label> <label class="md-top__button md-top__side md-top__side--toc" for=__toc> <svg xmlns=http://www.w3.org/2000/svg fill=none stroke=currentColor stroke-linecap=round stroke-linejoin=round stroke-width=2 class="lucide lucide-panel-right" viewbox="0 0 24 24"><rect width=18 height=18 x=3 y=3 rx=2 /><path d="M15 3v18"/></svg> </label> </div> </div> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../apple/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Apple"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> Apple </div> </div> </a> <a href=../../../ref/configuration/ class="md-footer__link md-footer__link--next" aria-label="Next: Configuration"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Configuration </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright © 2026 Headscale authors </div> Made with <a href=https://jaywhj.github.io/mkdocs-materialx/ target=_blank rel=noopener> MaterialX </a> </div> <div class=md-social> <a href=https://github.com/juanfont/headscale target=_blank rel=noopener title=github.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href=https://ko-fi.com/headscale target=_blank rel=noopener title=ko-fi.com class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M2 21h18v-2H2M20 8h-2V5h2m0-2H4v10a4 4 0 0 0 4 4h6a4 4 0 0 0 4-4v-3h2a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2"/></svg> </a> <aLine truncated
|
||||
+2
-2
@@ -10,8 +10,8 @@
|
||||
"version": "0.29.3",
|
||||
"title": "0.29.3",
|
||||
"aliases": [
|
||||
"latest",
|
||||
"stable"
|
||||
"stable",
|
||||
"latest"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
||||
Reference in new issue
Block a user