The `unbound` module performs queries against a DNS service to allow
FQDNs to be resolved during request processing.
+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
+functions for general use and for troubleshooting.
+
+## Caveats
+
+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 of libunbound until then.
+
## Configuration Settings
-File to read unbound configuration details from.
+filename:: The libunbound configuration file.
filename = "${confdir}/mods-config/unbound/default.conf"
-Timeout for unbound queries.
+timeoit:: For unbound queries.
timeout = 3000
-resolv.conf file to instruct unbound to load resolvers from.
+resolvconf:: resolv.conf file to instruct unbound to load
+resolvers from.
+
Defaults to not set.
-Without this set, unbound queries root DNS servers. If a local
-caching DNS server is available that will improve performance.
+
+Without this set, unbound will query the root DNS servers.
+This is NOT RECOMMENDED. A local caching DNS server will
+substantially improve performance.
resolvconf = "/etc/resolv.conf"
-hosts file to load data from. Defaults to not set.
+hosts:: hosts file to load data from.
+
+Defaults to not set.
hosts = "/etc/hosts"
-## xlat for DNS resolution
+## Functions for DNS resolution
+
+A function based on the instance name can be used to perform DNS lookups.
+
+%dns(<owner>, <record type>[, <limit>])
-An xlat based on the instance name can be used to perform DNS lookups.
+You must quote the parameters, e.g. `'example.com'`.
.Example
```
-%dns(www.example.com, A)
-%dns(www.example.com, AAAA)
+%dns('www.example.com', 'A')
+%dns('www.example.com', 'AAAA')
```
-Given an instance `dns` the above xlats will perform A record and
-AAAA record lookups on www.example.com.
+Given an instance `dns` the above function will perform `A` record and
+`AAAA` record lookups on `www.example.com`.
.Example
```
-%dns(1.1.168.192.in-addr.arpa, PTR)
+%dns('1.1.168.192.in-addr.arpa', 'PTR')
```
-The above example will perform reverse DNS lookup on 192.168.1.1
+The above example will perform reverse DNS lookup on `192.168.1.1`.
.Example
```
-%dns(example.com, MX, 1)
+%dns('example.com',' MX', '1')
```
-The above example will perform an MX lookup on example.com returning
-just the first result.
+The above example will perform an `MX` lookup on `example.com`, and
+will return just the first result.
+
+NOTE:: The DNS queries are blocking! A slow (or unavailable) DNS
+server can completely destroy the performance of FreeRADIUS.
+
== Default Configuration
}
```
-// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
+// Copyright (C) 2026 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
# The `unbound` module performs queries against a DNS service to allow
# FQDNs to be resolved during request processing.
#
+# 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
+# functions for general use and for troubleshooting.
+#
+# ## Caveats
+#
+# 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 of libunbound until then.
+#
#
# ## Configuration Settings
#
unbound dns {
#
- # File to read unbound configuration details from.
+ # filename:: The libunbound configuration file.
#
# filename = "${confdir}/mods-config/unbound/default.conf"
#
- # Timeout for unbound queries.
+ # timeoit:: For unbound queries.
#
# timeout = 3000
#
- # resolv.conf file to instruct unbound to load resolvers from.
+ # resolvconf:: resolv.conf file to instruct unbound to load
+ # resolvers from.
+ #
# Defaults to not set.
- # Without this set, unbound queries root DNS servers. If a local
- # caching DNS server is available that will improve performance.
+ #
+ # Without this set, unbound will query the root DNS servers.
+ # This is NOT RECOMMENDED. A local caching DNS server will
+ # substantially improve performance.
#
# resolvconf = "/etc/resolv.conf"
#
- # hosts file to load data from. Defaults to not set.
+ # hosts:: hosts file to load data from.
+ #
+ # Defaults to not set.
#
# hosts = "/etc/hosts"
}
#
-# ## xlat for DNS resolution
+# ## Functions for DNS resolution
+#
+# A function based on the instance name can be used to perform DNS lookups.
+#
+# %dns(<owner>, <record type>[, <limit>])
#
-# An xlat based on the instance name can be used to perform DNS lookups.
+# You must quote the parameters, e.g. `'example.com'`.
#
# .Example
#
# ```
-# %dns(www.example.com, A)
-# %dns(www.example.com, AAAA)
+# %dns('www.example.com', 'A')
+# %dns('www.example.com', 'AAAA')
# ```
#
-# Given an instance `dns` the above xlats will perform A record and
-# AAAA record lookups on www.example.com.
+# Given an instance `dns` the above function will perform `A` record and
+# `AAAA` record lookups on `www.example.com`.
#
# .Example
#
# ```
-# %dns(1.1.168.192.in-addr.arpa, PTR)
+# %dns('1.1.168.192.in-addr.arpa', 'PTR')
# ```
#
-# The above example will perform reverse DNS lookup on 192.168.1.1
+# The above example will perform reverse DNS lookup on `192.168.1.1`.
#
# .Example
#
# ```
-# %dns(example.com, MX, 1)
+# %dns('example.com',' MX', '1')
# ```
#
-# The above example will perform an MX lookup on example.com returning
-# just the first result.
+# The above example will perform an `MX` lookup on `example.com`, and
+# will return just the first result.
+#
+# NOTE:: The DNS queries are blocking! A slow (or unavailable) DNS
+# server can completely destroy the performance of FreeRADIUS.
+#
%files unbound
%defattr(-,root,root)
%{_libdir}/freeradius/rlm_unbound.so
-%doc %{_mandir}/man5/rlm_unbound.5.gz
%endif
%if %{with rlm_sigtran}
fprintf(output, " -h Print this help message.\n");
fprintf(output, " -i <file> File containing request attributes.\n");
fprintf(output, " -m On SIGINT or SIGQUIT exit cleanly instead of immediately.\n");
- fprintf(output, " -n <name> Read raddb/name.conf instead of raddb/radiusd.conf.\n");
+ fprintf(output, " -n <name> Read ${confdir}/name.conf instead of ${confdir}/radiusd.conf.\n");
fprintf(output, " -o <file> Output file for the reply.\n");
fprintf(output, " -p <radius|...> Define which protocol namespace is used to read the file\n");
fprintf(output, " Use radius, dhcpv4, or dhcpv6\n");
SRC_CFLAGS := @mod_cflags@
TGT_LDLIBS := @mod_ldflags@ $(OPENSSL_LIBS)
-MAN := rlm_unbound.5
-
LOG_ID_LIB = 54
+++ /dev/null
-.\" # DS - begin display
-.de DS
-.RS
-.nf
-.sp
-..
-.\" # DE - end display
-.de DE
-.fi
-.RE
-.sp
-..
-.TH rlm_unbound 5 "8 July 2013" "" "FreeRADIUS Module"
-.SH NAME
-rlm_unbound \- FreeRADIUS Module
-.SH DESCRIPTION
-Each instance of \fIrlm_unbound\fP provides an embedded DNS client
-for performing DNS lookups. Each instance may be configured separately
-to query different DNS horizons, change DNSSEC options, etc.
-.PP
-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.
-.PP
-Each instance of rlm_unbound may take the following parameters:
-.IP filename
-This file must exist and must point to a valid libunbound configuration file.
-The default is ${raddbdir}/mods-config/unbound/default.conf.
-.IP timeout
-While libunbound provides an asynchronous API for internal use, using any xlat
-is done synchronously 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.
-.PP
-An instance named, for example, "dns" will provide the following xlat
-functionalities:
-.IP %dns(<owner>, <record type>[, <limit>])
-Perform the lookup of <record type> against <owner> returning up to
-<limit> results. The returned data type is appropriate to the record
-type being queried.
-.IP %dns(<owner>, A)
-Performs an A lookup for the owner name, returning the results as IPv4
-addresses.
-.IP %dns(<owner>, AAAA)
-Performs an AAAA lookup for the owner name, returning the results as IPv6
-addresses.
-.IP %dns(<owner>, PTR)
-Performs a PTR lookup for the owner.
-.IP %dns(<owner>, MX, 1)
-Performs an MX lookup for the owner, returning just the first result.
-.PP
-.SH CAVEATS
-Logging from rlm_unbound can be problematic, especially 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.
-.PP
-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.
-.PP
-The logging behavior of rlm_unbound may vary depending on whether
-FreeRADIUS is compiled with support for threads.
-.PP
-.SH FILES
-.I /etc/raddb/modules-available/rlm_unbound
-.I /etc/raddb/modules-config/unbound/
-.PP
-.SH "SEE ALSO"
-.BR radiusd (8),
-.BR radiusd.conf (5)
-.BR libunbound (3)
-.BR unbound.conf (5)
-.SH AUTHOR
-Brian S. Julin, bjulin@clarku.edu
-
projects / thirdparty / freeradius-server.git / commitdiff
