== Unbound illustrates the Unix manpage mistake with its ratelimits documentation

Our departmental recursive nameservers are based on OpenBSD, which
has recently switched from BIND to Unbound and NSD. As a result of
this, we've been in the process of setting up a working Unbound
configuration. In the process of this we ran into an interesting
issue.

A relatively current _unbound.conf_ manpage has this to say about
(some) ratelimiting options (I'm excerpting here):

> - ~~ratelimit:~~ *<number or 0>*: Enable ratelimiting of queries
>   sent to the nameserver for performing recursion. If 0, the default,
>   it is disabled. [...] For example, 1000 may be a suitable value to
>   stop the server from being overloaded with random names, and keeps
>   unbound from sending traffic to the nameservers for those zones.
>
> - ~~ratelimit-for-domain:~~ *<domain>* *<number qps>*: Override the
>   global ratelimit for an exact match domain name with the listed
>   number. [...]

So you set up an Unbound configuration that contains the following:

.pn prewrap on

>  # apparent good practice
>  ratelimit: 1000
>
>  # but let's exempt our own zones from it,
>  # just in case.
>  ratelimit-for-domain: utoronto.ca 0

Congratulations, on at least the OpenBSD version of Unbound you
have just blown your own foot off; you'll probably be unable to
resolve anything in utoronto.ca. If you watch the logs sufficiently
carefully, you can eventually spot a little mention that your query
for say the A record of _www.utoronto.ca_ has been ratelimited.

(If you're writing a moderately complicated Unbound configuration
for the first time, it may take you some time to reach this point
instead of suspecting that you have screwed something up in other
bits of the configuration.)

What has happened is that you have not read the manpage with the
[[necessary closeness ../unix/BourneExecLimitation]] for a true
Unix manpage. You see, the manpage does not come out and actually
say that _ratelimit-for-domain_ treats a ratelimit of 0 as unlimited.
It just looks like it should, because _ratelimit-for-domain_ is a
more specialized version of plain _ratelimit_ so you'd certainly
assume that they treat their number argument in the same way. And
of course that would be the sensible thing to do so you can do just
what we're trying to do here.

This may or may not be an Unbound bug in either Unbound itself or
in the _unbound.conf_ manpage. Unix's minimalistic, legalistic
'close reading' history of both reading and writing manpages makes
it impossible to tell, because this could be both intended and
properly documented.

(In my opinion it is not well documented if it is intended, but
that is a different argument. Classical style Unix manpages take
specification-level terseness far too far for my tastes, partly for
historical reasons. However this is not a winning argument to make
with someone who likes this extreme terseness and 'pay attention
to every word, both present and absent' approach; they will just
tell you to read more carefully.)