fix: separate radius module to support separate deployment

2026-06-17 19:04:32 +00:00
parent 289615b3b2
commit b093a80630
50 changed files with 3821 additions and 69 deletions
@@ -0,0 +1,183 @@
+# Quick Start Guide
+
+## For New Deployments (Separate RADIUS Server)
+
+### 1. Install on RADIUS Server
+
+**Option A: Direct file copy (simplest)**
+```bash
+sudo cp device_manager_radius.py /etc/freeradius/3.0/mods-config/python3/
+sudo chmod 644 /etc/freeradius/3.0/mods-config/python3/device_manager_radius.py
+```
+
+**Option B: Use install script**
+```bash
+sudo ./install.sh
+# Follow prompts to configure API credentials
+```
+
+**Option C: Install as package**
+```bash
+pip install -e /path/to/radius_client
+```
+
+### 2. Configure FreeRADIUS Module
+
+Create `/etc/freeradius/3.0/mods-available/python3`:
+```text
+python3 device_manager_radius {
+    module = device_manager_radius
+    instantiate = ${.module}
+    authorize = ${.module}
+    post_auth = ${.module}
+}
+```
+
+Enable it:
+```bash
+sudo ln -s ../mods-available/python3 /etc/freeradius/3.0/mods-enabled/
+```
+
+### 3. Set Environment Variables
+
+Edit `/etc/systemd/system/freeradius.service.d/device-manager.conf`:
+```ini
+[Service]
+Environment="DEVICE_MANAGER_FRAPPE_URL=https://your-server.example.edu"
+Environment="DEVICE_MANAGER_API_KEY=your-api-key"
+Environment="DEVICE_MANAGER_API_SECRET=your-api-secret"
+```
+
+Reload:
+```bash
+sudo systemctl daemon-reload
+```
+
+### 4. Update Virtual Server
+
+Edit `/etc/freeradius/3.0/sites-enabled/default`:
+```text
+authorize {
+    preprocess
+    device_manager_radius
+    eap
+}
+
+post-auth {
+    device_manager_radius
+}
+```
+
+### 5. Test
+
+```bash
+# Test configuration
+sudo freeradius -X
+
+# In another terminal, test auth
+radtest testuser testpass localhost 0 testing123
+```
+
+## For Existing Deployments (Same Server as Frappe)
+
+### Continue Using Integrated Module
+
+No changes needed! Your current configuration with `device_manager.freeradius` continues to work.
+
+FreeRADIUS config:
+```text
+python3 device_manager {
+    module = device_manager.freeradius
+    instantiate = ${.module}
+    authorize = ${.module}
+    post_auth = ${.module}
+}
+```
+
+Environment:
+```bash
+DEVICE_MANAGER_BENCH_PATH=/home/frappe/frappe-bench
+DEVICE_MANAGER_SITE=your-site-name
+```
+
+## Configuration Reference
+
+### Required Environment Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `DEVICE_MANAGER_FRAPPE_URL` | Frappe server base URL | `https://device-manager.example.edu` |
+| `DEVICE_MANAGER_API_KEY` | API authentication key | `abc123...` |
+| `DEVICE_MANAGER_API_SECRET` | API authentication secret | `xyz789...` |
+
+### Optional Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEVICE_MANAGER_CACHE_PATH` | `/var/lib/freeradius/device_manager_cache.sqlite3` | SQLite cache file path |
+| `DEVICE_MANAGER_HTTP_TIMEOUT` | `2.5` | API call timeout (seconds) |
+| `DEVICE_MANAGER_CACHE_MAX_STALE_SECONDS` | `0` | Max cache age (0=unlimited) |
+| `DEVICE_MANAGER_POST_AUTH_EVALUATE` | `0` | Enable post-auth evaluation |
+
+## Generating API Credentials
+
+On your Frappe server:
+
+1. Go to **User** list
+2. Create or edit a System User
+3. Generate **API Key** and **API Secret**
+4. Grant permissions for:
+   - DM Device (Read)
+   - DM Radius Auth Event (Create)
+   - DM Access Decision (Create)
+   - DM Device Audit Event (Create)
+   - DM Network Segment (Read)
+
+## Troubleshooting
+
+### Module fails to load
+```bash
+# Check Python path
+python3 -c "import device_manager_radius"
+
+# Check file permissions
+ls -l /etc/freeradius/3.0/mods-config/python3/device_manager_radius.py
+```
+
+### API authentication fails
+```bash
+# Test API endpoint directly
+curl -X POST "$DEVICE_MANAGER_FRAPPE_URL/api/method/device_manager.api.radius_authorize" \
+  -H "Authorization: token $API_KEY:$API_SECRET" \
+  -d "calling_station_id=00:11:22:33:44:55"
+```
+
+### Cache permission denied
+```bash
+# Fix ownership
+sudo chown -R freerad:freerad /var/lib/freeradius
+sudo chmod 750 /var/lib/freeradius
+```
+
+### View logs
+```bash
+# Real-time debug
+sudo freeradius -X
+
+# System logs
+sudo journalctl -u freeradius -f
+```
+
+## What Next?
+
+- Read [CONFIGURATION.md](CONFIGURATION.md) for detailed setup
+- Review [README.md](README.md) for architecture details
+- Check [IMPLEMENTATION_SUMMARY.md](IMPLEMENTATION_SUMMARY.md) for technical background
+
+## Support
+
+For issues, check:
+1. FreeRADIUS debug logs (`freeradius -X`)
+2. Frappe logs on the application server
+3. Network connectivity between RADIUS and Frappe server
+4. API credentials are valid and have proper permissions