rlm_unbound - Man Page

Each instance of rlm_unbound provides an embedded DNS client for performing DNS lookups.  Each instance may be configured separately to query different DNS horizons, change DNSSEC options, etc.

The module is primarily intended for use by other modules through internal APIs, and so, instances should be initialized earlier than those modules which use them.  Each instance does also provide some xlat functionalities for general use and for troubleshooting.

Each instance of rlm_unbound may take the following parameters:

filename

This file must exist and must point to a valid libunbound configuration file. The default is ${raddbdir}/mods-config/unbound/default.conf.

timeout

While libunbound provides an asyncronous API for internal use, using any xlat is done syncronously from the perspective of unlang.  This value limits the amount of time a request will wait for DNS to respond, after which the xlat will fail.  The default is 3000 milliseconds.  This setting is independent of any libunbound configuration values.

resolvconf

Full path of a resolv.conf file to load resolver details from.  If this is not set then libunbound will query root DNS servers.

hosts

Full path of a hosts file to load.  This provides a mechanism for local overrides to names which would otherwise not resolve or need different results to those which a DNS resolution would provide.

An instance named, for example, "dns" will provide the following xlat functionalities:

%{dns-a:<owner>}

Performs an A lookup for the owner name, returning a stringified IPv4 address.  Only the first A record in the RRSET will be returned.

%{dns-aaaa:<owner>}

Performs an AAAA lookup for the owner name, returning a stringified IPv6 address.  Only the first AAAA record in the RRSET will be returned.

%{dns-ptr:<owner>}

Performs a PTR lookup for the owner.

Logging from rlm_unbound can be problematic, especialy if more than one instantiation of the module is used.  This is due to the need for additional features in the underlying libunbound which hopefully will be enhanced over time.

There is a potential for a FreeRADIUS server using rlm_unbound to either fail to terminate cleanly (leaving zombie processes, failing to clean up other modules, and hanging after a SIGTERM until a SIGKILL is sent) or to fail valgrind checks during termination when run with -m.  Likewise this problem will rely on upstream enhancements before it can be fixed, and the exact behavior may change in interim releases until then.

The logging behavior of rlm_unbound may vary depending on whether FreeRADIUS is compiled with support for threads.

/etc/raddb/modules-available/rlm_unbound /etc/raddb/modules-config/unbound/

radiusd(8), radiusd.conf(5) libunbound(3) unbound.conf(5)

Brian S. Julin, bjulin@clarku.edu