UGAIF
121 lines
5.0 KiB
Markdown
121 lines
5.0 KiB
Markdown
# RADIUS Support Implementation - Summary
|
|
|
|
## Problem Statement
|
|
|
|
The device_manager app started implementing RADIUS support but had a half-complete implementation. The issue was that even for "remote mode" (where FreeRADIUS runs on a separate server), the full device_manager Python package needed to be installed on the RADIUS server because FreeRADIUS needed to import `device_manager.freeradius`.
|
|
|
|
This prevented truly separate deployment where:
|
|
- RADIUS server runs independently on a dedicated appliance
|
|
- Frappe + device_manager runs on a separate application server
|
|
- RADIUS authenticates via API calls to Frappe (already implemented)
|
|
- No Frappe/device_manager installation needed on RADIUS server
|
|
|
|
## Solution Implemented
|
|
|
|
Created a **standalone RADIUS client** that can be deployed independently without requiring Frappe or device_manager to be installed locally.
|
|
|
|
### What Was Created
|
|
|
|
1. **Standalone Module** (`radius_client/device_manager_radius.py`)
|
|
- Self-contained Python module with zero dependencies beyond stdlib
|
|
- Only supports remote API mode (no local Frappe integration)
|
|
- Can be copied directly to FreeRADIUS without pip installation
|
|
- Makes HTTP API calls to Frappe Device Manager
|
|
- Implements SQLite credential caching for offline operation
|
|
|
|
2. **Packaging** (`radius_client/pyproject.toml`)
|
|
- Minimal package configuration for pip installation
|
|
- Can be installed with `pip install -e radius_client/`
|
|
- Provides `device_manager_radius` module
|
|
|
|
3. **Installation Script** (`radius_client/install.sh`)
|
|
- Automated deployment script for Ubuntu/Debian systems
|
|
- Copies module to FreeRADIUS Python path
|
|
- Configures systemd environment variables
|
|
- Sets up cache directory with proper permissions
|
|
- Interactive setup for API credentials
|
|
|
|
4. **Documentation**
|
|
- `radius_client/README.md` - Quick start and overview
|
|
- `radius_client/CONFIGURATION.md` - Detailed FreeRADIUS configuration examples
|
|
- Updated main `README.md` with deployment options
|
|
|
|
### Deployment Modes Now Supported
|
|
|
|
1. **Standalone Client (NEW - Recommended for Separate Servers)**
|
|
- Use: FreeRADIUS on separate server, no Frappe installed locally
|
|
- Module: `device_manager_radius.py` (from radius_client/)
|
|
- Dependencies: Python 3.10+ only
|
|
- Configuration: Environment variables for API URL/credentials
|
|
|
|
2. **Local Mode (Existing)**
|
|
- Use: FreeRADIUS on same host as Frappe bench
|
|
- Module: `device_manager.freeradius`
|
|
- Dependencies: Full Frappe + device_manager installation
|
|
- Configuration: DEVICE_MANAGER_BENCH_PATH, DEVICE_MANAGER_SITE
|
|
|
|
3. **Remote Mode (Existing)**
|
|
- Use: FreeRADIUS with device_manager installed but Frappe remote
|
|
- Module: `device_manager.freeradius`
|
|
- Dependencies: device_manager package installed
|
|
- Configuration: DEVICE_MANAGER_FRAPPE_URL, API credentials
|
|
|
|
### Key Features
|
|
|
|
- **Zero external dependencies**: Uses only Python stdlib (json, sqlite3, urllib)
|
|
- **Offline credential caching**: SQLite cache with configurable staleness
|
|
- **Automatic failover**: Falls back to cache when Frappe unreachable
|
|
- **VLAN assignment**: Returns VLAN and reply attributes from Frappe policy
|
|
- **Quarantine support**: Routes unknown devices to quarantine VLAN
|
|
- **Comprehensive logging**: Integrates with FreeRADIUS logging system
|
|
|
|
### Files Created
|
|
|
|
```
|
|
device_manager/radius_client/
|
|
├── __init__.py # Package init
|
|
├── .gitignore # Python build artifacts
|
|
├── CONFIGURATION.md # Detailed FreeRADIUS setup guide
|
|
├── README.md # Quick start guide
|
|
├── device_manager_radius.py # Standalone module (387 lines)
|
|
├── install.sh # Automated installation script
|
|
└── pyproject.toml # Package configuration
|
|
```
|
|
|
|
### Testing
|
|
|
|
The standalone module can be tested without affecting the main device_manager app:
|
|
|
|
```bash
|
|
# Copy to FreeRADIUS
|
|
sudo cp radius_client/device_manager_radius.py /etc/freeradius/3.0/mods-config/python3/
|
|
|
|
# Configure (see CONFIGURATION.md)
|
|
# ...
|
|
|
|
# Test in debug mode
|
|
sudo freeradius -X
|
|
```
|
|
|
|
### Migration Path
|
|
|
|
Existing deployments using `device_manager.freeradius` in remote mode can optionally migrate to the standalone client for a lighter footprint:
|
|
|
|
1. Copy `device_manager_radius.py` to RADIUS server
|
|
2. Update FreeRADIUS config to use `device_manager_radius` module
|
|
3. Keep same environment variables (DEVICE_MANAGER_FRAPPE_URL, etc.)
|
|
4. Uninstall device_manager package from RADIUS server (optional)
|
|
|
|
## Benefits
|
|
|
|
1. **True separation of concerns**: RADIUS server is just a RADIUS server
|
|
2. **Minimal attack surface**: No Frappe code on RADIUS appliance
|
|
3. **Easier deployment**: Single Python file + config
|
|
4. **Independent updates**: Update Frappe without touching RADIUS
|
|
5. **Better security**: RADIUS server doesn't need database credentials
|
|
6. **Simplified maintenance**: Fewer moving parts on RADIUS server
|
|
|
|
## Backward Compatibility
|
|
|
|
All existing deployment modes continue to work unchanged. The standalone client is an additional option, not a replacement.
|