autoreverse.8

.Dd February 15, 2023
.Dt AUTOREVERSE 8
.Os
.Sh NAME
.Nm autoreverse
.Nd a minimalist-configuration reverse DNS name server
.Sh SYNOPSIS
.Nm
.Fl h | -help | -manpage | v | -version
.Nm
.Fl -forward Ar zone-name | Fl -local-forward Ar zone-name
.Vt
.Fl -reverse Ar CIDR Ns
\[u2026]
|
.Fl -local-reverse Ar CIDR Ns
\[u2026]
.Vt
.Op Fl -listen Ar listen-address Ns
\[u2026]
.Op Fl -PTR-deduce Ar URL Ns
\[u2026]
.Op Fl -passthru Ar auth-server
.Vt
.Op Fl -synthesize Ns = Ns Ar true
.Op Fl -CHAOS Ns = Ns Ar true
.Op Fl -NSID Ar hostid
.Op Fl -TTL Ar time.Duration=1h
.Vt
.Op Fl -user Ar user-name
.Op Fl -group Ar group-name
.Op Fl -chroot Ar path
.Vt
.Op Fl -log-debug
.Op Fl -log-major Ns = Ns Ar true
.Op Fl -log-minor
.Op Fl -log-queries Ns = Ns Ar true
.Op Fl -report Ar time.Duration=1h
.Vt
.Op Fl -rrl-dryrun
.Op Fl -rrl-ipv4-CIDR Ar length
.Op Fl -rrl-ipv6-CIDR Ar length
.Op Fl -rrl-max-table-size Ar size
.Op Fl -rrl-window Ar size
.Op Fl -rrl-slip-ratio Ar ratio
.Op Fl -rrl-errors-psec Ar allowance
.Op Fl -rrl-nodata-psec Ar allowance
.Op Fl -rrl-nxdomain-psec Ar allowance
.Op Fl -rrl-referrals-psec Ar allowance
.Op Fl -rrl-requests-psec Ar allowance
.Op Fl -rrl-responses-psec Ar allowance
.Pp
The
.Ql \[u2026]
symbol indicates options which can be specified multiple times.
.Sh DESCRIPTION
.Nm
is a specialized authoritative DNS server whose goal is to make it as easy as
possible to auto-answer reverse queries without ever requiring reverse zone
files.
.Nm
synthesizes reverse answers and automatically derives
.Sy PTR
answers from specified forward zones.
Importantly,
.Nm
automatically answers
.Em forward
queries corresponding to the synthetic reverse answers, meeting the requirements
of many remote services which insist on matching forward and reverse names.
.Pp
.Nm
is designed to run on residential gateway routers and servers behind NATs which
acquire ISP-assigned addresses via DHCP or SLAAC, but it also runs on publicly
accessible servers with static network configurations.
.Pp
On start-up,
.Nm
extracts forward and reverse delegation details from the DNS to synthesize its
.Ql Zones of Authority .
This approach to gleaning information from the DNS represents an over-arching
philosophy of
.Nm
in that it
.Em never
requires configuration material which duplicates that already present in the
DNS.
This approach is suggested in rfc8501, Section 2.5
.Sy [RFC8501] .
.Pp
While
.Nm
normally runs with pre-configured forward and reverse delegations in
the global DNS, it also supports non-delegated rfc1918
.Sy [RFC1918]
and rfc4193
.Sy [RFC4193]
addresses, otherwise known as private addresses
or User Local addresses
.Sy ( ULAs ) .
.Pp
See
.Sx GETTING STARTED
for details on how to run
.Nm ,
but a typical invocation is:
.Bd -literal -offset indent
# autoreverse --forward autoreverse.example.net --reverse 2001:db8::/64
.Ed
.Pp
Where
.Ql autoreverse.example.net
and
.Ql 0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa
(the reverse zone for 2001:db8::/64) are delegated to the
.Nm
listening addresses(s).
.Pp
That's it! That's all that's needed to serve your reverse and matching
forward queries.
.Ss OPTIONS
Documentation Options are:
.Bl -tag -width indent
.It Fl h | -help
print command-line usage
.
.It Fl -manpage
print the raw mandoc text suitable for piping into
.Xr mandoc 1 .
.It Fl v | -version
print
.Nm
version and origin URL
.
.El
.Pp
Run-time Options are:
.Bl -tag -width indent
.It Fl -CHAOS Op =false
Answer
.Sy CHAOS TXT
queries for version.bind, version.server, authors.bind, hostname.bind and
id.server.
The default is
.Sy true .
.
.It Fl -NSID Ar hostid
Respond to
.Sy EDNS NSID
sub-option requests with the specified
.Ar hostid .
.Nm
manages the hexadecimal conversion implicitly so this option should be set as a
regular string, e.g.
.Ql --NSID\~a.ns.example.net .
.
.It Fl -PTR-deduce Ar URL
The zone is loaded from the URL and scanned for address records to deduce
.Sy PTR
answers in preference to synthetic answers.
This is a way of overlaying synthetic answers with zone data.
.Pp
Any
.Sy PTR RRs
found in the zone are also loaded in preference to synthetic answers.
Supported URL schemes are:
.Ql file ,
.Ql axfr ,
.Ql http
and
.Ql https .
.Pp
In all cases, address and
.Sy PTR
records are only considered if they are in-domain of
.Fl -reverse
or
.Fl -local-reverse
zones.
.Pp
.Sy CNAME RRs
are resolved while loading zones, thus if a CNAME resolves to an in-domain
reverse address it's included as a preferred response to PTR queries.
A classic use of this is when you have a CNAME to a
.Sy RIPE
Atlas probe such as:
.Pp
.D1 myprobe.example.net. 600 IN CNAME  pxxxx.probes.atlas.ripe.net.
.Pp
in this case a reverse query of the probe address returns
.Ql myprobe.example.net .
.Pp
The
.Fl -PTR-deduce
URLs are loaded after
.Fl -chroot
processing which means paths in
.Ql file
scheme URLs must be relative to the chroot directory.
.Pp
The reload strategy varies with the URL scheme:
.Ql file
periodically detects Date-Time-Modified changes while the other schemes rely on
the
.Sy SOA
.Ql Refresh
value expiring.
.Pp
If any of the
.Fl -PTR-deduce
URLs fail to load, the previous data for
.Sy all
zones is retained and the partially loaded new values are discarded.
If the initial load of any zone fails,
.Nm
exits.
In other words,
.Nm
continues to run with stale data, but does not start with missing data.
.Pp
Examples of syntactically valid
.Fl -PTR-deduce
URLs:
.Pp
.D1 axfr://a.ns.example.org/example.net
.D1 file:///etc/nsd/data/example.net.zone
.D1 https://www.example.com/example.org.txt
.Pp
The
.Fl -PTR-deduce
option can be specified multiple times.
.It Fl -TTL Ar time.Duration
.Ql Time To Live
for synthetic responses expressed in
.Ql go
.Sy time.Duration
syntax.
The minimum value allowed is
.Ql 1s
and the default is
.Ql 1h .
.
.It Fl -chroot Ar Path
Reduce process privileges by issuing
.Xr chroot 2
after
.Fl -listen
sockets have been established.
.Pp
In conjunction with
.Fl -user
and
.Fl -group ,
this option restricts access to a subset of the file system.
.Nm
must start as root for this option to succeed.
The specified path must be an absolute path otherwise
.Xr chroot 2
fails.
.Pp
There are caveats with
.Fl -chroot .
Once the chroot directory is set,
.Sy all
file access is relative to that directory.
This obviously affects
.Ql file
URLs given to
.Fl -PTR-deduce
but it also potentially impacts name resolution which often relies on files such
as
.Sy /etc/resolv.conf .
In other words, if not properly established,
.Fl -chroot
can cause name resolution to fail.
.Pp
.Nm
defers all zone loading and discovery until after process privileges are reduced
so any problems with chroot and friends are exposed at start up.
.
.It Fl -forward Ar Domain
The forward zone to discover and serve.
Also used as the suffix domain in
.Sy PTR
responses.
This zone
.Em must
be delegated to an
.Nm
listening address.
.Pp
.Nm
queries the DNS to extract delegation details for this zone from the parent
zone.
If one of the zone name servers self-identifies, as determined by DNS Probing,
the zone is accepted as a
.Ql Zone of Authority .
If the zone does not self-identify,
.Nm
exits.
Only one of
.Fl -forward
or
.Fl -local-forward
can be specified.
.Pp
.Nm
processes
.Fl -forward
before
.Fl -reverse
which means reverse zones can refer to forward zone name servers and
discovery will
.Ql just work
as
.Nm
is in a position to answer forward zone queries.
.Pp
.Nm
synthesizes zone information from the delegation details.
.It Fl -group Ar group-name
Reduce privileges by issuing a
.Xr setgid 2
after
.Fl -listen
sockets have been established.
.Pp
In conjunction with
.Fl -user
and
.Fl -chroot ,
this option removes root privileges and restricts access to other system
components.
.Nm
must start as root for this option to succeed.
.It Fl -listen Ar listen-address
Address to listen on for DNS queries.
If just an IP address or host name is specified,
.Nm
assumes the
.Ql domain
service (aka port 53).
A specific port can be provided with the usual
.Ql host:port ,
.Ql v4address:port
or
.Ql [v6address]:port
syntax.
.Pp
However the port is determined, on most Unix-like systems,
.Nm
normally needs to be started as root to listen on
.Ql privileged ports
such as port 53.
If started as root, it is highly recommended that the
.Nm
invocation include the
.Fl -user , -group
and
.Fl -chroot
options to reduce process privileges once the
.Fl listen
sockets have been established.
.Pp
.Nm
listens on both
.Sy UDP
and
.Sy TCP
networks for
.Sy DNS
queries.
The default is
.Ql :domain .
.Pp
The
.Fl -listen
option can be specified multiple times.
.It Fl -local-forward Ar Domain
A local forward zone to serve as a
.Ql Zone of Authority .
Unlike
.Fl -forward ,
no attempt is made to discover the delegation and self-identify the name server.
A skeletal SOA is created and
.Nm
arbitrarily serves the domain and uses it as a suffix for synthetic
.Sy PTR
generation.
.Pp
.Ar Domain
represents a zone which is not expected to be visible in the public DNS and is
thus only visible locally where local resolvers are configured to direct such
queries to
.Nm .
.Pp
Only one of
.Fl -forward
or
.Fl -local-forward
can be specified.
.It Fl -local-reverse Ar CIDR
.Sy CIDR
of a local reverse zone to serve as a
.Ql Zone of Authority .
Intended for rfc1918 and rfc4193 addresses otherwise known as private
addresses or
Unique Local Addresses in
.Sy ipv6
parlance.
Unlike
.Fl -reverse
no attempt is made to discover the delegation and self-identify the name server.
A skeletal SOA is created and
.Nm
arbitrarily serves the reverse domain.
.Pp
The
.Sy CIDR
represents a zone which is not expected to be visible in the public DNS and is
thus only visible locally where local resolvers are configured to direct reverse
queries to
.Nm .
How this redirection is achieved varies greatly depending on the local resolver.
.Pp
As one example, in the case of
.Xr unbound 8 ,
the normal approach is to use a
.Ql stub-zone
directive such as:
.Bd -literal -offset indent
stub-zone:
        name: "0.0.0.0.0.0.0.0.0.e.d.2.d.f.ip6.arpa."
        stub-host: autoreverse.example.net.
        stub-prime: yes
.Ed
.Pp
Which directs
.Sy unbound
to resolve all addresses within the
.Sy ULA
.Sy CIDR
of fd2d:e000::/48 by querying
.Ql autoreverse.example.net .
.Pp
The
.Fl -local-reverse
option can be specified multiple times.
.It Fl -log-major Op =false
Log major events to Stdout.
Major events are rare events which are something you normally want to know
about.
The default is
.Sy true .
.Pp
Most major events are start-up related, although there are some on-going major
events such as periodic statistics report.
There is no good reason to set
.Fl -log-major
to false unless you absolute cannot tolerate
.Em any
logging information at all.
.
.It Fl -log-minor Op =true
Log minor events to Stdout.
Minor events are an elaboration of major events logged by
.Fl -log-major
which provide additional insights behind the event.
Generally minor event logging is useful when you're trying to diagnose an
unexpected major event.
Setting
.Fl -log-minor
implies setting
.Fl -log-major .
The default is
.Sy false .
.
.It Fl log-debug Op =true
Log extensive diagnostic material - mostly discovery related.
Most likely of use to developers or sysadmins who are prepared to correlate log
details with source code to evaluate the behaviour of
.Nm .
Setting
.Fl -log-debug
implies setting
.Fl -log-major
and
.Fl -log-minor .
.It Fl -log-queries
Write a one line summary of each query to Stdout.
The output is intended to be amenable to programmatic post-processing and
statistics gathering, but still somewhat human-friendly.
On busy systems this option should probably be set to
.Sy false
unless you wish to generate voluminous log files.
This setting can be toggled at run-time with
.Sy SIGUSR2
if you wish to gather a snapshot of activity.
The default is
.Sy true .
.
.It Fl -max-answers Ar Integer
Maximum
.Sy PTRs
to allow in a response.
This further limits response sizes below the maximum allowed by the query and
system defaults.
.Pp
This limit only applies to potential multiple
.Sy PTRs
extracted from
.Fl -PTR-deduce
zones.
Regardless of this setting, responses are
.Sy always
limited to the maximum size allowed by the query including any EDNS0 values.
If set to zero, all available
.Sy PTRs
are placed in the response within size limits.
.Pp
The default is
.Sy 5 .
.It Fl -passthru Ar auth-server
Proxy not in-domain queries to the
.Ar auth-server .
.Pp
.Sy THIS IS AN EXPERIMENTAL FEATURE - USE WITH CAUTION.
.Pp
Normally not in-domain queries generate a
.Sy REFUSED
DNS response.
However, with this option set, not in-domain queries are proxied unmodified to
the
.Ar auth-server
using the same network type the query came in, i.e.
.Sy UDP
or
.Sy TCP .
Any response from the
.Ar auth-server
is similarly proxied unmodified back to the querying client.
No retries are attempted, nor are truncated UDP responses re-queried in
.Sy TCP .
In effect,
.Nm
acts as a transparent DNS proxy.
.Pp
This option is most likely of use in NAT/port-forwarding scenarios where a local
authority server is already running on port 53 on a single routable
.Sy IPv4
address.
.Pp
Be aware that DNS Cookies returned by the
.Ar auth-server
will not match those sent by
.Nm
which means clients will see
.Sy two
DNS Cookies from the same server IP address.
Since clients only retain the most recent DNS Cookie they are likely to send
back the wrong one when sending queries which are sometimes answered by
.Nm
and other times answered by the
.Ar auth-server .
There is no impact when
.Nm
received bad server cookies (at this stage), but there may be some if the
.Ar auth-server
de-prioritizes bad server cookies.
.It Fl -report Ar time.Duration
Interval between printing statistics reports expressed in
.Ql go
.Sy time.Duration
syntax.
The minimum value is 1s and the default is
.Sy 1h .
.It Fl -reverse Ar CIDR
Defines the starting point within the reverse zone to discover and serve.
.Pp
.Nm
ascends the reverse DNS tree from the starting point to discover the zone
delegated to
.Nm
as determined by DNS Probing.
If the zone cannot be verified by probing,
.Nm
exits.
.Pp
.Nm
processes
.Fl -reverse
.Em after
.Fl -forward
which means reverse delegations can refer to in-domain forward name servers and
.Nm
correctly responds to SOA related queries as part of the reverse discovery.
.Pp
.Nm
synthesizes zone information from the discovered delegation details.
.Pp
The
.Fl -reverse
option can be specified multiple times.
.It Fl -synthesize Op =false
Synthesize missing
.Sy PTRs .
.Pp
If a
.Sy PTR
query cannot be satisfied from
.Fl PTR-deduce
zones, a synthetic response is generated based on the domain name of the forward
zone.
If set false
.Sy NXDomain
is returned for missing
.Sy PTRs .
The default is
.Sy true .
.It Fl -user Ar user-name
Reduce privileges by issuing a
.Xr setuid 2
after
.Fl -listen
sockets have been established.
In conjunction with
.Fl -group
and
.Fl -chroot ,
this option removes root privileges and restricts access to other system
components.
.Nm
must start as root for this option to succeed.
.
.El
.Pp
Response Rate Limiting (or
.Sy [RRL] )
is only activated when at least one of the
.Fl -rrl-*-psec
options are set.
.Sy RRL
actions are shown on the 'ru=' field of logged queries with '/D'
and '/S' representing Drop and Slip respectively.
.Bl -tag -width indent
.It Fl -rrl-dryrun
Invoke RRL analysis but ignore any recommended action.
This allows for testing various RRL settings without inadvertently
triggering drops or slippage.
Logged queries still show what RRL action would have occurred if this
option was not set.
.It Fl -rrl-max-table-size Ar size
The maximum number of responses to be tracked at one time.
When exceeded,
.Sy RRL
stops rate limiting new responses.
The default is 100000.
.It Fl -rrl-window Ar size
Seconds during which response rates are tracked.
The default is 15.
.It Fl -rrl-slip-ratio Ar ratio
The ratio of rate-limited responses given a truncated response over a dropped
response.
A ratio of 0 disables slip processing and thus all rate-limited responses are
drop.
A ratio of 1 means every rate-limited response will be a truncated response and
the upper limit of 10 means 1 in every 10 rate-limited responses will be a
truncated with the remaining 9 being dropped.
The default is 2.
.It Fl -rrl-errors-psec Ar allowance-per-second
The number of Error responses allowed per second (excluding NXDomain).
An allowance of 0 disables Error rate limiting.
The default is
.Fl -rrl-responses-psec .
.It Fl -rrl-nodata-psec Ar allowance-per-second
The number of NoData responses allowed per second.
An allowance of 0 disables NoData rate limiting.
The default is
.Fl -rrl-responses-psec .
.It Fl -rrl-nxdomain-psec Ar allowance-per-second
The number of NXDomain responses allowed per second.
An allowance of 0 disables NXDomain rate limiting.
The default is
.Fl -rrl-responses-psec .
.It Fl -rrl-referrals-psec Ar allowance-per-second
The number of Referral responses allowed per second.
An allowance of 0 disables Referral rate limiting.
The default is
.Fl -rrl-responses-psec .
.It Fl -rrl-requests-psec Ar allowance-per-second
The number requests allowed per second from a source IP.
An allowance of 0 disables rate limiting of requests.
This value applies solely to the claimed source IP of the query (as masked by
.Fl -rrl-*-CIDR )
whereas all other settings apply to the response details.
The default is 0.
.It Fl -rrl-responses-psec Ar allowance-per-second
The number of Answer responses allowed per second.
If simple RRL processing is desired, this is the main option to set.
It defines the upper limit of your acceptable query rate and is the
default value used by most other RRL options.
An allowance of 0 disables Answer rate limiting.
The default is 0.
.\" The follow El macro terminates the options list started *way* up there with a Bl. It's not
.\" some macro that is accidentally here (which is what I think each time I see it)
.
.El
.
.Ss SIGNALS
.Nm
responds to the following signals:
.Bl -column ".Sy Signal" ".Sy Description"
.It Li SIGHUP Ta Reload all zones specified with Fl -PTR-deduce
.It Li SIGQUIT Ta Produce a stack dump and exit
.It Li SIGINT Ta Initiate shutdown
.It Li SIGTERM Ta Initiate shutdown
.It SIGUSR1 Ta Generates an immediate statistics report
.It SIGUSR2 Ta Toggles Fl -log-queries
.El
.
.Sh GETTING STARTED
Since
.Nm
relies on the forward and reverse delegation details to deduce its own zone
information, the first step is to add those delegation details into the global
DNS.
Here is an example of the recommended snippet for your forward zone:
.Bd -literal -offset indent
$ORIGIN yourdomain.
;;
autoreverse IN NS   autoreverse
            IN AAAA 2001:db8:aa:bb::53
            IN A    192.0.2.53
;;
.Ed
.Pp
Reverse delegation is typically managed by your ISP or address assignment
provider so normally you arrange with them to configure the reverse name server
as:
.Ql autoreverse.yourdomain
to match the
.Ql NS
entry in the above snippet.
.Pp
That completes the setup for
.Nm .
It is now ready to run!
.Ss INVOCATION
With forward and reverse delegations in place, the simplest invocation is to run
.Nm
with a single
.Fl -forward
and
.Fl -reverse
option:
.Pp
.D1 # autoreverse --forward autoreverse.yourdomain --reverse\~2001:db8:23::/64
.Pp
With that information
.Nm
walks and probes the global DNS to glean delegation details to create its
.Sy Zones of Authority
to serve.
.
.Sh IMPLEMENTATION NOTES
.Nm
starts at one label up from the
.Fl forward
and
.Fl reverse
zones and directly queries the parent name servers for delegation details
of the specified zone to populate its
.Ql Zones of Authority .
.Nm
continues
.Ql walking
up the DNS until it finds responding parents or reaches the upper reaches of the
DNS.
This
.Ql walking
process is important because there are (uncommonly) gaps between child and
parent zones in the forward direction, while such gaps are very common in the
reverse direction.
.Ql Walking
skips over those gaps to discover the delegation material.
.Pp
Once the parents are discovered,
.Nm
directly queries them for name servers of the delegated
.Fl -forward
and
.Fl -reverse
zones.
These purported delegated name servers are
.Em DNS Probed
to determine if any of them refer back to the
.Nm
instance.
If at least one does,
.Nm
accepts the domain as a
.Ql Zone of Authority
which it will server answers for.
.Pp
This is a convoluted way of saying that
.Nm
determines if it is one of the delegated name servers.
You might think that
.Nm
could simply compare interface addresses against the delegation details and
accept a match as
.Ql proof ,
but that doesn't work in a proxy or port forwarding or NAT environment.
Thus
.Nm
relies on the stronger proof of a
.Em DNS Probe .
.Ss PTR AND FORWARD SYNTHESIS
.Nm
answers
.Sy PTR
queries for in-domain zones with synthetic and matching forward names.
For example a
.Sy PTR
query might produce the following response:
.Pp
.D1 f.7.1.f.0.d. ... 8.b.d.0.1.0.0.2.ip6.arpa. 60 IN\~PTR\~2001-db8-0-0-0-0-d0-d17f.autoreverse.yourdomain.
or
.D1 54.2.0.192.in-addr.arpa. 60 IN\~PTR\~192-0-2-54.autoreverse.yourdomain.
.Pp
and
.Nm
answers forward queries for these synthetic
.Sy PTR
values with matching address records, i.e.:
.Pp
.D1 2001-db8-0-0-0-0-d0-d17f.autoreverse.yourdomain. 60 IN\~AAAA\~2001:db8::d0:d17f
and
.D1 192-0-2-54.autoreverse.yourdomain. 60 IN\~A\~192.0.2.54
.Pp
This automatic forward and reverse matching is perhaps the main reason for
deploying
.Nm
as it helps meet the requirements of many logging and checking systems which
insist on matching entries;
.Xr sshd 8
and
.Xr dovecot 1
IMAP and POP3 servers being prominent examples.
.Ss INTERMIXING
A common scenario is where you want to intermix configured names with synthetic
names in
.Sy PTR
responses.
This is the purpose of
.Fl PTR-deduce .
.Nm
loads the nominated zones and deduces
.Sy PTR RRs
for every
.Sy A ,
.Sy AAAA
and
.Sy CNAME
resource found.
It also directly loads any
.Sy PTR RRs
in the zone.
These deduced and direct
.Sy PTRs
have preference over synthetic
.Sy PTRs .
For example, if you supply a forward zone which contains:
.Bd -literal -offset indent
  $ORIGIN otherdomain.
  router IN AAAA 2001:db8::1
  s1     IN AAAA 2001:db8::2
  mail   IN AAAA 2001:db8::5
.Ed
.Pp
.Nm
replies to the following
.Sy PTR
queries with:
.Bd -literal -offset indent
  1.0.0. ... 8.b.d.0.1.0.0.2.ip6.arpa. 60 IN PTR router.otherdomain.
  2.0.0. ... 8.b.d.0.1.0.0.2.ip6.arpa. 60 IN PTR s1.otherdomain.
  3.0.0. ... 8.b.d.0.1.0.0.2.ip6.arpa. 60 IN PTR 2001-db8-0-0-0-0-0-3.autoreverse.yourdomain.
  4.0.0. ... 8.b.d.0.1.0.0.2.ip6.arpa. 60 IN PTR 2001-db8-0-0-0-0-0-4.autoreverse.yourdomain.
  5.0.0. ... 8.b.d.0.1.0.0.2.ip6.arpa. 60 IN PTR mail.otherdomain.
  6.0.0. ... 8.b.d.0.1.0.0.2.ip6.arpa. 60 IN PTR 2001-db8-0-0-0-0-0-6.autoreverse.yourdomain.
  ...
.Ed
.
.Sh EXAMPLES
Few use-cases require such a complicated invocation, but this example
demonstrates less common features:
.Bd -literal -offset indent
# autoreverse --forward autoreverse.mydomain --reverse 2001:db8::/64
               --log-query=false --NSID Host:`hostname` --CHAOS=false
               --user nobody --group nobody --chroot /tmp
               --listen 192.0.2.1 --listen [2001:db8::1]:53
               --passthru 127.0.0.1
               --PTR-deduce file:///etc/nsd/data/example.net.zone
               --PTR-deduce file:///etc/nsd/data/8.b.d.0.1.0.0.2.ip6.arpa
               --PTR-deduce axfr://a.ns.example.org/example.net
.Ed
.Pp
which causes
.Nm
to listen on multiple addresses, deduces reverse
.Sy PTR
names from multiple zone URLs and relinquishes root permissions to run as a
less-privileged daemon.
.Pp
This invocation also supplies the hostname in response to any query containing
the NSID option.
Finally, not in-domain queries are passed thru to a name server presumed to be
listening on 127.0.0.1 which allows
.Nm
to proxy or answer all inbound queries.
.
.Sh STATISTICS
This section describes the statistic periodically logged by
.Nm .
All such lines are prefixed by
.Dq Stats .
.Ss Total
.Bd -literal -offset indent
Total q=a/b/c/d C=e/f/g/h gen=i/j/k/l/m auth=n/o/p tc=q/r db=s/t/u/v synth=w/x/y sr=z/A/B/C
.Pp
q=Queries
   a Total Queries
   b Bad Requests
   c CHAOS queries
   d With NSID
C=Cookies
   e With Server Cookie
   f Cookie Only (Very rare)
   g Wrong Cookie (expired)
   h Malformed Cookie
gen=General
   i Passthru Out
   j Passthru In
   k CHAOS Refused
   l No Authority
   m Wrong Class
auth=Authority Zone Queries
   n ANY
   o SOA
   p NS
tc=Truncated
   q ipv4
   r ipv6
db=Answers from Zone Databases
   s Served from DB
   t NoError from DB
   u NXDomain from DB
   v FormErr from DB
synth=Synthesized Answer
   w=Forward Domain
   x=Reverse Domain
   y=Not synthesized
sr=Synthesized Result
   z=Served
   A=NoError
   B=NXDomain
   C=FormErr
.Ed
.Ss Ptr and Forward
.Bd -literal -offset indent
A Ptr q=a good=b(c) trunc=d invErr=e
AAAA Ptr q=a good=b(c) trunc=d invErr=e
A Forward q=a good=b(c) trunc=0 invErr=e
AAAA Forward q=a good=b(c) trunc=0 invErr=e
.Pp
   a=queries
   b=Good responses
   c=Good RRs in Answer Section
   d=Well formed but truncated, likely qname minimization
   e=Reverse qName is not an inverted IP Address
.Ed
.Ss RRL
.Bd -literal -offset indent
RRL RPS a/b/c/d/e Actions f/g/h IPR i/j/k/l/m RTR n/o/p/q/r/s L=t/u
.Pp
RPS=Allowance used per second
   a=Answers>0		(AllowanceAnswer)
   b=Authority>0	(AllowanceReferral)
   c=NOData		(AllowanceNoData)
   d=NXDomain		(AllowanceNXDomain)
   e=Error		(AllowanceError)
Actions=Recommended action
   f=Send
   g=Drop
   h=Slip
IPR=IP Reasons
   i=Ok
   j=Not Configured (--rrl-requests-psec)
   k=Not Reached (future counter)
   l=Rate Limited
   m=Cache Full
RTR=Response Tuple Reasons
   n=Ok
   o=Not Configured (--rrl-*-psec)
   p=Not Reached (future counter)
   q=Rate Limited
   r=Not UDP (RRL does not apply)
   s=Cache Full
L=Cache
   t=Average Cache Size
   u=Evictions
.Ed
.Sh PERFORMANCE
While
.Nm
is not particularly designed with performance in mind, it is interesting to note
the performance and concurrency impact of a
.Sy go [golang]
implementation.
A number of tests were run with
.Xr dnsperf 1
.Sy [dns-oarc]
to inject 4,000,000 random queries while simulating 20 concurrent clients.
This table shows the average results across multiple runs:
.
.\" The white spaces in Platform and OS are needed for the pdf output. Having said
.\" that, mandoc does not generate Ellipses correctly with pdf output, so...
.
.Bl -column ".Sy Platform    " ".Sy OS          " ".Sy Queries/s" ".Sy Memory"
.It Sy Platform Ta Sy OS Ta Sy Queries/s Ta Sy Memory
.It Li Pi4 (arm64) Ta Fx 13.0 Ta 18,112 Ta 17MB
.It Li i5-6260U (x64) Ta Debian 5.10 Ta 82,211 Ta 18MB
.El
.Pp
Since
.Xr dnsperf 1
was run on the
.Em same
system, exchanging queries via loopback, these results should be viewed as
indicative rather than definitive.
.Nm
was run with
.Fl -log-queries=false
during these tests but it was otherwise a normal invocation.
.
.Sh SEE ALSO
.
.\" Was .Bd -literal -offset indent ... .Ed
.
.Bl -column ".Sy Project" ".Sy Description      " ".Sy Link"
.It Li autoreverse Ta Project Home Page Ta https://github.com/markdingo/autoreverse
.It Li [dns-oarc] Ta dnsperf Ta https://www.dns-oarc.net/tools/dnsperf
.It Li [golang] Ta The go language Ta https://go.dev
.It Li [RFC1918] Ta ipv4 Private Addresses Ta https://datatracker.ietf.org/doc/html/rfc1918
.It Li [RFC4193] Ta ipv6 Private Addresses Ta https://datatracker.ietf.org/doc/html/rfc4193
.It Li [RFC7873] Ta DNS Cookies Ta https://datatracker.ietf.org/doc/html/rfc7873
.It Li [RFC8501] Ta Reverse DNS in IPv6 Ta https://datatracker.ietf.org/doc/html/rfc8501#section-2.5
.It Li [RRL] Ta Response Rate Limiting Ta https://kb.isc.org/docs/aa-01000
.El
.
.Sh FUTURE
.Ss Fl -cache-directory Ar path
Relying on access to the global DNS during start-up may cause difficulties in
some environments (though if connectivity is a problem, inbound queries are
unlikely to arrive anyway...).
.Pp
In such cases it may be sensible for
.Nm
to cache delegation material and
.Fl -PTR-deduce
zones to use as a fallback during start-up if current information is
inaccessible.
Cache information could be refreshed when fetched and deleted if the source
authoritatively says it no longer exists.
.Sh HISTORY
First released in late 2021,
.Nm
development was triggered by a local ISP (ABB) offering free
.Em static
/48
.Sy ipv6
allocations.
Importantly, they also supported free reverse delegation to home and small
business accounts which is where
.Nm
comes in handy.
.
.Sh AUTHORS
.Nm
and this manual page were written by
.An Mark Delany .
.
.Sh BUGS
.Nm
has no clue about
.Sy DNSSEC .
.Pp
As always, any bugs or feedback should be directed to the project page at
https://github.com/markdingo/autoreverse