Deployed 691ef563 to development with ProperDocs 1.6.7 and mike 2.2.0

This commit is contained in:
github-actions committed 2026-10-18 18:55:18 +00:00
1 parent 98cb8b4160
commit ec9e2d90d3
41 files changed
+115 -112

No files matched your search

+2 -2
View File
@@ -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/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
<!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.1"><title>API - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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>&lt;PREFIX&gt;
</span></code></pre></div> <h2 id=rest-api>REST API<a class=headerlink href=#rest-api title="Permanent link">&para;</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 &lt;API_KEY&gt;</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 &lt;API_KEY&gt;" \</span>
@@ -31,4 +31,4 @@
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-13-1><a id=__codelineno-13-1 name=__codelineno-13-1 href=#__codelineno-13-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>"&lt;HEADSCALE_URL&gt;"</span>
</span><span id=__span-13-2><a id=__codelineno-13-2 name=__codelineno-13-2 href=#__codelineno-13-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>"&lt;API_KEY&gt;"</span>
</span></code></pre></div> </div> </div> </div> <p>This instructs the <code>headscale</code> binary to connect to a remote instance at <code>&lt;HEADSCALE_URL&gt;</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-14-1><a id=__codelineno-14-1 name=__codelineno-14-1 href=#__codelineno-14-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">&para;</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">&para;</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 &copy; 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
</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">&para;</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">&para;</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 &copy; 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 -2
View File
@@ -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/ref/configuration/ rel=canonical><link href=../../usage/connect/windows/ rel=prev><link href=../registration/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Configuration - 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="Configuration - 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/configuration.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/configuration/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Configuration - 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/configuration.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=#configuration 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> Configuration </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 1Line 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/ref/configuration/ rel=canonical><link href=../../usage/connect/windows/ rel=prev><link href=../registration/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.1"><title>Configuration - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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="Configuration - 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/configuration.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/configuration/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Configuration - 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/configuration.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=#configuration 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> Configuration </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 1Line truncated
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a>wget<span class=w> </span>-O<span class=w> </span>config.yaml<span class=w> </span>https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
</span><span id=__span-0-3><a id=__codelineno-0-3 name=__codelineno-0-3 href=#__codelineno-0-3></a>
</span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=c1># Version 0.29.5</span>
@@ -8,4 +8,4 @@
</span><span id=__span-1-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a>
</span><span id=__span-1-4><a id=__codelineno-1-4 name=__codelineno-1-4 href=#__codelineno-1-4></a><span class=c1># Version 0.29.5</span>
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a>curl<span class=w> </span>-o<span class=w> </span>config.yaml<span class=w> </span>https://raw.githubusercontent.com/juanfont/headscale/v0.29.5/config-example.yaml
</span></code></pre></div> </div> </div> </div> </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=../../usage/connect/windows/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Windows"> <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> Windows </div> </div> </a> <a href=../registration/ class="md-footer__link md-footer__link--next" aria-label="Next: Registration methods"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Registration methods </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h66.1zm78.2 144.8H362v59.4Line truncated
</span></code></pre></div> </div> </div> </div> </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=../../usage/connect/windows/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Windows"> <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> Windows </div> </div> </a> <a href=../registration/ class="md-footer__link md-footer__link--next" aria-label="Next: Registration methods"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Registration methods </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h66.1zm78.2 144.8H362v59.4Line truncated
+2 -2
View File
@@ -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/ref/debug/ rel=canonical><link href=../tags/ rel=prev><link href=../integration/reverse-proxy/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Debug - 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="Debug - 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/debug.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/debug/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Debug - 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/debug.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=#debugging-and-troubleshooting 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> Debug </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-colLine 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/ref/debug/ rel=canonical><link href=../tags/ rel=prev><link href=../integration/reverse-proxy/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.1"><title>Debug - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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="Debug - 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/debug.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/debug/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Debug - 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/debug.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=#debugging-and-troubleshooting 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> Debug </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-colLine 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=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">&para;</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>
@@ -15,4 +15,4 @@
</span><span id=__span-4-3><a id=__codelineno-4-3 name=__codelineno-4-3 href=#__codelineno-4-3></a><span class=go>headscale serve</span>
</span></code></pre></div> <p>Access the debug interface on your device by opening <code>http://&lt;IP_OF_HEADSCALE&gt;:9090/debug/?debugkey=&lt;DEBUG_KEY&gt;</code> in your web browser. The <code>debugkey</code> parameter must be sent with every request.</p> </div> <div class=tabbed-block> <p>The debug endpoint expects traffic from localhost. A different debug IP address may be configured by setting the <code>TS_ALLOW_DEBUG_IP</code> environment variable before starting Headscale. The debug IP address is ignored when the HTTP header <code>X-Forwarded-For</code> is present.</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=go>export TS_ALLOW_DEBUG_IP=192.168.0.10 # IP address of your device</span>
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=go>headscale serve</span>
</span></code></pre></div> <p>Access the debug interface on your device by opening <code>http://&lt;IP_OF_HEADSCALE&gt;:9090/debug/</code> in your web browser.</p> </div> </div> </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=../tags/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Tags"> <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> Tags </div> </div> </a> <a href=../integration/reverse-proxy/ class="md-footer__link md-footer__link--next" aria-label="Next: Reverse proxy"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Reverse proxy </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025Line truncated
</span></code></pre></div> <p>Access the debug interface on your device by opening <code>http://&lt;IP_OF_HEADSCALE&gt;:9090/debug/</code> in your web browser.</p> </div> </div> </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=../tags/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Tags"> <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> Tags </div> </div> </a> <a href=../integration/reverse-proxy/ class="md-footer__link md-footer__link--next" aria-label="Next: Reverse proxy"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Reverse proxy </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025Line truncated
+2 -2
View File
@@ -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/ref/derp/ rel=canonical><link href=../dns/ rel=prev><link href=../api/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>DERP - 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="DERP - 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/derp.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/derp/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="DERP - 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/derp.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=#derp 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> DERP </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-scLine 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/ref/derp/ rel=canonical><link href=../dns/ rel=prev><link href=../api/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.1"><title>DERP - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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="DERP - 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/derp.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/derp/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="DERP - 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/derp.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=#derp 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> DERP </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-scLine 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>server</span><span class=p>:</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>enabled</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
</span></span><span id=__span-0-4><a id=__codelineno-0-4 name=__codelineno-0-4 href=#__codelineno-0-4></a><span class=hll><span class=w> </span><span class=nt>ipv4</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">198.51.100.1</span>
@@ -50,4 +50,4 @@
</span></span></code></pre></div> </div> </div> </div> <p>Independent of the custom DERP map, you may choose to <a href=#enable-embedded-derp>enable the embedded DERP server and have it automatically added to the custom DERP map</a>.</p> <h3 id=verify-clients>Verify clients<a class=headerlink href=#verify-clients title="Permanent link">&para;</a></h3> <p>Access to DERP serves can be restricted to nodes that are members of your Tailnet. Relay access is denied for unknown clients.</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>Embedded DERP</label><label for=__tabbed_2_2>3<sup>rd</sup>-party DERP</label></div> <div class=tabbed-content> <div class=tabbed-block> <p>Client verification is enabled by default.</p> <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>derp</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>server</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=hll><span class=w> </span><span class=nt>verify_clients</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> <p>Tailscale's <code>derper</code> provides two parameters to configure client verification:</p> <ul> <li>Use the <code>-verify-client-url</code> parameter of the <code>derper</code> and point it towards the <code>/verify</code> endpoint of your Headscale server (e.g <code>https://headscale.example.com/verify</code>). The DERP server will query your Headscale instance as soon as a client connects with it to ask whether access should be allowed or denied. Access is allowed if Headscale knows about the connecting client and denied otherwise.</li> <li>The parameter <code>-verify-client-url-fail-open</code> controls what should happen when the DERP server can't reach the Headscale instance. By default, it will allow access if Headscale is unreachable.</li> </ul> </div> </div> </div> <h2 id=check-derp-server-connectivity>Check DERP server connectivity<a class=headerlink href=#check-derp-server-connectivity title="Permanent link">&para;</a></h2> <p>Any Tailscale client may be used to introspect the DERP map and to check for connectivity issues with DERP servers.</p> <ul> <li>Display DERP map: <code>tailscale debug derp-map</code></li> <li>Check connectivity with the embedded DERP<sup id=fnref:1><a class=footnote-ref href=#fn:1>1</a></sup>:<code>tailscale debug derp headscale</code></li> </ul> <p>Additional DERP related metrics and information is available via the <a href=../debug/#metrics-and-debug-endpoint>metrics and debug endpoint</a>.</p> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="Permanent link">&para;</a></h2> <ul> <li>The embedded DERP server can't be used for Tailscale's captive portal checks as it doesn't support the <code>/generate_204</code> endpoint via HTTP on port tcp/80.</li> <li>There are no speed or throughput optimisations, the main purpose is to assist in node connectivity.</li> </ul> <div class=footnote> <hr> <ol> <li id=fn:1> <p>This assumes that the default region code of the <a href=../configuration/ >configuration file</a> is used.&#160;<a class=footnote-backref href=#fnref:1 title="Jump back to footnote 1 in the text">&#8617;</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=../dns/ class="md-footer__link md-footer__link--prev" aria-label="Previous: DNS"> <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> DNS </div> </div> </a> <a href=../api/ class="md-footer__link md-footer__link--next" aria-label="Next: API"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> API </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 &copy; 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=Line truncated
</span></span></code></pre></div> </div> <div class=tabbed-block> <p>Tailscale's <code>derper</code> provides two parameters to configure client verification:</p> <ul> <li>Use the <code>-verify-client-url</code> parameter of the <code>derper</code> and point it towards the <code>/verify</code> endpoint of your Headscale server (e.g <code>https://headscale.example.com/verify</code>). The DERP server will query your Headscale instance as soon as a client connects with it to ask whether access should be allowed or denied. Access is allowed if Headscale knows about the connecting client and denied otherwise.</li> <li>The parameter <code>-verify-client-url-fail-open</code> controls what should happen when the DERP server can't reach the Headscale instance. By default, it will allow access if Headscale is unreachable.</li> </ul> </div> </div> </div> <h2 id=check-derp-server-connectivity>Check DERP server connectivity<a class=headerlink href=#check-derp-server-connectivity title="Permanent link">&para;</a></h2> <p>Any Tailscale client may be used to introspect the DERP map and to check for connectivity issues with DERP servers.</p> <ul> <li>Display DERP map: <code>tailscale debug derp-map</code></li> <li>Check connectivity with the embedded DERP<sup id=fnref:1><a class=footnote-ref href=#fn:1>1</a></sup>:<code>tailscale debug derp headscale</code></li> </ul> <p>Additional DERP related metrics and information is available via the <a href=../debug/#metrics-and-debug-endpoint>metrics and debug endpoint</a>.</p> <h2 id=limitations>Limitations<a class=headerlink href=#limitations title="Permanent link">&para;</a></h2> <ul> <li>The embedded DERP server can't be used for Tailscale's captive portal checks as it doesn't support the <code>/generate_204</code> endpoint via HTTP on port tcp/80.</li> <li>There are no speed or throughput optimisations, the main purpose is to assist in node connectivity.</li> </ul> <div class=footnote> <hr> <ol> <li id=fn:1> <p>This assumes that the default region code of the <a href=../configuration/ >configuration file</a> is used.&#160;<a class=footnote-backref href=#fnref:1 title="Jump back to footnote 1 in the text">&#8617;</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=../dns/ class="md-footer__link md-footer__link--prev" aria-label="Previous: DNS"> <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> DNS </div> </div> </a> <a href=../api/ class="md-footer__link md-footer__link--next" aria-label="Next: API"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> API </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 &copy; 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=Line truncated
+2 -2
View File
@@ -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/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
<!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.1"><title>DNS - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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>
@@ -40,4 +40,4 @@
</span><span id=__span-4-13><a id=__codelineno-4-13 name=__codelineno-4-13 href=#__codelineno-4-13></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-4-14><a id=__codelineno-4-14 name=__codelineno-4-14 href=#__codelineno-4-14></a>
</span><span id=__span-4-15><a id=__codelineno-4-15 name=__codelineno-4-15 href=#__codelineno-4-15></a><span class=p>}</span>
</span></code></pre></div> </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=../policy/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Policy"> <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> Policy </div> </div> </a> <a href=../derp/ class="md-footer__link md-footer__link--next" aria-label="Next: DERP"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> DERP </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h66.1zm78.2 144.8H362v59.4h66.1zm-156.3-72.1h-66.1v60.1h66.1zm78.1 0h-66.1v60.1h66.1zm276.8 100c-14.4-Line truncated
</span></code></pre></div> </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=../policy/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Policy"> <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> Policy </div> </div> </a> <a href=../derp/ class="md-footer__link md-footer__link--next" aria-label="Next: DERP"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> DERP </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h66.1zm78.2 144.8H362v59.4h66.1zm-156.3-72.1h-66.1v60.1h66.1zm78.1 0h-66.1v60.1h66.1zm276.8 100c-14.4-Line truncated
@@ -1,6 +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/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>
<!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.1"><title>Reverse proxy - Headscale</title><link rel=stylesheet href=../../../assets/stylesheets/main.f07c159f.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</span><span class=p>:</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>cert_path</span><span class=p>:</span><span class=w> </span><span class=s>""</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>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">&para;</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,8 +11,9 @@
</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</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=nt>cert_path</span><span class=p>:</span><span class=w> </span><span class=s>""</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>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">&para;</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>&lt;SERVER_NAME&gt;</code>: The server name for your instance, e.g. <code>headscale.example.com</code></li> <li><code>&lt;PATH_TO_TLS_CERT&gt;</code>: Absolute path to your TLS certificate</li> <li><code>&lt;PATH_TO_TLS_KEY&gt;</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>&lt;VirtualHost</span><span class=w> </span><span class=s>*:80</span><span class=nt>&gt;</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>&lt;SERVER_NAME&gt;
</span></span><span id=__span-3-3><a id=__codelineno-3-3 name=__codelineno-3-3 href=#__codelineno-3-3></a>
@@ -125,4 +127,4 @@
</span><span id=__span-6-52><a id=__codelineno-6-52 name=__codelineno-6-52 href=#__codelineno-6-52></a><span class=w> </span><span class=kn>proxy_pass</span><span class=w> </span><span class=s>http://headscale</span><span class=p>;</span>
</span><span id=__span-6-53><a id=__codelineno-6-53 name=__codelineno-6-53 href=#__codelineno-6-53></a><span class=w> </span><span class=p>}</span>
</span><span id=__span-6-54><a id=__codelineno-6-54 name=__codelineno-6-54 href=#__codelineno-6-54></a><span class=p>}</span>
</span></code></pre></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=../../debug/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Debug"> <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> Debug </div> </div> </a> <a href=../web-ui/ class="md-footer__link md-footer__link--next" aria-label="Next: Web UI"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Web UI </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h66.1zm78.2 144.8H362v59.4h66.1zm-156.3-72.1h-66.1v60.1h66.1zm78.1 0h-66.1v60.1h66.1zm276.8 100c-14.4-9.7-47Line truncated
</span></code></pre></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=../../debug/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Debug"> <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> Debug </div> </div> </a> <a href=../web-ui/ class="md-footer__link md-footer__link--next" aria-label="Next: Web UI"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Web UI </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h66.1zm78.2 144.8H362v59.4h66.1zm-156.3-72.1h-66.1v60.1h66.1zm78.1 0h-66.1v60.1h66.1zm276.8 100c-14.4-9.7-47Line truncated
+1 -1
View File
@@ -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/ref/integration/tools/ rel=canonical><link href=../web-ui/ rel=prev><link rel=icon href=../../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Tools - 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="Tools - 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/tools.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/tools/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Tools - 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/tools.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=#tools-related-to-headscale 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> Tools </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-optLine 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/ref/integration/tools/ rel=canonical><link href=../web-ui/ rel=prev><link rel=icon href=../../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.1"><title>Tools - Headscale</title><link rel=stylesheet href=../../../assets/stylesheets/main.f07c159f.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="Tools - 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/tools.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/tools/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Tools - 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/tools.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=#tools-related-to-headscale 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> Tools </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-optLine truncated
@@ -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/ref/integration/web-ui/ rel=canonical><link href=../reverse-proxy/ rel=prev><link href=../tools/ rel=next><link rel=icon href=../../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Web UI - 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="Web UI - 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/web-ui.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/web-ui/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Web UI - 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/web-ui.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=#web-interfaces-for-headscale 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> Web UI </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.69LLine 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/ref/integration/web-ui/ rel=canonical><link href=../reverse-proxy/ rel=prev><link href=../tools/ rel=next><link rel=icon href=../../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.1"><title>Web UI - Headscale</title><link rel=stylesheet href=../../../assets/stylesheets/main.f07c159f.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="Web UI - 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/web-ui.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/web-ui/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Web UI - 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/web-ui.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=#web-interfaces-for-headscale 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> Web UI </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.69LLine truncated
+2 -2
View File
@@ -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/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
<!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.1"><title>OpenID Connect - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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>
@@ -58,4 +58,4 @@
</span></code></pre></div> </div> <h2 id=supported-oidc-claims>Supported OIDC claims<a class=headerlink href=#supported-oidc-claims title="Permanent link">&para;</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">&para;</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">&para;</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">&para;</a></h3> <p>Authelia is fully supported by Headscale.</p> <h3 id=authentik>Authentik<a class=headerlink href=#authentik title="Permanent link">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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">&para;</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/&lt;tenant-UUID&gt;/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></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">&para;</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 &copy; 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
</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">&para;</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 &copy; 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
+2 -2
View File
@@ -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/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
<!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.1"><title>Policy - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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">&para;</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-3><a id=__codelineno-1-3 name=__codelineno-1-3 href=#__codelineno-1-3></a><span class=p>}</span>
@@ -82,4 +82,4 @@
</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-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.&#160;<a class=footnote-backref href=#fnref:1 title="Jump back to footnote 1 in the text">&#8617;</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 ' Cap ' tailcfg/nodecap/nodecap.go</code> or by using <a href="https://github.com/search?q=repo%3Atailscale%2Ftailscale+language%3Ago+path%3Atailcfg%2Fnodecap%2Fnodecap.go+%2F+Cap+%2F&type=code">GitHub code search (requires login)</a>.&#160;<a class=footnote-backref href=#fnref:2 title="Jump back to footnote 2 in the text">&#8617;</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 &copy; 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-fLine truncated
</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.&#160;<a class=footnote-backref href=#fnref:1 title="Jump back to footnote 1 in the text">&#8617;</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 ' Cap ' tailcfg/nodecap/nodecap.go</code> or by using <a href="https://github.com/search?q=repo%3Atailscale%2Ftailscale+language%3Ago+path%3Atailcfg%2Fnodecap%2Fnodecap.go+%2F+Cap+%2F&type=code">GitHub code search (requires login)</a>.&#160;<a class=footnote-backref href=#fnref:2 title="Jump back to footnote 2 in the text">&#8617;</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 &copy; 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-fLine truncated
+2 -2
View File
@@ -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/ref/registration/ rel=canonical><link href=../configuration/ rel=prev><link href=../oidc/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Registration methods - 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="Registration methods - 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/registration.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/registration/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Registration methods - 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/registration.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=#registration-methods 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> Registration methods </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-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/ref/registration/ rel=canonical><link href=../configuration/ rel=prev><link href=../oidc/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.1"><title>Registration methods - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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="Registration methods - 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/registration.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/registration/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Registration methods - 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/registration.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=#registration-methods 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> Registration methods </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-Line truncated
</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 &lt;YOUR_HEADSCALE_URL&gt;</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 &lt;USER&gt; --auth-id &lt;AUTH_ID&gt;</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>&lt;USER&gt;</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>
@@ -14,4 +14,4 @@
</span></code></pre></div> <p>The above prints a pre authenticated key with the default settings (can be used once and is valid for one hour). Use this auth key to register a node non-interactively:</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>tailscale up --login-server &lt;YOUR_HEADSCALE_URL&gt; --authkey &lt;YOUR_AUTH_KEY&gt;</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>&lt;USER&gt;</code> as the owner of the node.</p> </div> <div class=tabbed-block> <p>Create a new pre authenticated key and provide at least one tag:</p> <div class="language-console 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=go>headscale preauthkeys create --tags tag:&lt;TAG&gt;</span>
</span></code></pre></div> <p>The above prints a pre authenticated key with the default settings (can be used once and is valid for one hour). Use this auth key to register a node non-interactively. You don't need to provide the <code>--advertise-tags</code> parameter as the tags are automatically read from the pre authenticated key. Advertising a subset of the key's tags is accepted; any other tag is rejected:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-10-1><a id=__codelineno-10-1 name=__codelineno-10-1 href=#__codelineno-10-1></a><span class=go>tailscale up --login-server &lt;YOUR_HEADSCALE_URL&gt; --authkey &lt;YOUR_AUTH_KEY&gt;</span>
</span></code></pre></div> <p>The registration of a tagged node is complete and it should be listed as "online" in the output of <code>headscale nodes list</code>. The "User" column displays <code>tagged-devices</code> as the owner of the node. See the "Tags" column for the list of assigned tags.</p> </div> </div> </div> <div class=footnote> <hr> <ol> <li id=fn:1> <p><a href=../oidc/#reference-a-user-in-the-policy>Ensure that the Headscale username does not end with <code>@</code>.</a>&#160;<a class=footnote-backref href=#fnref:1 title="Jump back to footnote 1 in the text">&#8617;</a><a class=footnote-backref href=#fnref2:1 title="Jump back to footnote 1 in the text">&#8617;</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=../configuration/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Configuration"> <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> Configuration </div> </div> </a> <a href=../oidc/ class="md-footer__link md-footer__link--next" aria-label="Next: OpenID Connect"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> OpenID Connect </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 &copy; 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/sLine truncated
</span></code></pre></div> <p>The registration of a tagged node is complete and it should be listed as "online" in the output of <code>headscale nodes list</code>. The "User" column displays <code>tagged-devices</code> as the owner of the node. See the "Tags" column for the list of assigned tags.</p> </div> </div> </div> <div class=footnote> <hr> <ol> <li id=fn:1> <p><a href=../oidc/#reference-a-user-in-the-policy>Ensure that the Headscale username does not end with <code>@</code>.</a>&#160;<a class=footnote-backref href=#fnref:1 title="Jump back to footnote 1 in the text">&#8617;</a><a class=footnote-backref href=#fnref2:1 title="Jump back to footnote 1 in the text">&#8617;</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=../configuration/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Configuration"> <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> Configuration </div> </div> </a> <a href=../oidc/ class="md-footer__link md-footer__link--next" aria-label="Next: OpenID Connect"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> OpenID Connect </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 &copy; 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/sLine truncated
+2 -2
View File
@@ -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/ref/routes/ rel=canonical><link href=../oidc/ rel=prev><link href=../tls/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Routes - 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="Routes - 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/routes.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/routes/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Routes - 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/routes.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=#routes 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> Routes </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: darkLine 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/ref/routes/ rel=canonical><link href=../oidc/ rel=prev><link href=../tls/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.1"><title>Routes - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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="Routes - 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/routes.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/routes/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Routes - 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/routes.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=#routes 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> Routes </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: darkLine truncated
</span></code></pre></div> <p>If the node is already registered, it can advertise new routes or update previously announced routes with:</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=gp>$ </span>sudo<span class=w> </span>tailscale<span class=w> </span><span class=nb>set</span><span class=w> </span>--advertise-routes<span class=o>=</span><span class=m>10</span>.0.0.0/8,192.168.0.0/24
</span></code></pre></div> <p>Finally, <a href=#enable-ip-forwarding>enable IP forwarding</a> to route traffic.</p> <h4 id=enable-the-subnet-router-on-the-control-server>Enable the subnet router on the control server<a class=headerlink href=#enable-the-subnet-router-on-the-control-server title="Permanent link">&para;</a></h4> <p>The routes of a tailnet can be displayed with the <code>headscale nodes list-routes</code> command. A subnet router with the hostname <code>myrouter</code> announced the IPv4 networks <code>10.0.0.0/8</code> and <code>192.168.0.0/24</code>. Those need to be approved before they can be used.</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=gp>$ </span>headscale<span class=w> </span>nodes<span class=w> </span>list-routes
</span><span id=__span-2-2><a id=__codelineno-2-2 name=__codelineno-2-2 href=#__codelineno-2-2></a><span class=go>ID | Hostname | Approved | Available | Serving (Primary)</span>
@@ -120,4 +120,4 @@
</span><span id=__span-19-24><a id=__codelineno-19-24 name=__codelineno-19-24 href=#__codelineno-19-24></a><span class=p>}</span>
</span></code></pre></div> <p>The Tailscale client can suggest a viable exit node with:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-20-1><a id=__codelineno-20-1 name=__codelineno-20-1 href=#__codelineno-20-1></a><span class=gp>$ </span>sudo<span class=w> </span>tailscale<span class=w> </span>exit-node<span class=w> </span>suggest
</span></code></pre></div> <p>or automatically select one by using <code>auto:any</code> as exit node identifier:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-21-1><a id=__codelineno-21-1 name=__codelineno-21-1 href=#__codelineno-21-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=o>=</span>auto:any
</span></code></pre></div> <p>Please see the <a href=https://tailscale.com/docs/features/exit-nodes/auto-exit-nodes>official Tailscale documentation</a> for more information on automatic exit node selection.</p> <h2 id=high-availability>High availability<a class=headerlink href=#high-availability title="Permanent link">&para;</a></h2> <p>Headscale supports high availability routing. Multiple subnet routers with overlapping routes or multiple exit nodes can be used to provide high availability for users. If one router node goes offline, another one can serve the same routes to clients. Please see the official <a href=https://tailscale.com/docs/how-to/set-up-high-availability#subnet-router-high-availability>Tailscale documentation on high availability</a> for details.</p> <p>This feature is enabled by default when at least two nodes advertise the same prefix. See the configuration options <code>node.routes.ha</code> in the <a href=../configuration/ >configuration file</a> for details.</p> <h2 id=troubleshooting>Troubleshooting<a class=headerlink href=#troubleshooting title="Permanent link">&para;</a></h2> <h3 id=enable-ip-forwarding>Enable IP forwarding<a class=headerlink href=#enable-ip-forwarding title="Permanent link">&para;</a></h3> <p>A subnet router or exit node is routing traffic on behalf of other nodes and thus requires IP forwarding. Check the official <a href=https://tailscale.com/docs/features/subnet-routers#enable-ip-forwarding>Tailscale documentation</a> for how to enable IP forwarding.</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=../oidc/ class="md-footer__link md-footer__link--prev" aria-label="Previous: OpenID Connect"> <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> OpenID Connect </div> </div> </a> <a href=../tls/ class="md-footer__link md-footer__link--next" aria-label="Next: TLS"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> TLS </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 &copy; 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.Line truncated
</span></code></pre></div> <p>Please see the <a href=https://tailscale.com/docs/features/exit-nodes/auto-exit-nodes>official Tailscale documentation</a> for more information on automatic exit node selection.</p> <h2 id=high-availability>High availability<a class=headerlink href=#high-availability title="Permanent link">&para;</a></h2> <p>Headscale supports high availability routing. Multiple subnet routers with overlapping routes or multiple exit nodes can be used to provide high availability for users. If one router node goes offline, another one can serve the same routes to clients. Please see the official <a href=https://tailscale.com/docs/how-to/set-up-high-availability#subnet-router-high-availability>Tailscale documentation on high availability</a> for details.</p> <p>This feature is enabled by default when at least two nodes advertise the same prefix. See the configuration options <code>node.routes.ha</code> in the <a href=../configuration/ >configuration file</a> for details.</p> <h2 id=troubleshooting>Troubleshooting<a class=headerlink href=#troubleshooting title="Permanent link">&para;</a></h2> <h3 id=enable-ip-forwarding>Enable IP forwarding<a class=headerlink href=#enable-ip-forwarding title="Permanent link">&para;</a></h3> <p>A subnet router or exit node is routing traffic on behalf of other nodes and thus requires IP forwarding. Check the official <a href=https://tailscale.com/docs/features/subnet-routers#enable-ip-forwarding>Tailscale documentation</a> for how to enable IP forwarding.</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=../oidc/ class="md-footer__link md-footer__link--prev" aria-label="Previous: OpenID Connect"> <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> OpenID Connect </div> </div> </a> <a href=../tls/ class="md-footer__link md-footer__link--next" aria-label="Next: TLS"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> TLS </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 &copy; 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.Line truncated
+2 -2
View File
@@ -1,5 +1,5 @@
<!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/tags/ rel=canonical><link href=../api/ rel=prev><link href=../debug/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.0"><title>Tags - 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="Tags - 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/tags.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/tags/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Tags - 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/tags.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=#tags 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> Tags </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-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/ref/tags/ rel=canonical><link href=../api/ rel=prev><link href=../debug/ rel=next><link rel=icon href=../../assets/favicon.png><meta name=generator content="mkdocs-ProperDocs 1.6.7, mkdocs-materialx-10.2.1"><title>Tags - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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="Tags - 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/tags.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/tags/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Tags - 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/tags.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=#tags 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> Tags </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-Line truncated
</span></code></pre></div> <h3 id=convert-from-personal-to-tagged-node>Convert from personal to tagged node<a class=headerlink href=#convert-from-personal-to-tagged-node title="Permanent link">&para;</a></h3> <p>Use the <code>headscale nodes tag</code> command to convert a personal (user-owned) node to a tagged node:</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>headscale nodes tag -i &lt;NODE_ID&gt; -t &lt;TAG&gt;</span>
</span></code></pre></div> <p>The node is now owned by the special user <code>tagged-devices</code> and has the specified tags assigned to it.</p> <h3 id=convert-from-tagged-to-personal-node>Convert from tagged to personal node<a class=headerlink href=#convert-from-tagged-to-personal-node title="Permanent link">&para;</a></h3> <p>Tagged nodes can return to personal (user-owned) nodes by re-authenticating with:</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>tailscale up --login-server &lt;YOUR_HEADSCALE_URL&gt; --advertise-tags= --force-reauth</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-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=go>headscale auth register --user &lt;USER&gt; --auth-id &lt;AUTH_ID&gt;</span>
</span></code></pre></div> <p>All previously assigned tags get removed and the node is now owned by the user specified in the above command.</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=../api/ class="md-footer__link md-footer__link--prev" aria-label="Previous: API"> <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> API </div> </div> </a> <a href=../debug/ class="md-footer__link md-footer__link--next" aria-label="Next: Debug"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Debug </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h6Line truncated
</span></code></pre></div> <p>All previously assigned tags get removed and the node is now owned by the user specified in the above command.</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=../api/ class="md-footer__link md-footer__link--prev" aria-label="Previous: API"> <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> API </div> </div> </a> <a href=../debug/ class="md-footer__link md-footer__link--next" aria-label="Next: Debug"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Debug </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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h6Line truncated
+11 -10
View File
@@ -1,13 +1,14 @@
<!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">&para;</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">&para;</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">&para;</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> <div class="admonition warning"> <p class=admonition-title><code>listen_addr</code> cannot also be port 80</p> <p><code>listen_addr</code> and <code>tls_letsencrypt_listen</code> must not bind the same TCP socket. A common mistake is setting <code>listen_addr: 0.0.0.0:80</code> together with <code>tls_letsencrypt_hostname</code> — both endpoints try to claim port 80, and the second bind fails with <code>address already in use</code> even though no other process is involved. Headscale validates this at startup and refuses to launch with a <code>Fatal config error: listen_addr and tls_letsencrypt_listen would bind the same TCP socket</code> message. Use <code>listen_addr: 0.0.0.0:443</code> (or any non-80 port) when HTTP-01 is enabled.</p> </div> <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">&para;</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">&para;</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">&para;</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
<!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.1"><title>TLS - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.f07c159f.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=w> </span><span class=nt>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=w> </span><span class=nt>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">&para;</a></h2> <p>To get a certificate automatically via <a href=https://letsencrypt.org/ >Let's Encrypt</a>, set <code>tls.acme.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.acme.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</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>acme</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>hostname</span><span class=p>:</span><span class=w> </span><span class=s>""</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>http_listen</span><span class=p>:</span><span class=w> </span><span class=s>":http"</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>cache_dir</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/var/lib/headscale/cache</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=nt>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">&para;</a></h3> <p>Headscale supports three values for <code>tls.acme.challenge_type</code>: <code>HTTP-01</code> (default), <code>TLS-ALPN-01</code> and <code>DNS-01</code>. <code>DNS-01</code> publishes the challenge through the DNS provider in <code>dns.challenge.provider</code>.</p> <h4 id=http-01>HTTP-01<a class=headerlink href=#http-01 title="Permanent link">&para;</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> <div class="admonition warning"> <p class=admonition-title><code>listen_addr</code> cannot also be port 80</p> <p><code>listen_addr</code> and <code>tls.acme.http_listen</code> must not bind the same TCP socket. A common mistake is setting <code>listen_addr: 0.0.0.0:80</code> together with <code>tls.acme.hostname</code> — both endpoints try to claim port 80, and the second bind fails with <code>address already in use</code> even though no other process is involved. Headscale validates this at startup and refuses to launch with a <code>Fatal config error: listen_addr and tls.acme.http_listen would bind the same TCP socket</code> message. Use <code>listen_addr: 0.0.0.0:443</code> (or any non-80 port) when HTTP-01 is enabled.</p> </div> <p>If you need to change the ip and/or port used by headscale for the Let's Encrypt validation process, set <code>tls.acme.http_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.acme.http_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.acme.http_listen</code>.</p> <h4 id=tls-alpn-01>TLS-ALPN-01<a class=headerlink href=#tls-alpn-01 title="Permanent link">&para;</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">&para;</a></h3> <p>Headscale uses <a href=https://github.com/caddyserver/certmagic>CertMagic</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 start when a third of the validity remains.</li> <li>Renewal checks run every 10 minutes.</li> <li>Log lines from the library are logged with <code>logger=acme</code>.</li> </ul> <h4 id=checking-certificate-expiry>Checking certificate expiry<a class=headerlink href=#checking-certificate-expiry title="Permanent link">&para;</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">&para;</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>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 &copy; 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
</span></code></pre></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=../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 &copy; 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 - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M349.9 236.3h-66.1v-59.4h66.1zm0-204.3h-66.1v60.7h66.1zm78.2 144.8H362v59.4h66.1zm-156.3-72.1h-66.1v60.1h66.1zm78.1 0h-66.1v60.1h66.1zm276.8 100c-14.4-9.7-47Line truncated