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
nblock · Dec 16, 2024 · 364d3cd · 364d3cd
1 parent 9e66c0a
commit 364d3cd
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 30 deletions.
diff --git 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
@@ -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
@@ -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`"
+
+        ```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 known"
 
-1.  Restart your headscale instance.
+            * 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: