device_manager/radius_client/CONFIGURATION.md

FreeRADIUS Configuration Examples

Module Configuration

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

python3 device_manager_radius {
    # Module path - Python will import device_manager_radius.py
    module = device_manager_radius
    
    # Call functions during FreeRADIUS lifecycle
    instantiate = ${.module}
    authorize = ${.module}
    post_auth = ${.module}
}

Enable the module:

sudo ln -s ../mods-available/python3 /etc/freeradius/3.0/mods-enabled/python3

Virtual Server Configuration

Add to /etc/freeradius/3.0/sites-available/default or your custom virtual server:

server default {
    authorize {
        # Pre-process request
        preprocess
        
        # Check for valid MAC address
        filter_username
        
        # Device Manager authorization
        device_manager_radius
        
        # If credentials are provided, validate them
        eap {
            ok = return
        }
    }
    
    authenticate {
        # Handle EAP authentication
        eap
    }
    
    post-auth {
        # Device Manager post-auth processing
        device_manager_radius
        
        # Update client list
        update {
            &reply: += &session-state:
        }
        
        Post-Auth-Type REJECT {
            attr_filter.access_reject
        }
    }
}

Environment Variables

Systemd Service Override

Create /etc/systemd/system/freeradius.service.d/device-manager.conf:

[Service]
# Required: Frappe server URL and authentication
Environment="DEVICE_MANAGER_FRAPPE_URL=https://device-manager.example.edu"
Environment="DEVICE_MANAGER_API_KEY=your-api-key-here"
Environment="DEVICE_MANAGER_API_SECRET=your-api-secret-here"

# Optional: Cache configuration
Environment="DEVICE_MANAGER_CACHE_PATH=/var/lib/freeradius/device_manager_verifier_cache.sqlite3"
Environment="DEVICE_MANAGER_HTTP_TIMEOUT=2.5"
Environment="DEVICE_MANAGER_CACHE_MAX_STALE_SECONDS=0"

# Optional: Enable post-auth evaluation
Environment="DEVICE_MANAGER_POST_AUTH_EVALUATE=0"

Reload systemd:

sudo systemctl daemon-reload
sudo systemctl restart freeradius

Alternative: /etc/default/freeradius

Add to /etc/default/freeradius:

DEVICE_MANAGER_FRAPPE_URL=https://device-manager.example.edu
DEVICE_MANAGER_API_KEY=your-api-key-here
DEVICE_MANAGER_API_SECRET=your-api-secret-here
DEVICE_MANAGER_CACHE_PATH=/var/lib/freeradius/device_manager_verifier_cache.sqlite3

Testing

Test FreeRADIUS Configuration

sudo freeradius -X

Look for log messages like:

device_manager_radius: initialized remote Device Manager mode: https://device-manager.example.edu/api/method/device_manager.api.radius_authorize
device_manager_radius: SQLite credential cache enabled for offline fallback

Test Authentication

Using radtest:

radtest testuser testpassword localhost 0 testing123

Using eapol_test for WPA-Enterprise:

eapol_test -c test.conf -a 127.0.0.1 -p 1812 -s testing123

Where test.conf contains:

network={
    ssid="test"
    key_mgmt=WPA-EAP
    eap=PEAP
    identity="testuser"
    password="testpassword"
}

Test API Connectivity

Test the Frappe API endpoint directly:

curl -X POST "https://device-manager.example.edu/api/method/device_manager.api.radius_authorize" \
  -H "Authorization: token YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "calling_station_id=00:11:22:33:44:55" \
  -d "username=testuser" \
  -d "nas_identifier=test-ap"

Expected response:

{
  "message": {
    "event": "AUTH-EVENT-001",
    "decision": "DEC-001",
    "device": "DEV-001",
    "result": "Allow",
    "reason": "Device approved for network access",
    "network_segment": "SEG-001",
    "vlan_id": 100,
    "radius_reply_attributes": null,
    "cacheable_credentials": {...}
  }
}

Troubleshooting

Enable Debug Logging

Run FreeRADIUS in debug mode:

sudo systemctl stop freeradius
sudo freeradius -X

Check Cache

Inspect the SQLite cache:

sudo sqlite3 /var/lib/freeradius/device_manager_verifier_cache.sqlite3

.schema
SELECT * FROM radius_verifier_cache;

Common Issues

1. Module not found: Ensure device_manager_radius.py is in Python's import path
2. API authentication fails: Verify API key/secret are correct
3. Cache permission denied: Check /var/lib/freeradius ownership (should be freerad:freerad)
4. Timeout errors: Increase DEVICE_MANAGER_HTTP_TIMEOUT or check network connectivity
5. SSL errors: Verify Frappe server certificate is trusted

Log Messages

Success:

device_manager_radius: initialized remote Device Manager mode: https://...
device_manager_radius: using cached credentials for username

Errors:

device_manager_radius: failed to initialize: Set DEVICE_MANAGER_FRAPPE_URL...
device_manager_radius: authorization failed: [Errno 111] Connection refused
device_manager_radius: authorization failed and no cached credentials matched...

Security Notes

1. Protect API credentials: Ensure systemd override files are mode 600
2. Use HTTPS: Always use HTTPS for the Frappe server URL
3. Firewall rules: Restrict RADIUS server to only access Frappe API endpoints
4. Cache expiration: Set appropriate DEVICE_MANAGER_CACHE_MAX_STALE_SECONDS for your security policy
5. Monitor logs: Regularly review FreeRADIUS logs for unauthorized access attempts