rlm_unbound(5)

💖 rlm_unbound — the FreeRADIUS module 💖

okay bestie, sit down, we're talking about rlm_unbound(5), the FreeRADIUS Module that's basically a whole DNS client living inside your RADIUS server. no cap.

---

✨ NAME ✨

rlm_unbound — FreeRADIUS Module. yeah that's it, that's the name, iconic.

---

🌸 DESCRIPTION 🌸

so every single instance of rlm_unbound gives you an embedded DNS client for doing DNS lookups. and the way each instance can be configured separately?? obsessed. you can point one at a whole different DNS horizon, flip your DNSSEC options, whatever you want, per instance. main character config energy fr fr.

now, the tea: this module is primarily intended for use by other modules through internal APIs. which means the instances should be initialized earlier than the modules that use them — like, they need to be up and ready before their friends come knocking, yk? and each instance also hands out some xlat functionalities for general use and for troubleshooting, so you're not totally locked out of playing with it yourself. 🎀

each instance of rlm_unbound may take the following parameters:

• filename — this file must exist (no skipping, it's required) and must point to a valid libunbound configuration file. the default is ${raddbdir}/mods-config/unbound/default.conf. 💅
• timeout — okay so libunbound gives you an asynchronous API for internal use, but the second you use any xlat, it's synchronous from unlang's point of view. so this value limits how long a request will wait for DNS to respond, and after that the xlat just fails. the default is 3000 milliseconds. and heads up — this setting is independent of any libunbound configuration values, so don't go thinking they're linked. 🙈
• 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 instead. choose your vibe. 🌈
• hosts — full path of a hosts file to load. this is your little cheat code for local overrides: names that would otherwise not resolve, or that need different results than what an actual DNS resolution would give you. lowkey so useful. 🍓

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. (just the one. the first. don't @ me.) ⭐
• %{dns-aaaa:<owner>} — performs an AAAA lookup for the owner name, returning a stringified IPv6 address. again, only the first AAAA record in the RRSET gets returned. 💜
• %{dns-ptr:<owner>} — performs a PTR lookup for the owner. short, sweet, slays. 🦋

---

💀 CAVEATS 💀

okay this is the part where we get real. logging from rlm_unbound can be problematic, especially if you're running more than one instantiation of the module. why? because the underlying libunbound needs additional features that it just... doesn't have yet. hopefully it'll get enhanced over time. fingers crossed bestie. 🤞

there's also a potential for a FreeRADIUS server using rlm_unbound to do one of two deeply unglamorous things:

• fail to terminate cleanly — leaving zombie processes, failing to clean up other modules, and hanging after a SIGTERM until a SIGKILL is sent 😭
• 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. so like, it's giving "we'll see" energy. not a bug we can just fix ourselves, fr.

and one more for the road: the logging behavior of rlm_unbound may vary depending on whether FreeRADIUS is compiled with support for threads. so your mileage genuinely depends on your build. 🧚

---

📁 FILES 📁

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

---

👀 SEE ALSO 👀

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

---

👑 AUTHOR 👑

Brian S. Julin, bjulin@clarku.edu — legend behavior, honestly.

---

and that's the whole page, bestie! this one's from 8 July 2013, part of the FreeRADIUS Module docs, and it's serving us DNS, xlat, and a lil bit of chaos on the way out. stan a module that tells you its flaws up front. 💖✨🎀