Skip to main content

Debugging FreeRADIUS

Verbose Logging

Starting the FreeRADIUS server with the -X flag will enable verbose logging.

This is managed through the GovWifi Terraform. Due to the volume of transactions on production, enabling this will have a significant impact on performance and is not recommended in production.

A better way to use this would be to enable it on staging and to have the client who is having trouble connect to that IP.

It will contain all the details of the authentication request which can be used to diagnose issues. While the debug output is comprehensive, there may be information it doesn’t provide which is useful to surface. See the ‘Learning about FreeRADIUS’ page for options.

Command line testing tools

Most Linux distributions include a FreeRADIUS utils package (freeradius-utils in both Ubuntu and Alpine) which includes the radtest command line tool. If using MacOS homebrew it is part of the freeradius-server package.

Radtest can be used to test that a FreeRADIUS server is broadly working but does not support the more advanced EAP/TLS methods used by GovWifi. It can be invoked as follows:

radtest testing password localhost 0 testing123"


  • ‘testing’ is a valid username (e.g. set in mods-config/files/authorize)
  • ‘password’ is the valid password for the ‘testing’ user
  • the server is running on the same host (replace ‘localhost’ with the correct IP address if not)
  • ‘0’ is the NAS-Port number. It can be set to anything.
  • ‘testing123’ is the shared secret set in the clients.conf file for the host on which radtest is being run.

To test EAP/TLS based authentication methods use the eapol_test tools. It is currently used in full-stack automated testing and health checking. Unfortunately eapol_test is not available in the repositories of most Linux distributions and has to be compiled. It is not available in homebrew and it is not practical to compile under MacOS.

The following Dockerfile will create a minimal Ubuntu Docker image and compile eapol_test:

FROM ubuntu:20.04

RUN apt-get update -y && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y \
    --no-install-recommends ca-certificates \
    git build-essential pkg-config libssl-dev libnl-3-dev \
    libnl-genl-3-dev && \
    apt-get clean && \
    apt-get autoremove && \
    rm -rf /var/lib/apt/lists

RUN git clone --depth 1 --single-branch --branch v3.2.x && \
    /freeradius-server/scripts/ci/ && \
    cp /freeradius-server/scripts/ci/eapol_test/eapol_test \
    /usr/local/bin/ && \
    rm -rf /freeradius-server

CMD ["/bin/bash"]

Common error messages

Error: Ignoring request to auth address * port 1812 bound to server default from unknown client

This means that the client isn’t whitelisted by the RADIUS server.

invalid Request Authenticator! (Shared secret is incorrect.)

The server knows the IP but it failed to authenticate with its pre-shared key.

This page was last reviewed on 5 September 2023. It needs to be reviewed again on 5 March 2024 by the page owner #govwifi .
This page was set to be reviewed before 5 March 2024 by the page owner #govwifi. This might mean the content is out of date.