Mail reverse DNS check, what Jarl adds to named.conf, lists one per line

jarld checks the reverse DNS of the public zones' MX and SPF addresses as the internet sees it, every 6 hours (Exposure page, jarl exposure mail, jarl_mail_reverse_dns_ok). The Server options page, jarl option generated and GET /options/generated list what Jarl writes into named.conf by itself; stats.rate_limit_log turns off the query-errors logging. Option lists of three or more elements are shown one per line.

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

docs/api.md

@@ -470,7 +470,8 @@ listing with `?changeset=` marks them `pending`.
 
 | Method | Path | Body / query |
 |--------|------|--------------|
-| GET | `/options` | `?scope=options\|view\|zone\|toplevel&scope_id=ID` (none: everything you may see) |
+| GET | `/options` | `?scope=options\|view\|zone\|toplevel&scope_id=ID` (none: everything you may see). `formatted` lays out a block over several lines, a list of three or more one element per line |
+| GET | `/options/generated` | What Jarl adds to named.conf by itself: `where`, `text`, `why`, `setting` (what turns it on or off) |
 | POST | `/options` | `{"scope": "zone", "scope_id": 11, "name": "allow-transfer", "value": "{ key xfer; }", "comment": "", "position": 0}` |
 | GET / PATCH / DELETE | `/options/{id}` | |
 | GET / PATCH | `/settings` | `{"nameservers": [...], "rname": "...", "default_ttl": 3600, "refresh": ..., "retry": ..., "expire": ..., "negative_ttl": ..., "serial_policy": "date"}` |

docs/cli.md

@@ -405,6 +405,7 @@ jarl exposure                                         # public views, findings,
 jarl exposure fix external exposure_rate_limit        # rate limiting, log-only first
 jarl exposure fix external exposure_rate_limit_log_only   # then start enforcing
 jarl exposure fix server exposure_version
+jarl exposure mail                                   # reverse DNS of the addresses that send and receive mail
 jarl exposure ack external security_open_resolver --reason "public resolver, monitored"
 jarl exposure unack external security_open_resolver
 jarl view update external --exposure public|private|auto
@@ -476,6 +477,7 @@ jarl option set logging '{ channel q { file "/var/log/named/query.log" versions
 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
 ```
 
 Options that end in a list (`allow-*`, `forwarders`, `listen-on`, ...) may

docs/concepts.md

@@ -48,6 +48,14 @@ overwritten. Jarl records a checksum of every file it writes and reports
 **drift** when a file changes behind its back. It then refuses to overwrite
 the file until you say so (`--force`, or `jarl resync --force`).
 
+Some of named.conf comes from Jarl itself rather than from your options:
+the include of keys.conf, the statistics channel and the logging
+statistics need, blocking's `response-policy` and policy zones, and the
+view keys at the front of each view's `match-clients`. The Server options
+page lists them under **Added by Jarl**, with why each is there and what
+turns it on or off (`jarl option generated`). Where you have a statement
+of your own (`logging`, `statistics-channels`), Jarl merges into it.
+
 Comments are part of the data model: zones, records, ACLs, views, keys and
 options can all carry a comment, and Jarl writes it into the generated file.
 Comments in imported zone files are kept.

docs/exposure.md

@@ -107,7 +107,10 @@ is only in its log (category `query-errors`). That is why the activity
 needs query statistics; without them, look at named's log for
 `would rate limit`. When rate limiting is configured and statistics are
 on, Jarl adds `query-errors` to its log channel (keeping named's syslog
-destination for it).
+destination for it). `stats.rate_limit_log: false` in jarl.yaml leaves
+`query-errors` alone; the page then can't show what rate limiting does.
+The Server options page lists this, and everything else Jarl adds to
+named.conf by itself, under **Added by Jarl** (`jarl option generated`).
 
 The statistics also count it: the `rrl` breakdown (`drop`, `slip`,
 `would-drop`, `would-slip`), the `ratelimited` and `ratelimited_name` top
@@ -160,6 +163,36 @@ external`). Set in the server options, it applies to every view that has
 none of its own, your internal resolver included, which RRL isn't meant
 for.
 
+## Mail
+
+Receivers such as Gmail and Outlook check the address mail comes from: it
+needs a PTR record (reverse DNS), and the name it gives must resolve back
+to the address. Without that, mail is rejected or marked as spam. The PTR
+records of your public addresses live in the reverse zones of whoever
+owns the addresses, your hosting provider or ISP: you set them in their
+panel, not in Jarl. A reverse zone you create in Jarl only answers your
+own clients (unless the owner delegated it to you).
+
+So Jarl checks them as the internet sees them, through the public
+resolvers of `acme.resolvers`: the addresses of every public zone's MX
+hosts (receiving) and SPF `ip4:`, `ip6:`, `a` and `a:` addresses
+(sending). The Exposure page's **Mail reverse DNS** panel shows each
+address, its PTR, who runs its reverse zone (the provider, from the
+zone's name server) and what to do; jarld checks a minute after it starts
+and every 6 hours, and logs an address that goes wrong.
+
+```
+$ jarl exposure mail
+ZONE         ADDRESS          FOR                           PTR               STATUS
+adbraun.lol  172.235.168.106  SPF ip4, MX mail.adbraun.lol  mail.adbraun.lol  ok
+```
+
+It warns when an address has no PTR record, or when its name doesn't
+resolve back to it; notes when the name is an alias (CNAME), or isn't the
+MX name (fine if the mail server uses it in HELO). `jarl exposure mail`
+exits 1 when an address isn't right; Prometheus has
+`jarl_mail_reverse_dns_ok{zone,address}`.
+
 ## Confirming a change that opens a view up
 
 A change that *introduces* an open resolver, open zone transfers, cache
@@ -204,7 +237,8 @@ monitoring, response size limits and usually a machine of its own.
 
 | Method | Path | Body |
 |--------|------|------|
-| GET | `/exposure` | `scopes` (per view, or the server: `public`, `override`, `reason`, `rate_limit` off/log-only/enforcing, `findings` with `fix` where Jarl has one), `server` (server-wide findings), `rate_limiting` (last 24h, with statistics: `counts`, `networks`, `names`) |
+| GET | `/exposure` | `scopes` (per view, or the server: `public`, `override`, `reason`, `rate_limit` off/log-only/enforcing, `findings` with `fix` where Jarl has one), `server` (server-wide findings), `rate_limiting` (last 24h, with statistics: `counts`, `networks`, `names`), `rate_limit_log`, `mail` (the last mail check) |
+| POST | `/exposure/mail` | Checks the mail addresses' reverse DNS now: `checked`, `results` (`zone`, `address`, `roles`, `ptr`, `ok`, `level` ok/info/warning, `message`, `reverse_zone`, `managed_by`, `local_zone`), `errors` |
 | POST | `/exposure/fix` | `{"view": "external", "code": "exposure_rate_limit"}` (`view_id` works too; no view: the server). Staged with `?changeset=` like any change |
 | POST | `/exposure/ack` | `{"view": "external", "code": "security_open_resolver", "reason": "..."}` |
 | POST | `/exposure/unack` | `{"view": "external", "code": "security_open_resolver"}` |

docs/metrics.md

@@ -132,6 +132,7 @@ same values.
 | `jarl_certificate_expiry_timestamp_seconds{certificate,source}` | When each certificate Jarl manages expires ([certificates.md](certificates.md)). |
 | `jarl_certificate_failing{certificate,source}` | 1 when obtaining (or reading) the certificate failed the last time, or it has expired. |
 | `jarl_certificate_renewal_failures{certificate}` | Failed attempts to obtain a certificate since its last success. |
+| `jarl_mail_reverse_dns_ok{zone,address}` | 1 when an address that sends or receives a public zone's mail has a PTR record that resolves back to it, at the last check, every 6 hours ([exposure.md](exposure.md#mail)). |
 | `jarl_encrypted_dns_up{kind,address,port}` | 1 when the DoT or DoH listener answered with the right, current certificate at the last check ([encrypted-dns.md](encrypted-dns.md#health)). |
 
 ### Queries (with `stats.enabled`)
@@ -238,6 +239,10 @@ groups:
         for: 20m
         annotations:
           summary: "DNS over {{ $labels.kind }} on {{ $labels.address }} port {{ $labels.port }} isn't working (see the Encrypted DNS page)"
+      - alert: MailReverseDNS
+        expr: jarl_mail_reverse_dns_ok == 0
+        annotations:
+          summary: "{{ $labels.address }} ({{ $labels.zone }} mail) has no reverse DNS that resolves back: receivers may reject its mail"
       - alert: BlockingPausedForLong
         expr: jarl_blocking_paused == 1
         for: 24h

docs/stats.md

@@ -60,6 +60,7 @@ off again. The statistics database stays until you delete it
 stats:
   enabled: false
   query_log: true          # per-query data; false = named's counters only
+  rate_limit_log: true     # with a rate-limit: also log what it limits (query-errors)
   database: /var/lib/jarl/stats.db
   statistics_channel: 127.0.0.1:8058   # must be a loopback address
   log_file: /var/log/named/jarl-responses.log
@@ -81,6 +82,13 @@ the response log. Logging every answer costs named some CPU and disk I/O,
 which is negligible at homelab volumes. At tens of thousands of queries per
 second, consider counters only.
 
+`rate_limit_log` matters only with a `rate-limit` set: Jarl then sends
+named's `query-errors` category (where rate limiting logs what it limits,
+or would in log-only mode) to the response log too, and keeps it in
+syslog. That other query errors come along is the price; `false` stops it,
+and the Exposure page can't show rate limiting's activity then
+([exposure.md](exposure.md#response-rate-limiting)).
+
 `exclude_clients` drops those clients from the log-derived figures (top
 lists, views, zones). named's own counters can't be filtered.