radius-admin

Version 0.2.5 Early development Free software, AGPL-3.0

A secure web console for FreeRADIUS.

radius-admin turns a FreeRADIUS 3.2 server into a network access control service you run from the browser. 802.1X, MAB, RadSec and switch logins live in one audited, role-based, MFA-protected portal, instead of hand-edited configuration files and SQL tables.

Every change is validated before FreeRADIUS sees it, and rolled back automatically if FreeRADIUS does not come back up.

Install steps View the code on GitHub

Runs on Ubuntu 24.04 LTS with FreeRADIUS 3.2.10, PostgreSQL 16 and nginx. No pip, no npm.

Safe apply What happens when you click Apply
  1. Staged waiting for Apply

    You changed a RADIUS client in the console. FreeRADIUS has not seen it yet.

  2. Validate

    The root helper runs radiusd -XC on a copy of the configuration with the new files in place. If that fails, nothing is touched.

  3. Back up and install

    The current files go to a timestamped backup. The new ones are installed atomically.

  4. Restart

    FreeRADIUS restarts with the new configuration.

  5. Check

    The helper waits up to 15 seconds for the service to be active and listening on UDP 1812.

  6. If it listens: Live applied

    FreeRADIUS is answering with the new configuration. The backup stays available for a manual roll back.

  7. If it does not: Rolled back apply failed

    The helper restores the backup and restarts FreeRADIUS with it. The network keeps authenticating on the last good configuration, and your change stays staged.

You always know whether a change is live

FreeRADIUS reads access decisions straight from PostgreSQL, so most edits need no restart. The few that do are held back until you apply them. The console uses one colour for each, and so does this page.

Live

Takes effect on the next authentication

  • Access rules: directory group to VLAN
  • MAB devices and approvals from the unknown-device queue
  • Device administrator accounts and the directory groups allowed to log in
  • Settings

No restart. A rule tester shows which rule would match before a device ever tries.

Staged

Waits until you click Apply

  • RADIUS clients (switches, access points, controllers)
  • RadSec listener and per-client transport
  • Custom unlang policy
  • Device profiles and the default profile

You review the difference, validate, then apply. Applying restarts FreeRADIUS through the safe-apply sequence above.

Red is reserved for rejects, failures and destructive actions.

What you can run with it

One server, several kinds of client. Each row is a setup the project covers today.

Computers with certificates
Wired and wireless 802.1X with EAP-TLS. The computer's Active Directory group decides the VLAN, per wired port or per SSID. Nested groups work.
People and devices with a password
EAP-TTLS with PAP inside, for local accounts with groups and expiry or for Active Directory accounts, using the same access rules. PEAP-MSCHAPv2 where devices need it.
Printers, cameras and IoT
MAC Authentication Bypass with a VLAN per device, optional expiry and vendor names, on wired ports and, where the device profile allows it, through wireless access points. Unknown devices that try to connect show up in a queue for one-click approval.
Switch and device administrators
Logins over RADIUS (PAP), limited to the management subnet, with optional full admin rights in the form the device expects.
Switches and access points from different vendors
Each RADIUS client has a device profile that decides the reply attributes, MAB port types, change of authorization and SNMP port names. Copy a built-in profile to describe a device of your own; no code changes needed.
Access points across untrusted networks
RadSec (RADIUS over TLS) per client. Move an access point to RadSec while your switches stay on plain RADIUS.
Regulated environments
Optional FIPS mode, a hash-chained audit log of every administrative action, and printable audit reports.
Teams with an identity provider
Admins sign in to the console with SAML single sign-on (Microsoft Entra ID tested). Their role comes from group membership.

The console

Access rules you can test before anyone connects

The first rule whose group matches assigns the VLAN. No match means reject. FreeRADIUS reads the rules on every authentication, so a saved change applies to the next one.

A rule can also send a role, for devices whose profile uses roles. The tester asks the same database function FreeRADIUS uses, and changes nothing.

Access rules

Test a match

Accept, VLAN 20

Matched rule: order 1, wired, group Wired-Staff.

Wired 3 rules, evaluated top to bottom

OrderAD groupVLANDescriptionStatus
1Wired-Staff20Staff computersEnabled
2Wired-Lab30labLab benchesEnabled
3Wired-Kiosks40Front desk kiosksDisabled

A reason for every reject

The authentication log records every accept and reject. Open one and you get the reject reason, the client certificate, the directory groups and the access rule that matched, or the fact that none did.

Passwords are never stored.

Rejected: host/pc-0142.example.net

Why it was rejected

no enabled access rule matches the computer's AD groups for this connection

Request

Result
Access-Reject
Method
802.1X certificate (EAP-TLS)
Switch
sw-floor2 192.0.2.21
Port
gi14
Station
AA-BB-CC-00-01-42

Client certificate

DNS name
pc-0142.example.net
Issuer
CN=Example Issuing CA
Groups
Domain Computers, Wired-Kiosks

Review the difference, then apply

Changes to RADIUS clients and the custom policy are rendered into two FreeRADIUS files. The Apply page shows exactly what would change, with shared secrets masked.

Validate runs the check without installing anything. Admins can roll back to an earlier backup from the same page.

Apply changes

Changes pending

policy 5d1c0a9be27f · clients a83f6e0b14cd

RADIUS clients /etc/freeradius/radius-admin-clients.conf 8 added, 0 removed

+client ap-lobby {+	ipaddr = 198.51.100.24+	secret = "********"+	shortname = ap-lobby+	nas_type = other+	require_message_authenticator = yes+	limit_proxy_state = yes+}

A dashboard that says what is left to do

After the install, a setup checklist tracks what is still to configure: RADIUS clients, access rules, the device admin subnet and a first apply. Single sign-on, RadSec, switch monitoring and alert e-mail are optional steps.

Day to day it shows whether FreeRADIUS is running, whether the configuration is in sync, and the most recent rejects.

Dashboard

FreeRADIUS

Running

FreeRADIUS Version 3.2.10

Configuration

Changes pending

Last applied 2026-11-04 09:12 by netadmin

42 RADIUS clients9 access rules118 MAB devices307 live sessions2 unknown devices1,204 accepts, 24 h7 rejects, 24 h

Everything it does today

Network access

  • RADIUS clients with per-client Message-Authenticator and Proxy-State settings (BlastRADIUS mitigations), generated shared secrets and CSV import.
  • RadSec per client: TLS 1.2/1.3, certificates from your CA, an optional expected certificate name, and OCSP revocation checks.
  • Device profiles per RADIUS client: built-in Cisco Catalyst 1200/1300 and generic RFC 3580 profiles, custom profiles copied and edited in the console, JSON export and import, and a dictionary check of attribute names.
  • Access rules for wired or per-SSID connections, with an optional role and a rule tester.
  • MAB devices from wired ports and wireless access points, and the unknown-device approval queue.
  • Device administrator logins for switches, access points and firewalls: local accounts, PBKDF2-hashed, or members of chosen directory groups with their directory password over LDAPS.
  • Custom unlang policy for administrators, checked before it is installed.

Operations

  • Dashboard, live sessions and change of authorization: disconnect, re-authenticate, bounce port, offering only what the device supports, with a CoA port per client.
  • Authentication log with the reason for every reject, the certificate, groups and matched rule.
  • SNMPv3 switch monitoring with per-port 802.1X state.
  • Alerts by syslog and e-mail: reject spikes, switches down, RADIUS down, portal down.
  • Audit reports as CSV or for print and PDF.
  • Safe apply with automatic roll back.

Console security

  • Local accounts with mandatory MFA (TOTP or client certificate) and three roles: viewer, operator, admin.
  • Step-up re-authentication for sensitive actions, and account lockout.
  • SAML single sign-on with group-to-role mapping, plus local break-glass administrators.
  • Hash-chained, append-only audit log.
  • Strict Content Security Policy. Light, dark or system colour theme.

Updates

  • An Updates page shows the installed and latest version and the changelog in between, and installs with a click.
  • Database backup first, health checks after, automatic roll back.
  • Choose a channel (main for stable releases, testing, dev), notify-only or automatic updates, and a maintenance window for updates that restart FreeRADIUS.
  • Builds are signed in CI with ECDSA P-384. The server verifies the signature before installing.

Read the changelog

How it works

The web portal has no privileges. It writes to PostgreSQL and stages files. A small root helper is the only component that can touch FreeRADIUS, and it accepts a fixed set of requests over a local socket.

Admin browser

On the management subnet

Identity provider

Optional SAML single sign-on

nftables and nginx

Port 443 only from the management subnet. nginx terminates TLS and checks client certificates.

Web portal unprivileged

Flask and gunicorn, sandboxed. Stages generated files.

PostgreSQL 16

Rules, MAB, users, logs, audit log

Root helper root

Allow-list, radiusd -XC, backups

FreeRADIUS 3.2.10

EAP-TLS, EAP-TTLS, PEAP, MAB, PAP. LDAPS to your directory.

  • Switches RADIUS, UDP 1812/1813
  • Access points RadSec, TCP 2083

Live path: read on every authentication Staged path: only when you apply

More detail in SPEC.md, the contract between the components.

Why you can put it in front of network access

A console that controls who gets on the network is a target. These are the design rules the code is held to.

  1. Only the root helper is privileged

    The web application never runs as root, never writes FreeRADIUS files and never restarts a service. It stages files and asks the helper, which checks them against an allow-list before radiusd -XC ever runs.

  2. Request data reaches SQL only as hex

    Values from a RADIUS request, such as a user name or MAC address, are hex-encoded by FreeRADIUS and decoded inside database functions. They are never interpolated into SQL text.

  3. MFA is mandatory

    Local accounts need TOTP or a client certificate. Sensitive actions ask for re-authentication, and repeated failures lock the account.

  4. Every admin action is audited

    The audit log is append-only and hash-chained with SHA-256, so a removed or altered entry breaks the chain.

  5. Updates are signed

    Builds are signed in CI with ECDSA P-384. The root helper verifies the signature before anything is installed, and a failed health check rolls the update back.

  6. A small, closed surface

    The firewall admits port 443 only from the management subnet. PostgreSQL uses peer authentication with no passwords. Dependencies are distribution packages only, and the Content Security Policy allows no inline scripts or styles.

FIPS mode is optional

The cryptography is the same in both modes: SHA-2, AES, PBKDF2-HMAC-SHA256, ECDSA and TLS 1.2 or later. One FreeRADIUS build works in standard and FIPS mode. With Ubuntu Pro FIPS and FIPS mode on, the portal refuses to start unless the kernel and OpenSSL are in FIPS mode.

What it does not fix

  • The RADIUS protocol itself uses MD5. Per-client Message-Authenticator and RadSec reduce the exposure; plain RADIUS should stay on networks you control.
  • MAB is identification, not authentication. A MAC address can be copied, so give MAB devices only the access they need.
  • PEAP-MSCHAPv2 needs an NT hash of the password, so it is weaker. Local users have to opt in, and it is never available in FIPS mode.

The full account, including the cryptographic boundary and documented exceptions, is in docs/SECURITY.md.

Get started

  1. Check the server

    A read-only check. It changes nothing.

    sudo ./deploy/preflight.sh
  2. Install

    Run the installer with no options and answer the questions: server name, management subnet, portal address, DNS resolvers, portal certificate and the first administrator.

    sudo ./deploy/install.sh
    Unattended install with an answers file

    Put the same answers in a file. The format is described in deploy/answers.sh.

    server_name: radius.example.net
    admin_net: 192.0.2.0/24
    switch_nets: "192.0.2.0/24 198.51.100.0/24"
    listen_ip: 192.0.2.10
    resolver: "192.0.2.53"
    tls: self-signed
    admin_username: netadmin
    sudo ./deploy/install.sh --answers site.yaml --print-answers   # check only
    sudo ./deploy/install.sh --answers site.yaml

    The installer keeps your answers in /etc/radius-admin/site.yaml for later runs.

  3. Sign in

    Browse from the management subnet to https://<server name>/. Sign in with the one-time password the installer printed, choose your own password and set up two-factor authentication.

  4. Follow the setup checklist

    Add RADIUS clients, create access rules, set the device admin subnet and apply.

The full procedure, including migration from an existing FreeRADIUS server, is in the runbook. The README has the same steps next to the code.

Where it stands

radius-admin is a young project under active development. It grew out of a console that has run a production network, and is now being turned into something anyone can install. Expect rough edges and frequent improvements.

Current limitations

  • One distribution. The bundled FreeRADIUS package is built for Ubuntu 24.04 on amd64. Debian 12 follows.
  • One tested switch family. Cisco Catalyst 1200/1300 is what the project is tested against today. The generic RFC 3580 profile is marked unverified until it has run against real hardware; other devices need a custom profile.
  • Certificates are yours to place. The installer expects the FreeRADIUS certificates under /etc/freeradius/certs/site/. Generating the whole FreeRADIUS configuration is the next phase.
  • Client-certificate MFA needs your PKI. The nginx phase expects the site CA bundle and an OCSP responder.

Found something? Report it on GitHub.

Licence

Copyright © 2026 Collin Linde. radius-admin is free software under the GNU Affero General Public License, version 3 or any later version. It is free to use, at home and in organizations.

If you run a modified version for others over a network, the AGPL asks you to offer them its source code (section 13). It comes without any warranty. Other licensing terms may be available from the copyright holder.

The release bundle also contains FreeRADIUS, a separate program under its own licence: GNU GPL version 2 or later, with parts under the LGPL. Its upstream source tarball and signature ship in the bundle, and its licence and copyright notices are installed with it. radius-admin runs and configures FreeRADIUS; it does not link to it.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md.

Pull requests can be merged once their author has accepted the Contributor License Agreement.

radiusadmin/radius-admin on GitHub