device_manager/radius_client/CONFIGURATION.md

# FreeRADIUS Configuration Examples

## Module Configuration

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

```text
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:
```bash
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:

```text
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`:

```ini
[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:
```bash
sudo systemctl daemon-reload
sudo systemctl restart freeradius
```

### Alternative: /etc/default/freeradius

Add to `/etc/default/freeradius`:

```bash
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

```bash
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`:
```bash
radtest testuser testpassword localhost 0 testing123
```

Using `eapol_test` for WPA-Enterprise:
```bash
eapol_test -c test.conf -a 127.0.0.1 -p 1812 -s testing123
```

Where `test.conf` contains:
```text
network={
    ssid="test"
    key_mgmt=WPA-EAP
    eap=PEAP
    identity="testuser"
    password="testpassword"
}
```

### Test API Connectivity

Test the Frappe API endpoint directly:
```bash
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:
```json
{
  "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:
```bash
sudo systemctl stop freeradius
sudo freeradius -X
```

### Check Cache

Inspect the SQLite cache:
```bash
sudo sqlite3 /var/lib/freeradius/device_manager_verifier_cache.sqlite3
```

```sql
.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