Deployed 545ace56 to development with ProperDocs 1.6.7 and mike 2.2.0

development/ref/registration/index.html

@@ -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.2"><title>Registration methods - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.1d60cbd7.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.2"><title>Registration methods - Headscale</title><link rel=stylesheet href=../../assets/stylesheets/main.1d60cbd7.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>
@@ -9,7 +9,7 @@
 </span><span id=__span-3-6><a id=__codelineno-3-6 name=__codelineno-3-6 href=#__codelineno-3-6></a><span class=p>}</span>
 </span></code></pre></div> <p>Run <code>tailscale up</code> and provide at least one tag to login a tagged device:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-4-1><a id=__codelineno-4-1 name=__codelineno-4-1 href=#__codelineno-4-1></a><span class=go>tailscale up --login-server &lt;YOUR_HEADSCALE_URL&gt; --advertise-tags tag:&lt;TAG&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-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a><span class=go>headscale auth register --user &lt;USER&gt; --auth-id &lt;AUTH_ID&gt;</span>
-</span></code></pre></div> <p>Headscale checks that <code>&lt;USER&gt;</code> is allowed to register a node with the specified tag(s) and then transfers ownership of the new node to the special user <code>tagged-devices</code>. 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> <h3 id=pre-authenticated-key>Pre authenticated key<a class=headerlink href=#pre-authenticated-key title="Permanent link">&para;</a></h3> <p>Registration with a pre authenticated key (or auth key) is a non-interactive way to register a new node. The Headscale administrator creates a preauthkey upfront and this preauthkey can then be used to register a node non-interactively. Its best suited for automation.</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>Personal devices</label><label for=__tabbed_2_2>Tagged devices</label></div> <div class=tabbed-content> <div class=tabbed-block> <p>A personal node is always assigned to a Headscale user. Use the <code>headscale users</code> command to create a new user<sup id=fnref2:1><a class=footnote-ref href=#fn:1>1</a></sup>:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=go>headscale users create &lt;USER&gt;</span>
+</span></code></pre></div> <p>Headscale checks that <code>&lt;USER&gt;</code> is allowed to register a node with the specified tag(s) and then transfers ownership of the new node to the special user <code>tagged-devices</code>. 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> <h3 id=pending-authentication-limits>Pending authentication limits<a class=headerlink href=#pending-authentication-limits title="Permanent link">&para;</a></h3> <p>Headscale keeps admitted authentication requests until they complete or expire. When registration capacity is reached, new requests receive HTTP 503 with <code>Retry-After</code> instead of invalidating someone else's pending approval. Existing approvals and pre-authenticated key registration remain available. SSH checks have 64 reserved entries beyond the registration allocation, including in the OIDC state cache.</p> <p>The default registration allocation is 1024 entries. The advanced <code>tuning.register_cache_max_entries</code> setting changes that allocation. Pending registration retains only hostname, OS and requested tags from Hostinfo; other metadata arrives with the node's first MapRequest. The full cached registration must fit within 64 KiB when serialized; larger payloads are rejected without truncating authentication metadata. Noise registrations return HTTP 200 with <code>RegisterResponse.Error</code> so the Tailscale client displays the permanent size error. The admin API reports this size error as HTTP 413. At the default allocation, retained registration payloads use at most 64 MiB plus record overhead. This is a cache-storage bound, not a bound on total server memory or concurrent request processing.</p> <p>OIDC login URLs must reference an existing pending authentication of the matching type. OIDC callback state is single-use, including when the identity provider exchange fails; restart the browser login flow after such an error. Capacity limits protect admitted requests but cannot guarantee admission during sustained overload.</p> <h3 id=pre-authenticated-key>Pre authenticated key<a class=headerlink href=#pre-authenticated-key title="Permanent link">&para;</a></h3> <p>Registration with a pre authenticated key (or auth key) is a non-interactive way to register a new node. The Headscale administrator creates a preauthkey upfront and this preauthkey can then be used to register a node non-interactively. Its best suited for automation.</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>Personal devices</label><label for=__tabbed_2_2>Tagged devices</label></div> <div class=tabbed-content> <div class=tabbed-block> <p>A personal node is always assigned to a Headscale user. Use the <code>headscale users</code> command to create a new user<sup id=fnref2:1><a class=footnote-ref href=#fn:1>1</a></sup>:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=go>headscale users create &lt;USER&gt;</span>
 </span></code></pre></div> <p>Create a new pre authenticated key for your user, by name or by the <code>&lt;USER_ID&gt;</code> that <code>headscale user list</code> shows:</p> <div class="language-console highlight"><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a><span class=go>headscale preauthkeys create --user &lt;USER&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:</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>