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)**
```bash
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**
```bash
sudo ./install.sh
# Follow prompts to configure API credentials
```

**Option C: Install as package**
```bash
pip install -e /path/to/radius_client
```

### 2. Configure FreeRADIUS Module

Create `/etc/freeradius/3.0/mods-available/python3`:
```text
python3 device_manager_radius {
    module = device_manager_radius
    instantiate = ${.module}
    authorize = ${.module}
    post_auth = ${.module}
}
```

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

### 4. Update Virtual Server

Edit `/etc/freeradius/3.0/sites-enabled/default`:
```text
authorize {
    preprocess
    device_manager_radius
    eap
}

post-auth {
    device_manager_radius
}
```

### 5. Test

```bash
# 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:
```text
python3 device_manager {
    module = device_manager.freeradius
    instantiate = ${.module}
    authorize = ${.module}
    post_auth = ${.module}
}
```

Environment:
```bash
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
```bash
# 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
```bash
# 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
```bash
# Fix ownership
sudo chown -R freerad:freerad /var/lib/freeradius
sudo chmod 750 /var/lib/freeradius
```

### View logs
```bash
# Real-time debug
sudo freeradius -X

# System logs
sudo journalctl -u freeradius -f
```

## What Next?

- Read [CONFIGURATION.md](CONFIGURATION.md) for detailed setup
- Review [README.md](README.md) for architecture details
- Check [IMPLEMENTATION_SUMMARY.md](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