From: Alan T. DeKok Date: Tue, 27 Jan 2026 21:07:37 +0000 (-0500) Subject: move rlm_unbound "man" page to module configuration file, and antora X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d54d54953bfd96b4273ee1096c4126120707d08c;p=thirdparty%2Ffreeradius-server.git move rlm_unbound "man" page to module configuration file, and antora --- diff --git a/doc/antora/modules/reference/pages/raddb/mods-available/unbound.adoc b/doc/antora/modules/reference/pages/raddb/mods-available/unbound.adoc index 4d805a4a67a..439c735527a 100644 --- a/doc/antora/modules/reference/pages/raddb/mods-available/unbound.adoc +++ b/doc/antora/modules/reference/pages/raddb/mods-available/unbound.adoc @@ -7,64 +7,92 @@ 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(, [, ]) -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 @@ -73,5 +101,5 @@ unbound dns { } ``` -// 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. diff --git a/raddb/mods-available/unbound b/raddb/mods-available/unbound index b08b826e70a..692275310a1 100644 --- a/raddb/mods-available/unbound +++ b/raddb/mods-available/unbound @@ -10,63 +10,91 @@ # 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(, [, ]) # -# 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. +# diff --git a/redhat/freeradius.spec b/redhat/freeradius.spec index c210f29de0a..72a9c3e58de 100644 --- a/redhat/freeradius.spec +++ b/redhat/freeradius.spec @@ -1316,7 +1316,6 @@ fi %files unbound %defattr(-,root,root) %{_libdir}/freeradius/rlm_unbound.so -%doc %{_mandir}/man5/rlm_unbound.5.gz %endif %if %{with rlm_sigtran} diff --git a/src/bin/unit_test_module.c b/src/bin/unit_test_module.c index 269abf3278f..bf7d5da8cf5 100644 --- a/src/bin/unit_test_module.c +++ b/src/bin/unit_test_module.c @@ -1360,7 +1360,7 @@ static NEVER_RETURNS void usage(main_config_t const *config, int status) fprintf(output, " -h Print this help message.\n"); fprintf(output, " -i File containing request attributes.\n"); fprintf(output, " -m On SIGINT or SIGQUIT exit cleanly instead of immediately.\n"); - fprintf(output, " -n Read raddb/name.conf instead of raddb/radiusd.conf.\n"); + fprintf(output, " -n Read ${confdir}/name.conf instead of ${confdir}/radiusd.conf.\n"); fprintf(output, " -o Output file for the reply.\n"); fprintf(output, " -p Define which protocol namespace is used to read the file\n"); fprintf(output, " Use radius, dhcpv4, or dhcpv6\n"); diff --git a/src/modules/rlm_unbound/all.mk.in b/src/modules/rlm_unbound/all.mk.in index 58195b3a314..f8847c70549 100644 --- a/src/modules/rlm_unbound/all.mk.in +++ b/src/modules/rlm_unbound/all.mk.in @@ -11,6 +11,4 @@ SOURCES := $(TARGETNAME).c io.c log.c SRC_CFLAGS := @mod_cflags@ TGT_LDLIBS := @mod_ldflags@ $(OPENSSL_LIBS) -MAN := rlm_unbound.5 - LOG_ID_LIB = 54 diff --git a/src/modules/rlm_unbound/rlm_unbound.5 b/src/modules/rlm_unbound/rlm_unbound.5 deleted file mode 100644 index 907934b0037..00000000000 --- a/src/modules/rlm_unbound/rlm_unbound.5 +++ /dev/null @@ -1,81 +0,0 @@ -.\" # 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(, [, ]) -Perform the lookup of against returning up to - results. The returned data type is appropriate to the record -type being queried. -.IP %dns(, A) -Performs an A lookup for the owner name, returning the results as IPv4 -addresses. -.IP %dns(, AAAA) -Performs an AAAA lookup for the owner name, returning the results as IPv6 -addresses. -.IP %dns(, PTR) -Performs a PTR lookup for the owner. -.IP %dns(, 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 -