jarl/docs/reverse.md

# Reverse zones

A reverse zone answers "which host has this address?" with PTR records:
`20.10.0.10.in-addr.arpa. PTR nas.adbraun.lol.`. Your own clients use them
for names in logs, `traceroute`, the router's client list and `ssh`
warnings. For your private networks they only exist if this server has
them, and they are easy to forget, so Jarl can work them out from the
records you already have.

Who asks matters:

* **Your own clients** ask this server, so a reverse zone in a private
  view (internal) answers them.
* **The internet** asks whoever owns the address: your ISP or hosting
  provider for public addresses. Mail servers check those PTR records, and
  you set them in the provider's panel, not in Jarl. The Exposure page
  checks them ([exposure.md](exposure.md#mail)). A reverse zone for a
  public address in a public view (external) does nothing unless the owner
  delegated it to you.

So reverse zones belong in private views. A view whose clients reach it
from the internet gets no suggestions, and neither does a view you turn
them off for: a view only a few servers use, such as one for your VPS,
matches only their addresses and so counts as private, but its clients
don't need reverse zones (`jarl view update vps
--reverse-suggestions=false`, or the view's settings). Exposure doesn't
change.

## Missing reverse zones

The Zones page lists, under **Missing reverse zones**, the reverse zones a
private view lacks for the addresses of its A and AAAA records, in two
groups:

```
$ jarl zone suggest-reverse
GROUP   VIEW      NETWORK                ZONE                              PTRS  FOR EXAMPLE
yours   internal  10.0.10.0/24           10.0.10.in-addr.arpa              14    10.0.10.1 router.adbraun.lol, ...
yours   internal  2a02:8013:7f3d::/48    d.3.f.7.3.1.0.8.2.0.a.2.ip6.arpa  9     2a02:8013:7f3d:10::5 nas.adbraun.lol, ...
public  internal  139.144.144.154/32     154.144.144.139.in-addr.arpa      1     139.144.144.154 ldn.adbraun.lol
public  internal  185.199.108.153/32     153.108.199.185.in-addr.arpa      1     185.199.108.153 blog.adbraun.lol

$ jarl zone suggest-reverse --create                                        # yours, filled, in one changeset
$ jarl zone create 139.144.144.154/32 --view internal --fill               # a public one that is yours
$ jarl zone suggest-reverse --dismiss 185.199.108.153/32 --view internal   # GitHub's, not yours
```

**Yours**, created by **Create all** (`--create`):

* the **/24** of a private IPv4 address (10/8, 172.16/12, 192.168/16,
  100.64/10);
* the **/48** of a ULA (fd00::/8), or of a public IPv6 prefix this server
  has an address in (the /48 your ISP delegates): one zone for all its
  subnets. If you have a /56, create that instead (`jarl zone create
  2a02:db8:1:ab00::/56`).

**Public addresses, only if they're yours**: any other public address,
each as a /32 (or /128) of its own. Jarl can't tell your VPS from a web
host's server (a `blog` record pointing at GitHub Pages), and a zone for
someone else's address would show your clients your name for it instead
of theirs. The rest of the /24 belongs to others: a /24 zone here would
answer NXDOMAIN to your clients for all of their addresses. Create the
ones that are yours one by one, and **Dismiss** the others: Jarl
remembers, per view (`--undismiss` brings one back).

There can be hundreds of public addresses (records pointing at a web
host or a CDN), so the group is folded away when it is long. Opened, it
has a search and shows 25 at a time; **Dismiss these N** dismisses every
address the search found, in one change: search `104.16.` and dismiss
the CDN's addresses together. From the CLI, `--dismiss` takes several
networks (comma separated or repeated). The New reverse zone list has a
search too.

Loopback and link-local addresses, wildcards and disabled records are left
out.

## Creating one by hand

Where nothing is suggested (a view with suggestions off, a dismissed
network, a public view) or the suggested size isn't the one you want,
**New reverse zone** on the Zones page lists every network your records
use that has no reverse zone, in every view, marked when it isn't
suggested unasked. Pick one: the network and the view are filled in.
Then the **Size** buttons change it, around the address of one of the
records: a suggested `2a02:8013:7f3d::/48` becomes
`2a02:8013:7f3d:10::/64` for the subnet the records are in, or `/128`
for one address. The zone name shows as you go, and **PTR records** stays
ticked, so the zone is created with a PTR record for each address
(IPv6 nibble names written for you).

```sh
jarl zone suggest-reverse --all --view vps                     # every network, hidden ones marked
jarl zone create 2a02:8013:7f3d:10::/64 --view internal --fill
```

**Records in another view.** With a view chosen (`--view internal`, or
the dialog's View), the list also has the addresses only other views'
records use, marked "records in external": say a VPS's AAAA record that
only the external view has. Fill names those from the other view's
record only when asked: `--other-views` (with `--fill` or `jarl zone
fill-ptr`), or the dialog's **Also for addresses only other views'
records use**, which is ticked for you when you pick a "records in"
network. Otherwise one view's host names would turn up in another's
reverse zone, which is what views are for keeping apart. Jarl says which
names came from another view. Keeping PTR records in step (below) stays
within a zone's own view and its linked views: a later change to that
external record doesn't reach the internal reverse zone.

```sh
jarl zone create 2600:3c01::f03c:93ff:fe2b:1/128 --view internal --fill --other-views
jarl zone fill-ptr 10.0.10.0/24 --view vps --other-views
```

## Creating and filling

```sh
jarl zone create 10.0.10.0/24 --fill       # the view whose records use 10.0.10.x
jarl zone fill-ptr 10.0.10.0/24            # later: add what is missing
```

**The view.** A reverse zone created without `--view` goes to the private
view whose records use addresses in its network (views with suggestions
off don't count). If none does, it goes to the only private view. If
several do, Jarl asks you to name the view, or to create the zone in each.

**Inside another zone.** A zone created inside an existing one in the same
view, a /24 inside a /8 or `lab.adbraun.lol` inside `adbraun.lol`, takes
the parent's records under it, in the same changeset: named answers those
names from the new zone, so left in the parent they would never be served
again. PTR records you added by hand come along; `--fill` then adds only
what is still missing. A delegation (NS records at the new zone's name,
with their glue) stays in the parent. A linked parent keeps its records,
with a warning, since its other views would lose them too.

**Fill** adds a PTR record for every address in the network that the
view's A and AAAA records use. An address with several names gets one PTR:

1. the name of a mail or name server (an MX or NS target), else
2. a host's name rather than the domain's own (`nas.adbraun.lol`, not
   `adbraun.lol`), else
3. the shortest name, then the first alphabetically.

Jarl says which name it chose, and which it didn't, so you can change it.
A reverse zone's page shows the addresses that still lack a PTR record and
the name each would get (the first 25), with a button to add them. `jarl
zone show` shows how many as `Missing PTRs`; the API lists them in
`ptr_missing_list`. Only the zone's own view's records count: an address
that only another view's records use isn't missing (say internal's
`claude.adbraun.lol` and the vps view's copy of `10.0.10.in-addr.arpa`).
Those are listed apart, with the name each would get: `Other views` in
`jarl zone show`, `ptr_other_views` and `ptr_other_views_list` in the
API, and a quiet note on the page with an **Add PTR records for them in
view vps** button. Filling never adds them unasked. `jarl zone show`
lists the missing ones too:

```
Missing PTRs:  1 (addresses the view's records use here; add them: jarl zone fill-ptr 10.0.10.0/24)
                 10.0.10.7 -> printer.adbraun.lol
Other views:   2 addresses with A or AAAA records only in view internal, so not missing here (add PTRs for them in this view too: jarl zone fill-ptr 10.0.10.0/24 --other-views)
                 10.0.10.26 -> gomft.adbraun.lol (view internal)
                 10.0.10.101 -> claude.adbraun.lol (view internal)
```

## Keeping PTR records in step

The **Update PTR** box on an A or AAAA record (`--ptr`) moves the PTR record
along with that one change. To have that on every change, turn it on for
the forward zone:

```sh
jarl zone update adbraun.lol --view internal --auto-ptr          # off: --auto-ptr=false
```

(Zone settings → **Reverse DNS** in the web UI.) Then adding, changing,
disabling, enabling or deleting an A or AAAA record in the zone does the
same to its PTR record, in the reverse zone of each view that has the
record. A whole set replaced at once (`jarl record set`, a batch) works
too.

**Linked zones** ([views.md](views.md#linked-zones)). PTR records follow
each view's own address records:

* A shared record gets a PTR record in every linked view that has it; a
  record local to one view gets one in that view only.
* An address that goes from one view (deleted, changed, or overridden by
  a local record) loses its PTR record there only. Views that still have
  the address keep theirs.
* Each zone's own **Reverse DNS** setting counts: a linked zone without
  it doesn't get PTR records from its partner's changes.
* In a linked reverse zone, these PTR records (and those **Fill** adds)
  are local to their view. A PTR record that is shared becomes local in
  each view the first time one of them changes it, so that a change in
  one view doesn't reach the others.

* **One name per address.** When an address's PTR record names another
  host, it stays: a second A record for the same address doesn't add a
  second PTR record.
* **No reverse zone, no PTR.** An address without a reverse zone in the
  view, such as a public address in the external view, is skipped without
  a warning. The suggestions above show what is missing.
* **Wildcards** (`*.dev`) never get a PTR record.

The PTR changes are part of the same changeset, so you review them, and
they are applied or undone together with the record.