Deployed 4cad0b56 to development with ProperDocs 1.6.7 and mike 2.2.0

development/ref/tls/index.html

@@ -4,7 +4,7 @@
 </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> <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
+</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
 </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>