docs: add detailed setup guide for RadiusController and UniFi integration #3
@@ -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://<server-ip>: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://<server-ip>: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 <username> <password> 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
|
||||
Reference in New Issue
Block a user