cgrates-radius/PPPOE_SETUP.md

# MikroTik PPPoE to CGRateS RADIUS Integration

## Architecture Overview

```
┌─────────────────────┐         RADIUS (UDP 1812/1813)         ┌──────────────────┐
│   MikroTik Router   │ ◄─────────────────────────────────────► │     CGRateS      │
│   (PPPoE Server)    │                                         │  RADIUS Agent    │
└─────────────────────┘                                         └──────────────────┘
         │                                                              │
         │ PPPoE                                                        │
         ▼                                                              ▼
┌─────────────────────┐                                         ┌──────────────────┐
│   PPPoE Clients     │                                         │   Redis (Data)   │
│   (Subscribers)     │                                         │   MySQL (CDRs)   │
└─────────────────────┘                                         └──────────────────┘
```

## CGRateS Configuration Files

| File | Description |
|------|-------------|
| `cgrates.json` | Main CGRateS configuration |
| `pppoe_auth.json` | PPPoE authentication request processors |
| `pppoe_accounting.json` | PPPoE accounting request processors |
| `tariffplans/pppoe/` | Tariff plan data (users, rates, balances) |

## MikroTik Configuration

### 1. Add RADIUS Server

```routeros
/radius
add address=<CGRATES_IP> secret=CGRateS.org service=ppp timeout=3s
```

### 2. Configure PPPoE Server Profile

```routeros
/ppp profile
add name=pppoe-profile use-radius=yes only-one=yes \
    rate-limit="" \
    incoming-filter="" outgoing-filter="" \
    local-address=10.0.0.1 \
    dns-server=8.8.8.8,8.8.4.4
```

### 3. Configure PPPoE Server

```routeros
/interface pppoe-server server
add service-name=pppoe-service interface=ether1 \
    default-profile=pppoe-profile \
    authentication=pap,chap,mschap2 \
    one-session-per-host=yes
```

### 4. Enable RADIUS for PPP

```routeros
/ppp aaa
set use-radius=yes accounting=yes interim-update=1m
```

### 5. (Optional) Configure RADIUS Incoming (CoA/Disconnect)

```routeros
/radius incoming
set accept=yes port=3799
```

## CGRateS Setup Commands

### 1. Start Redis

```bash
redis-server
```

### 2. Start CGRateS Engine

```bash
cgr-engine -config_path=/path/to/cgrates-radius/
```

### 3. Load Tariff Plan

```bash
cgr-loader -config_path=/path/to/cgrates-radius/ \
           -path=/path/to/cgrates-radius/tariffplans/pppoe/ \
           -verbose
```

## Sample PPPoE Users

| Username | Password | Static IP | Rate Limit | Balance |
|----------|----------|-----------|------------|---------|
| pppoe_user1 | SecurePass123 | 10.0.0.101 | 10M/10M | 100 units |
| pppoe_user2 | SecurePass456 | 10.0.0.102 | 20M/20M | 100 units |
| pppoe_user3 | SecurePass789 | Dynamic | 50M/50M | 100 units |

## Authentication Flow

1. **Client connects** → MikroTik sends Access-Request to CGRateS
2. **CGRateS processes** → `MikrotikPPPoEAuthCGR` extracts user info, checks balance
3. **Password validation** → `MikrotikPPPoEAuthPAP/CHAP/MSCHAPv2` validates credentials
4. **Access-Accept** → Returns Session-Timeout, Framed-IP-Address, Mikrotik-Rate-Limit
5. **Session starts** → MikroTik assigns IP and rate limit to client

## Accounting Flow

1. **Session starts** → `MikrotikPPPoEAcctStart` initiates session in CGRateS
2. **Interim updates** → `MikrotikPPPoEAcctInterim` updates usage every 60 seconds
3. **Session ends** → `MikrotikPPPoEAcctStop` terminates session, generates CDR

## RADIUS Attributes

### Authentication Request (from MikroTik)
- User-Name
- User-Password / CHAP-Password / MS-CHAP-Challenge
- NAS-IP-Address
- NAS-Port-Type
- Calling-Station-Id (MAC)
- Acct-Session-Id

### Authentication Reply (from CGRateS)
- Session-Timeout
- Acct-Interim-Interval
- Framed-IP-Address
- Framed-IP-Netmask
- Mikrotik-Rate-Limit

### Accounting Request (from MikroTik)
- Acct-Status-Type (Start/Interim-Update/Stop)
- Acct-Session-Id
- Acct-Session-Time
- Acct-Input-Octets
- Acct-Output-Octets
- User-Name
- NAS-IP-Address
- Framed-IP-Address

## Testing

### Test Authentication with radtest

```bash
radtest pppoe_user1 SecurePass123 localhost 1812 CGRateS.org
```

### Check Active Sessions

```bash
cgr-console 'sessions_get_active_sessions'
```

### Check Account Balance

```bash
cgr-console 'accounts Tenant="cgrates.org" Account="pppoe_user1"'
```

## Troubleshooting

### Enable CGRateS Debug Logging
Set `"log_level": 7` in cgrates.json

### Check RADIUS Traffic on MikroTik
```routeros
/tool sniffer
quick ip-protocol=udp port=1812-1813
```

### Verify RADIUS Secret
Ensure `secret=CGRateS.org` matches `client_secrets` in cgrates.json

## Notes

- **Shared Secret**: Default is `CGRateS.org` - change in production!
- **Rate Limit Format**: MikroTik uses `rx/tx` format (e.g., `10M/10M`)
- **Session-Timeout**: Returned in seconds based on prepaid balance
- **Interim Interval**: Set to 60 seconds for frequent balance updates