FreeRADIUS Docker Stack with MariaDB & phpMyAdmin

This project provides a complete, containerized FreeRADIUS environment backed by a MariaDB database. It includes automatic schema initialization and a web interface (phpMyAdmin) for database management.

Features

• FreeRADIUS 3.x: Pre-configured with the SQL module enabled.
• MariaDB Backend: Stores users, groups, accounting data, and NAS clients.
• Automatic Initialization: The container automatically checks for and imports the default FreeRADIUS SQL schema on first start.
• No Extra Init Container: Initialization logic is embedded in the main container via start.sh.
• phpMyAdmin: Easy web-based management for the database.
• Cross-Platform: Configured with platform: linux/amd64 to ensure compatibility on both AMD64 and ARM64 (Apple Silicon) hosts (via emulation).

Prerequisites

• Docker
• Docker Compose

Quick Start

1. Clone/Download this repository.
2. Start the stack:

   docker-compose up -d --build

3. Access phpMyAdmin at http://localhost:8888 (User: root, Pass: root).

External Database Support

By default, this stack starts a local MariaDB container (COMPOSE_PROFILES=local in .env).

To use an external database:

1. Open .env.
2. Comment out or remove COMPOSE_PROFILES=local.
3. Set MYSQL_HOST to your external database IP/Hostname.
4. Update User/Password/Port as needed.
5. Restart the stack. Docker will now ONLY start the FreeRADIUS container.

Ports

• 1812/udp: Authentication
• 1813/udp: Accounting
• 8888/tcp: phpMyAdmin (maps to 80)

Project Structure

• Dockerfile: Builds the custom FreeRADIUS image, installs mysql-client, and sets the entrypoint to start.sh.
• docker-compose.yml: Defines the services (radius, db, phpmyadmin).
• start.sh: The startup script that waits for the DB, imports the schema if missing, and starts FreeRADIUS.
• raddb/: Contains the extracted and modified configuration files.
  • mods-available/sql: Configured for MySQL, TLS disabled, read_clients = no (Pure Dynamic).
  • sites-available/default: SQL module enabled in all sections.
  • sites-available/dynamic-clients: Virtual server configuration for fully dynamic, SQL-based client lookups.

Management

Database Access

• Host: db (internal)
• Database: radius
• User: radius
• Password: radius
• Root Password: root

Adding a User

Execute the following SQL (e.g., via phpMyAdmin) to add a user with a cleartext password:

INSERT INTO radcheck (username, attribute, op, value) 
VALUES ('testuser', 'Cleartext-Password', ':=', 'testpass');

Adding a NAS Client (Dynamic)

Thanks to the dynamic_clients virtual server, managing NAS clients is completely dynamic. There is no need to reload or restart FreeRADIUS when helping new clients.

1. Insert Client into Database:

   INSERT INTO nas (nasname, shortname, type, secret, description) 
   VALUES ('172.16.0.254', 'office-ap', 'other', 'secureSecret', 'Main Office Access Point');

   • nasname: The IP address of the client.
   • secret: The shared secret.

2. Connect: The client can authenticate immediately.

How it works:

• The server accepts packets from any IP (0.0.0.0/0) due to the dynamic-clients configuration.
• It performs a SQL lookup for the source IP.
• If found in the nas table, the client parameters (secret, shortname, type) are loaded on-the-fly.
• If not found, adding the entry to the DB makes it work instantly.

Troubleshooting

"Bind for 0.0.0.0:1812 failed"

If you see this error, it means port 1812 is already in use on your host (often by a local instance of freeradius or a zombie docker process). Stop the blocking service on the host or map to a different port (e.g., 11812:1812).

Testing Authentication

You can test the server locally from within the container:

# Get container ID or name
docker ps

# Run radtest
docker exec -it freeradius-stack-radius-1 radtest testuser testpass localhost 0 testing123

Note: The internal shared secret for localhost is testing123 (defined in clients.conf, not the DB).

Debug Mode

To start FreeRADIUS in debug mode (foreground, highly verbose output):

1. Open .env.
2. Set RADIUS_DEBUG=true.
3. Recreate the container: docker-compose up -d --build.
4. View logs: docker logs -f freeradius-stack-radius-1.