From 319ce67c8785ca176674db3ef14239afce987014 Mon Sep 17 00:00:00 2001 From: Florian Preinstorfer Date: Mon, 16 Dec 2024 07:07:53 +0100 Subject: [PATCH] Update DNS documentation for dns.extra_records_path * Describe both ways to add extra DNS records * Use "extra" instead of "custom" to align with the configuration file * Include dns.extra_records_path in the configuration file --- config-example.yaml | 6 ++- docs/about/features.md | 2 +- docs/ref/dns.md | 88 ++++++++++++++++++++++++++++-------------- 3 files changed, 66 insertions(+), 30 deletions(-) diff --git a/config-example.yaml b/config-example.yaml index 529a80ed..cb7bf4da 100644 --- a/config-example.yaml +++ b/config-example.yaml @@ -301,7 +301,7 @@ dns: search_domains: [] # Extra DNS records - # so far only A-records are supported (on the tailscale side) + # so far only A and AAAA records are supported (on the tailscale side) # See: docs/ref/dns.md extra_records: [] # - name: "grafana.myvpn.example.com" @@ -310,6 +310,10 @@ dns: # # # you can also put it in one line # - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" } + # + # Alternatively, extra DNS records can be loaded from a JSON file. + # Headscale processes this file on each change. + # extra_records_path: /var/lib/headscale/extra-records.json # Unix socket used for the CLI to connect without authentication # Note: for production you will want to set this to something like: diff --git a/docs/about/features.md b/docs/about/features.md index 80e94874..d6d60cfd 100644 --- a/docs/about/features.md +++ b/docs/about/features.md @@ -12,7 +12,7 @@ provides on overview of headscale's feature and compatibility with the Tailscale - [x] [MagicDNS](https://tailscale.com/kb/1081/magicdns) - [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/kb/1054/dns#nameservers) - [x] [search domains](https://tailscale.com/kb/1054/dns#search-domains) - - [x] [Extra DNS records (headscale only)](../ref/dns.md#setting-custom-dns-records) + - [x] [Extra DNS records (headscale only)](../ref/dns.md#setting-extra-dns-records) - [x] [Taildrop (File Sharing)](https://tailscale.com/kb/1106/taildrop) - [x] Routing advertising (including exit nodes) - [x] Dual stack (IPv4 and IPv6) diff --git a/docs/ref/dns.md b/docs/ref/dns.md index 1e3ad897..09235106 100644 --- a/docs/ref/dns.md +++ b/docs/ref/dns.md @@ -1,44 +1,76 @@ # DNS -Headscale supports [most DNS features](../about/features.md) from Tailscale and DNS releated settings can be configured -in the [configuration file](./configuration.md) within the `dns` section. +Headscale supports [most DNS features](../about/features.md) from Tailscale. DNS releated settings can be configured +within `dns` section of the [configuration file](./configuration.md). -## Setting custom DNS records +## Setting extra DNS records -!!! warning "Community documentation" +Headscale allows to set extra DNS records which are made available via +[MagicDNS](https://tailscale.com/kb/1081/magicdns). Extra DNS records can be configured either via static entries in the +[configuration file](./configuration.md) or from a JSON file that Headscale continously watches for changes: - This page is not actively maintained by the headscale authors and is - written by community members. It is _not_ verified by headscale developers. +* Use the `dns.extra_records` option in the [configuration file](./configuration.md) for entries that are static and + don't change while Headscale is running. Those entries are processed when Headscale is starting up and changes to the + configuration require a restart of Headscale. +* For dynamic DNS records that may be added, updated or removed while Headscale is running or DNS records that are + generated by scripts the option `dns.extra_records_path` in the [configuration file](./configuration.md) is useful. + Set it to the absolute path of the JSON file containing DNS records and Headscale processes this file as it detects + changes. - **It might be outdated and it might miss necessary steps**. - -Headscale allows to set custom DNS records which are made available via -[MagicDNS](https://tailscale.com/kb/1081/magicdns). An example use case is to serve multiple apps on the same host via a -reverse proxy like NGINX, in this case a Prometheus monitoring stack. This allows to nicely access the service with -"http://grafana.myvpn.example.com" instead of the hostname and port combination -"http://hostname-in-magic-dns.myvpn.example.com:3000". +An example use case is to serve multiple apps on the same host via a reverse proxy like NGINX, in this case a Prometheus +monitoring stack. This allows to nicely access the service with "http://grafana.myvpn.example.com" instead of the +hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:3000". !!! warning "Limitations" - [Not all types of records are supported](https://github.com/tailscale/tailscale/blob/6edf357b96b28ee1be659a70232c0135b2ffedfd/ipn/ipnlocal/local.go#L2989-L3007), especially no CNAME records. + Currently, [only A and AAAA records are processed by Tailscale](https://github.com/tailscale/tailscale/blob/v1.78.3/ipn/ipnlocal/local.go#L4461-L4479). -1. Update the [configuration file](./configuration.md) to contain the desired records like so: - ```yaml - dns: - ... - extra_records: - - name: "prometheus.myvpn.example.com" - type: "A" - value: "100.64.0.3" +1. Configure extra DNS records using one of the available configuration options: - - name: "grafana.myvpn.example.com" - type: "A" - value: "100.64.0.3" - ... - ``` + === "Static entries, via `dns.extra_records`" -1. Restart your headscale instance. + ```yaml + dns: + ... + extra_records: + - name: "grafana.myvpn.example.com" + type: "A" + value: "100.64.0.3" + + - name: "prometheus.myvpn.example.com" + type: "A" + value: "100.64.0.3" + ... + ``` + + Restart your headscale instance. + + === "Dynamic entries, via `dns.extra_records_path`" + + ```json + [ + { + "name": "grafana.myvpn.example.com", + "type": "A", + "value": "100.64.0.3" + }, + { + "name": "prometheus.myvpn.example.com", + "type": "A", + "value": "100.64.0.3" + } + ] + ``` + + Headscale picks up changes to the above JSON file automatically. + + !!! tip "Good to know" + + * The `dns.extra_records_path` option in the [configuration file](./configuration.md) needs to reference the + JSON file containing extra DNS records. + * Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script. + Headscale uses a checksum to detect changes to the file and a stable output avoids unnecessary processing. 1. Verify that DNS records are properly set using the DNS querying tool of your choice: