option set: statements with a name replace only that one; forwarding over TLS documented

jarl option set tls NAME (and key, remote-servers, primaries, http, dnssec-policy, key-store, server, acl, view, zone, parental-agents) matches the name after the keyword too: setting tls cloudflare no longer replaces tls quad9. jarl option unset tls NAME removes one by its name. docs/encrypted-dns.md has forwarding to Quad9 or Cloudflare over TLS: one changeset, the options explained, several providers, checking it works, and why not over HTTPS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/cli.md

@@ -482,12 +482,22 @@ jarl option set allow-transfer 'key xfer; 10.0.10.53' --zone adbraun.lol
 jarl option set allow-query '10.0.20.1-10.0.20.99; localhost' --view internal
 jarl option set response-policy '{ zone "rpz.local"; }' --view internal
 jarl option set logging '{ channel q { file "/var/log/named/query.log" versions 3 size 20m; }; category queries { q; }; }' --toplevel
+jarl option set tls 'quad9 { remote-hostname "dns.quad9.net"; ca-file "/etc/ssl/certs/ca-certificates.crt"; }' --toplevel
+jarl option set tls 'cloudflare { remote-hostname "cloudflare-dns.com"; }' --toplevel   # tls quad9 stays
+jarl option unset tls cloudflare --toplevel          # statements with a name: say which
 jarl option unset forwarders
 jarl option describe                          # every option allowed at this scope
 jarl option describe allow-query-cache        # grammar and ARM description
 jarl option generated                         # what Jarl adds to named.conf by itself, and why
 ```
 
+`option set` replaces the option of that name. Statements told apart by
+the name after the keyword (`tls NAME`, `key NAME`, `remote-servers NAME`,
+`http NAME`, `dnssec-policy NAME`, `server ADDRESS`, ...) replace only the
+one with that name; `--add` adds another instance of any other option that
+may occur several times. Forwarding to Quad9 or Cloudflare over TLS:
+[encrypted-dns.md](encrypted-dns.md#forwarding-over-tls).
+
 Options that end in a list (`allow-*`, `forwarders`, `listen-on`, ...) may
 be given without the braces: elements are separated by `;`, `,` or spaces,
 and `key NAME` and `port N` stay with their element. Options are always

docs/encrypted-dns.md

@@ -14,6 +14,10 @@ host name's address records in your private views.
 In the web UI: **Encrypted DNS** (administrators). In the CLI: `jarl
 encrypted-dns`. In the API: `/api/v1/encrypted-dns`.
 
+That is encryption between your clients and this server. For encryption
+between this server and the resolvers it forwards to (Quad9, Cloudflare),
+see [Forwarding over TLS](#forwarding-over-tls) below.
+
 ## Setting it up
 
 ```sh
@@ -151,6 +155,62 @@ What it can say:
 | not from a CA this server trusts (warning) | a staging or test CA: clients reject it unless they trust it |
 | REFUSED (warning) | it works, but this server's own address gets a view that doesn't answer for the host name |
 
+## Forwarding over TLS
+
+When a view forwards its recursive queries (to Quad9, Cloudflare, your
+ISP's resolver), named can send them over TLS, so your ISP doesn't see the
+names you look up: only connections to the forwarder on port 853. It takes
+two options, a `tls` statement for each provider (the name its certificate
+must have) and the view's `forwarders` using it. Stage them in one
+changeset, so one revert undoes them:
+
+```sh
+CS=$(jarl changeset create "internal: forward to Quad9 over TLS" -q)
+jarl option set tls 'quad9 { remote-hostname "dns.quad9.net"; ca-file "/etc/ssl/certs/ca-certificates.crt"; }' --toplevel -C $CS
+jarl option set forwarders '{ 9.9.9.9 port 853 tls quad9; 149.112.112.112 port 853 tls quad9; 2620:fe::fe port 853 tls quad9; 2620:fe::9 port 853 tls quad9; }' --view internal -C $CS
+jarl option set forward only --view internal -C $CS
+jarl changeset diff $CS        # what named.conf gets
+jarl changeset apply $CS
+# undo: jarl changeset apply $(jarl changeset revert $CS -q)
+```
+
+* **`remote-hostname` and `ca-file`** make named check the forwarder's
+  certificate against that name (Debian's CA bundle at that path). Without
+  them the connection is encrypted but anyone in between could answer.
+* **`forward only`** stops named falling back to plain DNS (to the root
+  servers) when the forwarders don't answer: lookups then fail instead
+  (SERVFAIL), which you notice, rather than quietly going unencrypted.
+* **Several providers**: a `tls` statement each, and their addresses in one
+  `forwarders` list. Setting `tls cloudflare` doesn't touch `tls quad9`:
+  `jarl option set` replaces only the statement of that name.
+
+  ```sh
+  jarl option set tls 'cloudflare { remote-hostname "cloudflare-dns.com"; ca-file "/etc/ssl/certs/ca-certificates.crt"; }' --toplevel
+  jarl option set forwarders '{ 9.9.9.9 port 853 tls quad9; 149.112.112.112 port 853 tls quad9; 1.1.1.1 port 853 tls cloudflare; 1.0.0.1 port 853 tls cloudflare; 2606:4700:4700::1111 port 853 tls cloudflare; 2606:4700:4700::1001 port 853 tls cloudflare; }' --view internal
+  ```
+
+  named sends each query to whichever forwarder has answered fastest, not
+  in order, and the providers filter differently (Quad9 blocks known
+  malicious domains, Cloudflare's 1.1.1.1 doesn't; 1.1.1.2 does, with
+  `remote-hostname "security.cloudflare-dns.com"`).
+* **DNS over HTTPS** can't be used for forwarding: BIND serves DoH to
+  clients but forwards only over plain DNS or TLS. For a DoH upstream, run
+  a local proxy (dnscrypt-proxy, cloudflared) and forward to it on
+  `127.0.0.1`.
+* Providers write their DoT address as `tls://dns.quad9.net`: the name is
+  `remote-hostname`, and the addresses it resolves to go in `forwarders`
+  (named needs addresses there, not names).
+
+**Checking it works**: Quad9 says how a query reached it.
+
+```sh
+dig +short TXT proto.on.quad9.net @YOUR-SERVER     # "dot": over TLS
+```
+
+`do53-udp` means plain DNS. `ss -tnp | grep :853` shows named's connections
+only briefly: it closes them when idle. `tcpdump -ni any port 853` shows
+the traffic as it happens.
+
 ## What Jarl checks
 
 * A `tls` statement whose files don't exist is an error