From 271cb71754961cfe9a1cc3e82917255e9cd8fa4e Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Sun, 2 Jan 2022 19:38:04 +0000 Subject: [PATCH] Add more explaination and less redunancy with docs --- config-example.yaml | 87 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 79 insertions(+), 8 deletions(-) diff --git a/config-example.yaml b/config-example.yaml index aceb8ada..e26f06e8 100644 --- a/config-example.yaml +++ b/config-example.yaml @@ -1,21 +1,38 @@ --- # The url clients will connect to. -# Typically this will be a domain. +# Typically this will be a domain like: +# +# https://myheadscale.example.com:443 +# server_url: http://127.0.0.1:8080 # Address to listen to / bind to on the server +# listen_addr: 0.0.0.0:8080 -# Private key file which will be +# Private key used encrypt the traffic between headscale +# and Tailscale clients. +# The private key file which will be # autogenerated if it's missing private_key_path: /var/lib/headscale/private.key +# DERP is a relay system that Tailscale uses when a direct +# connection cannot be established. +# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp +# +# headscale needs a list of DERP servers that can be presented +# to the clients. derp: # List of externally available DERP maps encoded in JSON urls: - https://controlplane.tailscale.com/derpmap/default # Locally available DERP map files encoded in YAML + # + # This option is mostly interesting for people hosting + # their own DERP servers: + # https://tailscale.com/kb/1118/custom-derp-servers/ + # # paths: # - /etc/headscale/derp-example.yaml @@ -24,11 +41,13 @@ derp: # will be set up. auto_update_enabled: true - # How often should we check for updates? + # How often should we check for DERP updates? update_frequency: 24h -# Disables the automatic check for updates on startup +# Disables the automatic check for headscale updates on startup disable_check_updates: false + +# Time before an inactive ephemeral node is deleted? ephemeral_node_inactivity_timeout: 30m # SQLite config @@ -43,35 +62,87 @@ db_path: /var/lib/headscale/db.sqlite # db_user: foo # db_pass: bar +### TLS configuration +# +## Let's encrypt / ACME +# +# headscale supports automatically requesting and setting up +# TLS for a domain with Let's Encrypt. +# +# URL to ACME directory acme_url: https://acme-v02.api.letsencrypt.org/directory + +# Email to register with ACME provider acme_email: "" +# Domain name to request a TLS certificate for: tls_letsencrypt_hostname: "" -tls_letsencrypt_listen: ":http" -tls_letsencrypt_cache_dir: /var/lib/headscale/cache -tls_letsencrypt_challenge_type: HTTP-01 +# Path to store certificates and metadata needed by +# letsencrypt +tls_letsencrypt_cache_dir: /var/lib/headscale/cache + +# Type of ACME challenge to use, currently supported types: +# HTTP-01 or TLS_ALPN-01 +# See [docs/tls.md](docs/tls.md) for more information +tls_letsencrypt_challenge_type: HTTP-01 +# When HTTP-01 challenge is chosen, letsencrypt must set up a +# verification endpoint, and it will be listning on: +# :http = port 80 +tls_letsencrypt_listen: ":http" + +## Use already defined certificates: tls_cert_path: "" tls_key_path: "" log_level: info # Path to a file containg ACL policies. +# Recommended path: /etc/headscale/acl.hujson acl_policy_path: "" +## DNS +# +# headscale supports Tailscale's DNS configuration and MagicDNS. +# Please have a look to their KB to better understand the concepts: +# +# - https://tailscale.com/kb/1054/dns/ +# - https://tailscale.com/kb/1081/magicdns/ +# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/ +# dns_config: - # Upstream DNS servers + # List of DNS servers to expose to clients. nameservers: - 1.1.1.1 + + # Split DNS (see https://tailscale.com/kb/1054/dns/), + # list of search domains and the DNS to query for each one. + # + # restricted_nameservers: + # foo.bar.com: + # - 1.1.1.1 + # darp.headscale.net: + # - 1.1.1.1 + # - 8.8.8.8 + + # Search domains to inject. domains: [] + # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/). + # Only works if there is at least a nameserver defined. magic_dns: true + + # Defines the base domain to create the hostnames for MagicDNS. + # `base_domain` must be a FQDNs, without the trailing dot. + # The FQDN of the hosts will be + # `hostname.namespace.base_domain` (e.g., _myhost.mynamespace.example.com_). base_domain: example.com # Unix socket used for the CLI to connect without authentication # Note: for local development, you probably want to change this to: # unix_socket: ./headscale.sock unix_socket: /var/run/headscale.sock +# # headscale supports experimental OpenID connect support, # it is still being tested and might have some bugs, please # help us test it.