From 9a01bdf8432afda42ce64c573fe229c9400ebd9b Mon Sep 17 00:00:00 2001 From: RadiusDeck Dev Date: Mon, 26 Oct 2026 14:14:15 +0700 Subject: [PATCH] feat: publish FreeRADIUS unknown client guide Add "How to Fix FreeRADIUS Unknown Client Errors" at /blog/freeradius-unknown-client/, tested on FreeRADIUS 3.2.10. Link the clients.conf guide to the new article from "What counts as a RADIUS client" and "Unknown client". --- _posts/2026-10-23-freeradius-clients-conf.md | 8 +- .../2026-10-26-freeradius-unknown-client.md | 370 ++++++++++++++++++ 2 files changed, 376 insertions(+), 2 deletions(-) create mode 100644 _posts/2026-10-26-freeradius-unknown-client.md diff --git a/_posts/2026-10-23-freeradius-clients-conf.md b/_posts/2026-10-23-freeradius-clients-conf.md index 657708b..20eae9d 100644 --- a/_posts/2026-10-23-freeradius-clients-conf.md +++ b/_posts/2026-10-23-freeradius-clients-conf.md @@ -48,8 +48,9 @@ in `mods-config/files/authorize` or an SQL database. `clients.conf` answers one question: which devices may talk to this server, and which shared secret each of them uses. Requests from an address that matches no -client are ignored; the log message is shown under -[Unknown client](#unknown-client). +client are ignored. The log message is shown under +[Unknown client](#unknown-client); causes and fixes are in +[How to Fix FreeRADIUS Unknown Client Errors](/blog/freeradius-unknown-client/). ## Minimal client example @@ -371,6 +372,9 @@ network gateway `10.88.10.1`; the result depends on the Docker network configuration. If the client is already in the file, restart FreeRADIUS: a client added after startup is not loaded yet. +For the other causes and how to confirm the fix, see +[How to Fix FreeRADIUS Unknown Client Errors](/blog/freeradius-unknown-client/). + ## Frequently asked questions ### Do I need to restart FreeRADIUS after editing clients.conf? diff --git a/_posts/2026-10-26-freeradius-unknown-client.md b/_posts/2026-10-26-freeradius-unknown-client.md new file mode 100644 index 0000000..e791d42 --- /dev/null +++ b/_posts/2026-10-26-freeradius-unknown-client.md @@ -0,0 +1,370 @@ +--- +title: How to Fix FreeRADIUS Unknown Client Errors +description: >- + Fix "Ignoring request ... from unknown client" in FreeRADIUS: read the source + address from the log, check NAT and Docker, find the clients.conf the server + loads, restart, and confirm the fix with radtest. +tested: + date: 2026-10-26 + environment: Official FreeRADIUS Docker image, Docker 29.9.2 + freeradius: "3.2.10" +related: + - /blog/freeradius-clients-conf/ + - /blog/freeradius-web-gui/ +--- + +**Short answer:** `Ignoring request ... from unknown client 192.0.2.10` means +that no client entry in the configuration FreeRADIUS loaded matches the source +IP address of the request, so the server drops it without a reply. Take the +address from the message, add or fix a `client` block with that address in the +`clients.conf` the server actually reads, check the configuration with +`freeradius -XC`, restart FreeRADIUS, and send the request again. The shared +secret and the `NAS-IP-Address` attribute play no part in this check. + +* TOC +{:toc} + +## Tested with + +- FreeRADIUS 3.2.10, official Docker image `freeradius/freeradius-server:3.2.10`, + on Docker 29.9.2. +- Log file location checked on the Ubuntu 24.04 package, FreeRADIUS 3.2.5. +- Last technical check: October 26, 2026. + +Addresses come from documentation ranges (`192.0.2.0/24`, `2001:db8::/32`). In +the examples, the FreeRADIUS server is `192.0.2.1`, and the access points +`office-ap-01` and `office-ap-02` are `192.0.2.10` and `192.0.2.11`. The Docker +gateway addresses `10.88.10.1` and `172.17.0.1` are the real addresses from our +test setup. Replace all addresses and secrets with your own. + +## The error message + +With FreeRADIUS in debug mode (`freeradius -X`), the message looks like this: + +```text +Ignoring request to auth address * port 1812 bound to server default from unknown client 192.0.2.10 port 47823 proto udp +``` + +When the server runs normally, the same line goes to the log file with an +`Error:` prefix. On the Ubuntu package the file is +`/var/log/freeradius/radius.log`: + +```text +Mon Oct 26 06:17:36 2026 : Error: Ignoring request to auth address * port 1812 bound to server default from unknown client 192.0.2.10 port 40926 proto udp +``` + +Each part of the message points to something you can check: + +- `auth address * port 1812`: the socket that received the request. `auth` is + for authentication, `acct` for accounting (port `1813`). +- `bound to server default`: the virtual server of that socket. +- `unknown client 192.0.2.10`: the source IP address of the request, as + FreeRADIUS sees it. +- `port 47823 proto udp`: the source port. It can change between requests and + plays no part in selecting the client entry. + +FreeRADIUS does not answer an unknown client, so the device sees a timeout. +`radtest` sends the request three times and gives up: + +```text +(0) No reply from server for ID 132 socket 3 +``` + +Accounting requests from the same device produce the same error for the +`acct` socket: + +```text +Ignoring request to acct address * port 1813 bound to server default from unknown client 192.0.2.10 port 50595 proto udp +``` + +## Find the cause + +Compare the address in the message with the `ipaddr` values of your clients. +The table lists the causes we reproduced, in the order worth checking: + +| Cause | How to recognize it | +|---|---| +| [No client for this address](#no-client-for-this-address) | No `client` block has this `ipaddr`, and no network entry contains it | +| [The address is not what you expected](#the-source-address-is-not-what-you-expected) | The message shows a NAT, Docker gateway, or IPv6 address | +| [The client is in a file the server does not load](#the-client-is-in-a-file-the-server-does-not-load) | `freeradius -XC` does not list the file with the client | +| [The change was not applied](#the-change-has-not-been-applied) | The client is in the loaded file, but the server was not restarted | +| [The client belongs to another virtual server](#the-client-belongs-to-another-virtual-server) | The client is inside a `server` section, and the message names a different server or port | + +### No client for this address + +Add a client with the address from the message: + +```text +client office-ap-01 { + ipaddr = 192.0.2.10 + secret = "REPLACE-WITH-A-32-CHARACTER-RANDOM-SECRET" +} +``` + +The [clients.conf guide](/blog/freeradius-clients-conf/) explains the fields, +how to generate the secret, and how one entry can cover a whole network. + +### The source address is not what you expected + +FreeRADIUS selects the client by the source IP address of the packet. The +attributes inside the request do not matter. In our test, a request from +`192.0.2.11` carried `NAS-IP-Address = 192.0.2.10`, the address of a configured +client, and was still ignored: + +```text +Ignoring request to auth address * port 1812 bound to server default from unknown client 192.0.2.11 port 40370 proto udp +``` + +The source address can differ from the one you configured for the device: + +- **NAT.** Behind NAT, FreeRADIUS sees the translated address. The same applies + when a device sends requests from a different interface than the one you + expect, for example its management address instead of its LAN address. + Either configure the device to send from the expected address, or use the + address from the message. +- **Docker port publishing.** In our tests, requests sent to a published port + arrived from the address of the Docker network gateway, not from the sender. + A request from the Docker host to `127.0.0.1:18121` arrived from `10.88.10.1`, + the gateway of the container's network. A request from a container in another + Docker network to the host address arrived from `172.17.0.1`, the gateway of + the default `bridge` network: + + ```text + Ignoring request to auth address * port 1812 bound to server default from unknown client 10.88.10.1 port 59933 proto udp + Ignoring request to auth address * port 1812 bound to server default from unknown client 172.17.0.1 port 59601 proto udp + ``` + + What address you see depends on the Docker network configuration, so read it + from the message. +- **IPv6.** A device that reaches the server over IPv6 is matched by its IPv6 + address. In our test, a client with only an IPv4 address was unknown when the + same device sent the request over IPv6: + + ```text + Ignoring request to auth address :: port 1812 bound to server default from unknown client 2001:db8::10 port 45033 proto udp + ``` + + A `client` block holds one address, so add a second block for the IPv6 + address. `ipaddr` accepts IPv6 addresses: + + ```text + client office-ap-01-v6 { + ipaddr = 2001:db8::10 + secret = "REPLACE-WITH-THE-SECRET-OF-OFFICE-AP-01" + } + ``` + +Before you add a NAT or Docker gateway address as a client, consider what else +uses it. Every device whose requests come through that address will match the +same client entry and use the same secret. + +### The client is in a file the server does not load + +Check which files the server reads: + +```bash +sudo freeradius -XC | grep 'including' +``` + +The package installation on Ubuntu reads `/etc/freeradius/3.0/clients.conf`, +the official Docker image reads `/etc/freeradius/clients.conf`. A client in a +separate file is loaded only when `clients.conf` includes it. In our test, a +client in `clients.d/office-ap-01.conf` stayed unknown until we added this +line at the end of `clients.conf`: + +```text +$INCLUDE clients.d/ +``` + +After that, the check lists the file: + +```text +including files in directory /etc/freeradius/clients.d/ +including configuration file /etc/freeradius/clients.d/office-ap-01.conf +``` + +If FreeRADIUS runs in Docker with `clients.conf` mounted as a single file, +checks inside the container can show an old version of the file. Tools that +replace the file, such as `sed -i`, create a new file on the host. In our test, +`grep` inside the container did not find the new client, and `freeradius -XC` +inside the container checked the old file. After a container restart the new +file was loaded. Mounting the whole configuration directory avoids this. + +### The change has not been applied + +FreeRADIUS reads static clients at startup. In our test, a client saved to the +loaded `clients.conf` remained unknown until the restart: + +```text +Ignoring request to auth address * port 1812 bound to server default from unknown client 192.0.2.10 port 54783 proto udp +``` + +A reload does not help: on the Ubuntu package, `systemctl reload freeradius` +sends a HUP signal, and FreeRADIUS lead developer Alan DeKok writes that +["You can't reload clients.conf via a HUP."](https://lists.freeradius.org/pipermail/freeradius-users/2021-July/100451.html) +Restart the server as shown in [Confirm the fix](#confirm-the-fix). + +### The client belongs to another virtual server + +A `client` block inside a `server` section is known only to the `listen` +sockets of that section. The comments in the stock `sites-available/example` +put it this way: if the client sends a request to a different socket, the +server will treat it as an unknown client. + +The debug output lists the sockets and their virtual servers: + +```text +Listening on auth address * port 1812 bound to server default +Listening on auth address * port 1821 bound to server branch +``` + +In our test, `office-ap-01` was defined inside `server branch`. Its requests to +port `1821` were processed, and its requests to port `1812` were ignored: + +```text +Ignoring request to auth address * port 1812 bound to server default from unknown client 192.0.2.10 port 37215 proto udp +``` + +Either configure the device to send to the port of its virtual server, or +define the client outside any `server` section in `clients.conf`. + +## Confirm the fix + +Check the configuration, restart FreeRADIUS, and send the request again: + +```bash +# Package installation (systemd) +sudo freeradius -XC +sudo systemctl restart freeradius + +# Docker +docker exec freeradius -XC +docker restart +``` + +The check must end with `Configuration appears to be OK`. FreeRADIUS does not +start with a broken configuration. + +Then repeat the request that failed. Send it from the device's address, to the +same server address, port, and IP version as in the error message. `radtest` +is in the `freeradius-utils` package and in the official Docker image: + +```bash +radtest test-user test-password 192.0.2.1 0 'REPLACE-WITH-THE-CLIENT-SECRET' +``` + +The server argument also takes a port, and an IPv6 address in brackets: + +```bash +# Client of the branch virtual server on port 1821 +radtest test-user test-password 192.0.2.1:1821 0 'REPLACE-WITH-THE-CLIENT-SECRET' + +# Request over IPv6 +radtest test-user test-password '[2001:db8::1]' 0 'REPLACE-WITH-THE-CLIENT-SECRET' +``` + +`radtest` checks authentication only. If the error was for the `acct` socket, +send an accounting request with `radclient`, which is in the same package: + +```bash +echo 'Acct-Status-Type = Start, User-Name = test-user, Acct-Session-Id = test-1, NAS-IP-Address = 192.0.2.10' \ + | radclient 192.0.2.1:1813 acct 'REPLACE-WITH-THE-CLIENT-SECRET' +``` + +Expected result: + +```text +Received Accounting-Response Id 46 from 192.0.2.1:1813 to 192.0.2.10:34523 length 20 +``` + +For authentication, treat the disappearance of the error and a successful +login as two separate results. In our test, after the restart: + +- A user that does not exist got `Access-Reject`. The server no longer + ignored the request, so the client entry worked: + + ```text + Received Access-Reject Id 215 from 192.0.2.1:1812 to 192.0.2.10:39249 length 38 + ``` + +- The test user with the right password got `Access-Accept`: + + ```text + Received Access-Accept Id 111 from 192.0.2.1:1812 to 192.0.2.10:47056 length 38 + ``` + +An `Access-Reject` after the fix points to the user's credentials or the +authentication policy, not to `clients.conf`. + +If there is still no reply but the `unknown client` message is gone, the +server now recognizes the client and drops the request for another reason. The +log names it. The two common ones are a wrong shared secret +(`invalid Message-Authenticator`) and a device that does not send +Message-Authenticator. Both are explained in the clients.conf guide under +[Common errors](/blog/freeradius-clients-conf/#common-errors) and +[Message-Authenticator and BlastRADIUS settings](/blog/freeradius-clients-conf/#message-authenticator-and-blastradius-settings). + +If the log shows nothing at all for the request, the request did not reach +FreeRADIUS. Check the server address and port on the device, firewalls on the +way, and the `Listening on` lines in the debug output. + +## Frequently asked questions + +### Does the shared secret matter for an unknown client error? + +No. FreeRADIUS looks up the client by source address before it checks the +secret. In our test, requests with arbitrary secrets produced the same +message. A wrong secret for a known client produces a different message, +`invalid Message-Authenticator`. + +### Does NAS-IP-Address have to match ipaddr? + +No. The client is selected by the source IP address of the packet. A request +with the right `NAS-IP-Address` from a different source address is still +ignored. + +### Will systemctl reload fix it? + +No. A reload sends a HUP signal, and static clients from `clients.conf` are not +reloaded on HUP. Restart FreeRADIUS after adding or changing a client. + +### Where does FreeRADIUS log unknown client errors? + +In debug mode (`freeradius -X`), on the terminal. Otherwise in `radius.log` in +the log directory, `/var/log/freeradius/radius.log` on the Ubuntu package. With +the official Docker image, `docker logs ` shows the +output. + +### Why does the message show my Docker gateway address? + +Docker port publishing can change the source address of requests. In our +tests, requests to a published port arrived from the gateway of a Docker +network. FreeRADIUS matches clients against that address. + +### Why does the error mention port 1813? + +Port `1813` is for accounting. The device sends accounting requests to it, and +the same client entry must match them. Look up the source address the same way +as for authentication, and test the fix with an accounting request, as shown +under [Confirm the fix](#confirm-the-fix). + +## Add the client from a web interface + +The fix is always the same: a correct `client` block in the loaded +`clients.conf` and a restart. If you manage many devices, you can do the first +part with [RadiusDeck](https://github.com/radiusdeck/radiusdeck), an +open-source web interface for `clients.conf`. It edits the file in place, +which avoids the single-file Docker mount problem described above, and creates +a backup before each change. You still apply the change by restarting +FreeRADIUS, or through an optional reload sidecar. The +[RadiusDeck README](https://github.com/radiusdeck/radiusdeck#readme) covers +installation; its demo starts from an unknown client error and ends with a +successful request. + +## Sources + +- Comments in the stock `clients.conf`, `radiusd.conf`, and + `sites-available/example` of FreeRADIUS 3.2.10. +- [Reload Freeradius server without Restart](https://lists.freeradius.org/pipermail/freeradius-users/2021-July/100451.html), + freeradius-users mailing list, July 2021. +- [FreeRADIUS clients.conf: Examples and Best Practices](/blog/freeradius-clients-conf/).