From c9e4da3ff5d4879a27ba8d4ca1618010d7573d7a Mon Sep 17 00:00:00 2001
From: Juan Font Alonso <juanfontalonso@gmail.com>
Date: Sat, 2 Oct 2021 11:11:18 +0200
Subject: [PATCH] Improving documentation for DNS config

---
 config.json.postgres.example |  5 ++++-
 config.json.sqlite.example   |  5 ++++-
 docs/DNS.md                  | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 2 deletions(-)
 create mode 100644 docs/DNS.md

diff --git a/config.json.postgres.example b/config.json.postgres.example
index aba72063..5e5c5395 100644
--- a/config.json.postgres.example
+++ b/config.json.postgres.example
@@ -20,6 +20,9 @@
     "dns_config": {
         "nameservers": [
             "1.1.1.1"
-        ]
+        ],
+        "domains": [],
+        "magic_dns": true,
+        "base_domain": "example.com"
     }
 }
diff --git a/config.json.sqlite.example b/config.json.sqlite.example
index b22e5ace..a357bc85 100644
--- a/config.json.sqlite.example
+++ b/config.json.sqlite.example
@@ -16,6 +16,9 @@
     "dns_config": {
         "nameservers": [
             "1.1.1.1"
-        ]
+        ],
+        "domains": [],
+        "magic_dns": true,
+        "base_domain": "example.com"
     }
 }
diff --git a/docs/DNS.md b/docs/DNS.md
new file mode 100644
index 00000000..ca151bf2
--- /dev/null
+++ b/docs/DNS.md
@@ -0,0 +1,33 @@
+# DNS in Headscale
+
+Headscale supports Tailscale's DNS configuration and MagicDNS. Please have a look to their KB to better understand what this means:
+
+- https://tailscale.com/kb/1054/dns/
+- https://tailscale.com/kb/1081/magicdns/
+- https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
+
+Long story short, you can define the DNS servers you want to use in your tailnets, activate MagicDNS (so you don't have to remember the IP addresses of your nodes), define search domains, as well as predefined hosts. Headscale will inject that settings into your nodes.
+
+
+## Configuration reference
+
+The setup is done via the `config.json` file, under the `dns_config` key. 
+
+```json
+{
+    "server_url": "http://127.0.0.1:8001",
+    "listen_addr": "0.0.0.0:8001",
+    "private_key_path": "private.key",
+    //...
+    "dns_config": {
+        "nameservers": ["1.1.1.1", "8.8.8.8"],
+        "domains": [],
+        "magic_dns": true,
+        "base_domain": "example.com"
+    }
+}
+```
+- `nameservers`:  The list of DNS servers to use.
+- `domains`: Search domains to inject.
+- `magic_dns`: Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
+- `base_domain`: 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_).
\ No newline at end of file