|
| 1 | +--- |
| 2 | +# headscale will look for a configuration file named `config.yaml` (or `config.json`) in the following order: |
| 3 | +# |
| 4 | +# - `/etc/headscale` |
| 5 | +# - `~/.headscale` |
| 6 | +# - current working directory |
| 7 | + |
| 8 | +# The url clients will connect to. |
| 9 | +# Typically this will be a domain like: |
| 10 | +# |
| 11 | +# https://myheadscale.example.com:443 |
| 12 | +# |
| 13 | +server_url: https://headscale.example.com # change to your domain |
| 14 | + |
| 15 | +# Address to listen to / bind to on the server |
| 16 | +# |
| 17 | +listen_addr: 0.0.0.0:8080 |
| 18 | + |
| 19 | +# Address to listen to /metrics, you may want |
| 20 | +# to keep this endpoint private to your internal |
| 21 | +# network |
| 22 | +# |
| 23 | +metrics_listen_addr: 127.0.0.1:9090 |
| 24 | + |
| 25 | +# Address to listen for gRPC. |
| 26 | +# gRPC is used for controlling a headscale server |
| 27 | +# remotely with the CLI |
| 28 | +# Note: Remote access _only_ works if you have |
| 29 | +# valid certificates. |
| 30 | +grpc_listen_addr: 0.0.0.0:50443 |
| 31 | + |
| 32 | +# Allow the gRPC admin interface to run in INSECURE |
| 33 | +# mode. This is not recommended as the traffic will |
| 34 | +# be unencrypted. Only enable if you know what you |
| 35 | +# are doing. |
| 36 | +grpc_allow_insecure: false |
| 37 | + |
| 38 | +# Private key used encrypt the traffic between headscale |
| 39 | +# and Tailscale clients. |
| 40 | +# The private key file which will be |
| 41 | +# autogenerated if it's missing |
| 42 | +private_key_path: /var/lib/headscale/private.key |
| 43 | + |
| 44 | +# The Noise section includes specific configuration for the |
| 45 | +# TS2021 Noise protocol |
| 46 | +noise: |
| 47 | + # The Noise private key is used to encrypt the |
| 48 | + # traffic between headscale and Tailscale clients when |
| 49 | + # using the new Noise-based protocol. |
| 50 | + private_key_path: /var/lib/headscale/noise_private.key |
| 51 | + |
| 52 | +# List of IP prefixes to allocate tailaddresses from. |
| 53 | +# Each prefix consists of either an IPv4 or IPv6 address, |
| 54 | +# and the associated prefix length, delimited by a slash. |
| 55 | +ip_prefixes: |
| 56 | + - fd7a:115c:a1e0::/48 |
| 57 | + - 100.64.0.0/10 |
| 58 | + |
| 59 | +# DERP is a relay system that Tailscale uses when a direct |
| 60 | +# connection cannot be established. |
| 61 | +# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp |
| 62 | +# |
| 63 | +# headscale needs a list of DERP servers that can be presented |
| 64 | +# to the clients. |
| 65 | +derp: |
| 66 | + server: |
| 67 | + # If enabled, runs the embedded DERP server and merges it into the rest of the DERP config |
| 68 | + # The Headscale server_url defined above MUST be using https, DERP requires TLS to be in place |
| 69 | + enabled: false |
| 70 | + |
| 71 | + # Region ID to use for the embedded DERP server. |
| 72 | + # The local DERP prevails if the region ID collides with other region ID coming from |
| 73 | + # the regular DERP config. |
| 74 | + region_id: 999 |
| 75 | + |
| 76 | + # Region code and name are displayed in the Tailscale UI to identify a DERP region |
| 77 | + region_code: "headscale" |
| 78 | + region_name: "Headscale Embedded DERP" |
| 79 | + |
| 80 | + # Listens in UDP at the configured address for STUN connections to help on NAT traversal. |
| 81 | + # When the embedded DERP server is enabled stun_listen_addr MUST be defined. |
| 82 | + # |
| 83 | + # For more details on how this works, check this great article: https://tailscale.com/blog/how-tailscale-works/ |
| 84 | + stun_listen_addr: "0.0.0.0:3478" |
| 85 | + |
| 86 | + # List of externally available DERP maps encoded in JSON |
| 87 | + urls: |
| 88 | + - https://controlplane.tailscale.com/derpmap/default |
| 89 | + |
| 90 | + # Locally available DERP map files encoded in YAML |
| 91 | + # |
| 92 | + # This option is mostly interesting for people hosting |
| 93 | + # their own DERP servers: |
| 94 | + # https://tailscale.com/kb/1118/custom-derp-servers/ |
| 95 | + # |
| 96 | + # paths: |
| 97 | + # - /etc/headscale/derp-example.yaml |
| 98 | + paths: [] |
| 99 | + |
| 100 | + # If enabled, a worker will be set up to periodically |
| 101 | + # refresh the given sources and update the derpmap |
| 102 | + # will be set up. |
| 103 | + auto_update_enabled: true |
| 104 | + |
| 105 | + # How often should we check for DERP updates? |
| 106 | + update_frequency: 24h |
| 107 | + |
| 108 | +# Disables the automatic check for headscale updates on startup |
| 109 | +disable_check_updates: false |
| 110 | + |
| 111 | +# Time before an inactive ephemeral node is deleted? |
| 112 | +ephemeral_node_inactivity_timeout: 30m |
| 113 | + |
| 114 | +# Period to check for node updates in the tailnet. A value too low will severily affect |
| 115 | +# CPU consumption of Headscale. A value too high (over 60s) will cause problems |
| 116 | +# to the nodes, as they won't get updates or keep alive messages in time. |
| 117 | +# In case of doubts, do not touch the default 10s. |
| 118 | +node_update_check_interval: 10s |
| 119 | + |
| 120 | +# SQLite config |
| 121 | +db_type: sqlite3 |
| 122 | +db_path: /var/lib/headscale/db.sqlite |
| 123 | + |
| 124 | +# # Postgres config |
| 125 | +# If using a Unix socket to connect to Postgres, set the socket path in the 'host' field and leave 'port' blank. |
| 126 | +# db_type: postgres |
| 127 | +# db_host: localhost |
| 128 | +# db_port: 5432 |
| 129 | +# db_name: headscale |
| 130 | +# db_user: foo |
| 131 | +# db_pass: bar |
| 132 | +# db_ssl: false |
| 133 | + |
| 134 | +### TLS configuration |
| 135 | +# |
| 136 | +## Let's encrypt / ACME |
| 137 | +# |
| 138 | +# headscale supports automatically requesting and setting up |
| 139 | +# TLS for a domain with Let's Encrypt. |
| 140 | +# |
| 141 | +# URL to ACME directory |
| 142 | +acme_url: https://acme-v02.api.letsencrypt.org/directory |
| 143 | + |
| 144 | +# Email to register with ACME provider |
| 145 | +acme_email: "" |
| 146 | + |
| 147 | +# Domain name to request a TLS certificate for: |
| 148 | +tls_letsencrypt_hostname: "" |
| 149 | + |
| 150 | +# Client (Tailscale/Browser) authentication mode (mTLS) |
| 151 | +# Acceptable values: |
| 152 | +# - disabled: client authentication disabled |
| 153 | +# - relaxed: client certificate is required but not verified |
| 154 | +# - enforced: client certificate is required and verified |
| 155 | +tls_client_auth_mode: relaxed |
| 156 | + |
| 157 | +# Path to store certificates and metadata needed by |
| 158 | +# letsencrypt |
| 159 | +tls_letsencrypt_cache_dir: /var/lib/headscale/cache |
| 160 | + |
| 161 | +# Type of ACME challenge to use, currently supported types: |
| 162 | +# HTTP-01 or TLS-ALPN-01 |
| 163 | +# See [docs/tls.md](docs/tls.md) for more information |
| 164 | +tls_letsencrypt_challenge_type: HTTP-01 |
| 165 | +# When HTTP-01 challenge is chosen, letsencrypt must set up a |
| 166 | +# verification endpoint, and it will be listning on: |
| 167 | +# :http = port 80 |
| 168 | +tls_letsencrypt_listen: ":http" |
| 169 | + |
| 170 | +## Use already defined certificates: |
| 171 | +tls_cert_path: "" |
| 172 | +tls_key_path: "" |
| 173 | + |
| 174 | +log_level: info |
| 175 | + |
| 176 | +# Path to a file containg ACL policies. |
| 177 | +# ACLs can be defined as YAML or HUJSON. |
| 178 | +# https://tailscale.com/kb/1018/acls/ |
| 179 | +acl_policy_path: "" |
| 180 | + |
| 181 | +## DNS |
| 182 | +# |
| 183 | +# headscale supports Tailscale's DNS configuration and MagicDNS. |
| 184 | +# Please have a look to their KB to better understand the concepts: |
| 185 | +# |
| 186 | +# - https://tailscale.com/kb/1054/dns/ |
| 187 | +# - https://tailscale.com/kb/1081/magicdns/ |
| 188 | +# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/ |
| 189 | +# |
| 190 | +dns_config: |
| 191 | + # List of DNS servers to expose to clients. |
| 192 | + nameservers: |
| 193 | + - 1.1.1.1 |
| 194 | + |
| 195 | + # Split DNS (see https://tailscale.com/kb/1054/dns/), |
| 196 | + # list of search domains and the DNS to query for each one. |
| 197 | + # |
| 198 | + # restricted_nameservers: |
| 199 | + # foo.bar.com: |
| 200 | + # - 1.1.1.1 |
| 201 | + # darp.headscale.net: |
| 202 | + # - 1.1.1.1 |
| 203 | + # - 8.8.8.8 |
| 204 | + |
| 205 | + # Search domains to inject. |
| 206 | + domains: [] |
| 207 | + |
| 208 | + # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/). |
| 209 | + # Only works if there is at least a nameserver defined. |
| 210 | + magic_dns: true |
| 211 | + |
| 212 | + # Defines the base domain to create the hostnames for MagicDNS. |
| 213 | + # `base_domain` must be a FQDNs, without the trailing dot. |
| 214 | + # The FQDN of the hosts will be |
| 215 | + # `hostname.namespace.base_domain` (e.g., _myhost.mynamespace.example.com_). |
| 216 | + base_domain: example.com |
| 217 | + |
| 218 | +# Unix socket used for the CLI to connect without authentication |
| 219 | +# Note: for local development, you probably want to change this to: |
| 220 | +# unix_socket: ./headscale.sock |
| 221 | +unix_socket: /var/run/headscale.sock |
| 222 | +unix_socket_permission: "0770" |
| 223 | +# |
| 224 | +# headscale supports experimental OpenID connect support, |
| 225 | +# it is still being tested and might have some bugs, please |
| 226 | +# help us test it. |
| 227 | +# OpenID Connect |
| 228 | +# oidc: |
| 229 | +# issuer: "https://your-oidc.issuer.com/path" |
| 230 | +# client_id: "your-oidc-client-id" |
| 231 | +# client_secret: "your-oidc-client-secret" |
| 232 | +# |
| 233 | +# Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query |
| 234 | +# parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email". |
| 235 | +# |
| 236 | +# scope: ["openid", "profile", "email", "custom"] |
| 237 | +# extra_params: |
| 238 | +# domain_hint: example.com |
| 239 | +# |
| 240 | +# List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the |
| 241 | +# authentication request will be rejected. |
| 242 | +# |
| 243 | +# allowed_domains: |
| 244 | +# - example.com |
| 245 | +# allowed_users: |
| 246 | + |
| 247 | +# |
| 248 | +# If `strip_email_domain` is set to `true`, the domain part of the username email address will be removed. |
| 249 | +# This will transform `[email protected]` to the namespace `first-name.last-name` |
| 250 | +# If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the following |
| 251 | +# namespace: `first-name.last-name.example.com` |
| 252 | +# |
| 253 | +# strip_email_domain: true |
| 254 | + |
| 255 | +# Logtail configuration |
| 256 | +# Logtail is Tailscales logging and auditing infrastructure, it allows the control panel |
| 257 | +# to instruct tailscale nodes to log their activity to a remote server. |
| 258 | +logtail: |
| 259 | + # Enable logtail for this headscales clients. |
| 260 | + # As there is currently no support for overriding the log server in headscale, this is |
| 261 | + # disabled by default. Enabling this will make your clients send logs to Tailscale Inc. |
| 262 | + enabled: false |
| 263 | + |
| 264 | +# Enabling this option makes devices prefer a random port for WireGuard traffic over the |
| 265 | +# default static port 41641. This option is intended as a workaround for some buggy |
| 266 | +# firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information. |
| 267 | +randomize_client_port: false |
0 commit comments