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:
# 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 for a true
Unix manpage. You see, the manpage does not come out and actually
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
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
(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.)