device_manager/radius_client/QUICKSTART.md

Quick Start Guide

For New Deployments (Separate RADIUS Server)

1. Install on RADIUS Server

Option A: Direct file copy (simplest)

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

sudo ./install.sh
# Follow prompts to configure API credentials

Option C: Install as package

pip install -e /path/to/radius_client

2. Configure FreeRADIUS Module

Create /etc/freeradius/3.0/mods-available/python3:

python3 device_manager_radius {
    module = device_manager_radius
    instantiate = ${.module}
    authorize = ${.module}
    post_auth = ${.module}
}

Enable it:

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:

[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:

sudo systemctl daemon-reload

4. Update Virtual Server

Edit /etc/freeradius/3.0/sites-enabled/default:

authorize {
    preprocess
    device_manager_radius
    eap
}

post-auth {
    device_manager_radius
}

5. Test

# 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:

python3 device_manager {
    module = device_manager.freeradius
    instantiate = ${.module}
    authorize = ${.module}
    post_auth = ${.module}
}

Environment:

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

# 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

# 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

# Fix ownership
sudo chown -R freerad:freerad /var/lib/freeradius
sudo chmod 750 /var/lib/freeradius

View logs

# Real-time debug
sudo freeradius -X

# System logs
sudo journalctl -u freeradius -f

What Next?

• Read CONFIGURATION.md for detailed setup
• Review README.md for architecture details
• Check 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