public/headscale
1
0 Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-11-05 04:59:26 +09:00
Code Issues Packages Projects Releases Wiki Activity

Deployed 14af9b3a to development with MkDocs 1.6.1 and mike 2.1.3

Browse Source
This commit is contained in:
github-actions committed 2025-11-24 05:38:08 +00:00
1 parent 8f662ecbf0
commit 1e06b18fbb
5 files changed
+48 -47
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

development/search/search_index.json
+1 -1
View File
@@ -1 +1 @@
{"config":{"lang":["en"],"separator":"[\\s\\-,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to headscale","text":"<p>Headscale is an open source, self-hosted implementation of the Tailscale control server.</p> <p>This page contains the documentation for the latest version of headscale. Please also check our FAQ.</p> <p>Join our Discord server for a chat and community support.</p>"},{"location":"#design-goal","title":"Design goal","text":"<p>Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailscale network (tailnet), suitable for a personal use, or a small open-source organisation.</p>"},{"location":"#supporting-headscale","title":"Supporting headscale","text":"<p>Please see Sponsor for more information.</p>"},{"location":"#contributing","title":"Contributing","text":"<p>Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the Maintainers before being submitted.</p> <p>Please see Contributing for more information.</p>"},{"location":"#about","title":"About","text":"<p>Headscale is maintained by Kristoffer Dalby and Juan Font.</p>"},{"location":"about/clients/","title":"Client and operating system support","text":"<p>We aim to support the last 10 releases of the Tailscale client on all provided operating systems and platforms. Some platforms might require additional configuration to connect with headscale.</p> OS Supports headscale Linux Yes OpenBSD Yes FreeBSD Yes Windows Yes (see docs and <code>/windows</code> on your headscale for more information) Android Yes (see docs for more information) macOS Yes (see docs and <code>/apple</code> on your headscale for more information) iOS Yes (see docs and <code>/apple</code> on your headscale for more information) tvOS Yes (see docs and <code>/apple</code> on your headscale for more information)"},{"location":"about/contributing/","title":"Contributing","text":"<p>Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the maintainers before being added to the project. This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code.</p>"},{"location":"about/contributing/#why-do-we-have-this-model","title":"Why do we have this model?","text":"<p>Headscale has a small maintainer team that tries to balance working on the project, fixing bugs and reviewing contributions.</p> <p>When we work on issues ourselves, we develop first hand knowledge of the code and it makes it possible for us to maintain and own the code as the project develops.</p> <p>Code contributions are seen as a positive thing. People enjoy and engage with our project, but it also comes with some challenges; we have to understand the code, we have to understand the feature, we might have to become familiar with external libraries or services and we think about security implications. All those steps are required during the reviewing process. After the code has been merged, the feature has to be maintained. Any changes reliant on external services must be updated and expanded accordingly.</p> <p>The review and day-1 maintenance adds a significant burden on the maintainers. Often we hope that the contributor will help out, but we found that most of the time, they disappear after their new feature was added.</p> <p>This means that when someone contributes, we are mostly happy about it, but we do have to run it through a series of checks to establish if we actually can maintain this feature.</p>"},{"location":"about/contributing/#what-do-we-require","title":"What do we require?","text":"<p>A general description is provided here and an explicit list is provided in our pull request template.</p> <p>All new features have to start out with a design document, which should be discussed on the issue tracker (not discord). It should include a use case for the feature, how it can be implemented, who will implement it and a plan for maintaining it.</p> <p>All features have to be end-to-end tested (integration tests) and have good unit test coverage to ensure that they work as expected. This will also ensure that the feature continues to work as expected over time. If a change cannot be tested, a strong case for why this is not possible needs to be presented.</p> <p>The contributor should help to maintain the feature over time. In case the feature is not maintained probably, the maintainers reserve themselves the right to remove features they redeem as unmaintainable. This should help to improve the quality of the software and keep it iLine truncated
{"config":{"lang":["en"],"separator":"[\\s\\-,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to headscale","text":"<p>Headscale is an open source, self-hosted implementation of the Tailscale control server.</p> <p>This page contains the documentation for the latest version of headscale. Please also check our FAQ.</p> <p>Join our Discord server for a chat and community support.</p>"},{"location":"#design-goal","title":"Design goal","text":"<p>Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailscale network (tailnet), suitable for a personal use, or a small open-source organisation.</p>"},{"location":"#supporting-headscale","title":"Supporting headscale","text":"<p>Please see Sponsor for more information.</p>"},{"location":"#contributing","title":"Contributing","text":"<p>Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the Maintainers before being submitted.</p> <p>Please see Contributing for more information.</p>"},{"location":"#about","title":"About","text":"<p>Headscale is maintained by Kristoffer Dalby and Juan Font.</p>"},{"location":"about/clients/","title":"Client and operating system support","text":"<p>We aim to support the last 10 releases of the Tailscale client on all provided operating systems and platforms. Some platforms might require additional configuration to connect with headscale.</p> OS Supports headscale Linux Yes OpenBSD Yes FreeBSD Yes Windows Yes (see docs and <code>/windows</code> on your headscale for more information) Android Yes (see docs for more information) macOS Yes (see docs and <code>/apple</code> on your headscale for more information) iOS Yes (see docs and <code>/apple</code> on your headscale for more information) tvOS Yes (see docs and <code>/apple</code> on your headscale for more information)"},{"location":"about/contributing/","title":"Contributing","text":"<p>Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the maintainers before being added to the project. This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code.</p>"},{"location":"about/contributing/#why-do-we-have-this-model","title":"Why do we have this model?","text":"<p>Headscale has a small maintainer team that tries to balance working on the project, fixing bugs and reviewing contributions.</p> <p>When we work on issues ourselves, we develop first hand knowledge of the code and it makes it possible for us to maintain and own the code as the project develops.</p> <p>Code contributions are seen as a positive thing. People enjoy and engage with our project, but it also comes with some challenges; we have to understand the code, we have to understand the feature, we might have to become familiar with external libraries or services and we think about security implications. All those steps are required during the reviewing process. After the code has been merged, the feature has to be maintained. Any changes reliant on external services must be updated and expanded accordingly.</p> <p>The review and day-1 maintenance adds a significant burden on the maintainers. Often we hope that the contributor will help out, but we found that most of the time, they disappear after their new feature was added.</p> <p>This means that when someone contributes, we are mostly happy about it, but we do have to run it through a series of checks to establish if we actually can maintain this feature.</p>"},{"location":"about/contributing/#what-do-we-require","title":"What do we require?","text":"<p>A general description is provided here and an explicit list is provided in our pull request template.</p> <p>All new features have to start out with a design document, which should be discussed on the issue tracker (not discord). It should include a use case for the feature, how it can be implemented, who will implement it and a plan for maintaining it.</p> <p>All features have to be end-to-end tested (integration tests) and have good unit test coverage to ensure that they work as expected. This will also ensure that the feature continues to work as expected over time. If a change cannot be tested, a strong case for why this is not possible needs to be presented.</p> <p>The contributor should help to maintain the feature over time. In case the feature is not maintained probably, the maintainers reserve themselves the right to remove features they redeem as unmaintainable. This should help to improve the quality of the software and keep it iLine truncated
development/sitemap.xml
+30 -30
View File
@@ -2,122 +2,122 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>https://juanfont.github.io/headscale/development/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/about/clients/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/about/contributing/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/about/faq/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/about/features/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/about/help/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/about/releases/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/about/sponsor/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/acls/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/api/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/configuration/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/debug/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/derp/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/dns/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/oidc/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/routes/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/tls/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/integration/reverse-proxy/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/integration/tools/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/ref/integration/web-ui/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/setup/requirements/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/setup/upgrade/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/setup/install/community/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/setup/install/container/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/setup/install/official/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/setup/install/source/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/usage/getting-started/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/usage/connect/android/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/usage/connect/apple/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
<url>
<loc>https://juanfont.github.io/headscale/development/usage/connect/windows/</loc>
<lastmod>2025-11-18</lastmod>
<lastmod>2025-11-24</lastmod>
</url>
</urlset>
development/sitemap.xml.gz
BIN
View File
Binary file not shown.
development/usage/getting-started/index.html
+15 -14
View File
@@ -10,18 +10,19 @@
</span><span id=__span-1-5><a id=__codelineno-1-5 name=__codelineno-1-5 href=#__codelineno-1-5></a><span class=c1># Show help for a specific command</span>
</span><span id=__span-1-6><a id=__codelineno-1-6 name=__codelineno-1-6 href=#__codelineno-1-6></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</span>
</span><span id=__span-1-7><a id=__codelineno-1-7 name=__codelineno-1-7 href=#__codelineno-1-7></a><span class=w> </span>headscale<span class=w> </span>&lt;COMMAND&gt;<span class=w> </span>--help
</span></code></pre></div> </div> </div> </div> <h2 id=manage-headscale-users>Manage headscale users<a class=headerlink href=#manage-headscale-users title="Permanent link">&para;</a></h2> <p>In headscale, a node (also known as machine or device) is always assigned to a headscale user. Such a headscale user may have many nodes assigned to them and can be managed with the <code>headscale users</code> command. Invoke the built-in help for more information: <code>headscale users --help</code>.</p> <h3 id=create-a-headscale-user>Create a headscale user<a class=headerlink href=#create-a-headscale-user title="Permanent link">&para;</a></h3> <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>Native</label><label for=__tabbed_2_2>Container</label></div> <div class=tabbed-content> <div class=tabbed-block> <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>users<span class=w> </span>create<span class=w> </span>&lt;USER&gt;
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</span>
</span><span id=__span-3-2><a id=__codelineno-3-2 name=__codelineno-3-2 href=#__codelineno-3-2></a><span class=w> </span>headscale<span class=w> </span>users<span class=w> </span>create<span class=w> </span>&lt;USER&gt;
</span></code></pre></div> </div> </div> </div> <h3 id=list-existing-headscale-users>List existing headscale users<a class=headerlink href=#list-existing-headscale-users title="Permanent link">&para;</a></h3> <div class="tabbed-set tabbed-alternate" data-tabs=3:2><input checked=checked id=__tabbed_3_1 name=__tabbed_3 type=radio><input id=__tabbed_3_2 name=__tabbed_3 type=radio><div class=tabbed-labels><label for=__tabbed_3_1>Native</label><label for=__tabbed_3_2>Container</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a>headscale<span class=w> </span>users<span class=w> </span>list
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</span>
</span><span id=__span-5-2><a id=__codelineno-5-2 name=__codelineno-5-2 href=#__codelineno-5-2></a><span class=w> </span>headscale<span class=w> </span>users<span class=w> </span>list
</span></code></pre></div> </div> </div> </div> <h2 id=register-a-node>Register a node<a class=headerlink href=#register-a-node title="Permanent link">&para;</a></h2> <p>One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect <a href=../connect/android/ >Android</a>, <a href=../connect/apple/ >Apple</a> or <a href=../connect/windows/ >Windows</a> devices.</p> <h3 id=normal-interactive-login>Normal, interactive login<a class=headerlink href=#normal-interactive-login title="Permanent link">&para;</a></h3> <p>On a client machine, run the <code>tailscale up</code> command and provide the FQDN of your headscale instance as argument:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a>tailscale<span class=w> </span>up<span class=w> </span>--login-server<span class=w> </span>&lt;YOUR_HEADSCALE_URL&gt;
</span></code></pre></div> <p>Usually, a browser window with further instructions is opened and contains the value for <code>&lt;YOUR_MACHINE_KEY&gt;</code>. Approve and register the node on your headscale server:</p> <div class="tabbed-set tabbed-alternate" data-tabs=4:2><input checked=checked id=__tabbed_4_1 name=__tabbed_4 type=radio><input id=__tabbed_4_2 name=__tabbed_4 type=radio><div class=tabbed-labels><label for=__tabbed_4_1>Native</label><label for=__tabbed_4_2>Container</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a>headscale<span class=w> </span>nodes<span class=w> </span>register<span class=w> </span>--user<span class=w> </span>&lt;USER&gt;<span class=w> </span>--key<span class=w> </span>&lt;YOUR_MACHINE_KEY&gt;
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-8-1><a id=__codelineno-8-1 name=__codelineno-8-1 href=#__codelineno-8-1></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</span>
</span><span id=__span-8-2><a id=__codelineno-8-2 name=__codelineno-8-2 href=#__codelineno-8-2></a><span class=w> </span>headscale<span class=w> </span>nodes<span class=w> </span>register<span class=w> </span>--user<span class=w> </span>&lt;USER&gt;<span class=w> </span>--key<span class=w> </span>&lt;YOUR_MACHINE_KEY&gt;
</span></code></pre></div> </div> </div> </div> <h3 id=using-a-preauthkey>Using a preauthkey<a class=headerlink href=#using-a-preauthkey title="Permanent link">&para;</a></h3> <p>It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the headscale instance. By default, the key is valid for one hour and can only be used once (see <code>headscale preauthkeys --help</code> for other options):</p> <div class="tabbed-set tabbed-alternate" data-tabs=5:2><input checked=checked id=__tabbed_5_1 name=__tabbed_5 type=radio><input id=__tabbed_5_2 name=__tabbed_5 type=radio><div class=tabbed-labels><label for=__tabbed_5_1>Native</label><label for=__tabbed_5_2>Container</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-9-1><a id=__codelineno-9-1 name=__codelineno-9-1 href=#__codelineno-9-1></a>headscale<span class=w> </span>preauthkeys<span class=w> </span>create<span class=w> </span>--user<span class=w> </span>&lt;USER_ID&gt;
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-10-1><a id=__codelineno-10-1 name=__codelineno-10-1 href=#__codelineno-10-1></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</span>
</span><span id=__span-10-2><a id=__codelineno-10-2 name=__codelineno-10-2 href=#__codelineno-10-2></a><span class=w> </span>headscale<span class=w> </span>preauthkeys<span class=w> </span>create<span class=w> </span>--user<span class=w> </span>&lt;USER_ID&gt;
</span></code></pre></div> </div> </div> </div> <p>The command returns the preauthkey on success which is used to connect a node to the headscale instance via the <code>tailscale up</code> command:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-11-1><a id=__codelineno-11-1 name=__codelineno-11-1 href=#__codelineno-11-1></a>tailscale<span class=w> </span>up<span class=w> </span>--login-server<span class=w> </span>&lt;YOUR_HEADSCALE_URL&gt;<span class=w> </span>--authkey<span class=w> </span>&lt;YOUR_AUTH_KEY&gt;
</span></code></pre></div> </div> </div> </div> <div class="admonition note"> <p class=admonition-title>Manage headscale from another local user</p> <p>By default only the user <code>headscale</code> or <code>root</code> will have the necessary permissions to access the unix socket (<code>/var/run/headscale/headscale.sock</code>) that is used to communicate with the service. In order to be able to communicate with the headscale service you have to make sure the unix socket is accessible by the user that runs the commands. In general you can achieve this by any of the following methods:</p> <ul> <li>using <code>sudo</code></li> <li>run the commands as user <code>headscale</code></li> <li>add your user to the <code>headscale</code> group</li> </ul> <p>To verify you can run the following command using your preferred method:</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>users<span class=w> </span>list
</span></code></pre></div> </div> <h2 id=manage-headscale-users>Manage headscale users<a class=headerlink href=#manage-headscale-users title="Permanent link">&para;</a></h2> <p>In headscale, a node (also known as machine or device) is always assigned to a headscale user. Such a headscale user may have many nodes assigned to them and can be managed with the <code>headscale users</code> command. Invoke the built-in help for more information: <code>headscale users --help</code>.</p> <h3 id=create-a-headscale-user>Create a headscale user<a class=headerlink href=#create-a-headscale-user title="Permanent link">&para;</a></h3> <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>Native</label><label for=__tabbed_2_2>Container</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a>headscale<span class=w> </span>users<span class=w> </span>create<span class=w> </span>&lt;USER&gt;
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</span>
</span><span id=__span-4-2><a id=__codelineno-4-2 name=__codelineno-4-2 href=#__codelineno-4-2></a><span class=w> </span>headscale<span class=w> </span>users<span class=w> </span>create<span class=w> </span>&lt;USER&gt;
</span></code></pre></div> </div> </div> </div> <h3 id=list-existing-headscale-users>List existing headscale users<a class=headerlink href=#list-existing-headscale-users title="Permanent link">&para;</a></h3> <div class="tabbed-set tabbed-alternate" data-tabs=3:2><input checked=checked id=__tabbed_3_1 name=__tabbed_3 type=radio><input id=__tabbed_3_2 name=__tabbed_3 type=radio><div class=tabbed-labels><label for=__tabbed_3_1>Native</label><label for=__tabbed_3_2>Container</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a>headscale<span class=w> </span>users<span class=w> </span>list
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</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>headscale<span class=w> </span>users<span class=w> </span>list
</span></code></pre></div> </div> </div> </div> <h2 id=register-a-node>Register a node<a class=headerlink href=#register-a-node title="Permanent link">&para;</a></h2> <p>One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect <a href=../connect/android/ >Android</a>, <a href=../connect/apple/ >Apple</a> or <a href=../connect/windows/ >Windows</a> devices.</p> <h3 id=normal-interactive-login>Normal, interactive login<a class=headerlink href=#normal-interactive-login title="Permanent link">&para;</a></h3> <p>On a client machine, run the <code>tailscale up</code> command and provide the FQDN of your headscale instance as argument:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a>tailscale<span class=w> </span>up<span class=w> </span>--login-server<span class=w> </span>&lt;YOUR_HEADSCALE_URL&gt;
</span></code></pre></div> <p>Usually, a browser window with further instructions is opened and contains the value for <code>&lt;YOUR_MACHINE_KEY&gt;</code>. Approve and register the node on your headscale server:</p> <div class="tabbed-set tabbed-alternate" data-tabs=4:2><input checked=checked id=__tabbed_4_1 name=__tabbed_4 type=radio><input id=__tabbed_4_2 name=__tabbed_4 type=radio><div class=tabbed-labels><label for=__tabbed_4_1>Native</label><label for=__tabbed_4_2>Container</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-8-1><a id=__codelineno-8-1 name=__codelineno-8-1 href=#__codelineno-8-1></a>headscale<span class=w> </span>nodes<span class=w> </span>register<span class=w> </span>--user<span class=w> </span>&lt;USER&gt;<span class=w> </span>--key<span class=w> </span>&lt;YOUR_MACHINE_KEY&gt;
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-9-1><a id=__codelineno-9-1 name=__codelineno-9-1 href=#__codelineno-9-1></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</span>
</span><span id=__span-9-2><a id=__codelineno-9-2 name=__codelineno-9-2 href=#__codelineno-9-2></a><span class=w> </span>headscale<span class=w> </span>nodes<span class=w> </span>register<span class=w> </span>--user<span class=w> </span>&lt;USER&gt;<span class=w> </span>--key<span class=w> </span>&lt;YOUR_MACHINE_KEY&gt;
</span></code></pre></div> </div> </div> </div> <h3 id=using-a-preauthkey>Using a preauthkey<a class=headerlink href=#using-a-preauthkey title="Permanent link">&para;</a></h3> <p>It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the headscale instance. By default, the key is valid for one hour and can only be used once (see <code>headscale preauthkeys --help</code> for other options):</p> <div class="tabbed-set tabbed-alternate" data-tabs=5:2><input checked=checked id=__tabbed_5_1 name=__tabbed_5 type=radio><input id=__tabbed_5_2 name=__tabbed_5 type=radio><div class=tabbed-labels><label for=__tabbed_5_1>Native</label><label for=__tabbed_5_2>Container</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-10-1><a id=__codelineno-10-1 name=__codelineno-10-1 href=#__codelineno-10-1></a>headscale<span class=w> </span>preauthkeys<span class=w> </span>create<span class=w> </span>--user<span class=w> </span>&lt;USER_ID&gt;
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-11-1><a id=__codelineno-11-1 name=__codelineno-11-1 href=#__codelineno-11-1></a>docker<span class=w> </span><span class=nb>exec</span><span class=w> </span>-it<span class=w> </span>headscale<span class=w> </span><span class=se>\</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>headscale<span class=w> </span>preauthkeys<span class=w> </span>create<span class=w> </span>--user<span class=w> </span>&lt;USER_ID&gt;
</span></code></pre></div> </div> </div> </div> <p>The command returns the preauthkey on success which is used to connect a node to the headscale instance via the <code>tailscale up</code> command:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-12-1><a id=__codelineno-12-1 name=__codelineno-12-1 href=#__codelineno-12-1></a>tailscale<span class=w> </span>up<span class=w> </span>--login-server<span class=w> </span>&lt;YOUR_HEADSCALE_URL&gt;<span class=w> </span>--authkey<span class=w> </span>&lt;YOUR_AUTH_KEY&gt;
</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> <button type=button class="md-top md-icon" data-md-component=top hidden> <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> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../../setup/upgrade/ class="md-footer__link md-footer__link--prev" aria-label="Previous: Upgrade"> <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> Upgrade </div> </div> </a> <a href=../connect/android/ class="md-footer__link md-footer__link--next" aria-label="Next: Android"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Android </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; 2025 Headscale authors </div> Made with <a href=https://squidfunk.github.io/mkdocs-material/ target=_blank rel=noopener> Material for MkDocs </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-47.6-13.2-73.1-8.4-3.3-24-16.7-44.9-41.1-63.7l-14-9.3-9.3 14c-18.4 27.8-23.4 73.6-3.7 103.8-8.7 4.7-25.8 11.1-48.4 10.7H2.4c-8.7 50.8 5.8 116.8 44 162.1 37.1 43.9 92.7 66.2 165.4 66.2 157.4 0 273.9-72.5 328.4-204.2 21.4.4 67.6.1 91.3-45.2 1.5-2.5 6.6-13.2 8.5-17.1zm-511.1-27.9h-66v59.4h66.1v-59.4zm78.1 0h-66.1v59.4h66.1zm78.1 0h-66.1v59.4h66.1zm-78.1-72.1h-66.1v60.1h66.1z"/></svg> </a> <a href=https://discord.gg/c84AZQhmpx target=_blank rel=noopener title=discord.gg class=md-social__link> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 576 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) CopyrigLine truncated