From 21118838c0b5c93d167f7cfed13cd646ba931553 Mon Sep 17 00:00:00 2001 From: Tygozwolle Date: Fri, 24 Jul 2026 11:44:29 +0200 Subject: [PATCH] docs: add detailed setup guide for RadiusController and UniFi integration --- README.md | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..121b4d5 --- /dev/null +++ b/README.md @@ -0,0 +1,175 @@ +# RadiusController & FreeRADIUS - UniFi Setup Guide + +This project provides a complete **RADIUS Authentication & Accounting Controller** for Wi-Fi networks, integrated with **FreeRADIUS**, **PostgreSQL**, and a **Blazor Web Application** for Guest Portal and Admin management. + +--- + +## 🏗️ System Architecture + +``` +┌─────────────────┐ UDP 1812/1813 ┌──────────────────┐ +│ UniFi AP / │ ◄───────────────────────► │ FreeRADIUS │ +│ Dream Machine │ │ (Port 1812/13) │ +└────────┬────────┘ └────────┬─────────┘ + │ │ + │ Wi-Fi 802.1X / │ SQL Queries + │ Guest Auth ▼ + │ ┌──────────────────┐ + │ │ PostgreSQL │ + │ │ (Radius DB) │ + │ └────────▲─────────┘ + │ │ + │ HTTP/8080 │ EF Core + ▼ │ +┌─────────────────┐ │ +│ Guests / Admins │ ───────────────────────────────────┘ +│ (Web Portal) │ RadiusController Web App +└─────────────────┘ +``` + +--- + +## 🚀 Step 1: Deploying with Docker Compose (Unraid / Docker) + +1. Ensure your `docker-compose.yml` is configured with persistent volume paths (e.g. for Unraid): + +```yaml +version: '3.8' + +services: + postgres: + image: postgres:16-alpine + container_name: radius_postgres + restart: always + environment: + POSTGRES_DB: radius + POSTGRES_USER: radius + POSTGRES_PASSWORD: radpass + ports: + - "5432:5432" + volumes: + - /mnt/user/appdata/radiuscontroller/pgdata:/var/lib/postgresql/data + - /mnt/user/appdata/radiuscontroller/sql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro + + freeradius: + image: freeradius/freeradius-server:latest + container_name: radius_freeradius + restart: always + depends_on: + - postgres + ports: + - "1812:1812/udp" + - "1813:1813/udp" + environment: + - DB_NAME=radius + - DB_HOST=postgres + - DB_USER=radius + - DB_PASS=radpass + + radiuscontroller: + image: cablon.vanolst.tech/tygozwolle/radius:latest + container_name: radius_web_controller + restart: always + depends_on: + - postgres + ports: + - "8080:8080" + environment: + - ConnectionStrings__DefaultConnection=Host=postgres;Port=5432;Database=radius;Username=radius;Password=radpass; + - ASPNETCORE_ENVIRONMENT=Production +``` + +2. Start the stack: +```bash +docker compose up -d +``` + +--- + +## 🔑 Step 2: Register UniFi as a NAS (RADIUS Client) + +FreeRADIUS requires every Network Access Server (NAS) — such as your UniFi Dream Machine, Security Gateway, or Access Points — to be registered in the `nas` database table with a **shared secret**. + +Connect to your PostgreSQL database (e.g. via `psql` or database manager) and insert your UniFi device: + +```sql +INSERT INTO nas (nasname, shortname, type, secret, description) +VALUES ('192.168.1.1', 'unifi-gw', 'other', 'YourSharedSecret123', 'UniFi Gateway / Access Point'); +``` + +> 💡 **Tip:** If you have multiple UniFi Access Points or a subnet, you can add each AP's IP or register a CIDR subnet (e.g., `192.168.1.0/24`). + +--- + +## 📶 Step 3: Configure UniFi Network Application + +### A. Create a RADIUS Profile in UniFi + +1. Open your **UniFi Network Application** (e.g. `https://192.168.1.1`). +2. Go to **Settings** ⚙️ → **Profiles** → **RADIUS**. +3. Click **Create New RADIUS Profile**. +4. Configure the settings: + - **Profile Name**: `RadiusController` + - **VLAN Support**: Enable if using dynamic VLAN assignment via RADIUS. + - **Authentication Servers**: + - **IP Address**: Server IP running FreeRADIUS (e.g. `192.168.1.50`). + - **Port**: `1812` + - **Shared Secret**: Matches the secret in the `nas` table (`YourSharedSecret123`). + - **Accounting Servers**: + - **Enable Accounting**: `Checked` + - **IP Address**: Server IP (`192.168.1.50`). + - **Port**: `1813` + - **Shared Secret**: Matches the secret in the `nas` table (`YourSharedSecret123`). +5. Click **Save Changes**. + +--- + +### B. Configure WPA Enterprise Wi-Fi Network + +1. Go to **Settings** ⚙️ → **WiFi**. +2. Click **Create New WiFi Network** (or edit an existing one, e.g. `Guest-WiFi`). +3. Set the configuration: + - **Name (SSID)**: e.g. `Secure Guest WiFi` + - **Security Protocol**: **WPA2 Enterprise** or **WPA3 Enterprise**. + - **RADIUS Profile**: Select `RadiusController`. +4. Click **Save**. + +--- + +## 📱 Step 4: User Authentication & Portal Workflow + +1. **Guest Registration / Portal**: + - Guests connect to the Web Portal at `http://:8080/portal` (or via reverse proxy). + - Enter guest name to receive generated **Username** and **Password** (with session and data limits automatically assigned). + +2. **Connecting to Wi-Fi**: + - On their device (phone/laptop), select the `Secure Guest WiFi` network. + - Select **EAP Method**: `PEAP` or `TTLS` (Phase 2 Auth: `MSCHAPv2` or `GTC`). + - CA Certificate: `Do not validate` / `Unvalidated` (or install your custom CA if using custom EAP certs). + - Enter the **Username** and **Password** generated from the portal. + +3. **Admin Management**: + - Access the Admin Dashboard at `http://:8080/admin`. + - Default login: `admin` / `admin123`. + - Monitor active RADIUS sessions, data usage, enforce data limits, or revoke users. + +--- + +## 🛠️ Troubleshooting & Verification + +### Test RADIUS Server locally +Run `radtest` from another machine or inside the container to test authentication: +```bash +docker exec -it radius_freeradius radtest 127.0.0.1 0 testing123 +``` + +### View Live FreeRADIUS Logs +```bash +docker logs -f radius_freeradius +``` + +### Verify Firewall Ports on Host / Unraid +Ensure the following ports are open on your host firewall / router: +- **`1812/UDP`**: RADIUS Authentication +- **`1813/UDP`**: RADIUS Accounting +- **`8080/TCP`**: Web Controller / Portal -- 2.52.0