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,142 @@
+# RADIUS Client Changelog
+
+## Version 1.0.0 (2026-06-17)
+
+### Added - Standalone RADIUS Client
+
+**Major Feature: Complete separation of RADIUS server from Frappe installation**
+
+Created a standalone FreeRADIUS integration module that enables truly independent deployment:
+
+- **Standalone module** (`device_manager_radius.py`)
+  - Self-contained Python module with zero external dependencies
+  - Only requires Python 3.10+ standard library
+  - Can run on any RADIUS server without Frappe installation
+  - Makes authenticated HTTP API calls to remote Frappe instance
+  - Full offline credential caching with SQLite
+
+- **Automated installation** (`install.sh`)
+  - Interactive setup script for Ubuntu/Debian systems
+  - Automatic systemd environment configuration
+  - Creates cache directories with proper permissions
+  - Validates FreeRADIUS installation
+
+- **Comprehensive documentation**
+  - `README.md` - Overview and installation
+  - `QUICKSTART.md` - Fast-track setup guide
+  - `CONFIGURATION.md` - Detailed FreeRADIUS configuration
+  - `IMPLEMENTATION_SUMMARY.md` - Technical architecture
+
+- **Packaging support** (`pyproject.toml`)
+  - Can be installed as Python package
+  - Supports both pip and direct file deployment
+  - Proper project metadata and dependencies
+
+### Changed
+
+- **Updated main README.md**
+  - Clarified three deployment options (Standalone, Local, Remote)
+  - Added clear guidance on when to use each mode
+  - Removed redundant FreeRADIUS config examples
+  - Added references to new detailed documentation
+
+- **Enhanced freeradius.py docstring**
+  - Better explanation of deployment modes
+  - Reference to standalone client for separate servers
+
+### Technical Details
+
+**Lines of Code:**
+- Python: 387 lines (device_manager_radius.py)
+- Bash: 95 lines (install.sh)
+- Documentation: 613 lines across 5 markdown files
+- Total: ~1,095 lines
+
+**Key Improvements:**
+1. Zero dependency on Frappe/device_manager package for remote deployments
+2. Reduced attack surface on RADIUS appliances
+3. Simplified deployment and maintenance
+4. Better separation of concerns
+5. Backward compatible with existing deployments
+
+**API Compatibility:**
+- Uses existing `device_manager.api.radius_authorize` endpoint
+- Same environment variable names as remote mode
+- Compatible cache format with original implementation
+- No changes required to Frappe server
+
+### Migration Path
+
+Existing installations using `device_manager.freeradius` in remote mode can optionally migrate:
+
+1. Install standalone client on RADIUS server
+2. Update FreeRADIUS config to use `device_manager_radius`
+3. Keep existing environment variables unchanged
+4. Test authentication
+5. Optionally uninstall device_manager package from RADIUS server
+
+No migration is required - existing deployments continue to work without changes.
+
+### Files Added
+
+```
+radius_client/
+├── __init__.py                    # Package init
+├── .gitignore                     # Build artifacts ignore
+├── CONFIGURATION.md               # FreeRADIUS setup guide (184 lines)
+├── IMPLEMENTATION_SUMMARY.md      # Architecture docs (142 lines)
+├── QUICKSTART.md                  # Fast setup guide (185 lines)
+├── README.md                      # Overview (102 lines)
+├── device_manager_radius.py       # Standalone module (387 lines)
+├── install.sh                     # Installation script (95 lines)
+└── pyproject.toml                 # Package metadata (34 lines)
+```
+
+### Testing
+
+Validated:
+- [x] Python syntax (py_compile)
+- [x] Bash syntax (bash -n)
+- [x] File permissions
+- [x] Documentation formatting
+- [ ] Live FreeRADIUS integration (requires FreeRADIUS setup)
+- [ ] API authentication flow (requires Frappe instance)
+- [ ] Offline caching behavior (requires network interruption testing)
+
+### Breaking Changes
+
+None. This is purely additive - all existing functionality preserved.
+
+### Security Considerations
+
+- API credentials stored in systemd override (mode 600)
+- Cache file owned by freerad user
+- No plaintext passwords stored
+- HTTPS required for production Frappe URLs
+- Token-based API authentication
+
+### Known Limitations
+
+- Requires Python 3.10+ for type hints
+- SQLite cache not suitable for clustered RADIUS
+- HTTP timeout may need tuning for slow networks
+- No built-in credential rotation mechanism
+
+### Future Enhancements
+
+Potential improvements for future versions:
+- [ ] Redis cache backend for HA deployments
+- [ ] Prometheus metrics export
+- [ ] Health check endpoint
+- [ ] Automatic API credential rotation
+- [ ] Certificate pinning for HTTPS
+- [ ] Rate limiting for API calls
+- [ ] Batch request support
+
+### Contributors
+
+- University of Georgia Manufacturing Living Labs
+
+### License
+
+See main device_manager app license (MIT)