mirror of
https://github.com/juanfont/headscale.git
synced 2026-11-20 04:14:32 +09:00
728 lines
398 KiB
HTML
728 lines
398 KiB
HTML
<!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-options/ rel=canonical><link href=../configuration/ 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.2"><title>Configuration options - 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="Configuration options - 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-options.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-options/ property=og:url><meta property=twitter:card content=summary_large_image><meta property=twitter:title content="Configuration options - 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-options.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-options 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 options </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=slate data-md-color-primary=indigo data-md-color-accent=indigo aria-label="Switch to system preference" type=radio name=__palette id=__palette_2> <label class="md-header__button md-icon" title="Switch to system preference" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 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> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10.25 2a8.25 8.25 0 0 1 6.34 13.53l5.69 5.69a.749.749 0 0 1-.326 1.275.75.75 0 0 1-.734-.215l-5.69-5.69A8.25 8.25 0 1 1 10.25 2M3.5 10.25a6.75 6.75 0 1 0 13.5 0 6.75 6.75 0 0 0-13.5 0"/></svg> </label> <div class=md-search data-md-component=search role=dialog> <label class=md-search__overlay for=__search></label> <div class=md-search__inner role=search> <form class=md-search__form name=search> <input type=text class=md-search__input name=query aria-label=Search placeholder=Search autocapitalize=off autocorrect=off autocomplete=off spellcheck=false data-md-component=search-query required> <label class="md-search__icon md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10.25 2a8.25 8.25 0 0 1 6.34 13.53l5.69 5.69a.749.749 0 0 1-.326 1.275.75.75 0 0 1-.734-.215l-5.69-5.69A8.25 8.25 0 1 1 10.25 2M3.5 10.25a6.75 6.75 0 1 0 13.5 0 6.75 6.75 0 0 0-13.5 0"/></svg> <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> </label> <nav class=md-search__options aria-label=Search> <a href=javascript:void(0) class="md-search__icon md-icon" title=Share aria-label=Share data-clipboard data-clipboard-text data-md-component=search-share tabindex=-1> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 5.5a3.498 3.498 0 0 1-6.062 2.385l-5.112 3.021a3.5 3.5 0 0 1 0 2.188l5.112 3.021a3.5 3.5 0 1 1-.764 1.29l-5.112-3.02a3.499 3.499 0 1 1-3.843-5.642 3.5 3.5 0 0 1 3.843.872l5.112-3.021A3.5 3.5 0 1 1 20 5.5m-1.5 13a2 2 0 1 0-3.999-.001 2 2 0 0 0 3.999.001m0-13a2 2 0 1 0-3.999-.001A2 2 0 0 0 18.5 5.5M5.5 14a2 2 0 1 0 .001-3.999A2 2 0 0 0 5.5 14"/></svg> </a> <button type=reset class="md-search__icon md-icon" title=Clear aria-label=Clear tabindex=-1> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg> </button> </nav> <div class=md-search__suggest data-md-component=search-suggest></div> </form> <div class=md-search__output> <div class=md-search__scrollwrap tabindex=0> <div class="md-search-result md-search-result--lunr" data-md-component=search-result> <div class=md-search-result__meta> Initializing search </div> <ol class=md-search-result__list role=presentation></ol> </div> </div> </div> </div> </div> <div class=md-header__source> <a href=https://github.com/juanfont/headscale title="Go to repository" class=md-source data-md-component=source> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 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="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg> </div> <div class=md-source__repository> juanfont/headscale </div> </a> </div> </nav> </header> <div class=md-container data-md-component=container> <nav class=md-tabs aria-label=Tabs data-md-component=tabs> <div class=md-grid> <ul class=md-tabs__list> <li class=md-tabs__item> <a href=../.. class=md-tabs__link> Welcome </a> </li> <li class=md-tabs__item> <a href=../../about/faq/ class=md-tabs__link> About </a> </li> <li class=md-tabs__item> <a href=../../setup/requirements/ class=md-tabs__link> Setup </a> </li> <li class=md-tabs__item> <a href=../../usage/getting-started/ class=md-tabs__link> Usage </a> </li> <li class="md-tabs__item md-tabs__item--active"> <a href=../configuration/ class=md-tabs__link> Reference </a> </li> </ul> </div> </nav> <main class=md-main data-md-component=main> <div class="md-main__inner md-grid"> <div class="md-sidebar md-sidebar--primary" data-md-component=sidebar data-md-type=navigation> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--primary md-nav--lifted" aria-label=Navigation data-md-level=0> <label class=md-nav__title for=__drawer> <a href=../.. title=Headscale class="md-nav__button md-logo" aria-label=Headscale data-md-component=logo> <img src=../../assets/logo/headscale3-dots.svg alt=logo> </a> Headscale </label> <div class=md-nav__source> <a href=https://github.com/juanfont/headscale title="Go to repository" class=md-source data-md-component=source> <div class="md-source__icon md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 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="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg> </div> <div class=md-source__repository> juanfont/headscale </div> </a> </div> <ul class=md-nav__list> <li class=md-nav__item> <a href=../.. class=md-nav__link> <span class=md-ellipsis> Welcome </span> </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_2> <label class=md-nav__link for=__nav_2 id=__nav_2_label tabindex=0> <span class=md-ellipsis> About </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_2_label aria-expanded=false> <label class=md-nav__title for=__nav_2> <span class="md-nav__icon md-icon"></span> About </label> <ul class=md-nav__list> <li class=md-nav__item> <a href=../../about/faq/ class=md-nav__link> <span class=md-ellipsis> FAQ </span> </a> </li> <li class=md-nav__item> <a href=../../about/features/ class=md-nav__link> <span class=md-ellipsis> Features </span> </a> </li> <li class=md-nav__item> <a href=../../about/clients/ class=md-nav__link> <span class=md-ellipsis> Clients </span> </a> </li> <li class=md-nav__item> <a href=../../about/help/ class=md-nav__link> <span class=md-ellipsis> Getting help </span> </a> </li> <li class=md-nav__item> <a href=../../about/releases/ class=md-nav__link> <span class=md-ellipsis> Releases </span> </a> </li> <li class=md-nav__item> <a href=../../about/contributing/ class=md-nav__link> <span class=md-ellipsis> Contributing </span> </a> </li> <li class=md-nav__item> <a href=../../about/sponsor/ class=md-nav__link> <span class=md-ellipsis> Sponsor </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_3> <label class=md-nav__link for=__nav_3 id=__nav_3_label tabindex=0> <span class=md-ellipsis> Setup </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_3_label aria-expanded=false> <label class=md-nav__title for=__nav_3> <span class="md-nav__icon md-icon"></span> Setup </label> <ul class=md-nav__list> <li class=md-nav__item> <a href=../../setup/requirements/ class=md-nav__link> <span class=md-ellipsis> Requirements and Assumptions </span> </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_3_2> <label class=md-nav__link for=__nav_3_2 id=__nav_3_2_label tabindex=0> <span class=md-ellipsis> Installation </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_3_2_label aria-expanded=false> <label class=md-nav__title for=__nav_3_2> <span class="md-nav__icon md-icon"></span> Installation </label> <ul class=md-nav__list> <li class=md-nav__item> <a href=../../setup/install/official/ class=md-nav__link> <span class=md-ellipsis> Official releases </span> </a> </li> <li class=md-nav__item> <a href=../../setup/install/community/ class=md-nav__link> <span class=md-ellipsis> Community packages </span> </a> </li> <li class=md-nav__item> <a href=../../setup/install/container/ class=md-nav__link> <span class=md-ellipsis> Container </span> </a> </li> <li class=md-nav__item> <a href=../../setup/install/source/ class=md-nav__link> <span class=md-ellipsis> Build from source </span> </a> </li> <li class=md-nav__item> <a href=../../setup/install/main/ class=md-nav__link> <span class=md-ellipsis> Development builds </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../../setup/upgrade/ class=md-nav__link> <span class=md-ellipsis> Upgrade </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_4> <label class=md-nav__link for=__nav_4 id=__nav_4_label tabindex=0> <span class=md-ellipsis> Usage </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_4_label aria-expanded=false> <label class=md-nav__title for=__nav_4> <span class="md-nav__icon md-icon"></span> Usage </label> <ul class=md-nav__list> <li class=md-nav__item> <a href=../../usage/getting-started/ class=md-nav__link> <span class=md-ellipsis> Getting started </span> </a> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_4_2> <label class=md-nav__link for=__nav_4_2 id=__nav_4_2_label tabindex=0> <span class=md-ellipsis> Connect a node </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_4_2_label aria-expanded=false> <label class=md-nav__title for=__nav_4_2> <span class="md-nav__icon md-icon"></span> Connect a node </label> <ul class=md-nav__list> <li class=md-nav__item> <a href=../../usage/connect/android/ class=md-nav__link> <span class=md-ellipsis> Android </span> </a> </li> <li class=md-nav__item> <a href=../../usage/connect/apple/ class=md-nav__link> <span class=md-ellipsis> Apple </span> </a> </li> <li class=md-nav__item> <a href=../../usage/connect/windows/ class=md-nav__link> <span class=md-ellipsis> Windows </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_5 checked> <label class=md-nav__link for=__nav_5 id=__nav_5_label tabindex> <span class=md-ellipsis> Reference </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=1 aria-labelledby=__nav_5_label aria-expanded=true> <label class=md-nav__title for=__nav_5> <span class="md-nav__icon md-icon"></span> Reference </label> <ul class=md-nav__list> <li class=md-nav__item> <a href=../configuration/ class=md-nav__link> <span class=md-ellipsis> Configuration </span> </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type=checkbox id=__toc> <label class="md-nav__link md-nav__link--active" for=__toc> <span class=md-ellipsis> Configuration options </span> <span class="md-nav__icon md-icon"></span> </label> <a href=./ class="md-nav__link md-nav__link--active"> <span class=md-ellipsis> Configuration options </span> </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class=md-nav__title for=__toc> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class=md-nav__list data-md-component=toc> <li class=md-nav__item> <a href=#conventions class=md-nav__link> <span class=md-ellipsis> Conventions </span> </a> <nav class=md-nav aria-label=Conventions> <ul class=md-nav__list> <li class=md-nav__item> <a href=#types class=md-nav__link> <span class=md-ellipsis> Value types </span> </a> </li> <li class=md-nav__item> <a href=#env class=md-nav__link> <span class=md-ellipsis> Environment variables </span> </a> </li> <li class=md-nav__item> <a href=#secrets class=md-nav__link> <span class=md-ellipsis> Secrets </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#server_url class=md-nav__link> <span class=md-ellipsis> server_url </span> </a> </li> <li class=md-nav__item> <a href=#listen_addr class=md-nav__link> <span class=md-ellipsis> listen_addr </span> </a> </li> <li class=md-nav__item> <a href=#metrics_listen_addr class=md-nav__link> <span class=md-ellipsis> metrics_listen_addr </span> </a> </li> <li class=md-nav__item> <a href=#unix_socket class=md-nav__link> <span class=md-ellipsis> unix_socket </span> </a> </li> <li class=md-nav__item> <a href=#unix_socket_permission class=md-nav__link> <span class=md-ellipsis> unix_socket_permission </span> </a> </li> <li class=md-nav__item> <a href=#trusted_proxies class=md-nav__link> <span class=md-ellipsis> trusted_proxies </span> </a> </li> <li class=md-nav__item> <a href=#disable_check_updates class=md-nav__link> <span class=md-ellipsis> disable_check_updates </span> </a> </li> <li class=md-nav__item> <a href=#noise class=md-nav__link> <span class=md-ellipsis> noise </span> </a> <nav class=md-nav aria-label=noise> <ul class=md-nav__list> <li class=md-nav__item> <a href=#noise.private_key_path class=md-nav__link> <span class=md-ellipsis> private_key_path </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#prefixes class=md-nav__link> <span class=md-ellipsis> prefixes </span> </a> <nav class=md-nav aria-label=prefixes> <ul class=md-nav__list> <li class=md-nav__item> <a href=#prefixes.v4 class=md-nav__link> <span class=md-ellipsis> v4 </span> </a> </li> <li class=md-nav__item> <a href=#prefixes.v6 class=md-nav__link> <span class=md-ellipsis> v6 </span> </a> </li> <li class=md-nav__item> <a href=#prefixes.allocation class=md-nav__link> <span class=md-ellipsis> allocation </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#policy class=md-nav__link> <span class=md-ellipsis> policy </span> </a> <nav class=md-nav aria-label=policy> <ul class=md-nav__list> <li class=md-nav__item> <a href=#policy.path class=md-nav__link> <span class=md-ellipsis> path </span> </a> </li> <li class=md-nav__item> <a href=#policy.mode class=md-nav__link> <span class=md-ellipsis> mode </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#log class=md-nav__link> <span class=md-ellipsis> log </span> </a> <nav class=md-nav aria-label=log> <ul class=md-nav__list> <li class=md-nav__item> <a href=#log.level class=md-nav__link> <span class=md-ellipsis> level </span> </a> </li> <li class=md-nav__item> <a href=#log.format class=md-nav__link> <span class=md-ellipsis> format </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#node class=md-nav__link> <span class=md-ellipsis> node </span> </a> <nav class=md-nav aria-label=node> <ul class=md-nav__list> <li class=md-nav__item> <a href=#node.expiry class=md-nav__link> <span class=md-ellipsis> expiry </span> </a> </li> <li class=md-nav__item> <a href=#node.ephemeral class=md-nav__link> <span class=md-ellipsis> ephemeral </span> </a> <nav class=md-nav aria-label=ephemeral> <ul class=md-nav__list> <li class=md-nav__item> <a href=#node.ephemeral.inactivity_timeout class=md-nav__link> <span class=md-ellipsis> inactivity_timeout </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#node.routes class=md-nav__link> <span class=md-ellipsis> routes </span> </a> <nav class=md-nav aria-label=routes> <ul class=md-nav__list> <li class=md-nav__item> <a href=#node.routes.ha class=md-nav__link> <span class=md-ellipsis> ha </span> </a> <nav class=md-nav aria-label=ha> <ul class=md-nav__list> <li class=md-nav__item> <a href=#node.routes.ha.probe_interval class=md-nav__link> <span class=md-ellipsis> probe_interval </span> </a> </li> <li class=md-nav__item> <a href=#node.routes.ha.probe_timeout class=md-nav__link> <span class=md-ellipsis> probe_timeout </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#preauth_keys class=md-nav__link> <span class=md-ellipsis> preauth_keys </span> </a> <nav class=md-nav aria-label=preauth_keys> <ul class=md-nav__list> <li class=md-nav__item> <a href=#preauth_keys.revoked_retention class=md-nav__link> <span class=md-ellipsis> revoked_retention </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#derp class=md-nav__link> <span class=md-ellipsis> derp </span> </a> <nav class=md-nav aria-label=derp> <ul class=md-nav__list> <li class=md-nav__item> <a href=#derp.server class=md-nav__link> <span class=md-ellipsis> server </span> </a> <nav class=md-nav aria-label=server> <ul class=md-nav__list> <li class=md-nav__item> <a href=#derp.server.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.region_id class=md-nav__link> <span class=md-ellipsis> region_id </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.region_code class=md-nav__link> <span class=md-ellipsis> region_code </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.region_name class=md-nav__link> <span class=md-ellipsis> region_name </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.verify_clients class=md-nav__link> <span class=md-ellipsis> verify_clients </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.stun_listen_addr class=md-nav__link> <span class=md-ellipsis> stun_listen_addr </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.private_key_path class=md-nav__link> <span class=md-ellipsis> private_key_path </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.ipv4 class=md-nav__link> <span class=md-ellipsis> ipv4 </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.ipv6 class=md-nav__link> <span class=md-ellipsis> ipv6 </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.automatically_add_embedded_derp_region class=md-nav__link> <span class=md-ellipsis> automatically_add_embedded_derp_region </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#derp.urls class=md-nav__link> <span class=md-ellipsis> urls </span> </a> </li> <li class=md-nav__item> <a href=#derp.paths class=md-nav__link> <span class=md-ellipsis> paths </span> </a> </li> <li class=md-nav__item> <a href=#derp.auto_update_enabled class=md-nav__link> <span class=md-ellipsis> auto_update_enabled </span> </a> </li> <li class=md-nav__item> <a href=#derp.update_frequency class=md-nav__link> <span class=md-ellipsis> update_frequency </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#database class=md-nav__link> <span class=md-ellipsis> database </span> </a> <nav class=md-nav aria-label=database> <ul class=md-nav__list> <li class=md-nav__item> <a href=#database.type class=md-nav__link> <span class=md-ellipsis> type </span> </a> </li> <li class=md-nav__item> <a href=#database.debug class=md-nav__link> <span class=md-ellipsis> debug </span> </a> </li> <li class=md-nav__item> <a href=#database.gorm class=md-nav__link> <span class=md-ellipsis> gorm </span> </a> <nav class=md-nav aria-label=gorm> <ul class=md-nav__list> <li class=md-nav__item> <a href=#database.gorm.slow_threshold class=md-nav__link> <span class=md-ellipsis> slow_threshold </span> </a> </li> <li class=md-nav__item> <a href=#database.gorm.skip_err_record_not_found class=md-nav__link> <span class=md-ellipsis> skip_err_record_not_found </span> </a> </li> <li class=md-nav__item> <a href=#database.gorm.parameterized_queries class=md-nav__link> <span class=md-ellipsis> parameterized_queries </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#database.sqlite class=md-nav__link> <span class=md-ellipsis> sqlite </span> </a> <nav class=md-nav aria-label=sqlite> <ul class=md-nav__list> <li class=md-nav__item> <a href=#database.sqlite.path class=md-nav__link> <span class=md-ellipsis> path </span> </a> </li> <li class=md-nav__item> <a href=#database.sqlite.write_ahead_log class=md-nav__link> <span class=md-ellipsis> write_ahead_log </span> </a> </li> <li class=md-nav__item> <a href=#database.sqlite.wal_autocheckpoint class=md-nav__link> <span class=md-ellipsis> wal_autocheckpoint </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#database.postgres class=md-nav__link> <span class=md-ellipsis> postgres </span> </a> <nav class=md-nav aria-label=postgres> <ul class=md-nav__list> <li class=md-nav__item> <a href=#database.postgres.host class=md-nav__link> <span class=md-ellipsis> host </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.port class=md-nav__link> <span class=md-ellipsis> port </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.name class=md-nav__link> <span class=md-ellipsis> name </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.user class=md-nav__link> <span class=md-ellipsis> user </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.pass class=md-nav__link> <span class=md-ellipsis> pass </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.ssl class=md-nav__link> <span class=md-ellipsis> ssl </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.max_open_conns class=md-nav__link> <span class=md-ellipsis> max_open_conns </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.max_idle_conns class=md-nav__link> <span class=md-ellipsis> max_idle_conns </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.conn_max_idle_time_secs class=md-nav__link> <span class=md-ellipsis> conn_max_idle_time_secs </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#dns class=md-nav__link> <span class=md-ellipsis> dns </span> </a> <nav class=md-nav aria-label=dns> <ul class=md-nav__list> <li class=md-nav__item> <a href=#dns.magic_dns class=md-nav__link> <span class=md-ellipsis> magic_dns </span> </a> </li> <li class=md-nav__item> <a href=#dns.base_domain class=md-nav__link> <span class=md-ellipsis> base_domain </span> </a> </li> <li class=md-nav__item> <a href=#dns.override_local_dns class=md-nav__link> <span class=md-ellipsis> override_local_dns </span> </a> </li> <li class=md-nav__item> <a href=#dns.nameservers class=md-nav__link> <span class=md-ellipsis> nameservers </span> </a> <nav class=md-nav aria-label=nameservers> <ul class=md-nav__list> <li class=md-nav__item> <a href=#dns.nameservers.global class=md-nav__link> <span class=md-ellipsis> global </span> </a> </li> <li class=md-nav__item> <a href=#dns.nameservers.split class=md-nav__link> <span class=md-ellipsis> split </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#dns.search_domains class=md-nav__link> <span class=md-ellipsis> search_domains </span> </a> </li> <li class=md-nav__item> <a href=#dns.extra_records class=md-nav__link> <span class=md-ellipsis> extra_records </span> </a> </li> <li class=md-nav__item> <a href=#dns.extra_records_path class=md-nav__link> <span class=md-ellipsis> extra_records_path </span> </a> </li> <li class=md-nav__item> <a href=#dns.certificates class=md-nav__link> <span class=md-ellipsis> certificates </span> </a> <nav class=md-nav aria-label=certificates> <ul class=md-nav__list> <li class=md-nav__item> <a href=#dns.certificates.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> <li class=md-nav__item> <a href=#dns.certificates.zone class=md-nav__link> <span class=md-ellipsis> zone </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#dns.challenge class=md-nav__link> <span class=md-ellipsis> challenge </span> </a> <nav class=md-nav aria-label=challenge> <ul class=md-nav__list> <li class=md-nav__item> <a href=#dns.challenge.propagation_timeout class=md-nav__link> <span class=md-ellipsis> propagation_timeout </span> </a> </li> <li class=md-nav__item> <a href=#dns.challenge.resolvers class=md-nav__link> <span class=md-ellipsis> resolvers </span> </a> </li> <li class=md-nav__item> <a href=#dns.challenge.provider class=md-nav__link> <span class=md-ellipsis> provider </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#tls class=md-nav__link> <span class=md-ellipsis> tls </span> </a> <nav class=md-nav aria-label=tls> <ul class=md-nav__list> <li class=md-nav__item> <a href=#tls.cert_path class=md-nav__link> <span class=md-ellipsis> cert_path </span> </a> </li> <li class=md-nav__item> <a href=#tls.key_path class=md-nav__link> <span class=md-ellipsis> key_path </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme class=md-nav__link> <span class=md-ellipsis> acme </span> </a> <nav class=md-nav aria-label=acme> <ul class=md-nav__list> <li class=md-nav__item> <a href=#tls.acme.hostname class=md-nav__link> <span class=md-ellipsis> hostname </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.challenge_type class=md-nav__link> <span class=md-ellipsis> challenge_type </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.http_listen class=md-nav__link> <span class=md-ellipsis> http_listen </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.url class=md-nav__link> <span class=md-ellipsis> url </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.email class=md-nav__link> <span class=md-ellipsis> email </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.cache_dir class=md-nav__link> <span class=md-ellipsis> cache_dir </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#oidc class=md-nav__link> <span class=md-ellipsis> oidc </span> </a> <nav class=md-nav aria-label=oidc> <ul class=md-nav__list> <li class=md-nav__item> <a href=#oidc.only_start_if_oidc_is_available class=md-nav__link> <span class=md-ellipsis> only_start_if_oidc_is_available </span> </a> </li> <li class=md-nav__item> <a href=#oidc.issuer class=md-nav__link> <span class=md-ellipsis> issuer </span> </a> </li> <li class=md-nav__item> <a href=#oidc.client_id class=md-nav__link> <span class=md-ellipsis> client_id </span> </a> </li> <li class=md-nav__item> <a href=#oidc.client_secret class=md-nav__link> <span class=md-ellipsis> client_secret </span> </a> </li> <li class=md-nav__item> <a href=#oidc.scope class=md-nav__link> <span class=md-ellipsis> scope </span> </a> </li> <li class=md-nav__item> <a href=#oidc.extra_params class=md-nav__link> <span class=md-ellipsis> extra_params </span> </a> </li> <li class=md-nav__item> <a href=#oidc.allowed_domains class=md-nav__link> <span class=md-ellipsis> allowed_domains </span> </a> </li> <li class=md-nav__item> <a href=#oidc.allowed_users class=md-nav__link> <span class=md-ellipsis> allowed_users </span> </a> </li> <li class=md-nav__item> <a href=#oidc.allowed_groups class=md-nav__link> <span class=md-ellipsis> allowed_groups </span> </a> </li> <li class=md-nav__item> <a href=#oidc.email_verified_required class=md-nav__link> <span class=md-ellipsis> email_verified_required </span> </a> </li> <li class=md-nav__item> <a href=#oidc.use_expiry_from_token class=md-nav__link> <span class=md-ellipsis> use_expiry_from_token </span> </a> </li> <li class=md-nav__item> <a href=#oidc.pkce class=md-nav__link> <span class=md-ellipsis> pkce </span> </a> <nav class=md-nav aria-label=pkce> <ul class=md-nav__list> <li class=md-nav__item> <a href=#oidc.pkce.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> <li class=md-nav__item> <a href=#oidc.pkce.method class=md-nav__link> <span class=md-ellipsis> method </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#logtail class=md-nav__link> <span class=md-ellipsis> logtail </span> </a> <nav class=md-nav aria-label=logtail> <ul class=md-nav__list> <li class=md-nav__item> <a href=#logtail.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#taildrop class=md-nav__link> <span class=md-ellipsis> taildrop </span> </a> <nav class=md-nav aria-label=taildrop> <ul class=md-nav__list> <li class=md-nav__item> <a href=#taildrop.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#auto_update class=md-nav__link> <span class=md-ellipsis> auto_update </span> </a> <nav class=md-nav aria-label=auto_update> <ul class=md-nav__list> <li class=md-nav__item> <a href=#auto_update.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#cli class=md-nav__link> <span class=md-ellipsis> cli </span> </a> <nav class=md-nav aria-label=cli> <ul class=md-nav__list> <li class=md-nav__item> <a href=#cli.address class=md-nav__link> <span class=md-ellipsis> address </span> </a> </li> <li class=md-nav__item> <a href=#cli.api_key class=md-nav__link> <span class=md-ellipsis> api_key </span> </a> </li> <li class=md-nav__item> <a href=#cli.timeout class=md-nav__link> <span class=md-ellipsis> timeout </span> </a> </li> <li class=md-nav__item> <a href=#cli.insecure class=md-nav__link> <span class=md-ellipsis> insecure </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#tuning class=md-nav__link> <span class=md-ellipsis> tuning </span> </a> <nav class=md-nav aria-label=tuning> <ul class=md-nav__list> <li class=md-nav__item> <a href=#tuning.batch_change_delay class=md-nav__link> <span class=md-ellipsis> batch_change_delay </span> </a> </li> <li class=md-nav__item> <a href=#tuning.node_mapsession_buffered_chan_size class=md-nav__link> <span class=md-ellipsis> node_mapsession_buffered_chan_size </span> </a> </li> <li class=md-nav__item> <a href=#tuning.batcher_workers class=md-nav__link> <span class=md-ellipsis> batcher_workers </span> </a> </li> <li class=md-nav__item> <a href=#tuning.register_cache_expiration class=md-nav__link> <span class=md-ellipsis> register_cache_expiration </span> </a> </li> <li class=md-nav__item> <a href=#tuning.register_cache_max_entries class=md-nav__link> <span class=md-ellipsis> register_cache_max_entries </span> </a> </li> <li class=md-nav__item> <a href=#tuning.node_store_batch_size class=md-nav__link> <span class=md-ellipsis> node_store_batch_size </span> </a> </li> <li class=md-nav__item> <a href=#tuning.node_store_batch_timeout class=md-nav__link> <span class=md-ellipsis> node_store_batch_timeout </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#removed-keys class=md-nav__link> <span class=md-ellipsis> Removed keys </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=../registration/ class=md-nav__link> <span class=md-ellipsis> Registration methods </span> </a> </li> <li class=md-nav__item> <a href=../oidc/ class=md-nav__link> <span class=md-ellipsis> OpenID Connect </span> </a> </li> <li class=md-nav__item> <a href=../routes/ class=md-nav__link> <span class=md-ellipsis> Routes </span> </a> </li> <li class=md-nav__item> <a href=../tls/ class=md-nav__link> <span class=md-ellipsis> TLS </span> </a> </li> <li class=md-nav__item> <a href=../policy/ class=md-nav__link> <span class=md-ellipsis> Policy </span> </a> </li> <li class=md-nav__item> <a href=../dns/ class=md-nav__link> <span class=md-ellipsis> DNS </span> </a> </li> <li class=md-nav__item> <a href=../derp/ class=md-nav__link> <span class=md-ellipsis> DERP </span> </a> </li> <li class=md-nav__item> <a href=../api/ class=md-nav__link> <span class=md-ellipsis> API </span> </a> </li> <li class=md-nav__item> <a href=../tags/ class=md-nav__link> <span class=md-ellipsis> Tags </span> </a> </li> <li class=md-nav__item> <a href=../debug/ class=md-nav__link> <span class=md-ellipsis> Debug </span> </a> </li> <li class="md-nav__item md-nav__item--section md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type=checkbox id=__nav_5_13> <label class=md-nav__link for=__nav_5_13 id=__nav_5_13_label tabindex> <span class=md-ellipsis> Integration </span> <span class="md-nav__icon md-icon"></span> </label> <nav class=md-nav data-md-level=2 aria-labelledby=__nav_5_13_label aria-expanded=false> <label class=md-nav__title for=__nav_5_13> <span class="md-nav__icon md-icon"></span> Integration </label> <ul class=md-nav__list> <li class=md-nav__item> <a href=../integration/reverse-proxy/ class=md-nav__link> <span class=md-ellipsis> Reverse proxy </span> </a> </li> <li class=md-nav__item> <a href=../integration/web-ui/ class=md-nav__link> <span class=md-ellipsis> Web UI </span> </a> </li> <li class=md-nav__item> <a href=../integration/tools/ class=md-nav__link> <span class=md-ellipsis> Tools </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component=sidebar data-md-type=toc> <div class=md-sidebar__scrollwrap> <div class=md-sidebar__inner> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class=md-nav__title for=__toc> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class=md-nav__list data-md-component=toc> <li class=md-nav__item> <a href=#conventions class=md-nav__link> <span class=md-ellipsis> Conventions </span> </a> <nav class=md-nav aria-label=Conventions> <ul class=md-nav__list> <li class=md-nav__item> <a href=#types class=md-nav__link> <span class=md-ellipsis> Value types </span> </a> </li> <li class=md-nav__item> <a href=#env class=md-nav__link> <span class=md-ellipsis> Environment variables </span> </a> </li> <li class=md-nav__item> <a href=#secrets class=md-nav__link> <span class=md-ellipsis> Secrets </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#server_url class=md-nav__link> <span class=md-ellipsis> server_url </span> </a> </li> <li class=md-nav__item> <a href=#listen_addr class=md-nav__link> <span class=md-ellipsis> listen_addr </span> </a> </li> <li class=md-nav__item> <a href=#metrics_listen_addr class=md-nav__link> <span class=md-ellipsis> metrics_listen_addr </span> </a> </li> <li class=md-nav__item> <a href=#unix_socket class=md-nav__link> <span class=md-ellipsis> unix_socket </span> </a> </li> <li class=md-nav__item> <a href=#unix_socket_permission class=md-nav__link> <span class=md-ellipsis> unix_socket_permission </span> </a> </li> <li class=md-nav__item> <a href=#trusted_proxies class=md-nav__link> <span class=md-ellipsis> trusted_proxies </span> </a> </li> <li class=md-nav__item> <a href=#disable_check_updates class=md-nav__link> <span class=md-ellipsis> disable_check_updates </span> </a> </li> <li class=md-nav__item> <a href=#noise class=md-nav__link> <span class=md-ellipsis> noise </span> </a> <nav class=md-nav aria-label=noise> <ul class=md-nav__list> <li class=md-nav__item> <a href=#noise.private_key_path class=md-nav__link> <span class=md-ellipsis> private_key_path </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#prefixes class=md-nav__link> <span class=md-ellipsis> prefixes </span> </a> <nav class=md-nav aria-label=prefixes> <ul class=md-nav__list> <li class=md-nav__item> <a href=#prefixes.v4 class=md-nav__link> <span class=md-ellipsis> v4 </span> </a> </li> <li class=md-nav__item> <a href=#prefixes.v6 class=md-nav__link> <span class=md-ellipsis> v6 </span> </a> </li> <li class=md-nav__item> <a href=#prefixes.allocation class=md-nav__link> <span class=md-ellipsis> allocation </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#policy class=md-nav__link> <span class=md-ellipsis> policy </span> </a> <nav class=md-nav aria-label=policy> <ul class=md-nav__list> <li class=md-nav__item> <a href=#policy.path class=md-nav__link> <span class=md-ellipsis> path </span> </a> </li> <li class=md-nav__item> <a href=#policy.mode class=md-nav__link> <span class=md-ellipsis> mode </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#log class=md-nav__link> <span class=md-ellipsis> log </span> </a> <nav class=md-nav aria-label=log> <ul class=md-nav__list> <li class=md-nav__item> <a href=#log.level class=md-nav__link> <span class=md-ellipsis> level </span> </a> </li> <li class=md-nav__item> <a href=#log.format class=md-nav__link> <span class=md-ellipsis> format </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#node class=md-nav__link> <span class=md-ellipsis> node </span> </a> <nav class=md-nav aria-label=node> <ul class=md-nav__list> <li class=md-nav__item> <a href=#node.expiry class=md-nav__link> <span class=md-ellipsis> expiry </span> </a> </li> <li class=md-nav__item> <a href=#node.ephemeral class=md-nav__link> <span class=md-ellipsis> ephemeral </span> </a> <nav class=md-nav aria-label=ephemeral> <ul class=md-nav__list> <li class=md-nav__item> <a href=#node.ephemeral.inactivity_timeout class=md-nav__link> <span class=md-ellipsis> inactivity_timeout </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#node.routes class=md-nav__link> <span class=md-ellipsis> routes </span> </a> <nav class=md-nav aria-label=routes> <ul class=md-nav__list> <li class=md-nav__item> <a href=#node.routes.ha class=md-nav__link> <span class=md-ellipsis> ha </span> </a> <nav class=md-nav aria-label=ha> <ul class=md-nav__list> <li class=md-nav__item> <a href=#node.routes.ha.probe_interval class=md-nav__link> <span class=md-ellipsis> probe_interval </span> </a> </li> <li class=md-nav__item> <a href=#node.routes.ha.probe_timeout class=md-nav__link> <span class=md-ellipsis> probe_timeout </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#preauth_keys class=md-nav__link> <span class=md-ellipsis> preauth_keys </span> </a> <nav class=md-nav aria-label=preauth_keys> <ul class=md-nav__list> <li class=md-nav__item> <a href=#preauth_keys.revoked_retention class=md-nav__link> <span class=md-ellipsis> revoked_retention </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#derp class=md-nav__link> <span class=md-ellipsis> derp </span> </a> <nav class=md-nav aria-label=derp> <ul class=md-nav__list> <li class=md-nav__item> <a href=#derp.server class=md-nav__link> <span class=md-ellipsis> server </span> </a> <nav class=md-nav aria-label=server> <ul class=md-nav__list> <li class=md-nav__item> <a href=#derp.server.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.region_id class=md-nav__link> <span class=md-ellipsis> region_id </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.region_code class=md-nav__link> <span class=md-ellipsis> region_code </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.region_name class=md-nav__link> <span class=md-ellipsis> region_name </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.verify_clients class=md-nav__link> <span class=md-ellipsis> verify_clients </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.stun_listen_addr class=md-nav__link> <span class=md-ellipsis> stun_listen_addr </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.private_key_path class=md-nav__link> <span class=md-ellipsis> private_key_path </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.ipv4 class=md-nav__link> <span class=md-ellipsis> ipv4 </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.ipv6 class=md-nav__link> <span class=md-ellipsis> ipv6 </span> </a> </li> <li class=md-nav__item> <a href=#derp.server.automatically_add_embedded_derp_region class=md-nav__link> <span class=md-ellipsis> automatically_add_embedded_derp_region </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#derp.urls class=md-nav__link> <span class=md-ellipsis> urls </span> </a> </li> <li class=md-nav__item> <a href=#derp.paths class=md-nav__link> <span class=md-ellipsis> paths </span> </a> </li> <li class=md-nav__item> <a href=#derp.auto_update_enabled class=md-nav__link> <span class=md-ellipsis> auto_update_enabled </span> </a> </li> <li class=md-nav__item> <a href=#derp.update_frequency class=md-nav__link> <span class=md-ellipsis> update_frequency </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#database class=md-nav__link> <span class=md-ellipsis> database </span> </a> <nav class=md-nav aria-label=database> <ul class=md-nav__list> <li class=md-nav__item> <a href=#database.type class=md-nav__link> <span class=md-ellipsis> type </span> </a> </li> <li class=md-nav__item> <a href=#database.debug class=md-nav__link> <span class=md-ellipsis> debug </span> </a> </li> <li class=md-nav__item> <a href=#database.gorm class=md-nav__link> <span class=md-ellipsis> gorm </span> </a> <nav class=md-nav aria-label=gorm> <ul class=md-nav__list> <li class=md-nav__item> <a href=#database.gorm.slow_threshold class=md-nav__link> <span class=md-ellipsis> slow_threshold </span> </a> </li> <li class=md-nav__item> <a href=#database.gorm.skip_err_record_not_found class=md-nav__link> <span class=md-ellipsis> skip_err_record_not_found </span> </a> </li> <li class=md-nav__item> <a href=#database.gorm.parameterized_queries class=md-nav__link> <span class=md-ellipsis> parameterized_queries </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#database.sqlite class=md-nav__link> <span class=md-ellipsis> sqlite </span> </a> <nav class=md-nav aria-label=sqlite> <ul class=md-nav__list> <li class=md-nav__item> <a href=#database.sqlite.path class=md-nav__link> <span class=md-ellipsis> path </span> </a> </li> <li class=md-nav__item> <a href=#database.sqlite.write_ahead_log class=md-nav__link> <span class=md-ellipsis> write_ahead_log </span> </a> </li> <li class=md-nav__item> <a href=#database.sqlite.wal_autocheckpoint class=md-nav__link> <span class=md-ellipsis> wal_autocheckpoint </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#database.postgres class=md-nav__link> <span class=md-ellipsis> postgres </span> </a> <nav class=md-nav aria-label=postgres> <ul class=md-nav__list> <li class=md-nav__item> <a href=#database.postgres.host class=md-nav__link> <span class=md-ellipsis> host </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.port class=md-nav__link> <span class=md-ellipsis> port </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.name class=md-nav__link> <span class=md-ellipsis> name </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.user class=md-nav__link> <span class=md-ellipsis> user </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.pass class=md-nav__link> <span class=md-ellipsis> pass </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.ssl class=md-nav__link> <span class=md-ellipsis> ssl </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.max_open_conns class=md-nav__link> <span class=md-ellipsis> max_open_conns </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.max_idle_conns class=md-nav__link> <span class=md-ellipsis> max_idle_conns </span> </a> </li> <li class=md-nav__item> <a href=#database.postgres.conn_max_idle_time_secs class=md-nav__link> <span class=md-ellipsis> conn_max_idle_time_secs </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#dns class=md-nav__link> <span class=md-ellipsis> dns </span> </a> <nav class=md-nav aria-label=dns> <ul class=md-nav__list> <li class=md-nav__item> <a href=#dns.magic_dns class=md-nav__link> <span class=md-ellipsis> magic_dns </span> </a> </li> <li class=md-nav__item> <a href=#dns.base_domain class=md-nav__link> <span class=md-ellipsis> base_domain </span> </a> </li> <li class=md-nav__item> <a href=#dns.override_local_dns class=md-nav__link> <span class=md-ellipsis> override_local_dns </span> </a> </li> <li class=md-nav__item> <a href=#dns.nameservers class=md-nav__link> <span class=md-ellipsis> nameservers </span> </a> <nav class=md-nav aria-label=nameservers> <ul class=md-nav__list> <li class=md-nav__item> <a href=#dns.nameservers.global class=md-nav__link> <span class=md-ellipsis> global </span> </a> </li> <li class=md-nav__item> <a href=#dns.nameservers.split class=md-nav__link> <span class=md-ellipsis> split </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#dns.search_domains class=md-nav__link> <span class=md-ellipsis> search_domains </span> </a> </li> <li class=md-nav__item> <a href=#dns.extra_records class=md-nav__link> <span class=md-ellipsis> extra_records </span> </a> </li> <li class=md-nav__item> <a href=#dns.extra_records_path class=md-nav__link> <span class=md-ellipsis> extra_records_path </span> </a> </li> <li class=md-nav__item> <a href=#dns.certificates class=md-nav__link> <span class=md-ellipsis> certificates </span> </a> <nav class=md-nav aria-label=certificates> <ul class=md-nav__list> <li class=md-nav__item> <a href=#dns.certificates.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> <li class=md-nav__item> <a href=#dns.certificates.zone class=md-nav__link> <span class=md-ellipsis> zone </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#dns.challenge class=md-nav__link> <span class=md-ellipsis> challenge </span> </a> <nav class=md-nav aria-label=challenge> <ul class=md-nav__list> <li class=md-nav__item> <a href=#dns.challenge.propagation_timeout class=md-nav__link> <span class=md-ellipsis> propagation_timeout </span> </a> </li> <li class=md-nav__item> <a href=#dns.challenge.resolvers class=md-nav__link> <span class=md-ellipsis> resolvers </span> </a> </li> <li class=md-nav__item> <a href=#dns.challenge.provider class=md-nav__link> <span class=md-ellipsis> provider </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#tls class=md-nav__link> <span class=md-ellipsis> tls </span> </a> <nav class=md-nav aria-label=tls> <ul class=md-nav__list> <li class=md-nav__item> <a href=#tls.cert_path class=md-nav__link> <span class=md-ellipsis> cert_path </span> </a> </li> <li class=md-nav__item> <a href=#tls.key_path class=md-nav__link> <span class=md-ellipsis> key_path </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme class=md-nav__link> <span class=md-ellipsis> acme </span> </a> <nav class=md-nav aria-label=acme> <ul class=md-nav__list> <li class=md-nav__item> <a href=#tls.acme.hostname class=md-nav__link> <span class=md-ellipsis> hostname </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.challenge_type class=md-nav__link> <span class=md-ellipsis> challenge_type </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.http_listen class=md-nav__link> <span class=md-ellipsis> http_listen </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.url class=md-nav__link> <span class=md-ellipsis> url </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.email class=md-nav__link> <span class=md-ellipsis> email </span> </a> </li> <li class=md-nav__item> <a href=#tls.acme.cache_dir class=md-nav__link> <span class=md-ellipsis> cache_dir </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#oidc class=md-nav__link> <span class=md-ellipsis> oidc </span> </a> <nav class=md-nav aria-label=oidc> <ul class=md-nav__list> <li class=md-nav__item> <a href=#oidc.only_start_if_oidc_is_available class=md-nav__link> <span class=md-ellipsis> only_start_if_oidc_is_available </span> </a> </li> <li class=md-nav__item> <a href=#oidc.issuer class=md-nav__link> <span class=md-ellipsis> issuer </span> </a> </li> <li class=md-nav__item> <a href=#oidc.client_id class=md-nav__link> <span class=md-ellipsis> client_id </span> </a> </li> <li class=md-nav__item> <a href=#oidc.client_secret class=md-nav__link> <span class=md-ellipsis> client_secret </span> </a> </li> <li class=md-nav__item> <a href=#oidc.scope class=md-nav__link> <span class=md-ellipsis> scope </span> </a> </li> <li class=md-nav__item> <a href=#oidc.extra_params class=md-nav__link> <span class=md-ellipsis> extra_params </span> </a> </li> <li class=md-nav__item> <a href=#oidc.allowed_domains class=md-nav__link> <span class=md-ellipsis> allowed_domains </span> </a> </li> <li class=md-nav__item> <a href=#oidc.allowed_users class=md-nav__link> <span class=md-ellipsis> allowed_users </span> </a> </li> <li class=md-nav__item> <a href=#oidc.allowed_groups class=md-nav__link> <span class=md-ellipsis> allowed_groups </span> </a> </li> <li class=md-nav__item> <a href=#oidc.email_verified_required class=md-nav__link> <span class=md-ellipsis> email_verified_required </span> </a> </li> <li class=md-nav__item> <a href=#oidc.use_expiry_from_token class=md-nav__link> <span class=md-ellipsis> use_expiry_from_token </span> </a> </li> <li class=md-nav__item> <a href=#oidc.pkce class=md-nav__link> <span class=md-ellipsis> pkce </span> </a> <nav class=md-nav aria-label=pkce> <ul class=md-nav__list> <li class=md-nav__item> <a href=#oidc.pkce.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> <li class=md-nav__item> <a href=#oidc.pkce.method class=md-nav__link> <span class=md-ellipsis> method </span> </a> </li> </ul> </nav> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#logtail class=md-nav__link> <span class=md-ellipsis> logtail </span> </a> <nav class=md-nav aria-label=logtail> <ul class=md-nav__list> <li class=md-nav__item> <a href=#logtail.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#taildrop class=md-nav__link> <span class=md-ellipsis> taildrop </span> </a> <nav class=md-nav aria-label=taildrop> <ul class=md-nav__list> <li class=md-nav__item> <a href=#taildrop.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#auto_update class=md-nav__link> <span class=md-ellipsis> auto_update </span> </a> <nav class=md-nav aria-label=auto_update> <ul class=md-nav__list> <li class=md-nav__item> <a href=#auto_update.enabled class=md-nav__link> <span class=md-ellipsis> enabled </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#cli class=md-nav__link> <span class=md-ellipsis> cli </span> </a> <nav class=md-nav aria-label=cli> <ul class=md-nav__list> <li class=md-nav__item> <a href=#cli.address class=md-nav__link> <span class=md-ellipsis> address </span> </a> </li> <li class=md-nav__item> <a href=#cli.api_key class=md-nav__link> <span class=md-ellipsis> api_key </span> </a> </li> <li class=md-nav__item> <a href=#cli.timeout class=md-nav__link> <span class=md-ellipsis> timeout </span> </a> </li> <li class=md-nav__item> <a href=#cli.insecure class=md-nav__link> <span class=md-ellipsis> insecure </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#tuning class=md-nav__link> <span class=md-ellipsis> tuning </span> </a> <nav class=md-nav aria-label=tuning> <ul class=md-nav__list> <li class=md-nav__item> <a href=#tuning.batch_change_delay class=md-nav__link> <span class=md-ellipsis> batch_change_delay </span> </a> </li> <li class=md-nav__item> <a href=#tuning.node_mapsession_buffered_chan_size class=md-nav__link> <span class=md-ellipsis> node_mapsession_buffered_chan_size </span> </a> </li> <li class=md-nav__item> <a href=#tuning.batcher_workers class=md-nav__link> <span class=md-ellipsis> batcher_workers </span> </a> </li> <li class=md-nav__item> <a href=#tuning.register_cache_expiration class=md-nav__link> <span class=md-ellipsis> register_cache_expiration </span> </a> </li> <li class=md-nav__item> <a href=#tuning.register_cache_max_entries class=md-nav__link> <span class=md-ellipsis> register_cache_max_entries </span> </a> </li> <li class=md-nav__item> <a href=#tuning.node_store_batch_size class=md-nav__link> <span class=md-ellipsis> node_store_batch_size </span> </a> </li> <li class=md-nav__item> <a href=#tuning.node_store_batch_timeout class=md-nav__link> <span class=md-ellipsis> node_store_batch_timeout </span> </a> </li> </ul> </nav> </li> <li class=md-nav__item> <a href=#removed-keys class=md-nav__link> <span class=md-ellipsis> Removed keys </span> </a> </li> </ul> </nav> </div> </div> </div> <div class=md-content data-md-component=content> <article class="md-content__inner md-typeset"> <a href=https://github.com/juanfont/headscale/blob/main/docs/ref/configuration-options.md title="Edit this page" class="md-content__button md-icon" rel=edit> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg> </a> <a href=https://github.com/juanfont/headscale/raw/main/docs/ref/configuration-options.md title="View source of this page" class="md-content__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M17 18c.56 0 1 .44 1 1s-.44 1-1 1-1-.44-1-1 .44-1 1-1m0-3c-2.73 0-5.06 1.66-6 4 .94 2.34 3.27 4 6 4s5.06-1.66 6-4c-.94-2.34-3.27-4-6-4m0 6.5a2.5 2.5 0 0 1-2.5-2.5 2.5 2.5 0 0 1 2.5-2.5 2.5 2.5 0 0 1 2.5 2.5 2.5 2.5 0 0 1-2.5 2.5M9.27 20H6V4h7v5h5v4.07c.7.08 1.36.25 2 .49V8l-6-6H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h4.5a8.2 8.2 0 0 1-1.23-2"/></svg> </a> <h1 id=configuration-options>Configuration options<a class=headerlink href=#configuration-options title="Permanent link">¶</a></h1> <div class="admonition note"> <p class=admonition-title>Generated page</p> <p>This page is generated from the doc comments in <code>hscontrol/types/config.go</code> by <code>go generate ./hscontrol/types/</code>. Edit the comments there, not this page.</p> </div> <p>Every key headscale reads, in the order <code>headscale generate config</code> prints them, with its type, default, environment variable and an example for a configuration file, the environment and NixOS. Keys that no longer work are listed under <a href=#removed-keys>Removed keys</a>. <a href=../configuration/ >Configuration</a> explains where headscale finds its configuration, how to check it, and shows the full example.</p> <h2 id=conventions>Conventions<a class=headerlink href=#conventions title="Permanent link">¶</a></h2> <h3 id=types>Value types<a class=headerlink href=#types title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Type</th> <th>Format</th> <th>Example</th> </tr> </thead> <tbody> <tr> <td><span id=type-string></span>string</td> <td>Text. Quote it where YAML would read another type, as in <code>"0x1F"</code> or <code>"null"</code>.</td> <td><code>/var/lib/headscale/db.sqlite</code></td> </tr> <tr> <td><span id=type-boolean></span>boolean</td> <td><code>true</code> or <code>false</code>.</td> <td><code>true</code></td> </tr> <tr> <td><span id=type-integer></span>integer</td> <td>A whole number.</td> <td><code>1024</code></td> </tr> <tr> <td><span id=type-duration></span>duration</td> <td>A number with a unit, <code>ms</code>, <code>s</code>, <code>m</code>, <code>h</code>, <code>d</code>, <code>w</code> or <code>y</code>, units combined largest first; <code>0</code> needs none.</td> <td><code>1h30m</code></td> </tr> <tr> <td><span id=type-file-mode></span>file mode</td> <td>Octal permission bits, quoted.</td> <td><code>"0770"</code></td> </tr> <tr> <td><span id=type-listen-address></span>listen address</td> <td><code>host:port</code>. An empty host listens on every address; the port may be <code>http</code> or <code>https</code>.</td> <td><code>0.0.0.0:8080</code></td> </tr> <tr> <td><span id=type-URL></span>URL</td> <td>An absolute <code>http://</code> or <code>https://</code> URL with a host.</td> <td><code>https://headscale.example.com</code></td> </tr> <tr> <td><span id=type-prefix></span>prefix</td> <td>An IP range in CIDR notation.</td> <td><code>100.64.0.0/10</code></td> </tr> <tr> <td>secret</td> <td>Text, or <code>file:<path></code> to read it from a file.</td> <td><code>file:/run/secrets/oidc_client_secret</code></td> </tr> <tr> <td><span id=type-enum></span>enum</td> <td>One of the values listed with the key.</td> <td><code>sqlite</code></td> </tr> <tr> <td>DNS record</td> <td>An object with <code>name</code>, <code>type</code> and <code>value</code>.</td> <td><code>{name: grafana.example.com, type: A, value: 100.64.0.3}</code></td> </tr> <tr> <td>value</td> <td>Whatever the setting takes: text, a number, a boolean, a list or a map.</td> <td><code>file:/run/secrets/cloudflare</code></td> </tr> <tr> <td><span id=type-list></span>list</td> <td>A list. A variable holds it as a JSON array or, unless its values are objects, separated by spaces.</td> <td><code>[9.9.9.9, 2620:fe::fe]</code></td> </tr> <tr> <td><span id=type-map></span>map</td> <td>Keys you choose, each with a value. A variable holds a JSON object.</td> <td><code>{corp.example.com: [192.0.2.53]}</code></td> </tr> </tbody> </table> <h3 id=env>Environment variables<a class=headerlink href=#env title="Permanent link">¶</a></h3> <p>Every key can also be set with an environment variable: <code>HEADSCALE_</code> and the key's path in capitals, with <code>_</code> for <code>.</code>, e.g. <code>HEADSCALE_LOG_LEVEL</code> for <code>log.level</code>. Each key below names its variable. A variable wins over the configuration file, which wins over the default. An empty variable, like a key written with no value in the file, counts as unset and keeps the default. A variable set to <code>""</code> means what <code>""</code> means in the configuration file: it clears a key with a default, as <code>prefixes.v6: ""</code> does, and is an error where the file's <code>""</code> is one. A list also clears with <code>[]</code>. Quote the value so the quotes reach headscale:</p> <div class="language-shell highlight"><pre><span></span><code><span id=__span-0-1><a id=__codelineno-0-1 name=__codelineno-0-1 href=#__codelineno-0-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_PREFIXES_V6</span><span class=o>=</span><span class=s1>'""'</span>
|
|
</span><span id=__span-0-2><a id=__codelineno-0-2 name=__codelineno-0-2 href=#__codelineno-0-2></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_URLS</span><span class=o>=</span><span class=s1>'[]'</span>
|
|
</span></code></pre></div> <div class="language-yaml highlight"><span class=filename>docker-compose.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>environment</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>HEADSCALE_PREFIXES_V6</span><span class=p>:</span><span class=w> </span><span class=s>'""'</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>HEADSCALE_DERP_URLS</span><span class=p>:</span><span class=w> </span><span class=s>'[]'</span>
|
|
</span></code></pre></div> <p>An env file (a Compose <code>env_file</code>, a systemd <code>EnvironmentFile=</code>) and a systemd <code>Environment=</code> strip one level of quotes, so <code>KEY=""</code> there arrives empty and keeps the default: write <code>KEY='""'</code> in an env file and <code>Environment='KEY=""'</code> in a unit.</p> <p>A list is a JSON array or, unless its values are objects, its values separated by spaces. A map is a JSON object, which replaces the map in the configuration file instead of merging into it. The examples below write every list and map as JSON.</p> <p>A <code>HEADSCALE_</code> variable that names no key logs a warning, and one for a removed key also says what to do instead. Other software uses the same prefix, so neither stops headscale.</p> <p>A DNS provider setting that takes text can also be set on its own as <code>HEADSCALE_DNS_CHALLENGE_PROVIDER_<SETTING></code>, e.g. <code>HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN</code>; see <a href=#dns.challenge.provider><code>dns.challenge.provider</code></a>.</p> <h3 id=secrets>Secrets<a class=headerlink href=#secrets title="Permanent link">¶</a></h3> <p>A secret takes the value itself or <code>file:<path></code>, which reads it from that file. Environment variables in the path are expanded, as in <code>file:${CREDENTIALS_DIRECTORY}/oidc_client_secret</code>, and whitespace around the file's contents is trimmed; an empty file is an error. Headscale reads the file only where the secret is used, and <code>headscale check config</code> and <code>headscale check all</code> never read it. <code>headscale generate config --running</code> and <code>/debug/config</code> show a literal secret as <code><redacted></code> and a <code>file:</code> reference as written.</p> <p>The secrets are <a href=#database.postgres.pass><code>database.postgres.pass</code></a>, <a href=#oidc.client_secret><code>oidc.client_secret</code></a>, <a href=#cli.api_key><code>cli.api_key</code></a> and every string setting of <a href=#dns.challenge.provider><code>dns.challenge.provider</code></a>.</p> <p>On NixOS, keep a secret out of the Nix store: load it as a systemd credential and point the key at it.</p> <div class="language-nix highlight"><pre><span></span><code><span id=__span-2-1><a id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>client_secret</span> <span class=o>=</span> <span class=s2>"file:</span><span class=se>\$</span><span class=s2>{CREDENTIALS_DIRECTORY}/oidc_client_secret"</span><span class=p>;</span>
|
|
</span><span id=__span-2-2><a id=__codelineno-2-2 name=__codelineno-2-2 href=#__codelineno-2-2></a>systemd<span class=o>.</span>services<span class=o>.</span>headscale<span class=o>.</span>serviceConfig<span class=o>.</span><span class=ss>LoadCredential</span> <span class=o>=</span> <span class=p>[</span> <span class=s2>"oidc_client_secret:/run/secrets/oidc_client_secret"</span> <span class=p>];</span>
|
|
</span></code></pre></div> <h2 id=server_url><code>server_url</code><a class=headerlink href=#server_url title="Permanent link">¶</a></h2> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Required</strong></li> <li><strong>Env:</strong> <code>HEADSCALE_SERVER_URL</code></li> </ul> <p>The URL clients connect to, with its <code>http://</code> or <code>https://</code> scheme, e.g. <code>https://headscale.example.com:443</code>. A trailing slash is trimmed on load. Its host must not be <a href=#dns.base_domain><code>dns.base_domain</code></a> or a name below it.</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>YAML</label><label for=__tabbed_1_2>Environment</label><label for=__tabbed_1_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-3-1><a id=__codelineno-3-1 name=__codelineno-3-1 href=#__codelineno-3-1></a><span class=nt>server_url</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">https://headscale.example.com</span>
|
|
</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><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_SERVER_URL</span><span class=o>=</span>https://headscale.example.com
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-5-1><a id=__codelineno-5-1 name=__codelineno-5-1 href=#__codelineno-5-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span><span class=ss>server_url</span> <span class=o>=</span> <span class=s2>"https://headscale.example.com"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=listen_addr><code>listen_addr</code><a class=headerlink href=#listen_addr title="Permanent link">¶</a></h2> <ul> <li><strong>Type:</strong> <a href=#type-listen-address>listen address</a></li> <li><strong>Default:</strong> <code>0.0.0.0:8080</code></li> <li><strong>Env:</strong> <code>HEADSCALE_LISTEN_ADDR</code></li> </ul> <p>The host:port the server listens on for clients, the API and the web pages. It serves HTTPS when <a href=#tls.cert_path><code>tls.cert_path</code></a> or <a href=#tls.acme.hostname><code>tls.acme.hostname</code></a> is set, plain HTTP otherwise. The default listens on every address, IPv4 and IPv6 alike.</p> <div class="tabbed-set tabbed-alternate" data-tabs=2:3><input checked=checked id=__tabbed_2_1 name=__tabbed_2 type=radio><input id=__tabbed_2_2 name=__tabbed_2 type=radio><input id=__tabbed_2_3 name=__tabbed_2 type=radio><div class=tabbed-labels><label for=__tabbed_2_1>YAML</label><label for=__tabbed_2_2>Environment</label><label for=__tabbed_2_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-6-1><a id=__codelineno-6-1 name=__codelineno-6-1 href=#__codelineno-6-1></a><span class=nt>listen_addr</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">127.0.0.1:8080</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-7-1><a id=__codelineno-7-1 name=__codelineno-7-1 href=#__codelineno-7-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_LISTEN_ADDR</span><span class=o>=</span><span class=m>127</span>.0.0.1:8080
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-8-1><a id=__codelineno-8-1 name=__codelineno-8-1 href=#__codelineno-8-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span><span class=ss>listen_addr</span> <span class=o>=</span> <span class=s2>"127.0.0.1:8080"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=metrics_listen_addr><code>metrics_listen_addr</code><a class=headerlink href=#metrics_listen_addr title="Permanent link">¶</a></h2> <ul> <li><strong>Type:</strong> <a href=#type-listen-address>listen address</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_METRICS_LISTEN_ADDR</code></li> </ul> <p>The host:port serving <code>/metrics</code> and <code>/debug</code>; keep it private. Empty disables this listener.</p> <div class="tabbed-set tabbed-alternate" data-tabs=3:3><input checked=checked id=__tabbed_3_1 name=__tabbed_3 type=radio><input id=__tabbed_3_2 name=__tabbed_3 type=radio><input id=__tabbed_3_3 name=__tabbed_3 type=radio><div class=tabbed-labels><label for=__tabbed_3_1>YAML</label><label for=__tabbed_3_2>Environment</label><label for=__tabbed_3_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml 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=nt>metrics_listen_addr</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">127.0.0.1:9090</span>
|
|
</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><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_METRICS_LISTEN_ADDR</span><span class=o>=</span><span class=m>127</span>.0.0.1:9090
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-11-1><a id=__codelineno-11-1 name=__codelineno-11-1 href=#__codelineno-11-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span><span class=ss>metrics_listen_addr</span> <span class=o>=</span> <span class=s2>"127.0.0.1:9090"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=unix_socket><code>unix_socket</code><a class=headerlink href=#unix_socket title="Permanent link">¶</a></h2> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>/var/run/headscale/headscale.sock</code></li> <li><strong>Env:</strong> <code>HEADSCALE_UNIX_SOCKET</code></li> </ul> <p>Where the server serves the API without authentication, for the CLI on the same host. The CLI connects to it when <a href=#cli.address><code>cli.address</code></a> is empty.</p> <div class="tabbed-set tabbed-alternate" data-tabs=4:3><input checked=checked id=__tabbed_4_1 name=__tabbed_4 type=radio><input id=__tabbed_4_2 name=__tabbed_4 type=radio><input id=__tabbed_4_3 name=__tabbed_4 type=radio><div class=tabbed-labels><label for=__tabbed_4_1>YAML</label><label for=__tabbed_4_2>Environment</label><label for=__tabbed_4_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-12-1><a id=__codelineno-12-1 name=__codelineno-12-1 href=#__codelineno-12-1></a><span class=nt>unix_socket</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/run/headscale/headscale.sock</span>
|
|
</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_UNIX_SOCKET</span><span class=o>=</span>/run/headscale/headscale.sock
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-14-1><a id=__codelineno-14-1 name=__codelineno-14-1 href=#__codelineno-14-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span><span class=ss>unix_socket</span> <span class=o>=</span> <span class=s2>"/run/headscale/headscale.sock"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=unix_socket_permission><code>unix_socket_permission</code><a class=headerlink href=#unix_socket_permission title="Permanent link">¶</a></h2> <ul> <li><strong>Type:</strong> <a href=#type-file-mode>file mode</a></li> <li><strong>Default:</strong> <code>"0770"</code></li> <li><strong>Env:</strong> <code>HEADSCALE_UNIX_SOCKET_PERMISSION</code></li> </ul> <p>The file mode of <a href=#unix_socket><code>unix_socket</code></a>, in quoted octal (<code>"0770"</code>): unquoted, YAML reads <code>0770</code> as the number 504.</p> <div class="tabbed-set tabbed-alternate" data-tabs=5:3><input checked=checked id=__tabbed_5_1 name=__tabbed_5 type=radio><input id=__tabbed_5_2 name=__tabbed_5 type=radio><input id=__tabbed_5_3 name=__tabbed_5 type=radio><div class=tabbed-labels><label for=__tabbed_5_1>YAML</label><label for=__tabbed_5_2>Environment</label><label for=__tabbed_5_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-15-1><a id=__codelineno-15-1 name=__codelineno-15-1 href=#__codelineno-15-1></a><span class=nt>unix_socket_permission</span><span class=p>:</span><span class=w> </span><span class=s>"0660"</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-16-1><a id=__codelineno-16-1 name=__codelineno-16-1 href=#__codelineno-16-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_UNIX_SOCKET_PERMISSION</span><span class=o>=</span><span class=m>0660</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-17-1><a id=__codelineno-17-1 name=__codelineno-17-1 href=#__codelineno-17-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span><span class=ss>unix_socket_permission</span> <span class=o>=</span> <span class=s2>"0660"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=trusted_proxies><code>trusted_proxies</code><a class=headerlink href=#trusted_proxies title="Permanent link">¶</a></h2> <ul> <li><strong>Type:</strong> <a href=#type-list>list of prefixes</a></li> <li><strong>Default:</strong> <code>[]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TRUSTED_PROXIES</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>The CIDRs of reverse proxies whose <code>True-Client-IP</code>, <code>X-Real-IP</code> and <code>X-Forwarded-For</code> headers are honoured. Empty ignores those headers. Set without a proxy in front, clients can spoof their source IP in logs and the v2 API.</p> <div class="tabbed-set tabbed-alternate" data-tabs=6:3><input checked=checked id=__tabbed_6_1 name=__tabbed_6 type=radio><input id=__tabbed_6_2 name=__tabbed_6 type=radio><input id=__tabbed_6_3 name=__tabbed_6 type=radio><div class=tabbed-labels><label for=__tabbed_6_1>YAML</label><label for=__tabbed_6_2>Environment</label><label for=__tabbed_6_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-18-1><a id=__codelineno-18-1 name=__codelineno-18-1 href=#__codelineno-18-1></a><span class=nt>trusted_proxies</span><span class=p>:</span>
|
|
</span><span id=__span-18-2><a id=__codelineno-18-2 name=__codelineno-18-2 href=#__codelineno-18-2></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">192.0.2.10/32</span>
|
|
</span><span id=__span-18-3><a id=__codelineno-18-3 name=__codelineno-18-3 href=#__codelineno-18-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2001:db8::10/128</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-19-1><a id=__codelineno-19-1 name=__codelineno-19-1 href=#__codelineno-19-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TRUSTED_PROXIES</span><span class=o>=</span><span class=s1>'["192.0.2.10/32","2001:db8::10/128"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-20-1><a id=__codelineno-20-1 name=__codelineno-20-1 href=#__codelineno-20-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span><span class=ss>trusted_proxies</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-20-2><a id=__codelineno-20-2 name=__codelineno-20-2 href=#__codelineno-20-2></a> <span class=s2>"192.0.2.10/32"</span>
|
|
</span><span id=__span-20-3><a id=__codelineno-20-3 name=__codelineno-20-3 href=#__codelineno-20-3></a> <span class=s2>"2001:db8::10/128"</span>
|
|
</span><span id=__span-20-4><a id=__codelineno-20-4 name=__codelineno-20-4 href=#__codelineno-20-4></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=disable_check_updates><code>disable_check_updates</code><a class=headerlink href=#disable_check_updates title="Permanent link">¶</a></h2> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DISABLE_CHECK_UPDATES</code></li> </ul> <p>Skips the check for a newer headscale release that commands make at start.</p> <div class="tabbed-set tabbed-alternate" data-tabs=7:3><input checked=checked id=__tabbed_7_1 name=__tabbed_7 type=radio><input id=__tabbed_7_2 name=__tabbed_7 type=radio><input id=__tabbed_7_3 name=__tabbed_7 type=radio><div class=tabbed-labels><label for=__tabbed_7_1>YAML</label><label for=__tabbed_7_2>Environment</label><label for=__tabbed_7_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml 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=nt>disable_check_updates</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-22-1><a id=__codelineno-22-1 name=__codelineno-22-1 href=#__codelineno-22-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DISABLE_CHECK_UPDATES</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-23-1><a id=__codelineno-23-1 name=__codelineno-23-1 href=#__codelineno-23-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span><span class=ss>disable_check_updates</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=noise><code>noise</code><a class=headerlink href=#noise title="Permanent link">¶</a></h2> <p>The Noise protocol (TS2021) clients connect over.</p> <details class=example> <summary>All <code>noise</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-24-1><a id=__codelineno-24-1 name=__codelineno-24-1 href=#__codelineno-24-1></a><span class=nt>noise</span><span class=p>:</span>
|
|
</span><span id=__span-24-2><a id=__codelineno-24-2 name=__codelineno-24-2 href=#__codelineno-24-2></a><span class=w> </span><span class=nt>private_key_path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/var/lib/headscale/noise_private.key</span>
|
|
</span></code></pre></div> </details> <h3 id=noise.private_key_path><code>noise.private_key_path</code><a class=headerlink href=#noise.private_key_path title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>/var/lib/headscale/noise_private.key</code></li> <li><strong>Env:</strong> <code>HEADSCALE_NOISE_PRIVATE_KEY_PATH</code></li> </ul> <p>The file holding the Noise private key, which encrypts traffic between headscale and clients, relative to the configuration file. A missing file is created with a new key.</p> <div class="tabbed-set tabbed-alternate" data-tabs=8:3><input checked=checked id=__tabbed_8_1 name=__tabbed_8 type=radio><input id=__tabbed_8_2 name=__tabbed_8 type=radio><input id=__tabbed_8_3 name=__tabbed_8 type=radio><div class=tabbed-labels><label for=__tabbed_8_1>YAML</label><label for=__tabbed_8_2>Environment</label><label for=__tabbed_8_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-25-1><a id=__codelineno-25-1 name=__codelineno-25-1 href=#__codelineno-25-1></a><span class=nt>noise</span><span class=p>:</span>
|
|
</span><span id=__span-25-2><a id=__codelineno-25-2 name=__codelineno-25-2 href=#__codelineno-25-2></a><span class=w> </span><span class=nt>private_key_path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/opt/headscale/noise_private.key</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-26-1><a id=__codelineno-26-1 name=__codelineno-26-1 href=#__codelineno-26-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_NOISE_PRIVATE_KEY_PATH</span><span class=o>=</span>/opt/headscale/noise_private.key
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-27-1><a id=__codelineno-27-1 name=__codelineno-27-1 href=#__codelineno-27-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>noise<span class=o>.</span><span class=ss>private_key_path</span> <span class=o>=</span> <span class=s2>"/opt/headscale/noise_private.key"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>private_key_path</code> (<a href=#private_key_path>removed</a>). Replaces <code>noise_private_key_path</code> (<a href=#noise_private_key_path>removed</a>).</p> <h2 id=prefixes><code>prefixes</code><a class=headerlink href=#prefixes title="Permanent link">¶</a></h2> <p>The IP ranges node addresses are allocated from. Keep at least one of <a href=#prefixes.v4><code>prefixes.v4</code></a> and <a href=#prefixes.v6><code>prefixes.v6</code></a>. Use the Tailscale ranges, <code>100.64.0.0/10</code> and <code>fd7a:115c:a1e0::/48</code>, or ranges inside them: the client assumes them, and other ranges are unsupported.</p> <details class=example> <summary>All <code>prefixes</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-28-1><a id=__codelineno-28-1 name=__codelineno-28-1 href=#__codelineno-28-1></a><span class=nt>prefixes</span><span class=p>:</span>
|
|
</span><span id=__span-28-2><a id=__codelineno-28-2 name=__codelineno-28-2 href=#__codelineno-28-2></a><span class=w> </span><span class=nt>v4</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">100.64.0.0/10</span>
|
|
</span><span id=__span-28-3><a id=__codelineno-28-3 name=__codelineno-28-3 href=#__codelineno-28-3></a><span class=w> </span><span class=nt>v6</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">fd7a:115c:a1e0::/48</span>
|
|
</span><span id=__span-28-4><a id=__codelineno-28-4 name=__codelineno-28-4 href=#__codelineno-28-4></a><span class=w> </span><span class=nt>allocation</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">sequential</span>
|
|
</span></code></pre></div> </details> <h3 id=prefixes.v4><code>prefixes.v4</code><a class=headerlink href=#prefixes.v4 title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-prefix>prefix</a></li> <li><strong>Default:</strong> <code>100.64.0.0/10</code></li> <li><strong>Env:</strong> <code>HEADSCALE_PREFIXES_V4</code></li> </ul> <p>The IPv4 range, e.g. <code>100.64.0.0/10</code>. Empty gives nodes no IPv4 address.</p> <div class="tabbed-set tabbed-alternate" data-tabs=9:3><input checked=checked id=__tabbed_9_1 name=__tabbed_9 type=radio><input id=__tabbed_9_2 name=__tabbed_9 type=radio><input id=__tabbed_9_3 name=__tabbed_9 type=radio><div class=tabbed-labels><label for=__tabbed_9_1>YAML</label><label for=__tabbed_9_2>Environment</label><label for=__tabbed_9_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-29-1><a id=__codelineno-29-1 name=__codelineno-29-1 href=#__codelineno-29-1></a><span class=nt>prefixes</span><span class=p>:</span>
|
|
</span><span id=__span-29-2><a id=__codelineno-29-2 name=__codelineno-29-2 href=#__codelineno-29-2></a><span class=w> </span><span class=nt>v4</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">100.64.0.0/24</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-30-1><a id=__codelineno-30-1 name=__codelineno-30-1 href=#__codelineno-30-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_PREFIXES_V4</span><span class=o>=</span><span class=m>100</span>.64.0.0/24
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-31-1><a id=__codelineno-31-1 name=__codelineno-31-1 href=#__codelineno-31-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>prefixes<span class=o>.</span><span class=ss>v4</span> <span class=o>=</span> <span class=s2>"100.64.0.0/24"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>ip_prefixes</code> (<a href=#ip_prefixes>removed</a>).</p> <h3 id=prefixes.v6><code>prefixes.v6</code><a class=headerlink href=#prefixes.v6 title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-prefix>prefix</a></li> <li><strong>Default:</strong> <code>fd7a:115c:a1e0::/48</code></li> <li><strong>Env:</strong> <code>HEADSCALE_PREFIXES_V6</code></li> </ul> <p>The IPv6 range, e.g. <code>fd7a:115c:a1e0::/48</code>. Empty gives nodes no IPv6 address.</p> <div class="tabbed-set tabbed-alternate" data-tabs=10:3><input checked=checked id=__tabbed_10_1 name=__tabbed_10 type=radio><input id=__tabbed_10_2 name=__tabbed_10 type=radio><input id=__tabbed_10_3 name=__tabbed_10 type=radio><div class=tabbed-labels><label for=__tabbed_10_1>YAML</label><label for=__tabbed_10_2>Environment</label><label for=__tabbed_10_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-32-1><a id=__codelineno-32-1 name=__codelineno-32-1 href=#__codelineno-32-1></a><span class=nt>prefixes</span><span class=p>:</span>
|
|
</span><span id=__span-32-2><a id=__codelineno-32-2 name=__codelineno-32-2 href=#__codelineno-32-2></a><span class=w> </span><span class=nt>v6</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">fd7a:115c:a1e0::/64</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-33-1><a id=__codelineno-33-1 name=__codelineno-33-1 href=#__codelineno-33-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_PREFIXES_V6</span><span class=o>=</span>fd7a:115c:a1e0::/64
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-34-1><a id=__codelineno-34-1 name=__codelineno-34-1 href=#__codelineno-34-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>prefixes<span class=o>.</span><span class=ss>v6</span> <span class=o>=</span> <span class=s2>"fd7a:115c:a1e0::/64"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>ip_prefixes</code> (<a href=#ip_prefixes>removed</a>).</p> <h3 id=prefixes.allocation><code>prefixes.allocation</code><a class=headerlink href=#prefixes.allocation title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-enum>enum</a>: <code>sequential</code>, <code>random</code></li> <li><strong>Default:</strong> <code>sequential</code></li> <li><strong>Env:</strong> <code>HEADSCALE_PREFIXES_ALLOCATION</code></li> </ul> <p>How a new node's addresses are picked.</p> <table> <thead> <tr> <th>Value</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>sequential</code></td> <td>Takes the next free address after the last one handed out, and wraps around to reuse freed addresses.</td> </tr> <tr> <td><code>random</code></td> <td>Picks a free address at random.</td> </tr> </tbody> </table> <div class="tabbed-set tabbed-alternate" data-tabs=11:3><input checked=checked id=__tabbed_11_1 name=__tabbed_11 type=radio><input id=__tabbed_11_2 name=__tabbed_11 type=radio><input id=__tabbed_11_3 name=__tabbed_11 type=radio><div class=tabbed-labels><label for=__tabbed_11_1>YAML</label><label for=__tabbed_11_2>Environment</label><label for=__tabbed_11_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-35-1><a id=__codelineno-35-1 name=__codelineno-35-1 href=#__codelineno-35-1></a><span class=nt>prefixes</span><span class=p>:</span>
|
|
</span><span id=__span-35-2><a id=__codelineno-35-2 name=__codelineno-35-2 href=#__codelineno-35-2></a><span class=w> </span><span class=nt>allocation</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">random</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-36-1><a id=__codelineno-36-1 name=__codelineno-36-1 href=#__codelineno-36-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_PREFIXES_ALLOCATION</span><span class=o>=</span>random
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-37-1><a id=__codelineno-37-1 name=__codelineno-37-1 href=#__codelineno-37-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>prefixes<span class=o>.</span><span class=ss>allocation</span> <span class=o>=</span> <span class=s2>"random"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=policy><code>policy</code><a class=headerlink href=#policy title="Permanent link">¶</a></h2> <p>Where the access control policy is kept: in a file headscale reads, or in the database. See <a href=../policy/ >Policy</a>.</p> <details class=example> <summary>All <code>policy</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-38-1><a id=__codelineno-38-1 name=__codelineno-38-1 href=#__codelineno-38-1></a><span class=nt>policy</span><span class=p>:</span>
|
|
</span><span id=__span-38-2><a id=__codelineno-38-2 name=__codelineno-38-2 href=#__codelineno-38-2></a><span class=w> </span><span class=nt>path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-38-3><a id=__codelineno-38-3 name=__codelineno-38-3 href=#__codelineno-38-3></a><span class=w> </span><span class=nt>mode</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">file</span>
|
|
</span></code></pre></div> </details> <h3 id=policy.path><code>policy.path</code><a class=headerlink href=#policy.path title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_POLICY_PATH</code></li> </ul> <p>The HuJSON policy file read when <a href=#policy.mode><code>policy.mode</code></a> is <code>file</code>, relative to the configuration file. Empty starts without a policy, which allows all traffic.</p> <div class="tabbed-set tabbed-alternate" data-tabs=12:3><input checked=checked id=__tabbed_12_1 name=__tabbed_12 type=radio><input id=__tabbed_12_2 name=__tabbed_12 type=radio><input id=__tabbed_12_3 name=__tabbed_12 type=radio><div class=tabbed-labels><label for=__tabbed_12_1>YAML</label><label for=__tabbed_12_2>Environment</label><label for=__tabbed_12_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-39-1><a id=__codelineno-39-1 name=__codelineno-39-1 href=#__codelineno-39-1></a><span class=nt>policy</span><span class=p>:</span>
|
|
</span><span id=__span-39-2><a id=__codelineno-39-2 name=__codelineno-39-2 href=#__codelineno-39-2></a><span class=w> </span><span class=nt>path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/etc/headscale/policy.hujson</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-40-1><a id=__codelineno-40-1 name=__codelineno-40-1 href=#__codelineno-40-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_POLICY_PATH</span><span class=o>=</span>/etc/headscale/policy.hujson
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-41-1><a id=__codelineno-41-1 name=__codelineno-41-1 href=#__codelineno-41-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>policy<span class=o>.</span><span class=ss>path</span> <span class=o>=</span> <span class=s2>"/etc/headscale/policy.hujson"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>acl_policy_path</code> (<a href=#acl_policy_path>removed</a>).</p> <h3 id=policy.mode><code>policy.mode</code><a class=headerlink href=#policy.mode title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-enum>enum</a>: <code>file</code>, <code>database</code></li> <li><strong>Default:</strong> <code>file</code></li> <li><strong>Env:</strong> <code>HEADSCALE_POLICY_MODE</code></li> </ul> <p>Where the policy is kept: in the file <a href=#policy.path><code>policy.path</code></a>, or in the database, edited through the CLI or API.</p> <table> <thead> <tr> <th>Value</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>file</code></td> <td>Reads the policy from <a href=#policy.path><code>policy.path</code></a>. Send headscale <code>SIGHUP</code> to reload it after an edit.</td> </tr> <tr> <td><code>database</code></td> <td>Keeps the policy in the database, set with <code>headscale policy set</code> or the API. <a href=#policy.path><code>policy.path</code></a> is not read.</td> </tr> </tbody> </table> <div class="tabbed-set tabbed-alternate" data-tabs=13:3><input checked=checked id=__tabbed_13_1 name=__tabbed_13 type=radio><input id=__tabbed_13_2 name=__tabbed_13 type=radio><input id=__tabbed_13_3 name=__tabbed_13 type=radio><div class=tabbed-labels><label for=__tabbed_13_1>YAML</label><label for=__tabbed_13_2>Environment</label><label for=__tabbed_13_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-42-1><a id=__codelineno-42-1 name=__codelineno-42-1 href=#__codelineno-42-1></a><span class=nt>policy</span><span class=p>:</span>
|
|
</span><span id=__span-42-2><a id=__codelineno-42-2 name=__codelineno-42-2 href=#__codelineno-42-2></a><span class=w> </span><span class=nt>mode</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">database</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-43-1><a id=__codelineno-43-1 name=__codelineno-43-1 href=#__codelineno-43-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_POLICY_MODE</span><span class=o>=</span>database
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-44-1><a id=__codelineno-44-1 name=__codelineno-44-1 href=#__codelineno-44-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>policy<span class=o>.</span><span class=ss>mode</span> <span class=o>=</span> <span class=s2>"database"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=log><code>log</code><a class=headerlink href=#log title="Permanent link">¶</a></h2> <p>Headscale's own log output. See <a href=../debug/#application-logging>Debugging</a>.</p> <details class=example> <summary>All <code>log</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-45-1><a id=__codelineno-45-1 name=__codelineno-45-1 href=#__codelineno-45-1></a><span class=nt>log</span><span class=p>:</span>
|
|
</span><span id=__span-45-2><a id=__codelineno-45-2 name=__codelineno-45-2 href=#__codelineno-45-2></a><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">info</span>
|
|
</span><span id=__span-45-3><a id=__codelineno-45-3 name=__codelineno-45-3 href=#__codelineno-45-3></a><span class=w> </span><span class=nt>format</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">text</span>
|
|
</span></code></pre></div> </details> <h3 id=log.level><code>log.level</code><a class=headerlink href=#log.level title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-enum>enum</a>: <code>trace</code>, <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, <code>fatal</code>, <code>panic</code>, <code>disabled</code></li> <li><strong>Default:</strong> <code>info</code></li> <li><strong>Env:</strong> <code>HEADSCALE_LOG_LEVEL</code></li> </ul> <p>The lowest level logged.</p> <div class="tabbed-set tabbed-alternate" data-tabs=14:3><input checked=checked id=__tabbed_14_1 name=__tabbed_14 type=radio><input id=__tabbed_14_2 name=__tabbed_14 type=radio><input id=__tabbed_14_3 name=__tabbed_14 type=radio><div class=tabbed-labels><label for=__tabbed_14_1>YAML</label><label for=__tabbed_14_2>Environment</label><label for=__tabbed_14_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-46-1><a id=__codelineno-46-1 name=__codelineno-46-1 href=#__codelineno-46-1></a><span class=nt>log</span><span class=p>:</span>
|
|
</span><span id=__span-46-2><a id=__codelineno-46-2 name=__codelineno-46-2 href=#__codelineno-46-2></a><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></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-47-1><a id=__codelineno-47-1 name=__codelineno-47-1 href=#__codelineno-47-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_LOG_LEVEL</span><span class=o>=</span>debug
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-48-1><a id=__codelineno-48-1 name=__codelineno-48-1 href=#__codelineno-48-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>log<span class=o>.</span><span class=ss>level</span> <span class=o>=</span> <span class=s2>"debug"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>log_level</code> (<a href=#log_level>removed</a>).</p> <h3 id=log.format><code>log.format</code><a class=headerlink href=#log.format title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-enum>enum</a>: <code>text</code>, <code>json</code></li> <li><strong>Default:</strong> <code>text</code></li> <li><strong>Env:</strong> <code>HEADSCALE_LOG_FORMAT</code></li> </ul> <p>How log lines are written.</p> <table> <thead> <tr> <th>Value</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>text</code></td> <td>Writes human-readable lines, coloured when stderr is a terminal and <code>NO_COLOR</code> is unset.</td> </tr> <tr> <td><code>json</code></td> <td>Writes one JSON object per line, for log collectors.</td> </tr> </tbody> </table> <div class="tabbed-set tabbed-alternate" data-tabs=15:3><input checked=checked id=__tabbed_15_1 name=__tabbed_15 type=radio><input id=__tabbed_15_2 name=__tabbed_15 type=radio><input id=__tabbed_15_3 name=__tabbed_15 type=radio><div class=tabbed-labels><label for=__tabbed_15_1>YAML</label><label for=__tabbed_15_2>Environment</label><label for=__tabbed_15_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-49-1><a id=__codelineno-49-1 name=__codelineno-49-1 href=#__codelineno-49-1></a><span class=nt>log</span><span class=p>:</span>
|
|
</span><span id=__span-49-2><a id=__codelineno-49-2 name=__codelineno-49-2 href=#__codelineno-49-2></a><span class=w> </span><span class=nt>format</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">json</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-50-1><a id=__codelineno-50-1 name=__codelineno-50-1 href=#__codelineno-50-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_LOG_FORMAT</span><span class=o>=</span>json
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-51-1><a id=__codelineno-51-1 name=__codelineno-51-1 href=#__codelineno-51-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>log<span class=o>.</span><span class=ss>format</span> <span class=o>=</span> <span class=s2>"json"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>json_logs</code> (<a href=#json_logs>removed</a>).</p> <h2 id=node><code>node</code><a class=headerlink href=#node title="Permanent link">¶</a></h2> <p>Covers node key expiry, ephemeral nodes and subnet routes.</p> <details class=example> <summary>All <code>node</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-52-1><a id=__codelineno-52-1 name=__codelineno-52-1 href=#__codelineno-52-1></a><span class=nt>node</span><span class=p>:</span>
|
|
</span><span id=__span-52-2><a id=__codelineno-52-2 name=__codelineno-52-2 href=#__codelineno-52-2></a><span class=w> </span><span class=nt>expiry</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0s</span>
|
|
</span><span id=__span-52-3><a id=__codelineno-52-3 name=__codelineno-52-3 href=#__codelineno-52-3></a><span class=w> </span><span class=nt>ephemeral</span><span class=p>:</span>
|
|
</span><span id=__span-52-4><a id=__codelineno-52-4 name=__codelineno-52-4 href=#__codelineno-52-4></a><span class=w> </span><span class=nt>inactivity_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
|
|
</span><span id=__span-52-5><a id=__codelineno-52-5 name=__codelineno-52-5 href=#__codelineno-52-5></a><span class=w> </span><span class=nt>routes</span><span class=p>:</span>
|
|
</span><span id=__span-52-6><a id=__codelineno-52-6 name=__codelineno-52-6 href=#__codelineno-52-6></a><span class=w> </span><span class=nt>ha</span><span class=p>:</span>
|
|
</span><span id=__span-52-7><a id=__codelineno-52-7 name=__codelineno-52-7 href=#__codelineno-52-7></a><span class=w> </span><span class=nt>probe_interval</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">10s</span>
|
|
</span><span id=__span-52-8><a id=__codelineno-52-8 name=__codelineno-52-8 href=#__codelineno-52-8></a><span class=w> </span><span class=nt>probe_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">5s</span>
|
|
</span></code></pre></div> </details> <h3 id=node.expiry><code>node.expiry</code><a class=headerlink href=#node.expiry title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>0s</code></li> <li><strong>Env:</strong> <code>HEADSCALE_NODE_EXPIRY</code></li> </ul> <p>The key expiry given to a non-tagged node that registers without one, whatever the method (auth key, CLI, web, OIDC). An expiry the client asks for, <a href=#oidc.use_expiry_from_token><code>oidc.use_expiry_from_token</code></a> and an admin's <code>headscale nodes expire</code> still apply. Tagged nodes never get this default. Zero or negative disables the default.</p> <div class="tabbed-set tabbed-alternate" data-tabs=16:3><input checked=checked id=__tabbed_16_1 name=__tabbed_16 type=radio><input id=__tabbed_16_2 name=__tabbed_16 type=radio><input id=__tabbed_16_3 name=__tabbed_16 type=radio><div class=tabbed-labels><label for=__tabbed_16_1>YAML</label><label for=__tabbed_16_2>Environment</label><label for=__tabbed_16_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-53-1><a id=__codelineno-53-1 name=__codelineno-53-1 href=#__codelineno-53-1></a><span class=nt>node</span><span class=p>:</span>
|
|
</span><span id=__span-53-2><a id=__codelineno-53-2 name=__codelineno-53-2 href=#__codelineno-53-2></a><span class=w> </span><span class=nt>expiry</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2160h</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-54-1><a id=__codelineno-54-1 name=__codelineno-54-1 href=#__codelineno-54-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_NODE_EXPIRY</span><span class=o>=</span>2160h
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-55-1><a id=__codelineno-55-1 name=__codelineno-55-1 href=#__codelineno-55-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>node<span class=o>.</span><span class=ss>expiry</span> <span class=o>=</span> <span class=s2>"2160h"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>oidc.expiry</code> (<a href=#oidc.expiry>removed</a>).</p> <h3 id=node.ephemeral><code>node.ephemeral</code><a class=headerlink href=#node.ephemeral title="Permanent link">¶</a></h3> <p>Covers ephemeral nodes, which register with an ephemeral auth key and are deleted once they have been offline for <a href=#node.ephemeral.inactivity_timeout><code>node.ephemeral.inactivity_timeout</code></a>.</p> <details class=example> <summary>All <code>node.ephemeral</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-56-1><a id=__codelineno-56-1 name=__codelineno-56-1 href=#__codelineno-56-1></a><span class=nt>node</span><span class=p>:</span>
|
|
</span><span id=__span-56-2><a id=__codelineno-56-2 name=__codelineno-56-2 href=#__codelineno-56-2></a><span class=w> </span><span class=nt>ephemeral</span><span class=p>:</span>
|
|
</span><span id=__span-56-3><a id=__codelineno-56-3 name=__codelineno-56-3 href=#__codelineno-56-3></a><span class=w> </span><span class=nt>inactivity_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
|
|
</span></code></pre></div> </details> <h4 id=node.ephemeral.inactivity_timeout><code>node.ephemeral.inactivity_timeout</code><a class=headerlink href=#node.ephemeral.inactivity_timeout title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>30m</code></li> <li><strong>Env:</strong> <code>HEADSCALE_NODE_EPHEMERAL_INACTIVITY_TIMEOUT</code></li> </ul> <p>How long an ephemeral node can be offline before it is automatically deleted. It must exceed 65s, the client keepalive plus a margin.</p> <div class="tabbed-set tabbed-alternate" data-tabs=17:3><input checked=checked id=__tabbed_17_1 name=__tabbed_17 type=radio><input id=__tabbed_17_2 name=__tabbed_17 type=radio><input id=__tabbed_17_3 name=__tabbed_17 type=radio><div class=tabbed-labels><label for=__tabbed_17_1>YAML</label><label for=__tabbed_17_2>Environment</label><label for=__tabbed_17_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-57-1><a id=__codelineno-57-1 name=__codelineno-57-1 href=#__codelineno-57-1></a><span class=nt>node</span><span class=p>:</span>
|
|
</span><span id=__span-57-2><a id=__codelineno-57-2 name=__codelineno-57-2 href=#__codelineno-57-2></a><span class=w> </span><span class=nt>ephemeral</span><span class=p>:</span>
|
|
</span><span id=__span-57-3><a id=__codelineno-57-3 name=__codelineno-57-3 href=#__codelineno-57-3></a><span class=w> </span><span class=nt>inactivity_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">1h</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-58-1><a id=__codelineno-58-1 name=__codelineno-58-1 href=#__codelineno-58-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_NODE_EPHEMERAL_INACTIVITY_TIMEOUT</span><span class=o>=</span>1h
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-59-1><a id=__codelineno-59-1 name=__codelineno-59-1 href=#__codelineno-59-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>node<span class=o>.</span>ephemeral<span class=o>.</span><span class=ss>inactivity_timeout</span> <span class=o>=</span> <span class=s2>"1h"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>ephemeral_node_inactivity_timeout</code> (<a href=#ephemeral_node_inactivity_timeout>removed</a>).</p> <h3 id=node.routes><code>node.routes</code><a class=headerlink href=#node.routes title="Permanent link">¶</a></h3> <p>Covers the routes nodes advertise. See <a href=../routes/ >Routes</a>.</p> <details class=example> <summary>All <code>node.routes</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-60-1><a id=__codelineno-60-1 name=__codelineno-60-1 href=#__codelineno-60-1></a><span class=nt>node</span><span class=p>:</span>
|
|
</span><span id=__span-60-2><a id=__codelineno-60-2 name=__codelineno-60-2 href=#__codelineno-60-2></a><span class=w> </span><span class=nt>routes</span><span class=p>:</span>
|
|
</span><span id=__span-60-3><a id=__codelineno-60-3 name=__codelineno-60-3 href=#__codelineno-60-3></a><span class=w> </span><span class=nt>ha</span><span class=p>:</span>
|
|
</span><span id=__span-60-4><a id=__codelineno-60-4 name=__codelineno-60-4 href=#__codelineno-60-4></a><span class=w> </span><span class=nt>probe_interval</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">10s</span>
|
|
</span><span id=__span-60-5><a id=__codelineno-60-5 name=__codelineno-60-5 href=#__codelineno-60-5></a><span class=w> </span><span class=nt>probe_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">5s</span>
|
|
</span></code></pre></div> </details> <h4 id=node.routes.ha><code>node.routes.ha</code><a class=headerlink href=#node.routes.ha title="Permanent link">¶</a></h4> <p>Health probing of HA subnet routers. When two or more nodes advertise the same route, headscale pings each over Noise and moves the route away from one that does not answer in time. See <a href=../routes/#high-availability>High availability</a>.</p> <details class=example> <summary>All <code>node.routes.ha</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-61-1><a id=__codelineno-61-1 name=__codelineno-61-1 href=#__codelineno-61-1></a><span class=nt>node</span><span class=p>:</span>
|
|
</span><span id=__span-61-2><a id=__codelineno-61-2 name=__codelineno-61-2 href=#__codelineno-61-2></a><span class=w> </span><span class=nt>routes</span><span class=p>:</span>
|
|
</span><span id=__span-61-3><a id=__codelineno-61-3 name=__codelineno-61-3 href=#__codelineno-61-3></a><span class=w> </span><span class=nt>ha</span><span class=p>:</span>
|
|
</span><span id=__span-61-4><a id=__codelineno-61-4 name=__codelineno-61-4 href=#__codelineno-61-4></a><span class=w> </span><span class=nt>probe_interval</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">10s</span>
|
|
</span><span id=__span-61-5><a id=__codelineno-61-5 name=__codelineno-61-5 href=#__codelineno-61-5></a><span class=w> </span><span class=nt>probe_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">5s</span>
|
|
</span></code></pre></div> </details> <h5 id=node.routes.ha.probe_interval><code>node.routes.ha.probe_interval</code><a class=headerlink href=#node.routes.ha.probe_interval title="Permanent link">¶</a></h5> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>10s</code></li> <li><strong>Env:</strong> <code>HEADSCALE_NODE_ROUTES_HA_PROBE_INTERVAL</code></li> </ul> <p>How often HA subnet routers are probed; a positive interval must be at least 2s. Zero or negative disables probing, and with it the <a href=#node.routes.ha.probe_timeout><code>node.routes.ha.probe_timeout</code></a> rules.</p> <div class="tabbed-set tabbed-alternate" data-tabs=18:3><input checked=checked id=__tabbed_18_1 name=__tabbed_18 type=radio><input id=__tabbed_18_2 name=__tabbed_18 type=radio><input id=__tabbed_18_3 name=__tabbed_18 type=radio><div class=tabbed-labels><label for=__tabbed_18_1>YAML</label><label for=__tabbed_18_2>Environment</label><label for=__tabbed_18_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-62-1><a id=__codelineno-62-1 name=__codelineno-62-1 href=#__codelineno-62-1></a><span class=nt>node</span><span class=p>:</span>
|
|
</span><span id=__span-62-2><a id=__codelineno-62-2 name=__codelineno-62-2 href=#__codelineno-62-2></a><span class=w> </span><span class=nt>routes</span><span class=p>:</span>
|
|
</span><span id=__span-62-3><a id=__codelineno-62-3 name=__codelineno-62-3 href=#__codelineno-62-3></a><span class=w> </span><span class=nt>ha</span><span class=p>:</span>
|
|
</span><span id=__span-62-4><a id=__codelineno-62-4 name=__codelineno-62-4 href=#__codelineno-62-4></a><span class=w> </span><span class=nt>probe_interval</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">30s</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-63-1><a id=__codelineno-63-1 name=__codelineno-63-1 href=#__codelineno-63-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_NODE_ROUTES_HA_PROBE_INTERVAL</span><span class=o>=</span>30s
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-64-1><a id=__codelineno-64-1 name=__codelineno-64-1 href=#__codelineno-64-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>node<span class=o>.</span>routes<span class=o>.</span>ha<span class=o>.</span><span class=ss>probe_interval</span> <span class=o>=</span> <span class=s2>"30s"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h5 id=node.routes.ha.probe_timeout><code>node.routes.ha.probe_timeout</code><a class=headerlink href=#node.routes.ha.probe_timeout title="Permanent link">¶</a></h5> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>5s</code></li> <li><strong>Env:</strong> <code>HEADSCALE_NODE_ROUTES_HA_PROBE_TIMEOUT</code></li> </ul> <p>The maximum time to wait for a probe response before declaring a node unhealthy; at least 1s and less than <a href=#node.routes.ha.probe_interval><code>node.routes.ha.probe_interval</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=19:3><input checked=checked id=__tabbed_19_1 name=__tabbed_19 type=radio><input id=__tabbed_19_2 name=__tabbed_19 type=radio><input id=__tabbed_19_3 name=__tabbed_19 type=radio><div class=tabbed-labels><label for=__tabbed_19_1>YAML</label><label for=__tabbed_19_2>Environment</label><label for=__tabbed_19_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-65-1><a id=__codelineno-65-1 name=__codelineno-65-1 href=#__codelineno-65-1></a><span class=nt>node</span><span class=p>:</span>
|
|
</span><span id=__span-65-2><a id=__codelineno-65-2 name=__codelineno-65-2 href=#__codelineno-65-2></a><span class=w> </span><span class=nt>routes</span><span class=p>:</span>
|
|
</span><span id=__span-65-3><a id=__codelineno-65-3 name=__codelineno-65-3 href=#__codelineno-65-3></a><span class=w> </span><span class=nt>ha</span><span class=p>:</span>
|
|
</span><span id=__span-65-4><a id=__codelineno-65-4 name=__codelineno-65-4 href=#__codelineno-65-4></a><span class=w> </span><span class=nt>probe_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">3s</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-66-1><a id=__codelineno-66-1 name=__codelineno-66-1 href=#__codelineno-66-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_NODE_ROUTES_HA_PROBE_TIMEOUT</span><span class=o>=</span>3s
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-67-1><a id=__codelineno-67-1 name=__codelineno-67-1 href=#__codelineno-67-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>node<span class=o>.</span>routes<span class=o>.</span>ha<span class=o>.</span><span class=ss>probe_timeout</span> <span class=o>=</span> <span class=s2>"3s"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=preauth_keys><code>preauth_keys</code><a class=headerlink href=#preauth_keys title="Permanent link">¶</a></h2> <p>Covers the cleanup of revoked pre-auth keys. See <a href=../registration/#pre-authenticated-key>Pre authenticated key</a>.</p> <details class=example> <summary>All <code>preauth_keys</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-68-1><a id=__codelineno-68-1 name=__codelineno-68-1 href=#__codelineno-68-1></a><span class=nt>preauth_keys</span><span class=p>:</span>
|
|
</span><span id=__span-68-2><a id=__codelineno-68-2 name=__codelineno-68-2 href=#__codelineno-68-2></a><span class=w> </span><span class=nt>revoked_retention</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">168h</span>
|
|
</span></code></pre></div> </details> <h3 id=preauth_keys.revoked_retention><code>preauth_keys.revoked_retention</code><a class=headerlink href=#preauth_keys.revoked_retention title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>168h</code></li> <li><strong>Env:</strong> <code>HEADSCALE_PREAUTH_KEYS_REVOKED_RETENTION</code></li> </ul> <p>How long a soft-revoked pre-auth key (revoked via the v2 API's DELETE) is kept retrievable before the background collector hard-deletes it. Keys still backing a node are kept until the node is deleted. A zero or negative duration disables the collector.</p> <div class="tabbed-set tabbed-alternate" data-tabs=20:3><input checked=checked id=__tabbed_20_1 name=__tabbed_20 type=radio><input id=__tabbed_20_2 name=__tabbed_20 type=radio><input id=__tabbed_20_3 name=__tabbed_20 type=radio><div class=tabbed-labels><label for=__tabbed_20_1>YAML</label><label for=__tabbed_20_2>Environment</label><label for=__tabbed_20_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-69-1><a id=__codelineno-69-1 name=__codelineno-69-1 href=#__codelineno-69-1></a><span class=nt>preauth_keys</span><span class=p>:</span>
|
|
</span><span id=__span-69-2><a id=__codelineno-69-2 name=__codelineno-69-2 href=#__codelineno-69-2></a><span class=w> </span><span class=nt>revoked_retention</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">720h</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-70-1><a id=__codelineno-70-1 name=__codelineno-70-1 href=#__codelineno-70-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_PREAUTH_KEYS_REVOKED_RETENTION</span><span class=o>=</span>720h
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-71-1><a id=__codelineno-71-1 name=__codelineno-71-1 href=#__codelineno-71-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>preauth_keys<span class=o>.</span><span class=ss>revoked_retention</span> <span class=o>=</span> <span class=s2>"720h"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=derp><code>derp</code><a class=headerlink href=#derp title="Permanent link">¶</a></h2> <p>The DERP map: the relay servers clients use when they cannot connect directly, from <a href=#derp.urls><code>derp.urls</code></a>, <a href=#derp.paths><code>derp.paths</code></a> and the embedded server in <a href=#derp.server><code>derp.server</code></a>. A region replaces an earlier one with the same ID. See <a href=../derp/ >DERP</a>.</p> <details class=example> <summary>All <code>derp</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-72-1><a id=__codelineno-72-1 name=__codelineno-72-1 href=#__codelineno-72-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-72-2><a id=__codelineno-72-2 name=__codelineno-72-2 href=#__codelineno-72-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-72-3><a id=__codelineno-72-3 name=__codelineno-72-3 href=#__codelineno-72-3></a><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">false</span>
|
|
</span><span id=__span-72-4><a id=__codelineno-72-4 name=__codelineno-72-4 href=#__codelineno-72-4></a><span class=w> </span><span class=nt>region_id</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
</span><span id=__span-72-5><a id=__codelineno-72-5 name=__codelineno-72-5 href=#__codelineno-72-5></a><span class=w> </span><span class=nt>region_code</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-72-6><a id=__codelineno-72-6 name=__codelineno-72-6 href=#__codelineno-72-6></a><span class=w> </span><span class=nt>region_name</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-72-7><a id=__codelineno-72-7 name=__codelineno-72-7 href=#__codelineno-72-7></a><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 id=__span-72-8><a id=__codelineno-72-8 name=__codelineno-72-8 href=#__codelineno-72-8></a><span class=w> </span><span class=nt>stun_listen_addr</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-72-9><a id=__codelineno-72-9 name=__codelineno-72-9 href=#__codelineno-72-9></a><span class=w> </span><span class=nt>private_key_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-72-10><a id=__codelineno-72-10 name=__codelineno-72-10 href=#__codelineno-72-10></a><span class=w> </span><span class=nt>ipv4</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-72-11><a id=__codelineno-72-11 name=__codelineno-72-11 href=#__codelineno-72-11></a><span class=w> </span><span class=nt>ipv6</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-72-12><a id=__codelineno-72-12 name=__codelineno-72-12 href=#__codelineno-72-12></a><span class=w> </span><span class=nt>automatically_add_embedded_derp_region</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span><span id=__span-72-13><a id=__codelineno-72-13 name=__codelineno-72-13 href=#__codelineno-72-13></a><span class=w> </span><span class=nt>urls</span><span class=p>:</span>
|
|
</span><span id=__span-72-14><a id=__codelineno-72-14 name=__codelineno-72-14 href=#__codelineno-72-14></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">https://controlplane.tailscale.com/derpmap/default</span>
|
|
</span><span id=__span-72-15><a id=__codelineno-72-15 name=__codelineno-72-15 href=#__codelineno-72-15></a><span class=w> </span><span class=nt>paths</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[]</span>
|
|
</span><span id=__span-72-16><a id=__codelineno-72-16 name=__codelineno-72-16 href=#__codelineno-72-16></a><span class=w> </span><span class=nt>auto_update_enabled</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span><span id=__span-72-17><a id=__codelineno-72-17 name=__codelineno-72-17 href=#__codelineno-72-17></a><span class=w> </span><span class=nt>update_frequency</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">3h</span>
|
|
</span></code></pre></div> </details> <h3 id=derp.server><code>derp.server</code><a class=headerlink href=#derp.server title="Permanent link">¶</a></h3> <p>The embedded DERP server, a relay and STUN server run by headscale itself. See <a href=../derp/#enable-embedded-derp>Enable embedded DERP</a>.</p> <details class=example> <summary>All <code>derp.server</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-73-1><a id=__codelineno-73-1 name=__codelineno-73-1 href=#__codelineno-73-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-73-2><a id=__codelineno-73-2 name=__codelineno-73-2 href=#__codelineno-73-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-73-3><a id=__codelineno-73-3 name=__codelineno-73-3 href=#__codelineno-73-3></a><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">false</span>
|
|
</span><span id=__span-73-4><a id=__codelineno-73-4 name=__codelineno-73-4 href=#__codelineno-73-4></a><span class=w> </span><span class=nt>region_id</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
</span><span id=__span-73-5><a id=__codelineno-73-5 name=__codelineno-73-5 href=#__codelineno-73-5></a><span class=w> </span><span class=nt>region_code</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-73-6><a id=__codelineno-73-6 name=__codelineno-73-6 href=#__codelineno-73-6></a><span class=w> </span><span class=nt>region_name</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-73-7><a id=__codelineno-73-7 name=__codelineno-73-7 href=#__codelineno-73-7></a><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 id=__span-73-8><a id=__codelineno-73-8 name=__codelineno-73-8 href=#__codelineno-73-8></a><span class=w> </span><span class=nt>stun_listen_addr</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-73-9><a id=__codelineno-73-9 name=__codelineno-73-9 href=#__codelineno-73-9></a><span class=w> </span><span class=nt>private_key_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-73-10><a id=__codelineno-73-10 name=__codelineno-73-10 href=#__codelineno-73-10></a><span class=w> </span><span class=nt>ipv4</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-73-11><a id=__codelineno-73-11 name=__codelineno-73-11 href=#__codelineno-73-11></a><span class=w> </span><span class=nt>ipv6</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-73-12><a id=__codelineno-73-12 name=__codelineno-73-12 href=#__codelineno-73-12></a><span class=w> </span><span class=nt>automatically_add_embedded_derp_region</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span></code></pre></div> </details> <h4 id=derp.server.enabled><code>derp.server.enabled</code><a class=headerlink href=#derp.server.enabled title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_ENABLED</code></li> </ul> <p>Runs the embedded DERP server. DERP needs TLS, so <a href=#server_url><code>server_url</code></a> must be <code>https://</code>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=21:3><input checked=checked id=__tabbed_21_1 name=__tabbed_21 type=radio><input id=__tabbed_21_2 name=__tabbed_21 type=radio><input id=__tabbed_21_3 name=__tabbed_21 type=radio><div class=tabbed-labels><label for=__tabbed_21_1>YAML</label><label for=__tabbed_21_2>Environment</label><label for=__tabbed_21_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-74-1><a id=__codelineno-74-1 name=__codelineno-74-1 href=#__codelineno-74-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-74-2><a id=__codelineno-74-2 name=__codelineno-74-2 href=#__codelineno-74-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-74-3><a id=__codelineno-74-3 name=__codelineno-74-3 href=#__codelineno-74-3></a><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></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-75-1><a id=__codelineno-75-1 name=__codelineno-75-1 href=#__codelineno-75-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_ENABLED</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-76-1><a id=__codelineno-76-1 name=__codelineno-76-1 href=#__codelineno-76-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>enabled</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.region_id><code>derp.server.region_id</code><a class=headerlink href=#derp.server.region_id title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>0</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_REGION_ID</code></li> </ul> <p>The embedded server's region ID. It replaces a region with the same ID from the other sources.</p> <div class="tabbed-set tabbed-alternate" data-tabs=22:3><input checked=checked id=__tabbed_22_1 name=__tabbed_22 type=radio><input id=__tabbed_22_2 name=__tabbed_22 type=radio><input id=__tabbed_22_3 name=__tabbed_22 type=radio><div class=tabbed-labels><label for=__tabbed_22_1>YAML</label><label for=__tabbed_22_2>Environment</label><label for=__tabbed_22_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-77-1><a id=__codelineno-77-1 name=__codelineno-77-1 href=#__codelineno-77-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-77-2><a id=__codelineno-77-2 name=__codelineno-77-2 href=#__codelineno-77-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-77-3><a id=__codelineno-77-3 name=__codelineno-77-3 href=#__codelineno-77-3></a><span class=w> </span><span class=nt>region_id</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">999</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-78-1><a id=__codelineno-78-1 name=__codelineno-78-1 href=#__codelineno-78-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_REGION_ID</span><span class=o>=</span><span class=m>999</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-79-1><a id=__codelineno-79-1 name=__codelineno-79-1 href=#__codelineno-79-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>region_id</span> <span class=o>=</span> <span class=mi>999</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.region_code><code>derp.server.region_code</code><a class=headerlink href=#derp.server.region_code title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_REGION_CODE</code></li> </ul> <p>The region's short code, shown by Tailscale clients.</p> <div class="tabbed-set tabbed-alternate" data-tabs=23:3><input checked=checked id=__tabbed_23_1 name=__tabbed_23 type=radio><input id=__tabbed_23_2 name=__tabbed_23 type=radio><input id=__tabbed_23_3 name=__tabbed_23 type=radio><div class=tabbed-labels><label for=__tabbed_23_1>YAML</label><label for=__tabbed_23_2>Environment</label><label for=__tabbed_23_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-80-1><a id=__codelineno-80-1 name=__codelineno-80-1 href=#__codelineno-80-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-80-2><a id=__codelineno-80-2 name=__codelineno-80-2 href=#__codelineno-80-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-80-3><a id=__codelineno-80-3 name=__codelineno-80-3 href=#__codelineno-80-3></a><span class=w> </span><span class=nt>region_code</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">headscale</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-81-1><a id=__codelineno-81-1 name=__codelineno-81-1 href=#__codelineno-81-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_REGION_CODE</span><span class=o>=</span>headscale
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-82-1><a id=__codelineno-82-1 name=__codelineno-82-1 href=#__codelineno-82-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>region_code</span> <span class=o>=</span> <span class=s2>"headscale"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.region_name><code>derp.server.region_name</code><a class=headerlink href=#derp.server.region_name title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_REGION_NAME</code></li> </ul> <p>The region's name, shown by Tailscale clients.</p> <div class="tabbed-set tabbed-alternate" data-tabs=24:3><input checked=checked id=__tabbed_24_1 name=__tabbed_24 type=radio><input id=__tabbed_24_2 name=__tabbed_24 type=radio><input id=__tabbed_24_3 name=__tabbed_24 type=radio><div class=tabbed-labels><label for=__tabbed_24_1>YAML</label><label for=__tabbed_24_2>Environment</label><label for=__tabbed_24_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-83-1><a id=__codelineno-83-1 name=__codelineno-83-1 href=#__codelineno-83-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-83-2><a id=__codelineno-83-2 name=__codelineno-83-2 href=#__codelineno-83-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-83-3><a id=__codelineno-83-3 name=__codelineno-83-3 href=#__codelineno-83-3></a><span class=w> </span><span class=nt>region_name</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">Headscale Embedded DERP</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-84-1><a id=__codelineno-84-1 name=__codelineno-84-1 href=#__codelineno-84-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_REGION_NAME</span><span class=o>=</span><span class=s1>'Headscale Embedded DERP'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-85-1><a id=__codelineno-85-1 name=__codelineno-85-1 href=#__codelineno-85-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>region_name</span> <span class=o>=</span> <span class=s2>"Headscale Embedded DERP"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.verify_clients><code>derp.server.verify_clients</code><a class=headerlink href=#derp.server.verify_clients title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_VERIFY_CLIENTS</code></li> </ul> <p>Admits only nodes registered with this server.</p> <div class="tabbed-set tabbed-alternate" data-tabs=25:3><input checked=checked id=__tabbed_25_1 name=__tabbed_25 type=radio><input id=__tabbed_25_2 name=__tabbed_25 type=radio><input id=__tabbed_25_3 name=__tabbed_25 type=radio><div class=tabbed-labels><label for=__tabbed_25_1>YAML</label><label for=__tabbed_25_2>Environment</label><label for=__tabbed_25_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-86-1><a id=__codelineno-86-1 name=__codelineno-86-1 href=#__codelineno-86-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-86-2><a id=__codelineno-86-2 name=__codelineno-86-2 href=#__codelineno-86-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-86-3><a id=__codelineno-86-3 name=__codelineno-86-3 href=#__codelineno-86-3></a><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">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-87-1><a id=__codelineno-87-1 name=__codelineno-87-1 href=#__codelineno-87-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_VERIFY_CLIENTS</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-88-1><a id=__codelineno-88-1 name=__codelineno-88-1 href=#__codelineno-88-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>verify_clients</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.stun_listen_addr><code>derp.server.stun_listen_addr</code><a class=headerlink href=#derp.server.stun_listen_addr title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-listen-address>listen address</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_STUN_LISTEN_ADDR</code></li> </ul> <p>The UDP host:port of the STUN server, which helps clients with NAT traversal; required when <a href=#derp.server.enabled><code>derp.server.enabled</code></a> is true.</p> <div class="tabbed-set tabbed-alternate" data-tabs=26:3><input checked=checked id=__tabbed_26_1 name=__tabbed_26 type=radio><input id=__tabbed_26_2 name=__tabbed_26 type=radio><input id=__tabbed_26_3 name=__tabbed_26 type=radio><div class=tabbed-labels><label for=__tabbed_26_1>YAML</label><label for=__tabbed_26_2>Environment</label><label for=__tabbed_26_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-89-1><a id=__codelineno-89-1 name=__codelineno-89-1 href=#__codelineno-89-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-89-2><a id=__codelineno-89-2 name=__codelineno-89-2 href=#__codelineno-89-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-89-3><a id=__codelineno-89-3 name=__codelineno-89-3 href=#__codelineno-89-3></a><span class=w> </span><span class=nt>stun_listen_addr</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0.0.0.0:3478</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-90-1><a id=__codelineno-90-1 name=__codelineno-90-1 href=#__codelineno-90-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_STUN_LISTEN_ADDR</span><span class=o>=</span><span class=m>0</span>.0.0.0:3478
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-91-1><a id=__codelineno-91-1 name=__codelineno-91-1 href=#__codelineno-91-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>stun_listen_addr</span> <span class=o>=</span> <span class=s2>"0.0.0.0:3478"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.private_key_path><code>derp.server.private_key_path</code><a class=headerlink href=#derp.server.private_key_path title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_PRIVATE_KEY_PATH</code></li> </ul> <p>The file holding the DERP server's private key, relative to the configuration file; required when <a href=#derp.server.enabled><code>derp.server.enabled</code></a> is true. A missing file is created with a new key. It must differ from <a href=#noise.private_key_path><code>noise.private_key_path</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=27:3><input checked=checked id=__tabbed_27_1 name=__tabbed_27 type=radio><input id=__tabbed_27_2 name=__tabbed_27 type=radio><input id=__tabbed_27_3 name=__tabbed_27 type=radio><div class=tabbed-labels><label for=__tabbed_27_1>YAML</label><label for=__tabbed_27_2>Environment</label><label for=__tabbed_27_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-92-1><a id=__codelineno-92-1 name=__codelineno-92-1 href=#__codelineno-92-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-92-2><a id=__codelineno-92-2 name=__codelineno-92-2 href=#__codelineno-92-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-92-3><a id=__codelineno-92-3 name=__codelineno-92-3 href=#__codelineno-92-3></a><span class=w> </span><span class=nt>private_key_path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/var/lib/headscale/derp_server_private.key</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-93-1><a id=__codelineno-93-1 name=__codelineno-93-1 href=#__codelineno-93-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_PRIVATE_KEY_PATH</span><span class=o>=</span>/var/lib/headscale/derp_server_private.key
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-94-1><a id=__codelineno-94-1 name=__codelineno-94-1 href=#__codelineno-94-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>private_key_path</span> <span class=o>=</span> <span class=s2>"/var/lib/headscale/derp_server_private.key"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.ipv4><code>derp.server.ipv4</code><a class=headerlink href=#derp.server.ipv4 title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_IPV4</code></li> </ul> <p>The server's public IPv4 address, published in the DERP map so clients reach it without DNS. Empty publishes none.</p> <div class="tabbed-set tabbed-alternate" data-tabs=28:3><input checked=checked id=__tabbed_28_1 name=__tabbed_28 type=radio><input id=__tabbed_28_2 name=__tabbed_28 type=radio><input id=__tabbed_28_3 name=__tabbed_28 type=radio><div class=tabbed-labels><label for=__tabbed_28_1>YAML</label><label for=__tabbed_28_2>Environment</label><label for=__tabbed_28_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-95-1><a id=__codelineno-95-1 name=__codelineno-95-1 href=#__codelineno-95-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-95-2><a id=__codelineno-95-2 name=__codelineno-95-2 href=#__codelineno-95-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-95-3><a id=__codelineno-95-3 name=__codelineno-95-3 href=#__codelineno-95-3></a><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>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-96-1><a id=__codelineno-96-1 name=__codelineno-96-1 href=#__codelineno-96-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_IPV4</span><span class=o>=</span><span class=m>198</span>.51.100.1
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-97-1><a id=__codelineno-97-1 name=__codelineno-97-1 href=#__codelineno-97-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>ipv4</span> <span class=o>=</span> <span class=s2>"198.51.100.1"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.ipv6><code>derp.server.ipv6</code><a class=headerlink href=#derp.server.ipv6 title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_IPV6</code></li> </ul> <p>The server's public IPv6 address, published in the DERP map so clients reach it without DNS. Empty publishes none.</p> <div class="tabbed-set tabbed-alternate" data-tabs=29:3><input checked=checked id=__tabbed_29_1 name=__tabbed_29 type=radio><input id=__tabbed_29_2 name=__tabbed_29 type=radio><input id=__tabbed_29_3 name=__tabbed_29 type=radio><div class=tabbed-labels><label for=__tabbed_29_1>YAML</label><label for=__tabbed_29_2>Environment</label><label for=__tabbed_29_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-98-1><a id=__codelineno-98-1 name=__codelineno-98-1 href=#__codelineno-98-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-98-2><a id=__codelineno-98-2 name=__codelineno-98-2 href=#__codelineno-98-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-98-3><a id=__codelineno-98-3 name=__codelineno-98-3 href=#__codelineno-98-3></a><span class=w> </span><span class=nt>ipv6</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2001:db8::1</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-99-1><a id=__codelineno-99-1 name=__codelineno-99-1 href=#__codelineno-99-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_IPV6</span><span class=o>=</span><span class=m>2001</span>:db8::1
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-100-1><a id=__codelineno-100-1 name=__codelineno-100-1 href=#__codelineno-100-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>ipv6</span> <span class=o>=</span> <span class=s2>"2001:db8::1"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=derp.server.automatically_add_embedded_derp_region><code>derp.server.automatically_add_embedded_derp_region</code><a class=headerlink href=#derp.server.automatically_add_embedded_derp_region title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_SERVER_AUTOMATICALLY_ADD_EMBEDDED_DERP_REGION</code></li> </ul> <p>Adds the embedded server's region to the DERP map. When it is false and <a href=#derp.server.enabled><code>derp.server.enabled</code></a> is true, <a href=#derp.paths><code>derp.paths</code></a> is required: write the region there yourself.</p> <div class="tabbed-set tabbed-alternate" data-tabs=30:3><input checked=checked id=__tabbed_30_1 name=__tabbed_30 type=radio><input id=__tabbed_30_2 name=__tabbed_30 type=radio><input id=__tabbed_30_3 name=__tabbed_30 type=radio><div class=tabbed-labels><label for=__tabbed_30_1>YAML</label><label for=__tabbed_30_2>Environment</label><label for=__tabbed_30_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-101-1><a id=__codelineno-101-1 name=__codelineno-101-1 href=#__codelineno-101-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-101-2><a id=__codelineno-101-2 name=__codelineno-101-2 href=#__codelineno-101-2></a><span class=w> </span><span class=nt>server</span><span class=p>:</span>
|
|
</span><span id=__span-101-3><a id=__codelineno-101-3 name=__codelineno-101-3 href=#__codelineno-101-3></a><span class=w> </span><span class=nt>automatically_add_embedded_derp_region</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-102-1><a id=__codelineno-102-1 name=__codelineno-102-1 href=#__codelineno-102-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_SERVER_AUTOMATICALLY_ADD_EMBEDDED_DERP_REGION</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-103-1><a id=__codelineno-103-1 name=__codelineno-103-1 href=#__codelineno-103-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span>server<span class=o>.</span><span class=ss>automatically_add_embedded_derp_region</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=derp.urls><code>derp.urls</code><a class=headerlink href=#derp.urls title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-list>list of URLs</a></li> <li><strong>Default:</strong> <code>['https://controlplane.tailscale.com/derpmap/default']</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_URLS</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>DERP maps in JSON to fetch. One that fails to load is logged and skipped; startup fails only when no region remains. The default is Tailscale's map: headscale fetches it from Tailscale and clients relay through Tailscale's servers. <code>[]</code> keeps to your own.</p> <div class="tabbed-set tabbed-alternate" data-tabs=31:3><input checked=checked id=__tabbed_31_1 name=__tabbed_31 type=radio><input id=__tabbed_31_2 name=__tabbed_31 type=radio><input id=__tabbed_31_3 name=__tabbed_31 type=radio><div class=tabbed-labels><label for=__tabbed_31_1>YAML</label><label for=__tabbed_31_2>Environment</label><label for=__tabbed_31_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-104-1><a id=__codelineno-104-1 name=__codelineno-104-1 href=#__codelineno-104-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-104-2><a id=__codelineno-104-2 name=__codelineno-104-2 href=#__codelineno-104-2></a><span class=w> </span><span class=nt>urls</span><span class=p>:</span>
|
|
</span><span id=__span-104-3><a id=__codelineno-104-3 name=__codelineno-104-3 href=#__codelineno-104-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">https://derp.example.com/derpmap.json</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-105-1><a id=__codelineno-105-1 name=__codelineno-105-1 href=#__codelineno-105-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_URLS</span><span class=o>=</span><span class=s1>'["https://derp.example.com/derpmap.json"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-106-1><a id=__codelineno-106-1 name=__codelineno-106-1 href=#__codelineno-106-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span><span class=ss>urls</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-106-2><a id=__codelineno-106-2 name=__codelineno-106-2 href=#__codelineno-106-2></a> <span class=s2>"https://derp.example.com/derpmap.json"</span>
|
|
</span><span id=__span-106-3><a id=__codelineno-106-3 name=__codelineno-106-3 href=#__codelineno-106-3></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=derp.paths><code>derp.paths</code><a class=headerlink href=#derp.paths title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-list>list of strings</a></li> <li><strong>Default:</strong> <code>[]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_PATHS</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>DERP map files. The extension picks the format: <code>.yaml</code> or <code>.yml</code>, or Tailscale JSON as <code>.json</code> or <code>.hujson</code>, both accepting comments and trailing commas.</p> <div class="tabbed-set tabbed-alternate" data-tabs=32:3><input checked=checked id=__tabbed_32_1 name=__tabbed_32 type=radio><input id=__tabbed_32_2 name=__tabbed_32 type=radio><input id=__tabbed_32_3 name=__tabbed_32 type=radio><div class=tabbed-labels><label for=__tabbed_32_1>YAML</label><label for=__tabbed_32_2>Environment</label><label for=__tabbed_32_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-107-1><a id=__codelineno-107-1 name=__codelineno-107-1 href=#__codelineno-107-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-107-2><a id=__codelineno-107-2 name=__codelineno-107-2 href=#__codelineno-107-2></a><span class=w> </span><span class=nt>paths</span><span class=p>:</span>
|
|
</span><span id=__span-107-3><a id=__codelineno-107-3 name=__codelineno-107-3 href=#__codelineno-107-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/etc/headscale/derp.yaml</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-108-1><a id=__codelineno-108-1 name=__codelineno-108-1 href=#__codelineno-108-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_PATHS</span><span class=o>=</span><span class=s1>'["/etc/headscale/derp.yaml"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-109-1><a id=__codelineno-109-1 name=__codelineno-109-1 href=#__codelineno-109-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span><span class=ss>paths</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-109-2><a id=__codelineno-109-2 name=__codelineno-109-2 href=#__codelineno-109-2></a> <span class=s2>"/etc/headscale/derp.yaml"</span>
|
|
</span><span id=__span-109-3><a id=__codelineno-109-3 name=__codelineno-109-3 href=#__codelineno-109-3></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>derp_map_path</code> (<a href=#derp_map_path>removed</a>).</p> <h3 id=derp.auto_update_enabled><code>derp.auto_update_enabled</code><a class=headerlink href=#derp.auto_update_enabled title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_AUTO_UPDATE_ENABLED</code></li> </ul> <p>Reloads <a href=#derp.urls><code>derp.urls</code></a> and <a href=#derp.paths><code>derp.paths</code></a> every <a href=#derp.update_frequency><code>derp.update_frequency</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=33:3><input checked=checked id=__tabbed_33_1 name=__tabbed_33 type=radio><input id=__tabbed_33_2 name=__tabbed_33 type=radio><input id=__tabbed_33_3 name=__tabbed_33 type=radio><div class=tabbed-labels><label for=__tabbed_33_1>YAML</label><label for=__tabbed_33_2>Environment</label><label for=__tabbed_33_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-110-1><a id=__codelineno-110-1 name=__codelineno-110-1 href=#__codelineno-110-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-110-2><a id=__codelineno-110-2 name=__codelineno-110-2 href=#__codelineno-110-2></a><span class=w> </span><span class=nt>auto_update_enabled</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-111-1><a id=__codelineno-111-1 name=__codelineno-111-1 href=#__codelineno-111-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_AUTO_UPDATE_ENABLED</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-112-1><a id=__codelineno-112-1 name=__codelineno-112-1 href=#__codelineno-112-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span><span class=ss>auto_update_enabled</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=derp.update_frequency><code>derp.update_frequency</code><a class=headerlink href=#derp.update_frequency title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>3h</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DERP_UPDATE_FREQUENCY</code></li> </ul> <p>How often <a href=#derp.auto_update_enabled><code>derp.auto_update_enabled</code></a> reloads the DERP map. Zero disables reloading.</p> <div class="tabbed-set tabbed-alternate" data-tabs=34:3><input checked=checked id=__tabbed_34_1 name=__tabbed_34 type=radio><input id=__tabbed_34_2 name=__tabbed_34 type=radio><input id=__tabbed_34_3 name=__tabbed_34 type=radio><div class=tabbed-labels><label for=__tabbed_34_1>YAML</label><label for=__tabbed_34_2>Environment</label><label for=__tabbed_34_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-113-1><a id=__codelineno-113-1 name=__codelineno-113-1 href=#__codelineno-113-1></a><span class=nt>derp</span><span class=p>:</span>
|
|
</span><span id=__span-113-2><a id=__codelineno-113-2 name=__codelineno-113-2 href=#__codelineno-113-2></a><span class=w> </span><span class=nt>update_frequency</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">24h</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-114-1><a id=__codelineno-114-1 name=__codelineno-114-1 href=#__codelineno-114-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DERP_UPDATE_FREQUENCY</span><span class=o>=</span>24h
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-115-1><a id=__codelineno-115-1 name=__codelineno-115-1 href=#__codelineno-115-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>derp<span class=o>.</span><span class=ss>update_frequency</span> <span class=o>=</span> <span class=s2>"24h"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=database><code>database</code><a class=headerlink href=#database title="Permanent link">¶</a></h2> <p>Where headscale stores nodes, users and keys. SQLite is recommended; PostgreSQL is supported for legacy deployments only. <a href=#database.sqlite><code>database.sqlite</code></a> is read only for SQLite, <a href=#database.postgres><code>database.postgres</code></a> only for PostgreSQL.</p> <details class=example> <summary>All <code>database</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-116-1><a id=__codelineno-116-1 name=__codelineno-116-1 href=#__codelineno-116-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-116-2><a id=__codelineno-116-2 name=__codelineno-116-2 href=#__codelineno-116-2></a><span class=w> </span><span class=nt>type</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">sqlite</span>
|
|
</span><span id=__span-116-3><a id=__codelineno-116-3 name=__codelineno-116-3 href=#__codelineno-116-3></a><span class=w> </span><span class=nt>debug</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span><span id=__span-116-4><a id=__codelineno-116-4 name=__codelineno-116-4 href=#__codelineno-116-4></a><span class=w> </span><span class=nt>gorm</span><span class=p>:</span>
|
|
</span><span id=__span-116-5><a id=__codelineno-116-5 name=__codelineno-116-5 href=#__codelineno-116-5></a><span class=w> </span><span class=nt>slow_threshold</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
</span><span id=__span-116-6><a id=__codelineno-116-6 name=__codelineno-116-6 href=#__codelineno-116-6></a><span class=w> </span><span class=nt>skip_err_record_not_found</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span><span id=__span-116-7><a id=__codelineno-116-7 name=__codelineno-116-7 href=#__codelineno-116-7></a><span class=w> </span><span class=nt>parameterized_queries</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span><span id=__span-116-8><a id=__codelineno-116-8 name=__codelineno-116-8 href=#__codelineno-116-8></a><span class=w> </span><span class=nt>sqlite</span><span class=p>:</span>
|
|
</span><span id=__span-116-9><a id=__codelineno-116-9 name=__codelineno-116-9 href=#__codelineno-116-9></a><span class=w> </span><span class=nt>path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/var/lib/headscale/db.sqlite</span>
|
|
</span><span id=__span-116-10><a id=__codelineno-116-10 name=__codelineno-116-10 href=#__codelineno-116-10></a><span class=w> </span><span class=nt>write_ahead_log</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span><span id=__span-116-11><a id=__codelineno-116-11 name=__codelineno-116-11 href=#__codelineno-116-11></a><span class=w> </span><span class=nt>wal_autocheckpoint</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">1000</span>
|
|
</span><span id=__span-116-12><a id=__codelineno-116-12 name=__codelineno-116-12 href=#__codelineno-116-12></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-116-13><a id=__codelineno-116-13 name=__codelineno-116-13 href=#__codelineno-116-13></a><span class=w> </span><span class=nt>host</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-116-14><a id=__codelineno-116-14 name=__codelineno-116-14 href=#__codelineno-116-14></a><span class=w> </span><span class=nt>port</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
</span><span id=__span-116-15><a id=__codelineno-116-15 name=__codelineno-116-15 href=#__codelineno-116-15></a><span class=w> </span><span class=nt>name</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-116-16><a id=__codelineno-116-16 name=__codelineno-116-16 href=#__codelineno-116-16></a><span class=w> </span><span class=nt>user</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-116-17><a id=__codelineno-116-17 name=__codelineno-116-17 href=#__codelineno-116-17></a><span class=w> </span><span class=nt>pass</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-116-18><a id=__codelineno-116-18 name=__codelineno-116-18 href=#__codelineno-116-18></a><span class=w> </span><span class=nt>ssl</span><span class=p>:</span><span class=w> </span><span class=s>"false"</span>
|
|
</span><span id=__span-116-19><a id=__codelineno-116-19 name=__codelineno-116-19 href=#__codelineno-116-19></a><span class=w> </span><span class=nt>max_open_conns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
|
|
</span><span id=__span-116-20><a id=__codelineno-116-20 name=__codelineno-116-20 href=#__codelineno-116-20></a><span class=w> </span><span class=nt>max_idle_conns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
|
|
</span><span id=__span-116-21><a id=__codelineno-116-21 name=__codelineno-116-21 href=#__codelineno-116-21></a><span class=w> </span><span class=nt>conn_max_idle_time_secs</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">3600</span>
|
|
</span></code></pre></div> </details> <h3 id=database.type><code>database.type</code><a class=headerlink href=#database.type title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-enum>enum</a>: <code>sqlite</code>, <code>sqlite3</code>, <code>postgres</code></li> <li><strong>Default:</strong> <code>sqlite</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_TYPE</code></li> </ul> <p>The database backend. SQLite is recommended; PostgreSQL is supported for legacy deployments only.</p> <table> <thead> <tr> <th>Value</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>sqlite</code></td> <td>SQLite, in the file <a href=#database.sqlite.path><code>database.sqlite.path</code></a>.</td> </tr> <tr> <td><code>sqlite3</code></td> <td>The same as <code>sqlite</code>.</td> </tr> <tr> <td><code>postgres</code></td> <td>PostgreSQL, at <a href=#database.postgres.host><code>database.postgres.host</code></a>.</td> </tr> </tbody> </table> <div class="tabbed-set tabbed-alternate" data-tabs=35:3><input checked=checked id=__tabbed_35_1 name=__tabbed_35 type=radio><input id=__tabbed_35_2 name=__tabbed_35 type=radio><input id=__tabbed_35_3 name=__tabbed_35 type=radio><div class=tabbed-labels><label for=__tabbed_35_1>YAML</label><label for=__tabbed_35_2>Environment</label><label for=__tabbed_35_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-117-1><a id=__codelineno-117-1 name=__codelineno-117-1 href=#__codelineno-117-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-117-2><a id=__codelineno-117-2 name=__codelineno-117-2 href=#__codelineno-117-2></a><span class=w> </span><span class=nt>type</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">sqlite</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-118-1><a id=__codelineno-118-1 name=__codelineno-118-1 href=#__codelineno-118-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_TYPE</span><span class=o>=</span>sqlite
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-119-1><a id=__codelineno-119-1 name=__codelineno-119-1 href=#__codelineno-119-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span><span class=ss>type</span> <span class=o>=</span> <span class=s2>"sqlite"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>db_type</code> (<a href=#db_type>removed</a>).</p> <h3 id=database.debug><code>database.debug</code><a class=headerlink href=#database.debug title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_DEBUG</code></li> </ul> <p>Turns on query logging: ordinary queries at log level debug, shown only when <a href=#log.level><code>log.level</code></a> is <code>debug</code> or <code>trace</code>, slow ones at warn and failed ones at error. Off, no query is logged. <a href=#database.gorm><code>database.gorm</code></a> shapes the query log. See <a href=../debug/#database-logging>Database logging</a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=36:3><input checked=checked id=__tabbed_36_1 name=__tabbed_36 type=radio><input id=__tabbed_36_2 name=__tabbed_36 type=radio><input id=__tabbed_36_3 name=__tabbed_36 type=radio><div class=tabbed-labels><label for=__tabbed_36_1>YAML</label><label for=__tabbed_36_2>Environment</label><label for=__tabbed_36_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-120-1><a id=__codelineno-120-1 name=__codelineno-120-1 href=#__codelineno-120-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-120-2><a id=__codelineno-120-2 name=__codelineno-120-2 href=#__codelineno-120-2></a><span class=w> </span><span class=nt>debug</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-121-1><a id=__codelineno-121-1 name=__codelineno-121-1 href=#__codelineno-121-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_DEBUG</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-122-1><a id=__codelineno-122-1 name=__codelineno-122-1 href=#__codelineno-122-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span><span class=ss>debug</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=database.gorm><code>database.gorm</code><a class=headerlink href=#database.gorm title="Permanent link">¶</a></h3> <p>Query logging, applied only when <a href=#database.debug><code>database.debug</code></a> is true.</p> <details class=example> <summary>All <code>database.gorm</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-123-1><a id=__codelineno-123-1 name=__codelineno-123-1 href=#__codelineno-123-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-123-2><a id=__codelineno-123-2 name=__codelineno-123-2 href=#__codelineno-123-2></a><span class=w> </span><span class=nt>gorm</span><span class=p>:</span>
|
|
</span><span id=__span-123-3><a id=__codelineno-123-3 name=__codelineno-123-3 href=#__codelineno-123-3></a><span class=w> </span><span class=nt>slow_threshold</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
</span><span id=__span-123-4><a id=__codelineno-123-4 name=__codelineno-123-4 href=#__codelineno-123-4></a><span class=w> </span><span class=nt>skip_err_record_not_found</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span><span id=__span-123-5><a id=__codelineno-123-5 name=__codelineno-123-5 href=#__codelineno-123-5></a><span class=w> </span><span class=nt>parameterized_queries</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </details> <h4 id=database.gorm.slow_threshold><code>database.gorm.slow_threshold</code><a class=headerlink href=#database.gorm.slow_threshold title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>0</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_GORM_SLOW_THRESHOLD</code></li> </ul> <p>The query time, in milliseconds, above which a query is logged as a warning. Zero disables the warning.</p> <div class="tabbed-set tabbed-alternate" data-tabs=37:3><input checked=checked id=__tabbed_37_1 name=__tabbed_37 type=radio><input id=__tabbed_37_2 name=__tabbed_37 type=radio><input id=__tabbed_37_3 name=__tabbed_37 type=radio><div class=tabbed-labels><label for=__tabbed_37_1>YAML</label><label for=__tabbed_37_2>Environment</label><label for=__tabbed_37_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-124-1><a id=__codelineno-124-1 name=__codelineno-124-1 href=#__codelineno-124-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-124-2><a id=__codelineno-124-2 name=__codelineno-124-2 href=#__codelineno-124-2></a><span class=w> </span><span class=nt>gorm</span><span class=p>:</span>
|
|
</span><span id=__span-124-3><a id=__codelineno-124-3 name=__codelineno-124-3 href=#__codelineno-124-3></a><span class=w> </span><span class=nt>slow_threshold</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">1000</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-125-1><a id=__codelineno-125-1 name=__codelineno-125-1 href=#__codelineno-125-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_GORM_SLOW_THRESHOLD</span><span class=o>=</span><span class=m>1000</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-126-1><a id=__codelineno-126-1 name=__codelineno-126-1 href=#__codelineno-126-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>gorm<span class=o>.</span><span class=ss>slow_threshold</span> <span class=o>=</span> <span class=mi>1000</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=database.gorm.skip_err_record_not_found><code>database.gorm.skip_err_record_not_found</code><a class=headerlink href=#database.gorm.skip_err_record_not_found title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_GORM_SKIP_ERR_RECORD_NOT_FOUND</code></li> </ul> <p>Logs a query that finds no record as an ordinary query, not as an error.</p> <div class="tabbed-set tabbed-alternate" data-tabs=38:3><input checked=checked id=__tabbed_38_1 name=__tabbed_38 type=radio><input id=__tabbed_38_2 name=__tabbed_38 type=radio><input id=__tabbed_38_3 name=__tabbed_38 type=radio><div class=tabbed-labels><label for=__tabbed_38_1>YAML</label><label for=__tabbed_38_2>Environment</label><label for=__tabbed_38_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-127-1><a id=__codelineno-127-1 name=__codelineno-127-1 href=#__codelineno-127-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-127-2><a id=__codelineno-127-2 name=__codelineno-127-2 href=#__codelineno-127-2></a><span class=w> </span><span class=nt>gorm</span><span class=p>:</span>
|
|
</span><span id=__span-127-3><a id=__codelineno-127-3 name=__codelineno-127-3 href=#__codelineno-127-3></a><span class=w> </span><span class=nt>skip_err_record_not_found</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-128-1><a id=__codelineno-128-1 name=__codelineno-128-1 href=#__codelineno-128-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_GORM_SKIP_ERR_RECORD_NOT_FOUND</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-129-1><a id=__codelineno-129-1 name=__codelineno-129-1 href=#__codelineno-129-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>gorm<span class=o>.</span><span class=ss>skip_err_record_not_found</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=database.gorm.parameterized_queries><code>database.gorm.parameterized_queries</code><a class=headerlink href=#database.gorm.parameterized_queries title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_GORM_PARAMETERIZED_QUERIES</code></li> </ul> <p>Logs queries without their parameter values.</p> <div class="tabbed-set tabbed-alternate" data-tabs=39:3><input checked=checked id=__tabbed_39_1 name=__tabbed_39 type=radio><input id=__tabbed_39_2 name=__tabbed_39 type=radio><input id=__tabbed_39_3 name=__tabbed_39 type=radio><div class=tabbed-labels><label for=__tabbed_39_1>YAML</label><label for=__tabbed_39_2>Environment</label><label for=__tabbed_39_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-130-1><a id=__codelineno-130-1 name=__codelineno-130-1 href=#__codelineno-130-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-130-2><a id=__codelineno-130-2 name=__codelineno-130-2 href=#__codelineno-130-2></a><span class=w> </span><span class=nt>gorm</span><span class=p>:</span>
|
|
</span><span id=__span-130-3><a id=__codelineno-130-3 name=__codelineno-130-3 href=#__codelineno-130-3></a><span class=w> </span><span class=nt>parameterized_queries</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-131-1><a id=__codelineno-131-1 name=__codelineno-131-1 href=#__codelineno-131-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_GORM_PARAMETERIZED_QUERIES</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-132-1><a id=__codelineno-132-1 name=__codelineno-132-1 href=#__codelineno-132-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>gorm<span class=o>.</span><span class=ss>parameterized_queries</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=database.sqlite><code>database.sqlite</code><a class=headerlink href=#database.sqlite title="Permanent link">¶</a></h3> <p>SQLite, read only when <a href=#database.type><code>database.type</code></a> is <code>sqlite</code> or <code>sqlite3</code>.</p> <details class=example> <summary>All <code>database.sqlite</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-133-1><a id=__codelineno-133-1 name=__codelineno-133-1 href=#__codelineno-133-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-133-2><a id=__codelineno-133-2 name=__codelineno-133-2 href=#__codelineno-133-2></a><span class=w> </span><span class=nt>sqlite</span><span class=p>:</span>
|
|
</span><span id=__span-133-3><a id=__codelineno-133-3 name=__codelineno-133-3 href=#__codelineno-133-3></a><span class=w> </span><span class=nt>path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/var/lib/headscale/db.sqlite</span>
|
|
</span><span id=__span-133-4><a id=__codelineno-133-4 name=__codelineno-133-4 href=#__codelineno-133-4></a><span class=w> </span><span class=nt>write_ahead_log</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span><span id=__span-133-5><a id=__codelineno-133-5 name=__codelineno-133-5 href=#__codelineno-133-5></a><span class=w> </span><span class=nt>wal_autocheckpoint</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">1000</span>
|
|
</span></code></pre></div> </details> <h4 id=database.sqlite.path><code>database.sqlite.path</code><a class=headerlink href=#database.sqlite.path title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>/var/lib/headscale/db.sqlite</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_SQLITE_PATH</code></li> </ul> <p>The database file, relative to the configuration file; <code>:memory:</code> keeps the database in memory.</p> <div class="tabbed-set tabbed-alternate" data-tabs=40:3><input checked=checked id=__tabbed_40_1 name=__tabbed_40 type=radio><input id=__tabbed_40_2 name=__tabbed_40 type=radio><input id=__tabbed_40_3 name=__tabbed_40 type=radio><div class=tabbed-labels><label for=__tabbed_40_1>YAML</label><label for=__tabbed_40_2>Environment</label><label for=__tabbed_40_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-134-1><a id=__codelineno-134-1 name=__codelineno-134-1 href=#__codelineno-134-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-134-2><a id=__codelineno-134-2 name=__codelineno-134-2 href=#__codelineno-134-2></a><span class=w> </span><span class=nt>sqlite</span><span class=p>:</span>
|
|
</span><span id=__span-134-3><a id=__codelineno-134-3 name=__codelineno-134-3 href=#__codelineno-134-3></a><span class=w> </span><span class=nt>path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/opt/headscale/db.sqlite</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-135-1><a id=__codelineno-135-1 name=__codelineno-135-1 href=#__codelineno-135-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_SQLITE_PATH</span><span class=o>=</span>/opt/headscale/db.sqlite
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-136-1><a id=__codelineno-136-1 name=__codelineno-136-1 href=#__codelineno-136-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>sqlite<span class=o>.</span><span class=ss>path</span> <span class=o>=</span> <span class=s2>"/opt/headscale/db.sqlite"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>db_path</code> (<a href=#db_path>removed</a>).</p> <h4 id=database.sqlite.write_ahead_log><code>database.sqlite.write_ahead_log</code><a class=headerlink href=#database.sqlite.write_ahead_log title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_SQLITE_WRITE_AHEAD_LOG</code></li> </ul> <p>Applies <a href=#database.sqlite.wal_autocheckpoint><code>database.sqlite.wal_autocheckpoint</code></a> and compacts the database (<code>VACUUM</code>) on shutdown. SQLite runs in WAL mode either way; false keeps SQLite's default checkpoint of 1000 frames.</p> <div class="tabbed-set tabbed-alternate" data-tabs=41:3><input checked=checked id=__tabbed_41_1 name=__tabbed_41 type=radio><input id=__tabbed_41_2 name=__tabbed_41 type=radio><input id=__tabbed_41_3 name=__tabbed_41 type=radio><div class=tabbed-labels><label for=__tabbed_41_1>YAML</label><label for=__tabbed_41_2>Environment</label><label for=__tabbed_41_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-137-1><a id=__codelineno-137-1 name=__codelineno-137-1 href=#__codelineno-137-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-137-2><a id=__codelineno-137-2 name=__codelineno-137-2 href=#__codelineno-137-2></a><span class=w> </span><span class=nt>sqlite</span><span class=p>:</span>
|
|
</span><span id=__span-137-3><a id=__codelineno-137-3 name=__codelineno-137-3 href=#__codelineno-137-3></a><span class=w> </span><span class=nt>write_ahead_log</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-138-1><a id=__codelineno-138-1 name=__codelineno-138-1 href=#__codelineno-138-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_SQLITE_WRITE_AHEAD_LOG</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-139-1><a id=__codelineno-139-1 name=__codelineno-139-1 href=#__codelineno-139-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>sqlite<span class=o>.</span><span class=ss>write_ahead_log</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=database.sqlite.wal_autocheckpoint><code>database.sqlite.wal_autocheckpoint</code><a class=headerlink href=#database.sqlite.wal_autocheckpoint title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>1000</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_SQLITE_WAL_AUTOCHECKPOINT</code></li> </ul> <p>The number of WAL frames after which the WAL is checkpointed automatically; zero disables automatic checkpoints. Applied only when <a href=#database.sqlite.write_ahead_log><code>database.sqlite.write_ahead_log</code></a> is true.</p> <div class="tabbed-set tabbed-alternate" data-tabs=42:3><input checked=checked id=__tabbed_42_1 name=__tabbed_42 type=radio><input id=__tabbed_42_2 name=__tabbed_42 type=radio><input id=__tabbed_42_3 name=__tabbed_42 type=radio><div class=tabbed-labels><label for=__tabbed_42_1>YAML</label><label for=__tabbed_42_2>Environment</label><label for=__tabbed_42_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-140-1><a id=__codelineno-140-1 name=__codelineno-140-1 href=#__codelineno-140-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-140-2><a id=__codelineno-140-2 name=__codelineno-140-2 href=#__codelineno-140-2></a><span class=w> </span><span class=nt>sqlite</span><span class=p>:</span>
|
|
</span><span id=__span-140-3><a id=__codelineno-140-3 name=__codelineno-140-3 href=#__codelineno-140-3></a><span class=w> </span><span class=nt>wal_autocheckpoint</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2000</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-141-1><a id=__codelineno-141-1 name=__codelineno-141-1 href=#__codelineno-141-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_SQLITE_WAL_AUTOCHECKPOINT</span><span class=o>=</span><span class=m>2000</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-142-1><a id=__codelineno-142-1 name=__codelineno-142-1 href=#__codelineno-142-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>sqlite<span class=o>.</span><span class=ss>wal_autocheckpoint</span> <span class=o>=</span> <span class=mi>2000</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=database.postgres><code>database.postgres</code><a class=headerlink href=#database.postgres title="Permanent link">¶</a></h3> <p>PostgreSQL, read only when <a href=#database.type><code>database.type</code></a> is <code>postgres</code>.</p> <details class=example> <summary>All <code>database.postgres</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-143-1><a id=__codelineno-143-1 name=__codelineno-143-1 href=#__codelineno-143-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-143-2><a id=__codelineno-143-2 name=__codelineno-143-2 href=#__codelineno-143-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-143-3><a id=__codelineno-143-3 name=__codelineno-143-3 href=#__codelineno-143-3></a><span class=w> </span><span class=nt>host</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-143-4><a id=__codelineno-143-4 name=__codelineno-143-4 href=#__codelineno-143-4></a><span class=w> </span><span class=nt>port</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
</span><span id=__span-143-5><a id=__codelineno-143-5 name=__codelineno-143-5 href=#__codelineno-143-5></a><span class=w> </span><span class=nt>name</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-143-6><a id=__codelineno-143-6 name=__codelineno-143-6 href=#__codelineno-143-6></a><span class=w> </span><span class=nt>user</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-143-7><a id=__codelineno-143-7 name=__codelineno-143-7 href=#__codelineno-143-7></a><span class=w> </span><span class=nt>pass</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-143-8><a id=__codelineno-143-8 name=__codelineno-143-8 href=#__codelineno-143-8></a><span class=w> </span><span class=nt>ssl</span><span class=p>:</span><span class=w> </span><span class=s>"false"</span>
|
|
</span><span id=__span-143-9><a id=__codelineno-143-9 name=__codelineno-143-9 href=#__codelineno-143-9></a><span class=w> </span><span class=nt>max_open_conns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
|
|
</span><span id=__span-143-10><a id=__codelineno-143-10 name=__codelineno-143-10 href=#__codelineno-143-10></a><span class=w> </span><span class=nt>max_idle_conns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
|
|
</span><span id=__span-143-11><a id=__codelineno-143-11 name=__codelineno-143-11 href=#__codelineno-143-11></a><span class=w> </span><span class=nt>conn_max_idle_time_secs</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">3600</span>
|
|
</span></code></pre></div> </details> <h4 id=database.postgres.host><code>database.postgres.host</code><a class=headerlink href=#database.postgres.host title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_HOST</code></li> </ul> <p>The server's host name or IP, or the directory of its Unix socket (a path starting with <code>/</code>).</p> <div class="tabbed-set tabbed-alternate" data-tabs=43:3><input checked=checked id=__tabbed_43_1 name=__tabbed_43 type=radio><input id=__tabbed_43_2 name=__tabbed_43 type=radio><input id=__tabbed_43_3 name=__tabbed_43 type=radio><div class=tabbed-labels><label for=__tabbed_43_1>YAML</label><label for=__tabbed_43_2>Environment</label><label for=__tabbed_43_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-144-1><a id=__codelineno-144-1 name=__codelineno-144-1 href=#__codelineno-144-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-144-2><a id=__codelineno-144-2 name=__codelineno-144-2 href=#__codelineno-144-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-144-3><a id=__codelineno-144-3 name=__codelineno-144-3 href=#__codelineno-144-3></a><span class=w> </span><span class=nt>host</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">db.example.com</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-145-1><a id=__codelineno-145-1 name=__codelineno-145-1 href=#__codelineno-145-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_HOST</span><span class=o>=</span>db.example.com
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-146-1><a id=__codelineno-146-1 name=__codelineno-146-1 href=#__codelineno-146-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>host</span> <span class=o>=</span> <span class=s2>"db.example.com"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>db_host</code> (<a href=#db_host>removed</a>).</p> <h4 id=database.postgres.port><code>database.postgres.port</code><a class=headerlink href=#database.postgres.port title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>0</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_PORT</code></li> </ul> <p>The server's port or, with a Unix socket directory in <a href=#database.postgres.host><code>database.postgres.host</code></a>, the port in the socket's file name. Zero uses the driver's default.</p> <div class="tabbed-set tabbed-alternate" data-tabs=44:3><input checked=checked id=__tabbed_44_1 name=__tabbed_44 type=radio><input id=__tabbed_44_2 name=__tabbed_44 type=radio><input id=__tabbed_44_3 name=__tabbed_44 type=radio><div class=tabbed-labels><label for=__tabbed_44_1>YAML</label><label for=__tabbed_44_2>Environment</label><label for=__tabbed_44_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-147-1><a id=__codelineno-147-1 name=__codelineno-147-1 href=#__codelineno-147-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-147-2><a id=__codelineno-147-2 name=__codelineno-147-2 href=#__codelineno-147-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-147-3><a id=__codelineno-147-3 name=__codelineno-147-3 href=#__codelineno-147-3></a><span class=w> </span><span class=nt>port</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">5432</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-148-1><a id=__codelineno-148-1 name=__codelineno-148-1 href=#__codelineno-148-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_PORT</span><span class=o>=</span><span class=m>5432</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-149-1><a id=__codelineno-149-1 name=__codelineno-149-1 href=#__codelineno-149-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>port</span> <span class=o>=</span> <span class=mi>5432</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>db_port</code> (<a href=#db_port>removed</a>).</p> <h4 id=database.postgres.name><code>database.postgres.name</code><a class=headerlink href=#database.postgres.name title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_NAME</code></li> </ul> <p>The database name.</p> <div class="tabbed-set tabbed-alternate" data-tabs=45:3><input checked=checked id=__tabbed_45_1 name=__tabbed_45 type=radio><input id=__tabbed_45_2 name=__tabbed_45 type=radio><input id=__tabbed_45_3 name=__tabbed_45 type=radio><div class=tabbed-labels><label for=__tabbed_45_1>YAML</label><label for=__tabbed_45_2>Environment</label><label for=__tabbed_45_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-150-1><a id=__codelineno-150-1 name=__codelineno-150-1 href=#__codelineno-150-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-150-2><a id=__codelineno-150-2 name=__codelineno-150-2 href=#__codelineno-150-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-150-3><a id=__codelineno-150-3 name=__codelineno-150-3 href=#__codelineno-150-3></a><span class=w> </span><span class=nt>name</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">headscale</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-151-1><a id=__codelineno-151-1 name=__codelineno-151-1 href=#__codelineno-151-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_NAME</span><span class=o>=</span>headscale
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-152-1><a id=__codelineno-152-1 name=__codelineno-152-1 href=#__codelineno-152-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>name</span> <span class=o>=</span> <span class=s2>"headscale"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>db_name</code> (<a href=#db_name>removed</a>).</p> <h4 id=database.postgres.user><code>database.postgres.user</code><a class=headerlink href=#database.postgres.user title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_USER</code></li> </ul> <p>The user to connect as.</p> <div class="tabbed-set tabbed-alternate" data-tabs=46:3><input checked=checked id=__tabbed_46_1 name=__tabbed_46 type=radio><input id=__tabbed_46_2 name=__tabbed_46 type=radio><input id=__tabbed_46_3 name=__tabbed_46 type=radio><div class=tabbed-labels><label for=__tabbed_46_1>YAML</label><label for=__tabbed_46_2>Environment</label><label for=__tabbed_46_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-153-1><a id=__codelineno-153-1 name=__codelineno-153-1 href=#__codelineno-153-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-153-2><a id=__codelineno-153-2 name=__codelineno-153-2 href=#__codelineno-153-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-153-3><a id=__codelineno-153-3 name=__codelineno-153-3 href=#__codelineno-153-3></a><span class=w> </span><span class=nt>user</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">headscale</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-154-1><a id=__codelineno-154-1 name=__codelineno-154-1 href=#__codelineno-154-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_USER</span><span class=o>=</span>headscale
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-155-1><a id=__codelineno-155-1 name=__codelineno-155-1 href=#__codelineno-155-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>user</span> <span class=o>=</span> <span class=s2>"headscale"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>db_user</code> (<a href=#db_user>removed</a>).</p> <h4 id=database.postgres.pass><code>database.postgres.pass</code><a class=headerlink href=#database.postgres.pass title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#secrets>secret</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_PASS</code></li> </ul> <p>The password, or <code>file:<path></code> to read it from a file, read only when <a href=#database.type><code>database.type</code></a> is <code>postgres</code>. <code>headscale generate config --running</code> and <code>/debug/config</code> show a literal password as <code><redacted></code> and a <code>file:</code> reference as written.</p> <div class="tabbed-set tabbed-alternate" data-tabs=47:3><input checked=checked id=__tabbed_47_1 name=__tabbed_47 type=radio><input id=__tabbed_47_2 name=__tabbed_47 type=radio><input id=__tabbed_47_3 name=__tabbed_47 type=radio><div class=tabbed-labels><label for=__tabbed_47_1>YAML</label><label for=__tabbed_47_2>Environment</label><label for=__tabbed_47_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-156-1><a id=__codelineno-156-1 name=__codelineno-156-1 href=#__codelineno-156-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-156-2><a id=__codelineno-156-2 name=__codelineno-156-2 href=#__codelineno-156-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-156-3><a id=__codelineno-156-3 name=__codelineno-156-3 href=#__codelineno-156-3></a><span class=w> </span><span class=nt>pass</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">file:/run/secrets/postgres_password</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-157-1><a id=__codelineno-157-1 name=__codelineno-157-1 href=#__codelineno-157-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_PASS</span><span class=o>=</span>file:/run/secrets/postgres_password
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-158-1><a id=__codelineno-158-1 name=__codelineno-158-1 href=#__codelineno-158-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>pass</span> <span class=o>=</span> <span class=s2>"file:</span><span class=se>\$</span><span class=s2>{CREDENTIALS_DIRECTORY}/database_postgres_pass"</span><span class=p>;</span>
|
|
</span><span id=__span-158-2><a id=__codelineno-158-2 name=__codelineno-158-2 href=#__codelineno-158-2></a>systemd<span class=o>.</span>services<span class=o>.</span>headscale<span class=o>.</span>serviceConfig<span class=o>.</span><span class=ss>LoadCredential</span> <span class=o>=</span> <span class=p>[</span> <span class=s2>"database_postgres_pass:/run/secrets/postgres_password"</span> <span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>db_pass</code> (<a href=#db_pass>removed</a>). Replaces <code>db_password_file</code> (<a href=#db_password_file>removed</a>). Replaces <code>database.postgres.password_file</code> (<a href=#database.postgres.password_file>removed</a>).</p> <h4 id=database.postgres.ssl><code>database.postgres.ssl</code><a class=headerlink href=#database.postgres.ssl title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>"false"</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_SSL</code></li> </ul> <p>The TLS mode: <code>true</code> keeps the driver's default <code>sslmode</code>, <code>false</code> disables TLS, any other value is passed as <code>sslmode</code> (<code>require</code>, <code>verify-full</code>, ...).</p> <div class="tabbed-set tabbed-alternate" data-tabs=48:3><input checked=checked id=__tabbed_48_1 name=__tabbed_48 type=radio><input id=__tabbed_48_2 name=__tabbed_48 type=radio><input id=__tabbed_48_3 name=__tabbed_48 type=radio><div class=tabbed-labels><label for=__tabbed_48_1>YAML</label><label for=__tabbed_48_2>Environment</label><label for=__tabbed_48_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-159-1><a id=__codelineno-159-1 name=__codelineno-159-1 href=#__codelineno-159-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-159-2><a id=__codelineno-159-2 name=__codelineno-159-2 href=#__codelineno-159-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-159-3><a id=__codelineno-159-3 name=__codelineno-159-3 href=#__codelineno-159-3></a><span class=w> </span><span class=nt>ssl</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">verify-full</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-160-1><a id=__codelineno-160-1 name=__codelineno-160-1 href=#__codelineno-160-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_SSL</span><span class=o>=</span>verify-full
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-161-1><a id=__codelineno-161-1 name=__codelineno-161-1 href=#__codelineno-161-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>ssl</span> <span class=o>=</span> <span class=s2>"verify-full"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>db_ssl</code> (<a href=#db_ssl>removed</a>).</p> <h4 id=database.postgres.max_open_conns><code>database.postgres.max_open_conns</code><a class=headerlink href=#database.postgres.max_open_conns title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>10</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_MAX_OPEN_CONNS</code></li> </ul> <p>Caps open connections to the database.</p> <div class="tabbed-set tabbed-alternate" data-tabs=49:3><input checked=checked id=__tabbed_49_1 name=__tabbed_49 type=radio><input id=__tabbed_49_2 name=__tabbed_49 type=radio><input id=__tabbed_49_3 name=__tabbed_49 type=radio><div class=tabbed-labels><label for=__tabbed_49_1>YAML</label><label for=__tabbed_49_2>Environment</label><label for=__tabbed_49_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-162-1><a id=__codelineno-162-1 name=__codelineno-162-1 href=#__codelineno-162-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-162-2><a id=__codelineno-162-2 name=__codelineno-162-2 href=#__codelineno-162-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-162-3><a id=__codelineno-162-3 name=__codelineno-162-3 href=#__codelineno-162-3></a><span class=w> </span><span class=nt>max_open_conns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">20</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-163-1><a id=__codelineno-163-1 name=__codelineno-163-1 href=#__codelineno-163-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_MAX_OPEN_CONNS</span><span class=o>=</span><span class=m>20</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-164-1><a id=__codelineno-164-1 name=__codelineno-164-1 href=#__codelineno-164-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>max_open_conns</span> <span class=o>=</span> <span class=mi>20</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=database.postgres.max_idle_conns><code>database.postgres.max_idle_conns</code><a class=headerlink href=#database.postgres.max_idle_conns title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>10</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_MAX_IDLE_CONNS</code></li> </ul> <p>Caps idle connections kept in the pool.</p> <div class="tabbed-set tabbed-alternate" data-tabs=50:3><input checked=checked id=__tabbed_50_1 name=__tabbed_50 type=radio><input id=__tabbed_50_2 name=__tabbed_50 type=radio><input id=__tabbed_50_3 name=__tabbed_50 type=radio><div class=tabbed-labels><label for=__tabbed_50_1>YAML</label><label for=__tabbed_50_2>Environment</label><label for=__tabbed_50_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-165-1><a id=__codelineno-165-1 name=__codelineno-165-1 href=#__codelineno-165-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-165-2><a id=__codelineno-165-2 name=__codelineno-165-2 href=#__codelineno-165-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-165-3><a id=__codelineno-165-3 name=__codelineno-165-3 href=#__codelineno-165-3></a><span class=w> </span><span class=nt>max_idle_conns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">5</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-166-1><a id=__codelineno-166-1 name=__codelineno-166-1 href=#__codelineno-166-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_MAX_IDLE_CONNS</span><span class=o>=</span><span class=m>5</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-167-1><a id=__codelineno-167-1 name=__codelineno-167-1 href=#__codelineno-167-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>max_idle_conns</span> <span class=o>=</span> <span class=mi>5</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=database.postgres.conn_max_idle_time_secs><code>database.postgres.conn_max_idle_time_secs</code><a class=headerlink href=#database.postgres.conn_max_idle_time_secs title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>3600</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DATABASE_POSTGRES_CONN_MAX_IDLE_TIME_SECS</code></li> </ul> <p>How long, in seconds, a connection may stay idle before it is closed.</p> <div class="tabbed-set tabbed-alternate" data-tabs=51:3><input checked=checked id=__tabbed_51_1 name=__tabbed_51 type=radio><input id=__tabbed_51_2 name=__tabbed_51 type=radio><input id=__tabbed_51_3 name=__tabbed_51 type=radio><div class=tabbed-labels><label for=__tabbed_51_1>YAML</label><label for=__tabbed_51_2>Environment</label><label for=__tabbed_51_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-168-1><a id=__codelineno-168-1 name=__codelineno-168-1 href=#__codelineno-168-1></a><span class=nt>database</span><span class=p>:</span>
|
|
</span><span id=__span-168-2><a id=__codelineno-168-2 name=__codelineno-168-2 href=#__codelineno-168-2></a><span class=w> </span><span class=nt>postgres</span><span class=p>:</span>
|
|
</span><span id=__span-168-3><a id=__codelineno-168-3 name=__codelineno-168-3 href=#__codelineno-168-3></a><span class=w> </span><span class=nt>conn_max_idle_time_secs</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">600</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-169-1><a id=__codelineno-169-1 name=__codelineno-169-1 href=#__codelineno-169-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DATABASE_POSTGRES_CONN_MAX_IDLE_TIME_SECS</span><span class=o>=</span><span class=m>600</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-170-1><a id=__codelineno-170-1 name=__codelineno-170-1 href=#__codelineno-170-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>database<span class=o>.</span>postgres<span class=o>.</span><span class=ss>conn_max_idle_time_secs</span> <span class=o>=</span> <span class=mi>600</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=dns><code>dns</code><a class=headerlink href=#dns title="Permanent link">¶</a></h2> <p>The DNS configuration sent to clients, MagicDNS included, and TLS certificates for nodes. Clients apply it only with <code>--accept-dns</code>, their default. See <a href=../dns/ >DNS</a>.</p> <p>Replaces <code>dns_config</code> (<a href=#dns_config>removed</a>).</p> <details class=example> <summary>All <code>dns</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-171-1><a id=__codelineno-171-1 name=__codelineno-171-1 href=#__codelineno-171-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-171-2><a id=__codelineno-171-2 name=__codelineno-171-2 href=#__codelineno-171-2></a><span class=w> </span><span class=nt>magic_dns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span><span id=__span-171-3><a id=__codelineno-171-3 name=__codelineno-171-3 href=#__codelineno-171-3></a><span class=w> </span><span class=nt>base_domain</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">tailnet.internal</span>
|
|
</span><span id=__span-171-4><a id=__codelineno-171-4 name=__codelineno-171-4 href=#__codelineno-171-4></a><span class=w> </span><span class=nt>override_local_dns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span><span id=__span-171-5><a id=__codelineno-171-5 name=__codelineno-171-5 href=#__codelineno-171-5></a><span class=w> </span><span class=nt>nameservers</span><span class=p>:</span>
|
|
</span><span id=__span-171-6><a id=__codelineno-171-6 name=__codelineno-171-6 href=#__codelineno-171-6></a><span class=w> </span><span class=nt>global</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[]</span>
|
|
</span><span id=__span-171-7><a id=__codelineno-171-7 name=__codelineno-171-7 href=#__codelineno-171-7></a><span class=w> </span><span class=nt>split</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">{}</span>
|
|
</span><span id=__span-171-8><a id=__codelineno-171-8 name=__codelineno-171-8 href=#__codelineno-171-8></a><span class=w> </span><span class=nt>search_domains</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[]</span>
|
|
</span><span id=__span-171-9><a id=__codelineno-171-9 name=__codelineno-171-9 href=#__codelineno-171-9></a><span class=w> </span><span class=nt>extra_records</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[]</span>
|
|
</span><span id=__span-171-10><a id=__codelineno-171-10 name=__codelineno-171-10 href=#__codelineno-171-10></a><span class=w> </span><span class=nt>extra_records_path</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-171-11><a id=__codelineno-171-11 name=__codelineno-171-11 href=#__codelineno-171-11></a><span class=w> </span><span class=nt>certificates</span><span class=p>:</span>
|
|
</span><span id=__span-171-12><a id=__codelineno-171-12 name=__codelineno-171-12 href=#__codelineno-171-12></a><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">false</span>
|
|
</span><span id=__span-171-13><a id=__codelineno-171-13 name=__codelineno-171-13 href=#__codelineno-171-13></a><span class=w> </span><span class=nt>zone</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-171-14><a id=__codelineno-171-14 name=__codelineno-171-14 href=#__codelineno-171-14></a><span class=w> </span><span class=nt>challenge</span><span class=p>:</span>
|
|
</span><span id=__span-171-15><a id=__codelineno-171-15 name=__codelineno-171-15 href=#__codelineno-171-15></a><span class=w> </span><span class=nt>propagation_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2m</span>
|
|
</span><span id=__span-171-16><a id=__codelineno-171-16 name=__codelineno-171-16 href=#__codelineno-171-16></a><span class=w> </span><span class=nt>resolvers</span><span class=p>:</span>
|
|
</span><span id=__span-171-17><a id=__codelineno-171-17 name=__codelineno-171-17 href=#__codelineno-171-17></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">9.9.9.9:53</span>
|
|
</span><span id=__span-171-18><a id=__codelineno-171-18 name=__codelineno-171-18 href=#__codelineno-171-18></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">149.112.112.112:53</span>
|
|
</span><span id=__span-171-19><a id=__codelineno-171-19 name=__codelineno-171-19 href=#__codelineno-171-19></a><span class=w> </span><span class=nt>provider</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">{}</span>
|
|
</span></code></pre></div> </details> <h3 id=dns.magic_dns><code>dns.magic_dns</code><a class=headerlink href=#dns.magic_dns title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_MAGIC_DNS</code></li> </ul> <p>Gives each node a name below <a href=#dns.base_domain><code>dns.base_domain</code></a>, e.g. <code>laptop.example.com</code>, resolved by the client. It requires <a href=#dns.base_domain><code>dns.base_domain</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=52:3><input checked=checked id=__tabbed_52_1 name=__tabbed_52 type=radio><input id=__tabbed_52_2 name=__tabbed_52 type=radio><input id=__tabbed_52_3 name=__tabbed_52 type=radio><div class=tabbed-labels><label for=__tabbed_52_1>YAML</label><label for=__tabbed_52_2>Environment</label><label for=__tabbed_52_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-172-1><a id=__codelineno-172-1 name=__codelineno-172-1 href=#__codelineno-172-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-172-2><a id=__codelineno-172-2 name=__codelineno-172-2 href=#__codelineno-172-2></a><span class=w> </span><span class=nt>magic_dns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-173-1><a id=__codelineno-173-1 name=__codelineno-173-1 href=#__codelineno-173-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_MAGIC_DNS</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-174-1><a id=__codelineno-174-1 name=__codelineno-174-1 href=#__codelineno-174-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span><span class=ss>magic_dns</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>dns_config.magic_dns</code> (<a href=#dns_config.magic_dns>removed</a>).</p> <h3 id=dns.base_domain><code>dns.base_domain</code><a class=headerlink href=#dns.base_domain title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>tailnet.internal</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_BASE_DOMAIN</code></li> </ul> <p>The domain MagicDNS names live under, without a trailing dot, e.g. <code>example.com</code>. The host of <a href=#server_url><code>server_url</code></a> must not be this domain or a name below it: clients take the domain over. The default is a private-use name, so <a href=#dns.certificates><code>dns.certificates</code></a> needs a public domain you control.</p> <div class="tabbed-set tabbed-alternate" data-tabs=53:3><input checked=checked id=__tabbed_53_1 name=__tabbed_53 type=radio><input id=__tabbed_53_2 name=__tabbed_53 type=radio><input id=__tabbed_53_3 name=__tabbed_53 type=radio><div class=tabbed-labels><label for=__tabbed_53_1>YAML</label><label for=__tabbed_53_2>Environment</label><label for=__tabbed_53_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-175-1><a id=__codelineno-175-1 name=__codelineno-175-1 href=#__codelineno-175-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-175-2><a id=__codelineno-175-2 name=__codelineno-175-2 href=#__codelineno-175-2></a><span class=w> </span><span class=nt>base_domain</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">tailnet.example.com</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-176-1><a id=__codelineno-176-1 name=__codelineno-176-1 href=#__codelineno-176-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_BASE_DOMAIN</span><span class=o>=</span>tailnet.example.com
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-177-1><a id=__codelineno-177-1 name=__codelineno-177-1 href=#__codelineno-177-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span><span class=ss>base_domain</span> <span class=o>=</span> <span class=s2>"tailnet.example.com"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>dns_config.base_domain</code> (<a href=#dns_config.base_domain>removed</a>).</p> <h3 id=dns.override_local_dns><code>dns.override_local_dns</code><a class=headerlink href=#dns.override_local_dns title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_OVERRIDE_LOCAL_DNS</code></li> </ul> <p>Makes clients use <a href=#dns.nameservers.global><code>dns.nameservers.global</code></a> instead of their local DNS settings; with no global nameserver there is nothing to override with, and clients keep their own. False sends them only as fallback resolvers.</p> <div class="tabbed-set tabbed-alternate" data-tabs=54:3><input checked=checked id=__tabbed_54_1 name=__tabbed_54 type=radio><input id=__tabbed_54_2 name=__tabbed_54 type=radio><input id=__tabbed_54_3 name=__tabbed_54 type=radio><div class=tabbed-labels><label for=__tabbed_54_1>YAML</label><label for=__tabbed_54_2>Environment</label><label for=__tabbed_54_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-178-1><a id=__codelineno-178-1 name=__codelineno-178-1 href=#__codelineno-178-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-178-2><a id=__codelineno-178-2 name=__codelineno-178-2 href=#__codelineno-178-2></a><span class=w> </span><span class=nt>override_local_dns</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-179-1><a id=__codelineno-179-1 name=__codelineno-179-1 href=#__codelineno-179-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_OVERRIDE_LOCAL_DNS</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-180-1><a id=__codelineno-180-1 name=__codelineno-180-1 href=#__codelineno-180-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span><span class=ss>override_local_dns</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>dns_config.override_local_dns</code> (<a href=#dns_config.override_local_dns>removed</a>).</p> <h3 id=dns.nameservers><code>dns.nameservers</code><a class=headerlink href=#dns.nameservers title="Permanent link">¶</a></h3> <p>The upstream DNS servers sent to clients. An entry that is neither an IP address nor a URL is skipped with a warning.</p> <details class=example> <summary>All <code>dns.nameservers</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-181-1><a id=__codelineno-181-1 name=__codelineno-181-1 href=#__codelineno-181-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-181-2><a id=__codelineno-181-2 name=__codelineno-181-2 href=#__codelineno-181-2></a><span class=w> </span><span class=nt>nameservers</span><span class=p>:</span>
|
|
</span><span id=__span-181-3><a id=__codelineno-181-3 name=__codelineno-181-3 href=#__codelineno-181-3></a><span class=w> </span><span class=nt>global</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[]</span>
|
|
</span><span id=__span-181-4><a id=__codelineno-181-4 name=__codelineno-181-4 href=#__codelineno-181-4></a><span class=w> </span><span class=nt>split</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">{}</span>
|
|
</span></code></pre></div> </details> <h4 id=dns.nameservers.global><code>dns.nameservers.global</code><a class=headerlink href=#dns.nameservers.global title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-list>list of strings</a></li> <li><strong>Default:</strong> <code>[]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_NAMESERVERS_GLOBAL</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>The nameservers for names <a href=#dns.nameservers.split><code>dns.nameservers.split</code></a> does not cover: IP addresses, or DNS-over-HTTPS URLs such as <code>https://dns.nextdns.io/<id></code>. Empty by default, so clients keep their own DNS: headscale points them at no resolver you did not list.</p> <div class="tabbed-set tabbed-alternate" data-tabs=55:3><input checked=checked id=__tabbed_55_1 name=__tabbed_55 type=radio><input id=__tabbed_55_2 name=__tabbed_55 type=radio><input id=__tabbed_55_3 name=__tabbed_55 type=radio><div class=tabbed-labels><label for=__tabbed_55_1>YAML</label><label for=__tabbed_55_2>Environment</label><label for=__tabbed_55_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-182-1><a id=__codelineno-182-1 name=__codelineno-182-1 href=#__codelineno-182-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-182-2><a id=__codelineno-182-2 name=__codelineno-182-2 href=#__codelineno-182-2></a><span class=w> </span><span class=nt>nameservers</span><span class=p>:</span>
|
|
</span><span id=__span-182-3><a id=__codelineno-182-3 name=__codelineno-182-3 href=#__codelineno-182-3></a><span class=w> </span><span class=nt>global</span><span class=p>:</span>
|
|
</span><span id=__span-182-4><a id=__codelineno-182-4 name=__codelineno-182-4 href=#__codelineno-182-4></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">9.9.9.9</span>
|
|
</span><span id=__span-182-5><a id=__codelineno-182-5 name=__codelineno-182-5 href=#__codelineno-182-5></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">149.112.112.112</span>
|
|
</span><span id=__span-182-6><a id=__codelineno-182-6 name=__codelineno-182-6 href=#__codelineno-182-6></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2620:fe::fe</span>
|
|
</span><span id=__span-182-7><a id=__codelineno-182-7 name=__codelineno-182-7 href=#__codelineno-182-7></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2620:fe::9</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-183-1><a id=__codelineno-183-1 name=__codelineno-183-1 href=#__codelineno-183-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_NAMESERVERS_GLOBAL</span><span class=o>=</span><span class=s1>'["9.9.9.9","149.112.112.112","2620:fe::fe","2620:fe::9"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-184-1><a id=__codelineno-184-1 name=__codelineno-184-1 href=#__codelineno-184-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span>nameservers<span class=o>.</span><span class=ss>global</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-184-2><a id=__codelineno-184-2 name=__codelineno-184-2 href=#__codelineno-184-2></a> <span class=s2>"9.9.9.9"</span>
|
|
</span><span id=__span-184-3><a id=__codelineno-184-3 name=__codelineno-184-3 href=#__codelineno-184-3></a> <span class=s2>"149.112.112.112"</span>
|
|
</span><span id=__span-184-4><a id=__codelineno-184-4 name=__codelineno-184-4 href=#__codelineno-184-4></a> <span class=s2>"2620:fe::fe"</span>
|
|
</span><span id=__span-184-5><a id=__codelineno-184-5 name=__codelineno-184-5 href=#__codelineno-184-5></a> <span class=s2>"2620:fe::9"</span>
|
|
</span><span id=__span-184-6><a id=__codelineno-184-6 name=__codelineno-184-6 href=#__codelineno-184-6></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>dns_config.nameservers</code> (<a href=#dns_config.nameservers>removed</a>).</p> <h4 id=dns.nameservers.split><code>dns.nameservers.split</code><a class=headerlink href=#dns.nameservers.split title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-map>map of <code><domain></code> → list of strings</a></li> <li><strong>Default:</strong> <code>{}</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_NAMESERVERS_SPLIT</code> (<a href=#env>JSON object</a>)</li> </ul> <p>Maps a domain to the nameservers that answer for it (split DNS). Domains are lowercased on load; two that differ only in case are an error.</p> <div class="tabbed-set tabbed-alternate" data-tabs=56:3><input checked=checked id=__tabbed_56_1 name=__tabbed_56 type=radio><input id=__tabbed_56_2 name=__tabbed_56 type=radio><input id=__tabbed_56_3 name=__tabbed_56 type=radio><div class=tabbed-labels><label for=__tabbed_56_1>YAML</label><label for=__tabbed_56_2>Environment</label><label for=__tabbed_56_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-185-1><a id=__codelineno-185-1 name=__codelineno-185-1 href=#__codelineno-185-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-185-2><a id=__codelineno-185-2 name=__codelineno-185-2 href=#__codelineno-185-2></a><span class=w> </span><span class=nt>nameservers</span><span class=p>:</span>
|
|
</span><span id=__span-185-3><a id=__codelineno-185-3 name=__codelineno-185-3 href=#__codelineno-185-3></a><span class=w> </span><span class=nt>split</span><span class=p>:</span>
|
|
</span><span id=__span-185-4><a id=__codelineno-185-4 name=__codelineno-185-4 href=#__codelineno-185-4></a><span class=w> </span><span class=nt>corp.example.com</span><span class=p>:</span>
|
|
</span><span id=__span-185-5><a id=__codelineno-185-5 name=__codelineno-185-5 href=#__codelineno-185-5></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">192.0.2.53</span>
|
|
</span><span id=__span-185-6><a id=__codelineno-185-6 name=__codelineno-185-6 href=#__codelineno-185-6></a><span class=w> </span><span class=nt>lab.example.net</span><span class=p>:</span>
|
|
</span><span id=__span-185-7><a id=__codelineno-185-7 name=__codelineno-185-7 href=#__codelineno-185-7></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">198.51.100.53</span>
|
|
</span><span id=__span-185-8><a id=__codelineno-185-8 name=__codelineno-185-8 href=#__codelineno-185-8></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2001:db8::53</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-186-1><a id=__codelineno-186-1 name=__codelineno-186-1 href=#__codelineno-186-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_NAMESERVERS_SPLIT</span><span class=o>=</span><span class=s1>'{"corp.example.com":["192.0.2.53"],"lab.example.net":["198.51.100.53","2001:db8::53"]}'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-187-1><a id=__codelineno-187-1 name=__codelineno-187-1 href=#__codelineno-187-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span>nameservers<span class=o>.</span><span class=ss>split</span> <span class=o>=</span> <span class=p>{</span>
|
|
</span><span id=__span-187-2><a id=__codelineno-187-2 name=__codelineno-187-2 href=#__codelineno-187-2></a> <span class=s2>"corp.example.com"</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-187-3><a id=__codelineno-187-3 name=__codelineno-187-3 href=#__codelineno-187-3></a> <span class=s2>"192.0.2.53"</span>
|
|
</span><span id=__span-187-4><a id=__codelineno-187-4 name=__codelineno-187-4 href=#__codelineno-187-4></a> <span class=p>];</span>
|
|
</span><span id=__span-187-5><a id=__codelineno-187-5 name=__codelineno-187-5 href=#__codelineno-187-5></a> <span class=s2>"lab.example.net"</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-187-6><a id=__codelineno-187-6 name=__codelineno-187-6 href=#__codelineno-187-6></a> <span class=s2>"198.51.100.53"</span>
|
|
</span><span id=__span-187-7><a id=__codelineno-187-7 name=__codelineno-187-7 href=#__codelineno-187-7></a> <span class=s2>"2001:db8::53"</span>
|
|
</span><span id=__span-187-8><a id=__codelineno-187-8 name=__codelineno-187-8 href=#__codelineno-187-8></a> <span class=p>];</span>
|
|
</span><span id=__span-187-9><a id=__codelineno-187-9 name=__codelineno-187-9 href=#__codelineno-187-9></a><span class=p>};</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>dns_config.restricted_nameservers</code> (<a href=#dns_config.restricted_nameservers>removed</a>). Replaces <code>dns.split</code> (<a href=#dns.split>removed</a>).</p> <h3 id=dns.search_domains><code>dns.search_domains</code><a class=headerlink href=#dns.search_domains title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-list>list of strings</a></li> <li><strong>Default:</strong> <code>[]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_SEARCH_DOMAINS</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>DNS search domains sent to clients. With MagicDNS, <a href=#dns.base_domain><code>dns.base_domain</code></a> comes first.</p> <div class="tabbed-set tabbed-alternate" data-tabs=57:3><input checked=checked id=__tabbed_57_1 name=__tabbed_57 type=radio><input id=__tabbed_57_2 name=__tabbed_57 type=radio><input id=__tabbed_57_3 name=__tabbed_57 type=radio><div class=tabbed-labels><label for=__tabbed_57_1>YAML</label><label for=__tabbed_57_2>Environment</label><label for=__tabbed_57_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-188-1><a id=__codelineno-188-1 name=__codelineno-188-1 href=#__codelineno-188-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-188-2><a id=__codelineno-188-2 name=__codelineno-188-2 href=#__codelineno-188-2></a><span class=w> </span><span class=nt>search_domains</span><span class=p>:</span>
|
|
</span><span id=__span-188-3><a id=__codelineno-188-3 name=__codelineno-188-3 href=#__codelineno-188-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">corp.example.com</span>
|
|
</span><span id=__span-188-4><a id=__codelineno-188-4 name=__codelineno-188-4 href=#__codelineno-188-4></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">lab.example.net</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-189-1><a id=__codelineno-189-1 name=__codelineno-189-1 href=#__codelineno-189-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_SEARCH_DOMAINS</span><span class=o>=</span><span class=s1>'["corp.example.com","lab.example.net"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-190-1><a id=__codelineno-190-1 name=__codelineno-190-1 href=#__codelineno-190-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span><span class=ss>search_domains</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-190-2><a id=__codelineno-190-2 name=__codelineno-190-2 href=#__codelineno-190-2></a> <span class=s2>"corp.example.com"</span>
|
|
</span><span id=__span-190-3><a id=__codelineno-190-3 name=__codelineno-190-3 href=#__codelineno-190-3></a> <span class=s2>"lab.example.net"</span>
|
|
</span><span id=__span-190-4><a id=__codelineno-190-4 name=__codelineno-190-4 href=#__codelineno-190-4></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>dns_config.domains</code> (<a href=#dns_config.domains>removed</a>).</p> <h3 id=dns.extra_records><code>dns.extra_records</code><a class=headerlink href=#dns.extra_records title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-list>list of DNS records</a></li> <li><strong>Default:</strong> <code>[]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_EXTRA_RECORDS</code> (<a href=#env>JSON array</a>)</li> </ul> <p>DNS records served to clients, each with a <code>name</code>, <code>type</code> and <code>value</code>. Clients support <code>A</code> and <code>AAAA</code>. Mutually exclusive with <a href=#dns.extra_records_path><code>dns.extra_records_path</code></a>. See <a href=../dns/#setting-extra-dns-records>Setting extra DNS records</a>.</p> <table> <thead> <tr> <th>Field</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>name</code></td> <td><a href=#type-string>string</a></td> <td>The fully qualified domain name, e.g. <code>grafana.example.com</code>; the trailing dot is optional.</td> </tr> <tr> <td><code>type</code></td> <td><a href=#type-string>string</a></td> <td>The record type, <code>A</code> or <code>AAAA</code>; empty picks it from <code>value</code>. Clients ignore other types.</td> </tr> <tr> <td><code>value</code></td> <td><a href=#type-string>string</a></td> <td>The IP address the name resolves to.</td> </tr> </tbody> </table> <div class="tabbed-set tabbed-alternate" data-tabs=58:3><input checked=checked id=__tabbed_58_1 name=__tabbed_58 type=radio><input id=__tabbed_58_2 name=__tabbed_58 type=radio><input id=__tabbed_58_3 name=__tabbed_58 type=radio><div class=tabbed-labels><label for=__tabbed_58_1>YAML</label><label for=__tabbed_58_2>Environment</label><label for=__tabbed_58_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-191-1><a id=__codelineno-191-1 name=__codelineno-191-1 href=#__codelineno-191-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-191-2><a id=__codelineno-191-2 name=__codelineno-191-2 href=#__codelineno-191-2></a><span class=w> </span><span class=nt>extra_records</span><span class=p>:</span>
|
|
</span><span id=__span-191-3><a id=__codelineno-191-3 name=__codelineno-191-3 href=#__codelineno-191-3></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="l l-Scalar l-Scalar-Plain">grafana.tailnet.example.com</span>
|
|
</span><span id=__span-191-4><a id=__codelineno-191-4 name=__codelineno-191-4 href=#__codelineno-191-4></a><span class=w> </span><span class=nt>type</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">A</span>
|
|
</span><span id=__span-191-5><a id=__codelineno-191-5 name=__codelineno-191-5 href=#__codelineno-191-5></a><span class=w> </span><span class=nt>value</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">100.64.0.3</span>
|
|
</span><span id=__span-191-6><a id=__codelineno-191-6 name=__codelineno-191-6 href=#__codelineno-191-6></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="l l-Scalar l-Scalar-Plain">grafana.tailnet.example.com</span>
|
|
</span><span id=__span-191-7><a id=__codelineno-191-7 name=__codelineno-191-7 href=#__codelineno-191-7></a><span class=w> </span><span class=nt>type</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">AAAA</span>
|
|
</span><span id=__span-191-8><a id=__codelineno-191-8 name=__codelineno-191-8 href=#__codelineno-191-8></a><span class=w> </span><span class=nt>value</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">fd7a:115c:a1e0::3</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-192-1><a id=__codelineno-192-1 name=__codelineno-192-1 href=#__codelineno-192-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_EXTRA_RECORDS</span><span class=o>=</span><span class=s1>'[{"name":"grafana.tailnet.example.com","type":"A","value":"100.64.0.3"},{"name":"grafana.tailnet.example.com","type":"AAAA","value":"fd7a:115c:a1e0::3"}]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-193-1><a id=__codelineno-193-1 name=__codelineno-193-1 href=#__codelineno-193-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span><span class=ss>extra_records</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-193-2><a id=__codelineno-193-2 name=__codelineno-193-2 href=#__codelineno-193-2></a> <span class=p>{</span>
|
|
</span><span id=__span-193-3><a id=__codelineno-193-3 name=__codelineno-193-3 href=#__codelineno-193-3></a> <span class=ss>name</span> <span class=o>=</span> <span class=s2>"grafana.tailnet.example.com"</span><span class=p>;</span>
|
|
</span><span id=__span-193-4><a id=__codelineno-193-4 name=__codelineno-193-4 href=#__codelineno-193-4></a> <span class=ss>type</span> <span class=o>=</span> <span class=s2>"A"</span><span class=p>;</span>
|
|
</span><span id=__span-193-5><a id=__codelineno-193-5 name=__codelineno-193-5 href=#__codelineno-193-5></a> <span class=ss>value</span> <span class=o>=</span> <span class=s2>"100.64.0.3"</span><span class=p>;</span>
|
|
</span><span id=__span-193-6><a id=__codelineno-193-6 name=__codelineno-193-6 href=#__codelineno-193-6></a> <span class=p>}</span>
|
|
</span><span id=__span-193-7><a id=__codelineno-193-7 name=__codelineno-193-7 href=#__codelineno-193-7></a> <span class=p>{</span>
|
|
</span><span id=__span-193-8><a id=__codelineno-193-8 name=__codelineno-193-8 href=#__codelineno-193-8></a> <span class=ss>name</span> <span class=o>=</span> <span class=s2>"grafana.tailnet.example.com"</span><span class=p>;</span>
|
|
</span><span id=__span-193-9><a id=__codelineno-193-9 name=__codelineno-193-9 href=#__codelineno-193-9></a> <span class=ss>type</span> <span class=o>=</span> <span class=s2>"AAAA"</span><span class=p>;</span>
|
|
</span><span id=__span-193-10><a id=__codelineno-193-10 name=__codelineno-193-10 href=#__codelineno-193-10></a> <span class=ss>value</span> <span class=o>=</span> <span class=s2>"fd7a:115c:a1e0::3"</span><span class=p>;</span>
|
|
</span><span id=__span-193-11><a id=__codelineno-193-11 name=__codelineno-193-11 href=#__codelineno-193-11></a> <span class=p>}</span>
|
|
</span><span id=__span-193-12><a id=__codelineno-193-12 name=__codelineno-193-12 href=#__codelineno-193-12></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>dns_config.extra_records</code> (<a href=#dns_config.extra_records>removed</a>).</p> <h3 id=dns.extra_records_path><code>dns.extra_records_path</code><a class=headerlink href=#dns.extra_records_path title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_EXTRA_RECORDS_PATH</code></li> </ul> <p>A file of extra records, reloaded when it changes. The extension picks the format: <code>.json</code>, <code>.hujson</code>, <code>.yaml</code> or <code>.yml</code>. Mutually exclusive with <a href=#dns.extra_records><code>dns.extra_records</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=59:3><input checked=checked id=__tabbed_59_1 name=__tabbed_59 type=radio><input id=__tabbed_59_2 name=__tabbed_59 type=radio><input id=__tabbed_59_3 name=__tabbed_59 type=radio><div class=tabbed-labels><label for=__tabbed_59_1>YAML</label><label for=__tabbed_59_2>Environment</label><label for=__tabbed_59_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-194-1><a id=__codelineno-194-1 name=__codelineno-194-1 href=#__codelineno-194-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-194-2><a id=__codelineno-194-2 name=__codelineno-194-2 href=#__codelineno-194-2></a><span class=w> </span><span class=nt>extra_records_path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/var/lib/headscale/extra-records.json</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-195-1><a id=__codelineno-195-1 name=__codelineno-195-1 href=#__codelineno-195-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_EXTRA_RECORDS_PATH</span><span class=o>=</span>/var/lib/headscale/extra-records.json
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-196-1><a id=__codelineno-196-1 name=__codelineno-196-1 href=#__codelineno-196-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span><span class=ss>extra_records_path</span> <span class=o>=</span> <span class=s2>"/var/lib/headscale/extra-records.json"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=dns.certificates><code>dns.certificates</code><a class=headerlink href=#dns.certificates title="Permanent link">¶</a></h3> <p>Lets nodes get TLS certificates for their MagicDNS names with <code>tailscale cert</code>. The node runs ACME itself; headscale publishes its DNS-01 challenge through <a href=#dns.challenge.provider><code>dns.challenge.provider</code></a>.</p> <details class=example> <summary>All <code>dns.certificates</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-197-1><a id=__codelineno-197-1 name=__codelineno-197-1 href=#__codelineno-197-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-197-2><a id=__codelineno-197-2 name=__codelineno-197-2 href=#__codelineno-197-2></a><span class=w> </span><span class=nt>certificates</span><span class=p>:</span>
|
|
</span><span id=__span-197-3><a id=__codelineno-197-3 name=__codelineno-197-3 href=#__codelineno-197-3></a><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">false</span>
|
|
</span><span id=__span-197-4><a id=__codelineno-197-4 name=__codelineno-197-4 href=#__codelineno-197-4></a><span class=w> </span><span class=nt>zone</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span></code></pre></div> </details> <h4 id=dns.certificates.enabled><code>dns.certificates.enabled</code><a class=headerlink href=#dns.certificates.enabled title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_CERTIFICATES_ENABLED</code></li> </ul> <p>Lets nodes run <code>tailscale cert</code>. It requires <a href=#dns.magic_dns><code>dns.magic_dns</code></a>, a lowercase <a href=#dns.base_domain><code>dns.base_domain</code></a> and <a href=#dns.challenge.provider><code>dns.challenge.provider</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=60:3><input checked=checked id=__tabbed_60_1 name=__tabbed_60 type=radio><input id=__tabbed_60_2 name=__tabbed_60 type=radio><input id=__tabbed_60_3 name=__tabbed_60 type=radio><div class=tabbed-labels><label for=__tabbed_60_1>YAML</label><label for=__tabbed_60_2>Environment</label><label for=__tabbed_60_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-198-1><a id=__codelineno-198-1 name=__codelineno-198-1 href=#__codelineno-198-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-198-2><a id=__codelineno-198-2 name=__codelineno-198-2 href=#__codelineno-198-2></a><span class=w> </span><span class=nt>certificates</span><span class=p>:</span>
|
|
</span><span id=__span-198-3><a id=__codelineno-198-3 name=__codelineno-198-3 href=#__codelineno-198-3></a><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></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-199-1><a id=__codelineno-199-1 name=__codelineno-199-1 href=#__codelineno-199-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_CERTIFICATES_ENABLED</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-200-1><a id=__codelineno-200-1 name=__codelineno-200-1 href=#__codelineno-200-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span>certificates<span class=o>.</span><span class=ss>enabled</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=dns.certificates.zone><code>dns.certificates.zone</code><a class=headerlink href=#dns.certificates.zone title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_CERTIFICATES_ZONE</code></li> </ul> <p>The public DNS zone challenge records are written to, when <a href=#dns.base_domain><code>dns.base_domain</code></a> sits below the zone apex. It must contain <a href=#dns.base_domain><code>dns.base_domain</code></a>. Empty uses <a href=#dns.base_domain><code>dns.base_domain</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=61:3><input checked=checked id=__tabbed_61_1 name=__tabbed_61 type=radio><input id=__tabbed_61_2 name=__tabbed_61 type=radio><input id=__tabbed_61_3 name=__tabbed_61 type=radio><div class=tabbed-labels><label for=__tabbed_61_1>YAML</label><label for=__tabbed_61_2>Environment</label><label for=__tabbed_61_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-201-1><a id=__codelineno-201-1 name=__codelineno-201-1 href=#__codelineno-201-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-201-2><a id=__codelineno-201-2 name=__codelineno-201-2 href=#__codelineno-201-2></a><span class=w> </span><span class=nt>certificates</span><span class=p>:</span>
|
|
</span><span id=__span-201-3><a id=__codelineno-201-3 name=__codelineno-201-3 href=#__codelineno-201-3></a><span class=w> </span><span class=nt>zone</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">example.com</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-202-1><a id=__codelineno-202-1 name=__codelineno-202-1 href=#__codelineno-202-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_CERTIFICATES_ZONE</span><span class=o>=</span>example.com
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-203-1><a id=__codelineno-203-1 name=__codelineno-203-1 href=#__codelineno-203-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span>certificates<span class=o>.</span><span class=ss>zone</span> <span class=o>=</span> <span class=s2>"example.com"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=dns.challenge><code>dns.challenge</code><a class=headerlink href=#dns.challenge title="Permanent link">¶</a></h3> <p>The DNS provider answering ACME DNS-01 challenges, for node certificates and for headscale's own certificate when <a href=#tls.acme.challenge_type><code>tls.acme.challenge_type</code></a> is <code>DNS-01</code>. See <a href=../dns/#dns-01-challenge-provider>DNS-01 challenge provider</a>.</p> <details class=example> <summary>All <code>dns.challenge</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-204-1><a id=__codelineno-204-1 name=__codelineno-204-1 href=#__codelineno-204-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-204-2><a id=__codelineno-204-2 name=__codelineno-204-2 href=#__codelineno-204-2></a><span class=w> </span><span class=nt>challenge</span><span class=p>:</span>
|
|
</span><span id=__span-204-3><a id=__codelineno-204-3 name=__codelineno-204-3 href=#__codelineno-204-3></a><span class=w> </span><span class=nt>propagation_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">2m</span>
|
|
</span><span id=__span-204-4><a id=__codelineno-204-4 name=__codelineno-204-4 href=#__codelineno-204-4></a><span class=w> </span><span class=nt>resolvers</span><span class=p>:</span>
|
|
</span><span id=__span-204-5><a id=__codelineno-204-5 name=__codelineno-204-5 href=#__codelineno-204-5></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">9.9.9.9:53</span>
|
|
</span><span id=__span-204-6><a id=__codelineno-204-6 name=__codelineno-204-6 href=#__codelineno-204-6></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">149.112.112.112:53</span>
|
|
</span><span id=__span-204-7><a id=__codelineno-204-7 name=__codelineno-204-7 href=#__codelineno-204-7></a><span class=w> </span><span class=nt>provider</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">{}</span>
|
|
</span></code></pre></div> </details> <h4 id=dns.challenge.propagation_timeout><code>dns.challenge.propagation_timeout</code><a class=headerlink href=#dns.challenge.propagation_timeout title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>2m</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_CHALLENGE_PROPAGATION_TIMEOUT</code></li> </ul> <p>How long to wait for a challenge record to show up on every authoritative nameserver. Zero skips the check.</p> <div class="tabbed-set tabbed-alternate" data-tabs=62:3><input checked=checked id=__tabbed_62_1 name=__tabbed_62 type=radio><input id=__tabbed_62_2 name=__tabbed_62 type=radio><input id=__tabbed_62_3 name=__tabbed_62 type=radio><div class=tabbed-labels><label for=__tabbed_62_1>YAML</label><label for=__tabbed_62_2>Environment</label><label for=__tabbed_62_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-205-1><a id=__codelineno-205-1 name=__codelineno-205-1 href=#__codelineno-205-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-205-2><a id=__codelineno-205-2 name=__codelineno-205-2 href=#__codelineno-205-2></a><span class=w> </span><span class=nt>challenge</span><span class=p>:</span>
|
|
</span><span id=__span-205-3><a id=__codelineno-205-3 name=__codelineno-205-3 href=#__codelineno-205-3></a><span class=w> </span><span class=nt>propagation_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">5m</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-206-1><a id=__codelineno-206-1 name=__codelineno-206-1 href=#__codelineno-206-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_CHALLENGE_PROPAGATION_TIMEOUT</span><span class=o>=</span>5m
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-207-1><a id=__codelineno-207-1 name=__codelineno-207-1 href=#__codelineno-207-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span>challenge<span class=o>.</span><span class=ss>propagation_timeout</span> <span class=o>=</span> <span class=s2>"5m"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=dns.challenge.resolvers><code>dns.challenge.resolvers</code><a class=headerlink href=#dns.challenge.resolvers title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-list>list of strings</a></li> <li><strong>Default:</strong> <code>['9.9.9.9:53', '149.112.112.112:53']</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_CHALLENGE_RESOLVERS</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>The servers asked for the zone's nameservers, each an IP or host with an optional port (53 if omitted). Empty uses the default public resolvers. The system resolver is never used: on a host running MagicDNS it answers for <a href=#dns.base_domain><code>dns.base_domain</code></a> itself.</p> <div class="tabbed-set tabbed-alternate" data-tabs=63:3><input checked=checked id=__tabbed_63_1 name=__tabbed_63 type=radio><input id=__tabbed_63_2 name=__tabbed_63 type=radio><input id=__tabbed_63_3 name=__tabbed_63 type=radio><div class=tabbed-labels><label for=__tabbed_63_1>YAML</label><label for=__tabbed_63_2>Environment</label><label for=__tabbed_63_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-208-1><a id=__codelineno-208-1 name=__codelineno-208-1 href=#__codelineno-208-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-208-2><a id=__codelineno-208-2 name=__codelineno-208-2 href=#__codelineno-208-2></a><span class=w> </span><span class=nt>challenge</span><span class=p>:</span>
|
|
</span><span id=__span-208-3><a id=__codelineno-208-3 name=__codelineno-208-3 href=#__codelineno-208-3></a><span class=w> </span><span class=nt>resolvers</span><span class=p>:</span>
|
|
</span><span id=__span-208-4><a id=__codelineno-208-4 name=__codelineno-208-4 href=#__codelineno-208-4></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">9.9.9.9:53</span>
|
|
</span><span id=__span-208-5><a id=__codelineno-208-5 name=__codelineno-208-5 href=#__codelineno-208-5></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class=s>'[2620:fe::fe]:53'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-209-1><a id=__codelineno-209-1 name=__codelineno-209-1 href=#__codelineno-209-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_CHALLENGE_RESOLVERS</span><span class=o>=</span><span class=s1>'["9.9.9.9:53","[2620:fe::fe]:53"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-210-1><a id=__codelineno-210-1 name=__codelineno-210-1 href=#__codelineno-210-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span>challenge<span class=o>.</span><span class=ss>resolvers</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-210-2><a id=__codelineno-210-2 name=__codelineno-210-2 href=#__codelineno-210-2></a> <span class=s2>"9.9.9.9:53"</span>
|
|
</span><span id=__span-210-3><a id=__codelineno-210-3 name=__codelineno-210-3 href=#__codelineno-210-3></a> <span class=s2>"[2620:fe::fe]:53"</span>
|
|
</span><span id=__span-210-4><a id=__codelineno-210-4 name=__codelineno-210-4 href=#__codelineno-210-4></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=dns.challenge.provider><code>dns.challenge.provider</code><a class=headerlink href=#dns.challenge.provider title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-map>map of <code><setting></code> → value</a></li> <li><strong>Default:</strong> <code>{}</code></li> <li><strong>Env:</strong> <code>HEADSCALE_DNS_CHALLENGE_PROVIDER</code> (<a href=#env>JSON object</a>)</li> </ul> <p>The DNS provider that writes challenge records: <code>name</code> selects it, the other keys are its settings. Keys are lowercased on load, at every depth; two that differ only in case are an error. A string setting may be <code>file:<path></code> to read it from a file. <code>headscale generate config --running</code> and <code>/debug/config</code> show <code>name</code> and <code>file:</code> references; every other setting is <code><redacted></code>, as any may be a credential. See <a href=../dns/#dns-01-challenge-provider>DNS-01 challenge provider</a> to set a provider up, acme-dns included, and to set it from environment variables.</p> <table> <thead> <tr> <th>Provider</th> <th>Settings</th> </tr> </thead> <tbody> <tr> <td><code>acmedns</code></td> <td><code>config</code>, <code>password</code>, <code>server_url</code>, <code>subdomain</code>, <code>username</code></td> </tr> <tr> <td><code>cloudflare</code></td> <td><code>api_token</code>, <code>zone_token</code></td> </tr> <tr> <td><code>gigahost</code></td> <td><code>api_key</code></td> </tr> <tr> <td><code>hetzner</code></td> <td><code>api_token</code></td> </tr> <tr> <td><code>powerdns</code></td> <td><code>api_token</code>, <code>debug</code>, <code>server_id</code>, <code>server_url</code></td> </tr> <tr> <td><code>rfc2136</code></td> <td><code>key</code>, <code>key_alg</code>, <code>key_name</code>, <code>server</code></td> </tr> </tbody> </table> <p>Each text setting can also be set on its own as <code>HEADSCALE_DNS_CHALLENGE_PROVIDER_<SETTING></code>, e.g. <code>HEADSCALE_DNS_CHALLENGE_PROVIDER_API_TOKEN</code>, which wins over the same setting in <code>HEADSCALE_DNS_CHALLENGE_PROVIDER</code> and in the configuration file. An object setting, such as the <code>config</code> of <code>acmedns</code>, goes inside the JSON object of <code>HEADSCALE_DNS_CHALLENGE_PROVIDER</code>; see <a href=../dns/#environment-variables>Environment variables</a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=64:3><input checked=checked id=__tabbed_64_1 name=__tabbed_64 type=radio><input id=__tabbed_64_2 name=__tabbed_64 type=radio><input id=__tabbed_64_3 name=__tabbed_64 type=radio><div class=tabbed-labels><label for=__tabbed_64_1>YAML</label><label for=__tabbed_64_2>Environment</label><label for=__tabbed_64_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-211-1><a id=__codelineno-211-1 name=__codelineno-211-1 href=#__codelineno-211-1></a><span class=nt>dns</span><span class=p>:</span>
|
|
</span><span id=__span-211-2><a id=__codelineno-211-2 name=__codelineno-211-2 href=#__codelineno-211-2></a><span class=w> </span><span class=nt>challenge</span><span class=p>:</span>
|
|
</span><span id=__span-211-3><a id=__codelineno-211-3 name=__codelineno-211-3 href=#__codelineno-211-3></a><span class=w> </span><span class=nt>provider</span><span class=p>:</span>
|
|
</span><span id=__span-211-4><a id=__codelineno-211-4 name=__codelineno-211-4 href=#__codelineno-211-4></a><span class=w> </span><span class=nt>api_token</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">file:/run/secrets/cloudflare</span>
|
|
</span><span id=__span-211-5><a id=__codelineno-211-5 name=__codelineno-211-5 href=#__codelineno-211-5></a><span class=w> </span><span class=nt>name</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">cloudflare</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-212-1><a id=__codelineno-212-1 name=__codelineno-212-1 href=#__codelineno-212-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_DNS_CHALLENGE_PROVIDER</span><span class=o>=</span><span class=s1>'{"api_token":"file:/run/secrets/cloudflare","name":"cloudflare"}'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-213-1><a id=__codelineno-213-1 name=__codelineno-213-1 href=#__codelineno-213-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>dns<span class=o>.</span>challenge<span class=o>.</span><span class=ss>provider</span> <span class=o>=</span> <span class=p>{</span>
|
|
</span><span id=__span-213-2><a id=__codelineno-213-2 name=__codelineno-213-2 href=#__codelineno-213-2></a> <span class=ss>api_token</span> <span class=o>=</span> <span class=s2>"file:</span><span class=se>\$</span><span class=s2>{CREDENTIALS_DIRECTORY}/dns_challenge_provider_api_token"</span><span class=p>;</span>
|
|
</span><span id=__span-213-3><a id=__codelineno-213-3 name=__codelineno-213-3 href=#__codelineno-213-3></a> <span class=ss>name</span> <span class=o>=</span> <span class=s2>"cloudflare"</span><span class=p>;</span>
|
|
</span><span id=__span-213-4><a id=__codelineno-213-4 name=__codelineno-213-4 href=#__codelineno-213-4></a><span class=p>};</span>
|
|
</span><span id=__span-213-5><a id=__codelineno-213-5 name=__codelineno-213-5 href=#__codelineno-213-5></a>systemd<span class=o>.</span>services<span class=o>.</span>headscale<span class=o>.</span>serviceConfig<span class=o>.</span><span class=ss>LoadCredential</span> <span class=o>=</span> <span class=p>[</span> <span class=s2>"dns_challenge_provider_api_token:/run/secrets/cloudflare"</span> <span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=tls><code>tls</code><a class=headerlink href=#tls title="Permanent link">¶</a></h2> <p>Headscale's own HTTPS certificate on <a href=#listen_addr><code>listen_addr</code></a>: from the files <a href=#tls.cert_path><code>tls.cert_path</code></a> and <a href=#tls.key_path><code>tls.key_path</code></a>, or from ACME in <a href=#tls.acme><code>tls.acme</code></a>, not both. Without either, the server speaks plain HTTP. See <a href=../tls/ >TLS</a>.</p> <details class=example> <summary>All <code>tls</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-214-1><a id=__codelineno-214-1 name=__codelineno-214-1 href=#__codelineno-214-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-214-2><a id=__codelineno-214-2 name=__codelineno-214-2 href=#__codelineno-214-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-214-3><a id=__codelineno-214-3 name=__codelineno-214-3 href=#__codelineno-214-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><span id=__span-214-4><a id=__codelineno-214-4 name=__codelineno-214-4 href=#__codelineno-214-4></a><span class=w> </span><span class=nt>acme</span><span class=p>:</span>
|
|
</span><span id=__span-214-5><a id=__codelineno-214-5 name=__codelineno-214-5 href=#__codelineno-214-5></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-214-6><a id=__codelineno-214-6 name=__codelineno-214-6 href=#__codelineno-214-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><span id=__span-214-7><a id=__codelineno-214-7 name=__codelineno-214-7 href=#__codelineno-214-7></a><span class=w> </span><span class=nt>http_listen</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">:http</span>
|
|
</span><span id=__span-214-8><a id=__codelineno-214-8 name=__codelineno-214-8 href=#__codelineno-214-8></a><span class=w> </span><span class=nt>url</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-214-9><a id=__codelineno-214-9 name=__codelineno-214-9 href=#__codelineno-214-9></a><span class=w> </span><span class=nt>email</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-214-10><a id=__codelineno-214-10 name=__codelineno-214-10 href=#__codelineno-214-10></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></code></pre></div> </details> <h3 id=tls.cert_path><code>tls.cert_path</code><a class=headerlink href=#tls.cert_path title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TLS_CERT_PATH</code></li> </ul> <p>The PEM certificate file, relative to the configuration file. Setting it turns TLS on.</p> <div class="tabbed-set tabbed-alternate" data-tabs=65:3><input checked=checked id=__tabbed_65_1 name=__tabbed_65 type=radio><input id=__tabbed_65_2 name=__tabbed_65 type=radio><input id=__tabbed_65_3 name=__tabbed_65 type=radio><div class=tabbed-labels><label for=__tabbed_65_1>YAML</label><label for=__tabbed_65_2>Environment</label><label for=__tabbed_65_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-215-1><a id=__codelineno-215-1 name=__codelineno-215-1 href=#__codelineno-215-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-215-2><a id=__codelineno-215-2 name=__codelineno-215-2 href=#__codelineno-215-2></a><span class=w> </span><span class=nt>cert_path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/etc/headscale/tls/cert.pem</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-216-1><a id=__codelineno-216-1 name=__codelineno-216-1 href=#__codelineno-216-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TLS_CERT_PATH</span><span class=o>=</span>/etc/headscale/tls/cert.pem
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-217-1><a id=__codelineno-217-1 name=__codelineno-217-1 href=#__codelineno-217-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tls<span class=o>.</span><span class=ss>cert_path</span> <span class=o>=</span> <span class=s2>"/etc/headscale/tls/cert.pem"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>tls_cert_path</code> (<a href=#tls_cert_path>removed</a>).</p> <h3 id=tls.key_path><code>tls.key_path</code><a class=headerlink href=#tls.key_path title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TLS_KEY_PATH</code></li> </ul> <p>The PEM private key file of <a href=#tls.cert_path><code>tls.cert_path</code></a>, relative to the configuration file.</p> <div class="tabbed-set tabbed-alternate" data-tabs=66:3><input checked=checked id=__tabbed_66_1 name=__tabbed_66 type=radio><input id=__tabbed_66_2 name=__tabbed_66 type=radio><input id=__tabbed_66_3 name=__tabbed_66 type=radio><div class=tabbed-labels><label for=__tabbed_66_1>YAML</label><label for=__tabbed_66_2>Environment</label><label for=__tabbed_66_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-218-1><a id=__codelineno-218-1 name=__codelineno-218-1 href=#__codelineno-218-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-218-2><a id=__codelineno-218-2 name=__codelineno-218-2 href=#__codelineno-218-2></a><span class=w> </span><span class=nt>key_path</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">/etc/headscale/tls/key.pem</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-219-1><a id=__codelineno-219-1 name=__codelineno-219-1 href=#__codelineno-219-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TLS_KEY_PATH</span><span class=o>=</span>/etc/headscale/tls/key.pem
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-220-1><a id=__codelineno-220-1 name=__codelineno-220-1 href=#__codelineno-220-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tls<span class=o>.</span><span class=ss>key_path</span> <span class=o>=</span> <span class=s2>"/etc/headscale/tls/key.pem"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>tls_key_path</code> (<a href=#tls_key_path>removed</a>).</p> <h3 id=tls.acme><code>tls.acme</code><a class=headerlink href=#tls.acme title="Permanent link">¶</a></h3> <p>Gets the certificate from an ACME CA such as Let's Encrypt, and renews it. Setting <a href=#tls.acme.hostname><code>tls.acme.hostname</code></a> turns it on.</p> <details class=example> <summary>All <code>tls.acme</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-221-1><a id=__codelineno-221-1 name=__codelineno-221-1 href=#__codelineno-221-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-221-2><a id=__codelineno-221-2 name=__codelineno-221-2 href=#__codelineno-221-2></a><span class=w> </span><span class=nt>acme</span><span class=p>:</span>
|
|
</span><span id=__span-221-3><a id=__codelineno-221-3 name=__codelineno-221-3 href=#__codelineno-221-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-221-4><a id=__codelineno-221-4 name=__codelineno-221-4 href=#__codelineno-221-4></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><span id=__span-221-5><a id=__codelineno-221-5 name=__codelineno-221-5 href=#__codelineno-221-5></a><span class=w> </span><span class=nt>http_listen</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">:http</span>
|
|
</span><span id=__span-221-6><a id=__codelineno-221-6 name=__codelineno-221-6 href=#__codelineno-221-6></a><span class=w> </span><span class=nt>url</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-221-7><a id=__codelineno-221-7 name=__codelineno-221-7 href=#__codelineno-221-7></a><span class=w> </span><span class=nt>email</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-221-8><a id=__codelineno-221-8 name=__codelineno-221-8 href=#__codelineno-221-8></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></code></pre></div> </details> <h4 id=tls.acme.hostname><code>tls.acme.hostname</code><a class=headerlink href=#tls.acme.hostname title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TLS_ACME_HOSTNAME</code></li> </ul> <p>The domain to request a certificate for. Setting it turns ACME on.</p> <div class="tabbed-set tabbed-alternate" data-tabs=67:3><input checked=checked id=__tabbed_67_1 name=__tabbed_67 type=radio><input id=__tabbed_67_2 name=__tabbed_67 type=radio><input id=__tabbed_67_3 name=__tabbed_67 type=radio><div class=tabbed-labels><label for=__tabbed_67_1>YAML</label><label for=__tabbed_67_2>Environment</label><label for=__tabbed_67_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-222-1><a id=__codelineno-222-1 name=__codelineno-222-1 href=#__codelineno-222-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-222-2><a id=__codelineno-222-2 name=__codelineno-222-2 href=#__codelineno-222-2></a><span class=w> </span><span class=nt>acme</span><span class=p>:</span>
|
|
</span><span id=__span-222-3><a id=__codelineno-222-3 name=__codelineno-222-3 href=#__codelineno-222-3></a><span class=w> </span><span class=nt>hostname</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">headscale.example.com</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-223-1><a id=__codelineno-223-1 name=__codelineno-223-1 href=#__codelineno-223-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TLS_ACME_HOSTNAME</span><span class=o>=</span>headscale.example.com
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-224-1><a id=__codelineno-224-1 name=__codelineno-224-1 href=#__codelineno-224-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tls<span class=o>.</span>acme<span class=o>.</span><span class=ss>hostname</span> <span class=o>=</span> <span class=s2>"headscale.example.com"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>tls_letsencrypt_hostname</code> (<a href=#tls_letsencrypt_hostname>removed</a>).</p> <h4 id=tls.acme.challenge_type><code>tls.acme.challenge_type</code><a class=headerlink href=#tls.acme.challenge_type title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-enum>enum</a>: <code>HTTP-01</code>, <code>TLS-ALPN-01</code>, <code>DNS-01</code></li> <li><strong>Default:</strong> <code>HTTP-01</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TLS_ACME_CHALLENGE_TYPE</code></li> </ul> <p>How the CA verifies that headscale controls <a href=#tls.acme.hostname><code>tls.acme.hostname</code></a>.</p> <table> <thead> <tr> <th>Value</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>HTTP-01</code></td> <td>Has the CA fetch a token over HTTP on port 80, answered on <a href=#tls.acme.http_listen><code>tls.acme.http_listen</code></a>. TLS-ALPN-01 on <a href=#listen_addr><code>listen_addr</code></a> stays enabled too.</td> </tr> <tr> <td><code>TLS-ALPN-01</code></td> <td>Has the CA check a special certificate on port 443, answered on <a href=#listen_addr><code>listen_addr</code></a>, which must be reachable there.</td> </tr> <tr> <td><code>DNS-01</code></td> <td>Has the CA look up a TXT record, which headscale writes through <a href=#dns.challenge.provider><code>dns.challenge.provider</code></a>. It needs no open port.</td> </tr> </tbody> </table> <div class="tabbed-set tabbed-alternate" data-tabs=68:3><input checked=checked id=__tabbed_68_1 name=__tabbed_68 type=radio><input id=__tabbed_68_2 name=__tabbed_68 type=radio><input id=__tabbed_68_3 name=__tabbed_68 type=radio><div class=tabbed-labels><label for=__tabbed_68_1>YAML</label><label for=__tabbed_68_2>Environment</label><label for=__tabbed_68_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-225-1><a id=__codelineno-225-1 name=__codelineno-225-1 href=#__codelineno-225-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-225-2><a id=__codelineno-225-2 name=__codelineno-225-2 href=#__codelineno-225-2></a><span class=w> </span><span class=nt>acme</span><span class=p>:</span>
|
|
</span><span id=__span-225-3><a id=__codelineno-225-3 name=__codelineno-225-3 href=#__codelineno-225-3></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">TLS-ALPN-01</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-226-1><a id=__codelineno-226-1 name=__codelineno-226-1 href=#__codelineno-226-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TLS_ACME_CHALLENGE_TYPE</span><span class=o>=</span>TLS-ALPN-01
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-227-1><a id=__codelineno-227-1 name=__codelineno-227-1 href=#__codelineno-227-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tls<span class=o>.</span>acme<span class=o>.</span><span class=ss>challenge_type</span> <span class=o>=</span> <span class=s2>"TLS-ALPN-01"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>tls_letsencrypt_challenge_type</code> (<a href=#tls_letsencrypt_challenge_type>removed</a>).</p> <h4 id=tls.acme.http_listen><code>tls.acme.http_listen</code><a class=headerlink href=#tls.acme.http_listen title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-listen-address>listen address</a></li> <li><strong>Default:</strong> <code>:http</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TLS_ACME_HTTP_LISTEN</code></li> </ul> <p>The host:port serving HTTP-01 challenges; the port may be a name, as in <code>:http</code> for port 80. Other requests to it are redirected to <a href=#server_url><code>server_url</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=69:3><input checked=checked id=__tabbed_69_1 name=__tabbed_69 type=radio><input id=__tabbed_69_2 name=__tabbed_69 type=radio><input id=__tabbed_69_3 name=__tabbed_69 type=radio><div class=tabbed-labels><label for=__tabbed_69_1>YAML</label><label for=__tabbed_69_2>Environment</label><label for=__tabbed_69_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-228-1><a id=__codelineno-228-1 name=__codelineno-228-1 href=#__codelineno-228-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-228-2><a id=__codelineno-228-2 name=__codelineno-228-2 href=#__codelineno-228-2></a><span class=w> </span><span class=nt>acme</span><span class=p>:</span>
|
|
</span><span id=__span-228-3><a id=__codelineno-228-3 name=__codelineno-228-3 href=#__codelineno-228-3></a><span class=w> </span><span class=nt>http_listen</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0.0.0.0:80</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-229-1><a id=__codelineno-229-1 name=__codelineno-229-1 href=#__codelineno-229-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TLS_ACME_HTTP_LISTEN</span><span class=o>=</span><span class=m>0</span>.0.0.0:80
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-230-1><a id=__codelineno-230-1 name=__codelineno-230-1 href=#__codelineno-230-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tls<span class=o>.</span>acme<span class=o>.</span><span class=ss>http_listen</span> <span class=o>=</span> <span class=s2>"0.0.0.0:80"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>tls_letsencrypt_listen</code> (<a href=#tls_letsencrypt_listen>removed</a>).</p> <h4 id=tls.acme.url><code>tls.acme.url</code><a class=headerlink href=#tls.acme.url title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-URL>URL</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TLS_ACME_URL</code></li> </ul> <p>The CA's ACME directory. Empty uses Let's Encrypt.</p> <div class="tabbed-set tabbed-alternate" data-tabs=70:3><input checked=checked id=__tabbed_70_1 name=__tabbed_70 type=radio><input id=__tabbed_70_2 name=__tabbed_70 type=radio><input id=__tabbed_70_3 name=__tabbed_70 type=radio><div class=tabbed-labels><label for=__tabbed_70_1>YAML</label><label for=__tabbed_70_2>Environment</label><label for=__tabbed_70_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-231-1><a id=__codelineno-231-1 name=__codelineno-231-1 href=#__codelineno-231-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-231-2><a id=__codelineno-231-2 name=__codelineno-231-2 href=#__codelineno-231-2></a><span class=w> </span><span class=nt>acme</span><span class=p>:</span>
|
|
</span><span id=__span-231-3><a id=__codelineno-231-3 name=__codelineno-231-3 href=#__codelineno-231-3></a><span class=w> </span><span class=nt>url</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">https://acme-staging-v02.api.letsencrypt.org/directory</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-232-1><a id=__codelineno-232-1 name=__codelineno-232-1 href=#__codelineno-232-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TLS_ACME_URL</span><span class=o>=</span>https://acme-staging-v02.api.letsencrypt.org/directory
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-233-1><a id=__codelineno-233-1 name=__codelineno-233-1 href=#__codelineno-233-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tls<span class=o>.</span>acme<span class=o>.</span><span class=ss>url</span> <span class=o>=</span> <span class=s2>"https://acme-staging-v02.api.letsencrypt.org/directory"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>acme_url</code> (<a href=#acme_url>removed</a>).</p> <h4 id=tls.acme.email><code>tls.acme.email</code><a class=headerlink href=#tls.acme.email title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TLS_ACME_EMAIL</code></li> </ul> <p>The contact address registered with the CA.</p> <div class="tabbed-set tabbed-alternate" data-tabs=71:3><input checked=checked id=__tabbed_71_1 name=__tabbed_71 type=radio><input id=__tabbed_71_2 name=__tabbed_71 type=radio><input id=__tabbed_71_3 name=__tabbed_71 type=radio><div class=tabbed-labels><label for=__tabbed_71_1>YAML</label><label for=__tabbed_71_2>Environment</label><label for=__tabbed_71_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-234-1><a id=__codelineno-234-1 name=__codelineno-234-1 href=#__codelineno-234-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-234-2><a id=__codelineno-234-2 name=__codelineno-234-2 href=#__codelineno-234-2></a><span class=w> </span><span class=nt>acme</span><span class=p>:</span>
|
|
</span><span id=__span-234-3><a id=__codelineno-234-3 name=__codelineno-234-3 href=#__codelineno-234-3></a><span class=w> </span><span class=nt>email</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">admin@example.com</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-235-1><a id=__codelineno-235-1 name=__codelineno-235-1 href=#__codelineno-235-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TLS_ACME_EMAIL</span><span class=o>=</span>admin@example.com
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-236-1><a id=__codelineno-236-1 name=__codelineno-236-1 href=#__codelineno-236-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tls<span class=o>.</span>acme<span class=o>.</span><span class=ss>email</span> <span class=o>=</span> <span class=s2>"admin@example.com"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>acme_email</code> (<a href=#acme_email>removed</a>).</p> <h4 id=tls.acme.cache_dir><code>tls.acme.cache_dir</code><a class=headerlink href=#tls.acme.cache_dir title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>/var/lib/headscale/cache</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TLS_ACME_CACHE_DIR</code></li> </ul> <p>Where certificates and ACME account data are stored, relative to the configuration file.</p> <div class="tabbed-set tabbed-alternate" data-tabs=72:3><input checked=checked id=__tabbed_72_1 name=__tabbed_72 type=radio><input id=__tabbed_72_2 name=__tabbed_72 type=radio><input id=__tabbed_72_3 name=__tabbed_72 type=radio><div class=tabbed-labels><label for=__tabbed_72_1>YAML</label><label for=__tabbed_72_2>Environment</label><label for=__tabbed_72_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-237-1><a id=__codelineno-237-1 name=__codelineno-237-1 href=#__codelineno-237-1></a><span class=nt>tls</span><span class=p>:</span>
|
|
</span><span id=__span-237-2><a id=__codelineno-237-2 name=__codelineno-237-2 href=#__codelineno-237-2></a><span class=w> </span><span class=nt>acme</span><span class=p>:</span>
|
|
</span><span id=__span-237-3><a id=__codelineno-237-3 name=__codelineno-237-3 href=#__codelineno-237-3></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/cache/headscale/acme</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-238-1><a id=__codelineno-238-1 name=__codelineno-238-1 href=#__codelineno-238-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TLS_ACME_CACHE_DIR</span><span class=o>=</span>/var/cache/headscale/acme
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-239-1><a id=__codelineno-239-1 name=__codelineno-239-1 href=#__codelineno-239-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tls<span class=o>.</span>acme<span class=o>.</span><span class=ss>cache_dir</span> <span class=o>=</span> <span class=s2>"/var/cache/headscale/acme"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>tls_letsencrypt_cache_dir</code> (<a href=#tls_letsencrypt_cache_dir>removed</a>).</p> <h2 id=oidc><code>oidc</code><a class=headerlink href=#oidc title="Permanent link">¶</a></h2> <p>Login through an OpenID Connect provider. Setting <a href=#oidc.issuer><code>oidc.issuer</code></a> turns it on and requires <a href=#oidc.client_id><code>oidc.client_id</code></a> and <a href=#oidc.client_secret><code>oidc.client_secret</code></a>. See <a href=../oidc/ >OpenID Connect</a>.</p> <details class=example> <summary>All <code>oidc</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-240-1><a id=__codelineno-240-1 name=__codelineno-240-1 href=#__codelineno-240-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-240-2><a id=__codelineno-240-2 name=__codelineno-240-2 href=#__codelineno-240-2></a><span class=w> </span><span class=nt>only_start_if_oidc_is_available</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span><span id=__span-240-3><a id=__codelineno-240-3 name=__codelineno-240-3 href=#__codelineno-240-3></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-240-4><a id=__codelineno-240-4 name=__codelineno-240-4 href=#__codelineno-240-4></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-240-5><a id=__codelineno-240-5 name=__codelineno-240-5 href=#__codelineno-240-5></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-240-6><a id=__codelineno-240-6 name=__codelineno-240-6 href=#__codelineno-240-6></a><span class=w> </span><span class=nt>scope</span><span class=p>:</span>
|
|
</span><span id=__span-240-7><a id=__codelineno-240-7 name=__codelineno-240-7 href=#__codelineno-240-7></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">openid</span>
|
|
</span><span id=__span-240-8><a id=__codelineno-240-8 name=__codelineno-240-8 href=#__codelineno-240-8></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">profile</span>
|
|
</span><span id=__span-240-9><a id=__codelineno-240-9 name=__codelineno-240-9 href=#__codelineno-240-9></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">email</span>
|
|
</span><span id=__span-240-10><a id=__codelineno-240-10 name=__codelineno-240-10 href=#__codelineno-240-10></a><span class=w> </span><span class=nt>extra_params</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">{}</span>
|
|
</span><span id=__span-240-11><a id=__codelineno-240-11 name=__codelineno-240-11 href=#__codelineno-240-11></a><span class=w> </span><span class=nt>allowed_domains</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[]</span>
|
|
</span><span id=__span-240-12><a id=__codelineno-240-12 name=__codelineno-240-12 href=#__codelineno-240-12></a><span class=w> </span><span class=nt>allowed_users</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[]</span>
|
|
</span><span id=__span-240-13><a id=__codelineno-240-13 name=__codelineno-240-13 href=#__codelineno-240-13></a><span class=w> </span><span class=nt>allowed_groups</span><span class=p>:</span><span class=w> </span><span class="p p-Indicator">[]</span>
|
|
</span><span id=__span-240-14><a id=__codelineno-240-14 name=__codelineno-240-14 href=#__codelineno-240-14></a><span class=w> </span><span class=nt>email_verified_required</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span><span id=__span-240-15><a id=__codelineno-240-15 name=__codelineno-240-15 href=#__codelineno-240-15></a><span class=w> </span><span class=nt>use_expiry_from_token</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span><span id=__span-240-16><a id=__codelineno-240-16 name=__codelineno-240-16 href=#__codelineno-240-16></a><span class=w> </span><span class=nt>pkce</span><span class=p>:</span>
|
|
</span><span id=__span-240-17><a id=__codelineno-240-17 name=__codelineno-240-17 href=#__codelineno-240-17></a><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">false</span>
|
|
</span><span id=__span-240-18><a id=__codelineno-240-18 name=__codelineno-240-18 href=#__codelineno-240-18></a><span class=w> </span><span class=nt>method</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">S256</span>
|
|
</span></code></pre></div> </details> <h3 id=oidc.only_start_if_oidc_is_available><code>oidc.only_start_if_oidc_is_available</code><a class=headerlink href=#oidc.only_start_if_oidc_is_available title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_ONLY_START_IF_OIDC_IS_AVAILABLE</code></li> </ul> <p>Stops startup when the provider cannot be reached. False starts without OIDC, with CLI-based registration.</p> <div class="tabbed-set tabbed-alternate" data-tabs=73:3><input checked=checked id=__tabbed_73_1 name=__tabbed_73 type=radio><input id=__tabbed_73_2 name=__tabbed_73 type=radio><input id=__tabbed_73_3 name=__tabbed_73 type=radio><div class=tabbed-labels><label for=__tabbed_73_1>YAML</label><label for=__tabbed_73_2>Environment</label><label for=__tabbed_73_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-241-1><a id=__codelineno-241-1 name=__codelineno-241-1 href=#__codelineno-241-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-241-2><a id=__codelineno-241-2 name=__codelineno-241-2 href=#__codelineno-241-2></a><span class=w> </span><span class=nt>only_start_if_oidc_is_available</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-242-1><a id=__codelineno-242-1 name=__codelineno-242-1 href=#__codelineno-242-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_ONLY_START_IF_OIDC_IS_AVAILABLE</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-243-1><a id=__codelineno-243-1 name=__codelineno-243-1 href=#__codelineno-243-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>only_start_if_oidc_is_available</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.issuer><code>oidc.issuer</code><a class=headerlink href=#oidc.issuer title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-URL>URL</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_ISSUER</code></li> </ul> <p>The provider's issuer URL. Setting it turns OIDC on.</p> <div class="tabbed-set tabbed-alternate" data-tabs=74:3><input checked=checked id=__tabbed_74_1 name=__tabbed_74 type=radio><input id=__tabbed_74_2 name=__tabbed_74 type=radio><input id=__tabbed_74_3 name=__tabbed_74 type=radio><div class=tabbed-labels><label for=__tabbed_74_1>YAML</label><label for=__tabbed_74_2>Environment</label><label for=__tabbed_74_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-244-1><a id=__codelineno-244-1 name=__codelineno-244-1 href=#__codelineno-244-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-244-2><a id=__codelineno-244-2 name=__codelineno-244-2 href=#__codelineno-244-2></a><span class=w> </span><span class=nt>issuer</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">https://idp.example.com/realms/headscale</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-245-1><a id=__codelineno-245-1 name=__codelineno-245-1 href=#__codelineno-245-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_ISSUER</span><span class=o>=</span>https://idp.example.com/realms/headscale
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-246-1><a id=__codelineno-246-1 name=__codelineno-246-1 href=#__codelineno-246-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>issuer</span> <span class=o>=</span> <span class=s2>"https://idp.example.com/realms/headscale"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.client_id><code>oidc.client_id</code><a class=headerlink href=#oidc.client_id title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_CLIENT_ID</code></li> </ul> <p>The client ID from the provider; required when <a href=#oidc.issuer><code>oidc.issuer</code></a> is set.</p> <div class="tabbed-set tabbed-alternate" data-tabs=75:3><input checked=checked id=__tabbed_75_1 name=__tabbed_75 type=radio><input id=__tabbed_75_2 name=__tabbed_75 type=radio><input id=__tabbed_75_3 name=__tabbed_75 type=radio><div class=tabbed-labels><label for=__tabbed_75_1>YAML</label><label for=__tabbed_75_2>Environment</label><label for=__tabbed_75_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-247-1><a id=__codelineno-247-1 name=__codelineno-247-1 href=#__codelineno-247-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-247-2><a id=__codelineno-247-2 name=__codelineno-247-2 href=#__codelineno-247-2></a><span class=w> </span><span class=nt>client_id</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">headscale</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-248-1><a id=__codelineno-248-1 name=__codelineno-248-1 href=#__codelineno-248-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_CLIENT_ID</span><span class=o>=</span>headscale
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-249-1><a id=__codelineno-249-1 name=__codelineno-249-1 href=#__codelineno-249-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>client_id</span> <span class=o>=</span> <span class=s2>"headscale"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.client_secret><code>oidc.client_secret</code><a class=headerlink href=#oidc.client_secret title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#secrets>secret</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_CLIENT_SECRET</code></li> </ul> <p>The client secret from the provider, or <code>file:<path></code> to read it from a file; required when <a href=#oidc.issuer><code>oidc.issuer</code></a> is set. <code>headscale generate config --running</code> and <code>/debug/config</code> show a literal secret as <code><redacted></code> and a <code>file:</code> reference as written.</p> <div class="tabbed-set tabbed-alternate" data-tabs=76:3><input checked=checked id=__tabbed_76_1 name=__tabbed_76 type=radio><input id=__tabbed_76_2 name=__tabbed_76 type=radio><input id=__tabbed_76_3 name=__tabbed_76 type=radio><div class=tabbed-labels><label for=__tabbed_76_1>YAML</label><label for=__tabbed_76_2>Environment</label><label for=__tabbed_76_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-250-1><a id=__codelineno-250-1 name=__codelineno-250-1 href=#__codelineno-250-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-250-2><a id=__codelineno-250-2 name=__codelineno-250-2 href=#__codelineno-250-2></a><span class=w> </span><span class=nt>client_secret</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">file:/run/secrets/oidc_client_secret</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-251-1><a id=__codelineno-251-1 name=__codelineno-251-1 href=#__codelineno-251-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_CLIENT_SECRET</span><span class=o>=</span>file:/run/secrets/oidc_client_secret
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-252-1><a id=__codelineno-252-1 name=__codelineno-252-1 href=#__codelineno-252-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>client_secret</span> <span class=o>=</span> <span class=s2>"file:</span><span class=se>\$</span><span class=s2>{CREDENTIALS_DIRECTORY}/oidc_client_secret"</span><span class=p>;</span>
|
|
</span><span id=__span-252-2><a id=__codelineno-252-2 name=__codelineno-252-2 href=#__codelineno-252-2></a>systemd<span class=o>.</span>services<span class=o>.</span>headscale<span class=o>.</span>serviceConfig<span class=o>.</span><span class=ss>LoadCredential</span> <span class=o>=</span> <span class=p>[</span> <span class=s2>"oidc_client_secret:/run/secrets/oidc_client_secret"</span> <span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <p>Replaces <code>oidc.client_secret_path</code> (<a href=#oidc.client_secret_path>removed</a>).</p> <h3 id=oidc.scope><code>oidc.scope</code><a class=headerlink href=#oidc.scope title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-list>list of strings</a></li> <li><strong>Default:</strong> <code>[openid, profile, email]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_SCOPE</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>The scopes requested; include <code>openid</code>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=77:3><input checked=checked id=__tabbed_77_1 name=__tabbed_77 type=radio><input id=__tabbed_77_2 name=__tabbed_77 type=radio><input id=__tabbed_77_3 name=__tabbed_77 type=radio><div class=tabbed-labels><label for=__tabbed_77_1>YAML</label><label for=__tabbed_77_2>Environment</label><label for=__tabbed_77_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-253-1><a id=__codelineno-253-1 name=__codelineno-253-1 href=#__codelineno-253-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-253-2><a id=__codelineno-253-2 name=__codelineno-253-2 href=#__codelineno-253-2></a><span class=w> </span><span class=nt>scope</span><span class=p>:</span>
|
|
</span><span id=__span-253-3><a id=__codelineno-253-3 name=__codelineno-253-3 href=#__codelineno-253-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">openid</span>
|
|
</span><span id=__span-253-4><a id=__codelineno-253-4 name=__codelineno-253-4 href=#__codelineno-253-4></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">profile</span>
|
|
</span><span id=__span-253-5><a id=__codelineno-253-5 name=__codelineno-253-5 href=#__codelineno-253-5></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">email</span>
|
|
</span><span id=__span-253-6><a id=__codelineno-253-6 name=__codelineno-253-6 href=#__codelineno-253-6></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">groups</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-254-1><a id=__codelineno-254-1 name=__codelineno-254-1 href=#__codelineno-254-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_SCOPE</span><span class=o>=</span><span class=s1>'["openid","profile","email","groups"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-255-1><a id=__codelineno-255-1 name=__codelineno-255-1 href=#__codelineno-255-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>scope</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-255-2><a id=__codelineno-255-2 name=__codelineno-255-2 href=#__codelineno-255-2></a> <span class=s2>"openid"</span>
|
|
</span><span id=__span-255-3><a id=__codelineno-255-3 name=__codelineno-255-3 href=#__codelineno-255-3></a> <span class=s2>"profile"</span>
|
|
</span><span id=__span-255-4><a id=__codelineno-255-4 name=__codelineno-255-4 href=#__codelineno-255-4></a> <span class=s2>"email"</span>
|
|
</span><span id=__span-255-5><a id=__codelineno-255-5 name=__codelineno-255-5 href=#__codelineno-255-5></a> <span class=s2>"groups"</span>
|
|
</span><span id=__span-255-6><a id=__codelineno-255-6 name=__codelineno-255-6 href=#__codelineno-255-6></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.extra_params><code>oidc.extra_params</code><a class=headerlink href=#oidc.extra_params title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-map>map of <code><param></code> → string</a></li> <li><strong>Default:</strong> <code>{}</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_EXTRA_PARAMS</code> (<a href=#env>JSON object</a>)</li> </ul> <p>Sent as is to the provider's authorization endpoint, e.g. <code>domain_hint</code>; names keep their case.</p> <div class="tabbed-set tabbed-alternate" data-tabs=78:3><input checked=checked id=__tabbed_78_1 name=__tabbed_78 type=radio><input id=__tabbed_78_2 name=__tabbed_78 type=radio><input id=__tabbed_78_3 name=__tabbed_78 type=radio><div class=tabbed-labels><label for=__tabbed_78_1>YAML</label><label for=__tabbed_78_2>Environment</label><label for=__tabbed_78_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-256-1><a id=__codelineno-256-1 name=__codelineno-256-1 href=#__codelineno-256-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-256-2><a id=__codelineno-256-2 name=__codelineno-256-2 href=#__codelineno-256-2></a><span class=w> </span><span class=nt>extra_params</span><span class=p>:</span>
|
|
</span><span id=__span-256-3><a id=__codelineno-256-3 name=__codelineno-256-3 href=#__codelineno-256-3></a><span class=w> </span><span class=nt>domain_hint</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">example.com</span>
|
|
</span><span id=__span-256-4><a id=__codelineno-256-4 name=__codelineno-256-4 href=#__codelineno-256-4></a><span class=w> </span><span class=nt>prompt</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">select_account</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-257-1><a id=__codelineno-257-1 name=__codelineno-257-1 href=#__codelineno-257-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_EXTRA_PARAMS</span><span class=o>=</span><span class=s1>'{"domain_hint":"example.com","prompt":"select_account"}'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-258-1><a id=__codelineno-258-1 name=__codelineno-258-1 href=#__codelineno-258-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>extra_params</span> <span class=o>=</span> <span class=p>{</span>
|
|
</span><span id=__span-258-2><a id=__codelineno-258-2 name=__codelineno-258-2 href=#__codelineno-258-2></a> <span class=ss>domain_hint</span> <span class=o>=</span> <span class=s2>"example.com"</span><span class=p>;</span>
|
|
</span><span id=__span-258-3><a id=__codelineno-258-3 name=__codelineno-258-3 href=#__codelineno-258-3></a> <span class=ss>prompt</span> <span class=o>=</span> <span class=s2>"select_account"</span><span class=p>;</span>
|
|
</span><span id=__span-258-4><a id=__codelineno-258-4 name=__codelineno-258-4 href=#__codelineno-258-4></a><span class=p>};</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.allowed_domains><code>oidc.allowed_domains</code><a class=headerlink href=#oidc.allowed_domains title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-list>list of strings</a></li> <li><strong>Default:</strong> <code>[]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_ALLOWED_DOMAINS</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>Admits only users whose email domain is listed. Empty admits any domain.</p> <div class="tabbed-set tabbed-alternate" data-tabs=79:3><input checked=checked id=__tabbed_79_1 name=__tabbed_79 type=radio><input id=__tabbed_79_2 name=__tabbed_79 type=radio><input id=__tabbed_79_3 name=__tabbed_79 type=radio><div class=tabbed-labels><label for=__tabbed_79_1>YAML</label><label for=__tabbed_79_2>Environment</label><label for=__tabbed_79_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-259-1><a id=__codelineno-259-1 name=__codelineno-259-1 href=#__codelineno-259-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-259-2><a id=__codelineno-259-2 name=__codelineno-259-2 href=#__codelineno-259-2></a><span class=w> </span><span class=nt>allowed_domains</span><span class=p>:</span>
|
|
</span><span id=__span-259-3><a id=__codelineno-259-3 name=__codelineno-259-3 href=#__codelineno-259-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">example.com</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-260-1><a id=__codelineno-260-1 name=__codelineno-260-1 href=#__codelineno-260-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_ALLOWED_DOMAINS</span><span class=o>=</span><span class=s1>'["example.com"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-261-1><a id=__codelineno-261-1 name=__codelineno-261-1 href=#__codelineno-261-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>allowed_domains</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-261-2><a id=__codelineno-261-2 name=__codelineno-261-2 href=#__codelineno-261-2></a> <span class=s2>"example.com"</span>
|
|
</span><span id=__span-261-3><a id=__codelineno-261-3 name=__codelineno-261-3 href=#__codelineno-261-3></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.allowed_users><code>oidc.allowed_users</code><a class=headerlink href=#oidc.allowed_users title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-list>list of strings</a></li> <li><strong>Default:</strong> <code>[]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_ALLOWED_USERS</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>Admits only users whose email address is listed. Empty admits any user.</p> <div class="tabbed-set tabbed-alternate" data-tabs=80:3><input checked=checked id=__tabbed_80_1 name=__tabbed_80 type=radio><input id=__tabbed_80_2 name=__tabbed_80 type=radio><input id=__tabbed_80_3 name=__tabbed_80 type=radio><div class=tabbed-labels><label for=__tabbed_80_1>YAML</label><label for=__tabbed_80_2>Environment</label><label for=__tabbed_80_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-262-1><a id=__codelineno-262-1 name=__codelineno-262-1 href=#__codelineno-262-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-262-2><a id=__codelineno-262-2 name=__codelineno-262-2 href=#__codelineno-262-2></a><span class=w> </span><span class=nt>allowed_users</span><span class=p>:</span>
|
|
</span><span id=__span-262-3><a id=__codelineno-262-3 name=__codelineno-262-3 href=#__codelineno-262-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">alice@example.com</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-263-1><a id=__codelineno-263-1 name=__codelineno-263-1 href=#__codelineno-263-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_ALLOWED_USERS</span><span class=o>=</span><span class=s1>'["alice@example.com"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-264-1><a id=__codelineno-264-1 name=__codelineno-264-1 href=#__codelineno-264-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>allowed_users</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-264-2><a id=__codelineno-264-2 name=__codelineno-264-2 href=#__codelineno-264-2></a> <span class=s2>"alice@example.com"</span>
|
|
</span><span id=__span-264-3><a id=__codelineno-264-3 name=__codelineno-264-3 href=#__codelineno-264-3></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.allowed_groups><code>oidc.allowed_groups</code><a class=headerlink href=#oidc.allowed_groups title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-list>list of strings</a></li> <li><strong>Default:</strong> <code>[]</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_ALLOWED_GROUPS</code> (<a href=#env>space-separated or JSON array</a>)</li> </ul> <p>Admits only members of at least one listed group, from the provider's <code>groups</code> claim: UserInfo first, the ID token as fallback. Empty admits any group.</p> <div class="tabbed-set tabbed-alternate" data-tabs=81:3><input checked=checked id=__tabbed_81_1 name=__tabbed_81 type=radio><input id=__tabbed_81_2 name=__tabbed_81 type=radio><input id=__tabbed_81_3 name=__tabbed_81 type=radio><div class=tabbed-labels><label for=__tabbed_81_1>YAML</label><label for=__tabbed_81_2>Environment</label><label for=__tabbed_81_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-265-1><a id=__codelineno-265-1 name=__codelineno-265-1 href=#__codelineno-265-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-265-2><a id=__codelineno-265-2 name=__codelineno-265-2 href=#__codelineno-265-2></a><span class=w> </span><span class=nt>allowed_groups</span><span class=p>:</span>
|
|
</span><span id=__span-265-3><a id=__codelineno-265-3 name=__codelineno-265-3 href=#__codelineno-265-3></a><span class=w> </span><span class="p p-Indicator">-</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">headscale-users</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-266-1><a id=__codelineno-266-1 name=__codelineno-266-1 href=#__codelineno-266-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_ALLOWED_GROUPS</span><span class=o>=</span><span class=s1>'["headscale-users"]'</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-267-1><a id=__codelineno-267-1 name=__codelineno-267-1 href=#__codelineno-267-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>allowed_groups</span> <span class=o>=</span> <span class=p>[</span>
|
|
</span><span id=__span-267-2><a id=__codelineno-267-2 name=__codelineno-267-2 href=#__codelineno-267-2></a> <span class=s2>"headscale-users"</span>
|
|
</span><span id=__span-267-3><a id=__codelineno-267-3 name=__codelineno-267-3 href=#__codelineno-267-3></a><span class=p>];</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.email_verified_required><code>oidc.email_verified_required</code><a class=headerlink href=#oidc.email_verified_required title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_EMAIL_VERIFIED_REQUIRED</code></li> </ul> <p>Trusts an email only when the provider marks it verified: an unverified one fails <a href=#oidc.allowed_domains><code>oidc.allowed_domains</code></a> and <a href=#oidc.allowed_users><code>oidc.allowed_users</code></a> and is not copied to the user. Turn it off for a provider that does not send <code>email_verified</code>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=82:3><input checked=checked id=__tabbed_82_1 name=__tabbed_82 type=radio><input id=__tabbed_82_2 name=__tabbed_82 type=radio><input id=__tabbed_82_3 name=__tabbed_82 type=radio><div class=tabbed-labels><label for=__tabbed_82_1>YAML</label><label for=__tabbed_82_2>Environment</label><label for=__tabbed_82_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-268-1><a id=__codelineno-268-1 name=__codelineno-268-1 href=#__codelineno-268-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-268-2><a id=__codelineno-268-2 name=__codelineno-268-2 href=#__codelineno-268-2></a><span class=w> </span><span class=nt>email_verified_required</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-269-1><a id=__codelineno-269-1 name=__codelineno-269-1 href=#__codelineno-269-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_EMAIL_VERIFIED_REQUIRED</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-270-1><a id=__codelineno-270-1 name=__codelineno-270-1 href=#__codelineno-270-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>email_verified_required</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.use_expiry_from_token><code>oidc.use_expiry_from_token</code><a class=headerlink href=#oidc.use_expiry_from_token title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_USE_EXPIRY_FROM_TOKEN</code></li> </ul> <p>Expires an OIDC-registered node with its token, instead of <a href=#node.expiry><code>node.expiry</code></a>. Tokens are often short-lived, forcing frequent logins.</p> <div class="tabbed-set tabbed-alternate" data-tabs=83:3><input checked=checked id=__tabbed_83_1 name=__tabbed_83 type=radio><input id=__tabbed_83_2 name=__tabbed_83 type=radio><input id=__tabbed_83_3 name=__tabbed_83 type=radio><div class=tabbed-labels><label for=__tabbed_83_1>YAML</label><label for=__tabbed_83_2>Environment</label><label for=__tabbed_83_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-271-1><a id=__codelineno-271-1 name=__codelineno-271-1 href=#__codelineno-271-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-271-2><a id=__codelineno-271-2 name=__codelineno-271-2 href=#__codelineno-271-2></a><span class=w> </span><span class=nt>use_expiry_from_token</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-272-1><a id=__codelineno-272-1 name=__codelineno-272-1 href=#__codelineno-272-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_USE_EXPIRY_FROM_TOKEN</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-273-1><a id=__codelineno-273-1 name=__codelineno-273-1 href=#__codelineno-273-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span><span class=ss>use_expiry_from_token</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=oidc.pkce><code>oidc.pkce</code><a class=headerlink href=#oidc.pkce title="Permanent link">¶</a></h3> <p>Proof Key for Code Exchange (RFC 7636), which protects the authorization code from interception. See <a href=../oidc/#enable-pkce-recommended>Enable PKCE</a>.</p> <details class=example> <summary>All <code>oidc.pkce</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-274-1><a id=__codelineno-274-1 name=__codelineno-274-1 href=#__codelineno-274-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-274-2><a id=__codelineno-274-2 name=__codelineno-274-2 href=#__codelineno-274-2></a><span class=w> </span><span class=nt>pkce</span><span class=p>:</span>
|
|
</span><span id=__span-274-3><a id=__codelineno-274-3 name=__codelineno-274-3 href=#__codelineno-274-3></a><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">false</span>
|
|
</span><span id=__span-274-4><a id=__codelineno-274-4 name=__codelineno-274-4 href=#__codelineno-274-4></a><span class=w> </span><span class=nt>method</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">S256</span>
|
|
</span></code></pre></div> </details> <h4 id=oidc.pkce.enabled><code>oidc.pkce.enabled</code><a class=headerlink href=#oidc.pkce.enabled title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_PKCE_ENABLED</code></li> </ul> <p>Sends a PKCE challenge with each login.</p> <div class="tabbed-set tabbed-alternate" data-tabs=84:3><input checked=checked id=__tabbed_84_1 name=__tabbed_84 type=radio><input id=__tabbed_84_2 name=__tabbed_84 type=radio><input id=__tabbed_84_3 name=__tabbed_84 type=radio><div class=tabbed-labels><label for=__tabbed_84_1>YAML</label><label for=__tabbed_84_2>Environment</label><label for=__tabbed_84_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-275-1><a id=__codelineno-275-1 name=__codelineno-275-1 href=#__codelineno-275-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-275-2><a id=__codelineno-275-2 name=__codelineno-275-2 href=#__codelineno-275-2></a><span class=w> </span><span class=nt>pkce</span><span class=p>:</span>
|
|
</span><span id=__span-275-3><a id=__codelineno-275-3 name=__codelineno-275-3 href=#__codelineno-275-3></a><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></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-276-1><a id=__codelineno-276-1 name=__codelineno-276-1 href=#__codelineno-276-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_PKCE_ENABLED</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-277-1><a id=__codelineno-277-1 name=__codelineno-277-1 href=#__codelineno-277-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span>pkce<span class=o>.</span><span class=ss>enabled</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h4 id=oidc.pkce.method><code>oidc.pkce.method</code><a class=headerlink href=#oidc.pkce.method title="Permanent link">¶</a></h4> <ul> <li><strong>Type:</strong> <a href=#type-enum>enum</a>: <code>plain</code>, <code>S256</code></li> <li><strong>Default:</strong> <code>S256</code></li> <li><strong>Env:</strong> <code>HEADSCALE_OIDC_PKCE_METHOD</code></li> </ul> <p>How the code challenge is derived from the verifier. The verifier is sent as is in the token exchange.</p> <table> <thead> <tr> <th>Value</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>plain</code></td> <td>Sends the verifier itself as the challenge. Use it only with a provider that does not support <code>S256</code>.</td> </tr> <tr> <td><code>S256</code></td> <td>Sends the base64url SHA-256 of the verifier as the challenge. Recommended.</td> </tr> </tbody> </table> <div class="tabbed-set tabbed-alternate" data-tabs=85:3><input checked=checked id=__tabbed_85_1 name=__tabbed_85 type=radio><input id=__tabbed_85_2 name=__tabbed_85 type=radio><input id=__tabbed_85_3 name=__tabbed_85 type=radio><div class=tabbed-labels><label for=__tabbed_85_1>YAML</label><label for=__tabbed_85_2>Environment</label><label for=__tabbed_85_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-278-1><a id=__codelineno-278-1 name=__codelineno-278-1 href=#__codelineno-278-1></a><span class=nt>oidc</span><span class=p>:</span>
|
|
</span><span id=__span-278-2><a id=__codelineno-278-2 name=__codelineno-278-2 href=#__codelineno-278-2></a><span class=w> </span><span class=nt>pkce</span><span class=p>:</span>
|
|
</span><span id=__span-278-3><a id=__codelineno-278-3 name=__codelineno-278-3 href=#__codelineno-278-3></a><span class=w> </span><span class=nt>method</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">plain</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-279-1><a id=__codelineno-279-1 name=__codelineno-279-1 href=#__codelineno-279-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_OIDC_PKCE_METHOD</span><span class=o>=</span>plain
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-280-1><a id=__codelineno-280-1 name=__codelineno-280-1 href=#__codelineno-280-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>oidc<span class=o>.</span>pkce<span class=o>.</span><span class=ss>method</span> <span class=o>=</span> <span class=s2>"plain"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=logtail><code>logtail</code><a class=headerlink href=#logtail title="Permanent link">¶</a></h2> <p>Whether nodes send their logs to Tailscale.</p> <details class=example> <summary>All <code>logtail</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-281-1><a id=__codelineno-281-1 name=__codelineno-281-1 href=#__codelineno-281-1></a><span class=nt>logtail</span><span class=p>:</span>
|
|
</span><span id=__span-281-2><a id=__codelineno-281-2 name=__codelineno-281-2 href=#__codelineno-281-2></a><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">false</span>
|
|
</span></code></pre></div> </details> <h3 id=logtail.enabled><code>logtail.enabled</code><a class=headerlink href=#logtail.enabled title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_LOGTAIL_ENABLED</code></li> </ul> <p>Lets nodes send their logs to Tailscale Inc.; headscale cannot point them at another log server. False tells nodes not to.</p> <div class="tabbed-set tabbed-alternate" data-tabs=86:3><input checked=checked id=__tabbed_86_1 name=__tabbed_86 type=radio><input id=__tabbed_86_2 name=__tabbed_86 type=radio><input id=__tabbed_86_3 name=__tabbed_86 type=radio><div class=tabbed-labels><label for=__tabbed_86_1>YAML</label><label for=__tabbed_86_2>Environment</label><label for=__tabbed_86_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-282-1><a id=__codelineno-282-1 name=__codelineno-282-1 href=#__codelineno-282-1></a><span class=nt>logtail</span><span class=p>:</span>
|
|
</span><span id=__span-282-2><a id=__codelineno-282-2 name=__codelineno-282-2 href=#__codelineno-282-2></a><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></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-283-1><a id=__codelineno-283-1 name=__codelineno-283-1 href=#__codelineno-283-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_LOGTAIL_ENABLED</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-284-1><a id=__codelineno-284-1 name=__codelineno-284-1 href=#__codelineno-284-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>logtail<span class=o>.</span><span class=ss>enabled</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=taildrop><code>taildrop</code><a class=headerlink href=#taildrop title="Permanent link">¶</a></h2> <p>Taildrop, Tailscale's file sharing between nodes.</p> <details class=example> <summary>All <code>taildrop</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-285-1><a id=__codelineno-285-1 name=__codelineno-285-1 href=#__codelineno-285-1></a><span class=nt>taildrop</span><span class=p>:</span>
|
|
</span><span id=__span-285-2><a id=__codelineno-285-2 name=__codelineno-285-2 href=#__codelineno-285-2></a><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></code></pre></div> </details> <h3 id=taildrop.enabled><code>taildrop.enabled</code><a class=headerlink href=#taildrop.enabled title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>true</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TAILDROP_ENABLED</code></li> </ul> <p>Gives every node the file-sharing capability. False omits it from the baseline; a policy <code>nodeAttrs</code> grant can still give it.</p> <div class="tabbed-set tabbed-alternate" data-tabs=87:3><input checked=checked id=__tabbed_87_1 name=__tabbed_87 type=radio><input id=__tabbed_87_2 name=__tabbed_87 type=radio><input id=__tabbed_87_3 name=__tabbed_87 type=radio><div class=tabbed-labels><label for=__tabbed_87_1>YAML</label><label for=__tabbed_87_2>Environment</label><label for=__tabbed_87_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-286-1><a id=__codelineno-286-1 name=__codelineno-286-1 href=#__codelineno-286-1></a><span class=nt>taildrop</span><span class=p>:</span>
|
|
</span><span id=__span-286-2><a id=__codelineno-286-2 name=__codelineno-286-2 href=#__codelineno-286-2></a><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">false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-287-1><a id=__codelineno-287-1 name=__codelineno-287-1 href=#__codelineno-287-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TAILDROP_ENABLED</span><span class=o>=</span><span class=nb>false</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-288-1><a id=__codelineno-288-1 name=__codelineno-288-1 href=#__codelineno-288-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>taildrop<span class=o>.</span><span class=ss>enabled</span> <span class=o>=</span> <span class=no>false</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=auto_update><code>auto_update</code><a class=headerlink href=#auto_update title="Permanent link">¶</a></h2> <p>The tailnet-wide default for client auto-updates.</p> <details class=example> <summary>All <code>auto_update</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-289-1><a id=__codelineno-289-1 name=__codelineno-289-1 href=#__codelineno-289-1></a><span class=nt>auto_update</span><span class=p>:</span>
|
|
</span><span id=__span-289-2><a id=__codelineno-289-2 name=__codelineno-289-2 href=#__codelineno-289-2></a><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">false</span>
|
|
</span></code></pre></div> </details> <h3 id=auto_update.enabled><code>auto_update.enabled</code><a class=headerlink href=#auto_update.enabled title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_AUTO_UPDATE_ENABLED</code></li> </ul> <p>Makes auto-update the default for clients that have not chosen locally. Clients store the default they first see, so a later change reaches only new clients.</p> <div class="tabbed-set tabbed-alternate" data-tabs=88:3><input checked=checked id=__tabbed_88_1 name=__tabbed_88 type=radio><input id=__tabbed_88_2 name=__tabbed_88 type=radio><input id=__tabbed_88_3 name=__tabbed_88 type=radio><div class=tabbed-labels><label for=__tabbed_88_1>YAML</label><label for=__tabbed_88_2>Environment</label><label for=__tabbed_88_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-290-1><a id=__codelineno-290-1 name=__codelineno-290-1 href=#__codelineno-290-1></a><span class=nt>auto_update</span><span class=p>:</span>
|
|
</span><span id=__span-290-2><a id=__codelineno-290-2 name=__codelineno-290-2 href=#__codelineno-290-2></a><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></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-291-1><a id=__codelineno-291-1 name=__codelineno-291-1 href=#__codelineno-291-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_AUTO_UPDATE_ENABLED</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-292-1><a id=__codelineno-292-1 name=__codelineno-292-1 href=#__codelineno-292-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>auto_update<span class=o>.</span><span class=ss>enabled</span> <span class=o>=</span> <span class=no>true</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=cli><code>cli</code><a class=headerlink href=#cli title="Permanent link">¶</a></h2> <p>How the headscale CLI reaches the server: the local <a href=#unix_socket><code>unix_socket</code></a> without authentication, or a remote <a href=#cli.address><code>cli.address</code></a> with <a href=#cli.api_key><code>cli.api_key</code></a>. The CLI reads these keys from its own configuration, such as <code>~/.config/headscale/config.yaml</code>, or from <code>HEADSCALE_CLI_*</code> variables; the server does not read them, so on NixOS they do not belong in <code>services.headscale.settings</code>. See <a href=../api/#remote-control>Remote control</a>.</p> <details class=example> <summary>All <code>cli</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-293-1><a id=__codelineno-293-1 name=__codelineno-293-1 href=#__codelineno-293-1></a><span class=nt>cli</span><span class=p>:</span>
|
|
</span><span id=__span-293-2><a id=__codelineno-293-2 name=__codelineno-293-2 href=#__codelineno-293-2></a><span class=w> </span><span class=nt>address</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-293-3><a id=__codelineno-293-3 name=__codelineno-293-3 href=#__codelineno-293-3></a><span class=w> </span><span class=nt>api_key</span><span class=p>:</span><span class=w> </span><span class=s>""</span>
|
|
</span><span id=__span-293-4><a id=__codelineno-293-4 name=__codelineno-293-4 href=#__codelineno-293-4></a><span class=w> </span><span class=nt>timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">5s</span>
|
|
</span><span id=__span-293-5><a id=__codelineno-293-5 name=__codelineno-293-5 href=#__codelineno-293-5></a><span class=w> </span><span class=nt>insecure</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">false</span>
|
|
</span></code></pre></div> </details> <h3 id=cli.address><code>cli.address</code><a class=headerlink href=#cli.address title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-string>string</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_CLI_ADDRESS</code></li> </ul> <p>The remote server's host:port or URL; <code>https://</code> is assumed without a scheme. Empty uses <a href=#unix_socket><code>unix_socket</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=89:2><input checked=checked id=__tabbed_89_1 name=__tabbed_89 type=radio><input id=__tabbed_89_2 name=__tabbed_89 type=radio><div class=tabbed-labels><label for=__tabbed_89_1>YAML</label><label for=__tabbed_89_2>Environment</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-294-1><a id=__codelineno-294-1 name=__codelineno-294-1 href=#__codelineno-294-1></a><span class=nt>cli</span><span class=p>:</span>
|
|
</span><span id=__span-294-2><a id=__codelineno-294-2 name=__codelineno-294-2 href=#__codelineno-294-2></a><span class=w> </span><span class=nt>address</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">headscale.example.com:443</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-295-1><a id=__codelineno-295-1 name=__codelineno-295-1 href=#__codelineno-295-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_CLI_ADDRESS</span><span class=o>=</span>headscale.example.com:443
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=cli.api_key><code>cli.api_key</code><a class=headerlink href=#cli.api_key title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#secrets>secret</a></li> <li><strong>Default:</strong> <code>""</code></li> <li><strong>Env:</strong> <code>HEADSCALE_CLI_API_KEY</code></li> </ul> <p>The API key the CLI sends to <a href=#cli.address><code>cli.address</code></a>, or <code>file:<path></code> to read it from a file. Read only by the CLI.</p> <div class="tabbed-set tabbed-alternate" data-tabs=90:2><input checked=checked id=__tabbed_90_1 name=__tabbed_90 type=radio><input id=__tabbed_90_2 name=__tabbed_90 type=radio><div class=tabbed-labels><label for=__tabbed_90_1>YAML</label><label for=__tabbed_90_2>Environment</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-296-1><a id=__codelineno-296-1 name=__codelineno-296-1 href=#__codelineno-296-1></a><span class=nt>cli</span><span class=p>:</span>
|
|
</span><span id=__span-296-2><a id=__codelineno-296-2 name=__codelineno-296-2 href=#__codelineno-296-2></a><span class=w> </span><span class=nt>api_key</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">file:/run/secrets/headscale_api_key</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-297-1><a id=__codelineno-297-1 name=__codelineno-297-1 href=#__codelineno-297-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_CLI_API_KEY</span><span class=o>=</span>file:/run/secrets/headscale_api_key
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=cli.timeout><code>cli.timeout</code><a class=headerlink href=#cli.timeout title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>5s</code></li> <li><strong>Env:</strong> <code>HEADSCALE_CLI_TIMEOUT</code></li> </ul> <p>Bounds each CLI command's requests to the server.</p> <div class="tabbed-set tabbed-alternate" data-tabs=91:2><input checked=checked id=__tabbed_91_1 name=__tabbed_91 type=radio><input id=__tabbed_91_2 name=__tabbed_91 type=radio><div class=tabbed-labels><label for=__tabbed_91_1>YAML</label><label for=__tabbed_91_2>Environment</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-298-1><a id=__codelineno-298-1 name=__codelineno-298-1 href=#__codelineno-298-1></a><span class=nt>cli</span><span class=p>:</span>
|
|
</span><span id=__span-298-2><a id=__codelineno-298-2 name=__codelineno-298-2 href=#__codelineno-298-2></a><span class=w> </span><span class=nt>timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">30s</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-299-1><a id=__codelineno-299-1 name=__codelineno-299-1 href=#__codelineno-299-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_CLI_TIMEOUT</span><span class=o>=</span>30s
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=cli.insecure><code>cli.insecure</code><a class=headerlink href=#cli.insecure title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-boolean>boolean</a></li> <li><strong>Default:</strong> <code>false</code></li> <li><strong>Env:</strong> <code>HEADSCALE_CLI_INSECURE</code></li> </ul> <p>Skips TLS certificate verification of <a href=#cli.address><code>cli.address</code></a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=92:2><input checked=checked id=__tabbed_92_1 name=__tabbed_92 type=radio><input id=__tabbed_92_2 name=__tabbed_92 type=radio><div class=tabbed-labels><label for=__tabbed_92_1>YAML</label><label for=__tabbed_92_2>Environment</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-300-1><a id=__codelineno-300-1 name=__codelineno-300-1 href=#__codelineno-300-1></a><span class=nt>cli</span><span class=p>:</span>
|
|
</span><span id=__span-300-2><a id=__codelineno-300-2 name=__codelineno-300-2 href=#__codelineno-300-2></a><span class=w> </span><span class=nt>insecure</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-301-1><a id=__codelineno-301-1 name=__codelineno-301-1 href=#__codelineno-301-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_CLI_INSECURE</span><span class=o>=</span><span class=nb>true</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=tuning><code>tuning</code><a class=headerlink href=#tuning title="Permanent link">¶</a></h2> <p>Holds performance settings that rarely need changing.</p> <details class=example> <summary>All <code>tuning</code> keys and defaults</summary> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-302-1><a id=__codelineno-302-1 name=__codelineno-302-1 href=#__codelineno-302-1></a><span class=nt>tuning</span><span class=p>:</span>
|
|
</span><span id=__span-302-2><a id=__codelineno-302-2 name=__codelineno-302-2 href=#__codelineno-302-2></a><span class=w> </span><span class=nt>batch_change_delay</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">800ms</span>
|
|
</span><span id=__span-302-3><a id=__codelineno-302-3 name=__codelineno-302-3 href=#__codelineno-302-3></a><span class=w> </span><span class=nt>node_mapsession_buffered_chan_size</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">30</span>
|
|
</span><span id=__span-302-4><a id=__codelineno-302-4 name=__codelineno-302-4 href=#__codelineno-302-4></a><span class=w> </span><span class=nt>batcher_workers</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">0</span>
|
|
</span><span id=__span-302-5><a id=__codelineno-302-5 name=__codelineno-302-5 href=#__codelineno-302-5></a><span class=w> </span><span class=nt>register_cache_expiration</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">15m</span>
|
|
</span><span id=__span-302-6><a id=__codelineno-302-6 name=__codelineno-302-6 href=#__codelineno-302-6></a><span class=w> </span><span class=nt>register_cache_max_entries</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">1024</span>
|
|
</span><span id=__span-302-7><a id=__codelineno-302-7 name=__codelineno-302-7 href=#__codelineno-302-7></a><span class=w> </span><span class=nt>node_store_batch_size</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">100</span>
|
|
</span><span id=__span-302-8><a id=__codelineno-302-8 name=__codelineno-302-8 href=#__codelineno-302-8></a><span class=w> </span><span class=nt>node_store_batch_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">500ms</span>
|
|
</span></code></pre></div> </details> <h3 id=tuning.batch_change_delay><code>tuning.batch_change_delay</code><a class=headerlink href=#tuning.batch_change_delay title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>800ms</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TUNING_BATCH_CHANGE_DELAY</code></li> </ul> <p>How often queued changes are sent to clients as one update; must be positive.</p> <div class="tabbed-set tabbed-alternate" data-tabs=93:3><input checked=checked id=__tabbed_93_1 name=__tabbed_93 type=radio><input id=__tabbed_93_2 name=__tabbed_93 type=radio><input id=__tabbed_93_3 name=__tabbed_93 type=radio><div class=tabbed-labels><label for=__tabbed_93_1>YAML</label><label for=__tabbed_93_2>Environment</label><label for=__tabbed_93_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-303-1><a id=__codelineno-303-1 name=__codelineno-303-1 href=#__codelineno-303-1></a><span class=nt>tuning</span><span class=p>:</span>
|
|
</span><span id=__span-303-2><a id=__codelineno-303-2 name=__codelineno-303-2 href=#__codelineno-303-2></a><span class=w> </span><span class=nt>batch_change_delay</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">500ms</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-304-1><a id=__codelineno-304-1 name=__codelineno-304-1 href=#__codelineno-304-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TUNING_BATCH_CHANGE_DELAY</span><span class=o>=</span>500ms
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-305-1><a id=__codelineno-305-1 name=__codelineno-305-1 href=#__codelineno-305-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tuning<span class=o>.</span><span class=ss>batch_change_delay</span> <span class=o>=</span> <span class=s2>"500ms"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=tuning.node_mapsession_buffered_chan_size><code>tuning.node_mapsession_buffered_chan_size</code><a class=headerlink href=#tuning.node_mapsession_buffered_chan_size title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>30</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TUNING_NODE_MAPSESSION_BUFFERED_CHAN_SIZE</code></li> </ul> <p>How many map updates are queued per connected client.</p> <div class="tabbed-set tabbed-alternate" data-tabs=94:3><input checked=checked id=__tabbed_94_1 name=__tabbed_94 type=radio><input id=__tabbed_94_2 name=__tabbed_94 type=radio><input id=__tabbed_94_3 name=__tabbed_94 type=radio><div class=tabbed-labels><label for=__tabbed_94_1>YAML</label><label for=__tabbed_94_2>Environment</label><label for=__tabbed_94_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-306-1><a id=__codelineno-306-1 name=__codelineno-306-1 href=#__codelineno-306-1></a><span class=nt>tuning</span><span class=p>:</span>
|
|
</span><span id=__span-306-2><a id=__codelineno-306-2 name=__codelineno-306-2 href=#__codelineno-306-2></a><span class=w> </span><span class=nt>node_mapsession_buffered_chan_size</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">60</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-307-1><a id=__codelineno-307-1 name=__codelineno-307-1 href=#__codelineno-307-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TUNING_NODE_MAPSESSION_BUFFERED_CHAN_SIZE</span><span class=o>=</span><span class=m>60</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-308-1><a id=__codelineno-308-1 name=__codelineno-308-1 href=#__codelineno-308-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tuning<span class=o>.</span><span class=ss>node_mapsession_buffered_chan_size</span> <span class=o>=</span> <span class=mi>60</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=tuning.batcher_workers><code>tuning.batcher_workers</code><a class=headerlink href=#tuning.batcher_workers title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>0</code> (three quarters of the CPU cores, at least one)</li> <li><strong>Env:</strong> <code>HEADSCALE_TUNING_BATCHER_WORKERS</code></li> </ul> <p>The number of workers building map updates for connected clients. Zero picks the number from the CPU count.</p> <div class="tabbed-set tabbed-alternate" data-tabs=95:3><input checked=checked id=__tabbed_95_1 name=__tabbed_95 type=radio><input id=__tabbed_95_2 name=__tabbed_95 type=radio><input id=__tabbed_95_3 name=__tabbed_95 type=radio><div class=tabbed-labels><label for=__tabbed_95_1>YAML</label><label for=__tabbed_95_2>Environment</label><label for=__tabbed_95_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-309-1><a id=__codelineno-309-1 name=__codelineno-309-1 href=#__codelineno-309-1></a><span class=nt>tuning</span><span class=p>:</span>
|
|
</span><span id=__span-309-2><a id=__codelineno-309-2 name=__codelineno-309-2 href=#__codelineno-309-2></a><span class=w> </span><span class=nt>batcher_workers</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">8</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-310-1><a id=__codelineno-310-1 name=__codelineno-310-1 href=#__codelineno-310-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TUNING_BATCHER_WORKERS</span><span class=o>=</span><span class=m>8</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-311-1><a id=__codelineno-311-1 name=__codelineno-311-1 href=#__codelineno-311-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tuning<span class=o>.</span><span class=ss>batcher_workers</span> <span class=o>=</span> <span class=mi>8</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=tuning.register_cache_expiration><code>tuning.register_cache_expiration</code><a class=headerlink href=#tuning.register_cache_expiration title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>15m</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TUNING_REGISTER_CACHE_EXPIRATION</code></li> </ul> <p>How long a pending registration waits to be completed. Zero uses the default.</p> <div class="tabbed-set tabbed-alternate" data-tabs=96:3><input checked=checked id=__tabbed_96_1 name=__tabbed_96 type=radio><input id=__tabbed_96_2 name=__tabbed_96 type=radio><input id=__tabbed_96_3 name=__tabbed_96 type=radio><div class=tabbed-labels><label for=__tabbed_96_1>YAML</label><label for=__tabbed_96_2>Environment</label><label for=__tabbed_96_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-312-1><a id=__codelineno-312-1 name=__codelineno-312-1 href=#__codelineno-312-1></a><span class=nt>tuning</span><span class=p>:</span>
|
|
</span><span id=__span-312-2><a id=__codelineno-312-2 name=__codelineno-312-2 href=#__codelineno-312-2></a><span class=w> </span><span class=nt>register_cache_expiration</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-313-1><a id=__codelineno-313-1 name=__codelineno-313-1 href=#__codelineno-313-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TUNING_REGISTER_CACHE_EXPIRATION</span><span class=o>=</span>30m
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-314-1><a id=__codelineno-314-1 name=__codelineno-314-1 href=#__codelineno-314-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tuning<span class=o>.</span><span class=ss>register_cache_expiration</span> <span class=o>=</span> <span class=s2>"30m"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=tuning.register_cache_max_entries><code>tuning.register_cache_max_entries</code><a class=headerlink href=#tuning.register_cache_max_entries title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>1024</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TUNING_REGISTER_CACHE_MAX_ENTRIES</code></li> </ul> <p>Bounds pending registrations. At capacity, new registrations are refused without evicting pending ones; SSH checks have a small reserve beyond it. Zero uses the default. See <a href=../registration/#pending-authentication-limits>Pending authentication limits</a>.</p> <div class="tabbed-set tabbed-alternate" data-tabs=97:3><input checked=checked id=__tabbed_97_1 name=__tabbed_97 type=radio><input id=__tabbed_97_2 name=__tabbed_97 type=radio><input id=__tabbed_97_3 name=__tabbed_97 type=radio><div class=tabbed-labels><label for=__tabbed_97_1>YAML</label><label for=__tabbed_97_2>Environment</label><label for=__tabbed_97_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-315-1><a id=__codelineno-315-1 name=__codelineno-315-1 href=#__codelineno-315-1></a><span class=nt>tuning</span><span class=p>:</span>
|
|
</span><span id=__span-315-2><a id=__codelineno-315-2 name=__codelineno-315-2 href=#__codelineno-315-2></a><span class=w> </span><span class=nt>register_cache_max_entries</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">4096</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-316-1><a id=__codelineno-316-1 name=__codelineno-316-1 href=#__codelineno-316-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TUNING_REGISTER_CACHE_MAX_ENTRIES</span><span class=o>=</span><span class=m>4096</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-317-1><a id=__codelineno-317-1 name=__codelineno-317-1 href=#__codelineno-317-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tuning<span class=o>.</span><span class=ss>register_cache_max_entries</span> <span class=o>=</span> <span class=mi>4096</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=tuning.node_store_batch_size><code>tuning.node_store_batch_size</code><a class=headerlink href=#tuning.node_store_batch_size title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-integer>integer</a></li> <li><strong>Default:</strong> <code>100</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TUNING_NODE_STORE_BATCH_SIZE</code></li> </ul> <p>How many node changes are batched before the in-memory node state, peer relationships included, is rebuilt; must be positive. Higher values save CPU on bulk changes but delay each change until its batch is full or <a href=#tuning.node_store_batch_timeout><code>tuning.node_store_batch_timeout</code></a> passes.</p> <div class="tabbed-set tabbed-alternate" data-tabs=98:3><input checked=checked id=__tabbed_98_1 name=__tabbed_98 type=radio><input id=__tabbed_98_2 name=__tabbed_98 type=radio><input id=__tabbed_98_3 name=__tabbed_98 type=radio><div class=tabbed-labels><label for=__tabbed_98_1>YAML</label><label for=__tabbed_98_2>Environment</label><label for=__tabbed_98_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-318-1><a id=__codelineno-318-1 name=__codelineno-318-1 href=#__codelineno-318-1></a><span class=nt>tuning</span><span class=p>:</span>
|
|
</span><span id=__span-318-2><a id=__codelineno-318-2 name=__codelineno-318-2 href=#__codelineno-318-2></a><span class=w> </span><span class=nt>node_store_batch_size</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">200</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-319-1><a id=__codelineno-319-1 name=__codelineno-319-1 href=#__codelineno-319-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TUNING_NODE_STORE_BATCH_SIZE</span><span class=o>=</span><span class=m>200</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-320-1><a id=__codelineno-320-1 name=__codelineno-320-1 href=#__codelineno-320-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tuning<span class=o>.</span><span class=ss>node_store_batch_size</span> <span class=o>=</span> <span class=mi>200</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h3 id=tuning.node_store_batch_timeout><code>tuning.node_store_batch_timeout</code><a class=headerlink href=#tuning.node_store_batch_timeout title="Permanent link">¶</a></h3> <ul> <li><strong>Type:</strong> <a href=#type-duration>duration</a></li> <li><strong>Default:</strong> <code>500ms</code></li> <li><strong>Env:</strong> <code>HEADSCALE_TUNING_NODE_STORE_BATCH_TIMEOUT</code></li> </ul> <p>The longest a partial batch of node changes waits before the rebuild; must be positive. Lower values answer single changes faster at the cost of more rebuilds.</p> <div class="tabbed-set tabbed-alternate" data-tabs=99:3><input checked=checked id=__tabbed_99_1 name=__tabbed_99 type=radio><input id=__tabbed_99_2 name=__tabbed_99 type=radio><input id=__tabbed_99_3 name=__tabbed_99 type=radio><div class=tabbed-labels><label for=__tabbed_99_1>YAML</label><label for=__tabbed_99_2>Environment</label><label for=__tabbed_99_3>NixOS</label></div> <div class=tabbed-content> <div class=tabbed-block> <div class="language-yaml highlight"><pre><span></span><code><span id=__span-321-1><a id=__codelineno-321-1 name=__codelineno-321-1 href=#__codelineno-321-1></a><span class=nt>tuning</span><span class=p>:</span>
|
|
</span><span id=__span-321-2><a id=__codelineno-321-2 name=__codelineno-321-2 href=#__codelineno-321-2></a><span class=w> </span><span class=nt>node_store_batch_timeout</span><span class=p>:</span><span class=w> </span><span class="l l-Scalar l-Scalar-Plain">1s</span>
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-shell highlight"><pre><span></span><code><span id=__span-322-1><a id=__codelineno-322-1 name=__codelineno-322-1 href=#__codelineno-322-1></a><span class=nb>export</span><span class=w> </span><span class=nv>HEADSCALE_TUNING_NODE_STORE_BATCH_TIMEOUT</span><span class=o>=</span>1s
|
|
</span></code></pre></div> </div> <div class=tabbed-block> <div class="language-nix highlight"><pre><span></span><code><span id=__span-323-1><a id=__codelineno-323-1 name=__codelineno-323-1 href=#__codelineno-323-1></a>services<span class=o>.</span>headscale<span class=o>.</span>settings<span class=o>.</span>tuning<span class=o>.</span><span class=ss>node_store_batch_timeout</span> <span class=o>=</span> <span class=s2>"1s"</span><span class=p>;</span>
|
|
</span></code></pre></div> </div> </div> </div> <h2 id=removed-keys>Removed keys<a class=headerlink href=#removed-keys title="Permanent link">¶</a></h2> <p>Keys headscale no longer reads. One in the configuration file stops headscale with an error and a variable for one logs a warning, each saying what to do instead, as the table does.</p> <table> <thead> <tr> <th>Key</th> <th>Removed in</th> <th>What to do</th> </tr> </thead> <tbody> <tr> <td><span id=acl_policy_path></span><code>acl_policy_path</code></td> <td>0.30</td> <td>use <a href=#policy.path><code>policy.path</code></a></td> </tr> <tr> <td><span id=acme_email></span><code>acme_email</code></td> <td>0.30</td> <td>use <a href=#tls.acme.email><code>tls.acme.email</code></a></td> </tr> <tr> <td><span id=acme_url></span><code>acme_url</code></td> <td>0.30</td> <td>use <a href=#tls.acme.url><code>tls.acme.url</code></a></td> </tr> <tr> <td><span id=changes_check_interval></span><code>changes_check_interval</code></td> <td>0.30</td> <td>remove <code>changes_check_interval</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=database.gorm.prepare_stmt></span><code>database.gorm.prepare_stmt</code></td> <td>0.30</td> <td>remove <code>database.gorm.prepare_stmt</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=database.postgres.password_file></span><code>database.postgres.password_file</code></td> <td>0.30</td> <td>use <a href=#database.postgres.pass><code>database.postgres.pass</code></a>: <code>file:<path></code></td> </tr> <tr> <td><span id=db_host></span><code>db_host</code></td> <td>0.30</td> <td>use <a href=#database.postgres.host><code>database.postgres.host</code></a></td> </tr> <tr> <td><span id=db_name></span><code>db_name</code></td> <td>0.30</td> <td>use <a href=#database.postgres.name><code>database.postgres.name</code></a></td> </tr> <tr> <td><span id=db_pass></span><code>db_pass</code></td> <td>0.30</td> <td>use <a href=#database.postgres.pass><code>database.postgres.pass</code></a></td> </tr> <tr> <td><span id=db_password_file></span><code>db_password_file</code></td> <td>0.30</td> <td>use <a href=#database.postgres.pass><code>database.postgres.pass</code></a>: <code>file:<path></code></td> </tr> <tr> <td><span id=db_path></span><code>db_path</code></td> <td>0.30</td> <td>use <a href=#database.sqlite.path><code>database.sqlite.path</code></a></td> </tr> <tr> <td><span id=db_port></span><code>db_port</code></td> <td>0.30</td> <td>use <a href=#database.postgres.port><code>database.postgres.port</code></a></td> </tr> <tr> <td><span id=db_ssl></span><code>db_ssl</code></td> <td>0.30</td> <td>use <a href=#database.postgres.ssl><code>database.postgres.ssl</code></a></td> </tr> <tr> <td><span id=db_type></span><code>db_type</code></td> <td>0.30</td> <td>use <a href=#database.type><code>database.type</code></a></td> </tr> <tr> <td><span id=db_user></span><code>db_user</code></td> <td>0.30</td> <td>use <a href=#database.postgres.user><code>database.postgres.user</code></a></td> </tr> <tr> <td><span id=derp.server.stun.enabled></span><code>derp.server.stun.enabled</code></td> <td>0.30</td> <td>remove it: headscale never read it; the embedded DERP server always serves STUN on <a href=#derp.server.stun_listen_addr><code>derp.server.stun_listen_addr</code></a></td> </tr> <tr> <td><span id=derp_map_path></span><code>derp_map_path</code></td> <td>0.30</td> <td>use <a href=#derp.paths><code>derp.paths</code></a></td> </tr> <tr> <td><span id=dns.challenge.provider.setting_path></span><code>dns.challenge.provider.<setting>_path</code></td> <td>0.30</td> <td>use <a href=#dns.challenge.provider><code>dns.challenge.provider.<setting></code></a>: <code>file:<path></code></td> </tr> <tr> <td><span id=dns.split></span><code>dns.split</code></td> <td>0.30</td> <td>use <a href=#dns.nameservers.split><code>dns.nameservers.split</code></a></td> </tr> <tr> <td><span id=dns.use_username_in_magic_dns></span><code>dns.use_username_in_magic_dns</code></td> <td>0.24</td> <td>remove <code>dns.use_username_in_magic_dns</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=dns_config></span><code>dns_config</code></td> <td>0.30</td> <td>move every <code>dns_config.*</code> key to dns (nameservers to <a href=#dns.nameservers.global><code>dns.nameservers.global</code></a>, restricted_nameservers to <a href=#dns.nameservers.split><code>dns.nameservers.split</code></a>, domains to <a href=#dns.search_domains><code>dns.search_domains</code></a>)</td> </tr> <tr> <td><span id=dns_config.base_domain></span><code>dns_config.base_domain</code></td> <td>0.30</td> <td>use <a href=#dns.base_domain><code>dns.base_domain</code></a></td> </tr> <tr> <td><span id=dns_config.domains></span><code>dns_config.domains</code></td> <td>0.30</td> <td>use <a href=#dns.search_domains><code>dns.search_domains</code></a></td> </tr> <tr> <td><span id=dns_config.extra_records></span><code>dns_config.extra_records</code></td> <td>0.30</td> <td>use <a href=#dns.extra_records><code>dns.extra_records</code></a></td> </tr> <tr> <td><span id=dns_config.magic_dns></span><code>dns_config.magic_dns</code></td> <td>0.30</td> <td>use <a href=#dns.magic_dns><code>dns.magic_dns</code></a></td> </tr> <tr> <td><span id=dns_config.nameservers></span><code>dns_config.nameservers</code></td> <td>0.30</td> <td>use <a href=#dns.nameservers.global><code>dns.nameservers.global</code></a></td> </tr> <tr> <td><span id=dns_config.override_local_dns></span><code>dns_config.override_local_dns</code></td> <td>0.30</td> <td>use <a href=#dns.override_local_dns><code>dns.override_local_dns</code></a></td> </tr> <tr> <td><span id=dns_config.restricted_nameservers></span><code>dns_config.restricted_nameservers</code></td> <td>0.30</td> <td>use <a href=#dns.nameservers.split><code>dns.nameservers.split</code></a></td> </tr> <tr> <td><span id=dns_config.use_username_in_magic_dns></span><code>dns_config.use_username_in_magic_dns</code></td> <td>0.24</td> <td>remove <code>dns_config.use_username_in_magic_dns</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=ephemeral_node_inactivity_timeout></span><code>ephemeral_node_inactivity_timeout</code></td> <td>0.30</td> <td>use <a href=#node.ephemeral.inactivity_timeout><code>node.ephemeral.inactivity_timeout</code></a></td> </tr> <tr> <td><span id=grpc_allow_insecure></span><code>grpc_allow_insecure</code></td> <td>0.30</td> <td>remove <code>grpc_allow_insecure</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=grpc_listen_addr></span><code>grpc_listen_addr</code></td> <td>0.30</td> <td>remove <code>grpc_listen_addr</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=ip_prefixes></span><code>ip_prefixes</code></td> <td>0.23</td> <td>use <a href=#prefixes.v4><code>prefixes.v4</code></a> and <a href=#prefixes.v6><code>prefixes.v6</code></a></td> </tr> <tr> <td><span id=json_logs></span><code>json_logs</code></td> <td>0.30</td> <td>use <a href=#log.format><code>log.format</code></a>: <code>json</code></td> </tr> <tr> <td><span id=log_level></span><code>log_level</code></td> <td>0.17</td> <td>use <a href=#log.level><code>log.level</code></a></td> </tr> <tr> <td><span id=metrics_enabled></span><code>metrics_enabled</code></td> <td>0.30</td> <td>remove <code>metrics_enabled</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=node_update_check_interval></span><code>node_update_check_interval</code></td> <td>0.30</td> <td>remove <code>node_update_check_interval</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=noise_private_key_path></span><code>noise_private_key_path</code></td> <td>0.30</td> <td>use <a href=#noise.private_key_path><code>noise.private_key_path</code></a></td> </tr> <tr> <td><span id=oidc.client_secret_path></span><code>oidc.client_secret_path</code></td> <td>0.30</td> <td>use <a href=#oidc.client_secret><code>oidc.client_secret</code></a>: <code>file:<path></code></td> </tr> <tr> <td><span id=oidc.domain_map></span><code>oidc.domain_map</code></td> <td>0.13</td> <td>remove <code>oidc.domain_map</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=oidc.expiry></span><code>oidc.expiry</code></td> <td>0.29</td> <td>use <a href=#node.expiry><code>node.expiry</code></a></td> </tr> <tr> <td><span id=oidc.map_legacy_users></span><code>oidc.map_legacy_users</code></td> <td>0.26</td> <td>remove <code>oidc.map_legacy_users</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=oidc.namespace></span><code>oidc.namespace</code></td> <td>0.30</td> <td>remove <code>oidc.namespace</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=oidc.strip_email_domain></span><code>oidc.strip_email_domain</code></td> <td>0.26</td> <td>remove <code>oidc.strip_email_domain</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=oidc.user></span><code>oidc.user</code></td> <td>0.30</td> <td>remove <code>oidc.user</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=private_key_path></span><code>private_key_path</code></td> <td>0.23</td> <td>use <a href=#noise.private_key_path><code>noise.private_key_path</code></a></td> </tr> <tr> <td><span id=randomize_client_port></span><code>randomize_client_port</code></td> <td>0.29</td> <td>set "randomizeClientPort": true at the top level of the policy file, or grant the cap per node via a "nodeAttrs" entry</td> </tr> <tr> <td><span id=tls_cert_path></span><code>tls_cert_path</code></td> <td>0.30</td> <td>use <a href=#tls.cert_path><code>tls.cert_path</code></a></td> </tr> <tr> <td><span id=tls_client_auth_mode></span><code>tls_client_auth_mode</code></td> <td>0.30</td> <td>remove <code>tls_client_auth_mode</code>; see the CHANGELOG for context</td> </tr> <tr> <td><span id=tls_key_path></span><code>tls_key_path</code></td> <td>0.30</td> <td>use <a href=#tls.key_path><code>tls.key_path</code></a></td> </tr> <tr> <td><span id=tls_letsencrypt_cache_dir></span><code>tls_letsencrypt_cache_dir</code></td> <td>0.30</td> <td>use <a href=#tls.acme.cache_dir><code>tls.acme.cache_dir</code></a></td> </tr> <tr> <td><span id=tls_letsencrypt_challenge_type></span><code>tls_letsencrypt_challenge_type</code></td> <td>0.30</td> <td>use <a href=#tls.acme.challenge_type><code>tls.acme.challenge_type</code></a></td> </tr> <tr> <td><span id=tls_letsencrypt_hostname></span><code>tls_letsencrypt_hostname</code></td> <td>0.30</td> <td>use <a href=#tls.acme.hostname><code>tls.acme.hostname</code></a></td> </tr> <tr> <td><span id=tls_letsencrypt_listen></span><code>tls_letsencrypt_listen</code></td> <td>0.30</td> <td>use <a href=#tls.acme.http_listen><code>tls.acme.http_listen</code></a></td> </tr> <tr> <td><span id=tuning.notifier_send_timeout></span><code>tuning.notifier_send_timeout</code></td> <td>0.30</td> <td>remove it: it had no effect</td> </tr> </tbody> </table> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <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=../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 © 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-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) Copyright 2025 Fonticons, Inc.--><path d="M492.5 69.8c-.2-.3-.4-.6-.8-.7-38.1-17.5-78.4-30-119.7-37.1-.4-.1-.8 0-1.1.1s-.6.4-.8.8c-5.5 9.9-10.5 20.2-14.9 30.6-44.6-6.8-89.9-6.8-134.4 0-4.5-10.5-9.5-20.7-15.1-30.6-.2-.3-.5-.6-.8-.8s-.7-.2-1.1-.2C162.5 39 122.2 51.5 84.1 69c-.3.1-.6.4-.8.7C7.1 183.5-13.8 294.6-3.6 404.2c0 .3.1.5.2.8s.3.4.5.6c44.4 32.9 94 58 146.8 74.2.4.1.8.1 1.1 0s.7-.4.9-.7c11.3-15.4 21.4-31.8 30-48.8.1-.2.2-.5.2-.8s0-.5-.1-.8-.2-.5-.4-.6-.4-.3-.7-.4c-15.8-6.1-31.2-13.4-45.9-21.9-.3-.2-.5-.4-.7-.6s-.3-.6-.3-.9 0-.6.2-.9.3-.5.6-.7c3.1-2.3 6.2-4.7 9.1-7.1.3-.2.6-.4.9-.4s.7 0 1 .1c96.2 43.9 200.4 43.9 295.5 0 .3-.1.7-.2 1-.2s.7.2.9.4c2.9 2.4 6 4.9 9.1 7.2.2.2.4.4.6.7s.2.6.2.9-.1.6-.3.9-.4.5-.6.6c-14.7 8.6-30 15.9-45.9 21.8-.2.1-.5.2-.7.4s-.3.4-.4.7-.1.5-.1.8.1.5.2.8c8.8 17 18.8 33.3 30 48.8.2.3.6.6.9.7s.8.1 1.1 0c52.9-16.2 102.6-41.3 147.1-74.2.2-.2.4-.4.5-.6s.2-.5.2-.8c12.3-126.8-20.5-236.9-86.9-334.5zm-302 267.7c-29 0-52.8-26.6-52.8-59.2s23.4-59.2 52.8-59.2c29.7 0 53.3 26.8 52.8 59.2 0 32.7-23.4 59.2-52.8 59.2m195.4 0c-29 0-52.8-26.6-52.8-59.2s23.4-59.2 52.8-59.2c29.7 0 53.3 26.8 52.8 59.2 0 32.7-23.2 59.2-52.8 59.2"/></svg> </a> </div> </div> </div> </footer> </div> <div class=md-dialog data-md-component=dialog> <div class="md-dialog__inner md-typeset"></div> </div> <script id=__config type=application/json>{"annotate": {"json": [".s2"]}, "base": "../..", "code": null, "features": ["announce.dismiss", "content.action.edit", "content.action.view", "content.code.annotate", "content.code.copy", "content.tabs.link", "content.tooltips", "navigation.footer", "navigation.indexes", "navigation.sections", "navigation.tabs", "navigation.top", "navigation.tracking", "search.highlight", "search.share", "search.suggest", "toc.follow"], "search": {"options": {"indexUrl": "../../search/search_index.json", "offlineIndexUrl": "../../search/search_index.js", "suggest": true, "workerUrl": "../../assets/javascripts/workers/search.0af6d06b.min.js"}, "provider": "lunr"}, "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "code.collapse": "Collapse", "code.download": "Download", "code.expand": "Expand remaining # lines", "code.select": "Toggle line selection", "search.offline": "Switch to Lunr for offline search", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"alias": true, "provider": "mike"}}</script> <script src=../../assets/javascripts/bundle.19ace10b.min.js></script> </body> </html> |