# client2server

> Lightweight event forwarder for OpenWrt routers to central server

## Overview

Lightweight bash/lua scripts that listen to OpenWrt events (WiFi, DHCP, network) and forward them to a central server via HTTP.

## Why This?

- **Tiny footprint**: ~20KB (vs 5MB+ Go binary)
- **No dependencies**: Uses built-in OpenWrt tools
- **Real-time**: Direct ubus/netlink event stream
- **Reliable**: Can run in procd as a service

## Architecture

```
┌─────────────────┐      HTTP/WebSocket      ┌─────────────────┐
│   OpenWrt       │ ────────────────────────► │ Central Server  │
│   Router       │                           │                 │
│                 │                         │  - Receive     │
│  ubus events   │                         │  - Store        │
│  hostapd_cli  │                         │  - Notify       │
│  dnsmasq      │                         │  - Dashboard   │
└─────────────────┘                         └─────────────────┘
```

## Supported Events

| Event Type | Source | Payload |
|------------|--------|---------|
| WiFi connect | hostapd | client MAC, signal |
| WiFi disconnect | hostapd | client MAC, reason |
| DHCP lease | dnsmasq | IP, MAC, hostname |
| Interface up/down | netifd | device, state |
| Network changes | ubus | config changes |

## Files

| File | Purpose |
|------|---------|
| `etc/init.d/event-forwarder` | Main daemon startup script |
| `etc/config/event-forwarder` | UCI configuration |
| `usr/sbin/event-forwarder` | Main event listener script |
| `usr/lib/rpcd/event-forwarder` | ubus RPC plugin (optional) |
| `README.md` | This file |

## Installation

```bash
# Copy to OpenWrt router
scp -r etc root@router:/tmp/
ssh router "mv /tmp/etc/* /etc/"

# Enable service
/etc/init.d/event-forwarder enable
/etc/init.d/event-forwarder start

# Check logs
logread -f -e event-forwarder
```

## Configuration

```bash
# Edit config on router
uci set event-forwarder.server.url='https://your-server.com/api/events'
uci set event-forwarder.server.token='your-secret-token'
uci set event-forwarder.general.interval='60'
uci commit event-forwarder
/etc/init.d/event-forwarder restart
```

## Central Server API

Expected endpoint:

```json
POST /api/events
Headers: Authorization: Bearer <token>
Content-Type: application/json

{
  "router_id": "router-hostname-or-id",
  "event_type": "wifi_connect|wifi_disconnect|dhcp_lease|interface_up|config_change",
  "payload": {
    "mac": "AA:BB:CC:DD:EE:FF",
    "ip": "192.168.1.100",
    "hostname": "device-name",
    "signal": -45,
    "device": "wlan0"
  },
  "timestamp": "2026-06-04T18:00:00Z"
}
```

## Security

- Use HTTPS for production
- Store token in `/etc/config/event-forwarder`
- Consider firewall rules to limit who can POST

## License

MIT