Wandering Thoughts archives


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 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.)

sysadmin/UnboundRatelimitDocsGotcha written at 01:30:47; Add Comment

Page tools: See As Normal.
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.