# CoovaChilli → Weird Network session reporting

This shim forwards successful CoovaChilli authentications to the
`/api/sessions/start` endpoint so devices show up in your
provider dashboard, including the
[Live Sessions page](../provider-sessions.html) that polls every 10s.

CoovaChilli does not natively POST to a third-party API, so we ship a tiny
bash shim you can wire into one of three call sites.

## Files

- `report-session.sh` — portable POSIX-bash script, no jq required
- `/etc/weird-network.conf` (optional) — environment fallback for the script

## Configuration

Either environment variables or `/etc/weird-network.conf` should define:

```bash
WEIRD_NETWORK_PROVIDER_ID=42        # your provider id (Integer from /provider/dashboard)
WEIRD_NETWORK_LOCATION_ID=7         # default location id (overridable via --location)
WEIRD_NETWORK_ROUTER_ID=3           # default router id (optional)
WEIRD_NETWORK_API_URL=https://weird-network.io/api/sessions/start
```

The script also accepts CLI overrides:

```bash
report-session.sh --mac AA:BB:CC:DD:EE:FF --auth form_capture \
                  --provider 42 --location 7 --router 3
```

`--auth` accepts `form_capture`, `social_gate`, or `voucher` (matches the
`session_auth_method` enum in `captive_portal_sessions`).

## Call sites

### 1. CoovaChilli post-auth hook (recommended — fires within seconds)

Add this to `/etc/chilli/config` on the router:

```
HS_UAM_SCRIPT="/etc/chilli/report-form.sh"
```

CoovaChilli invokes `HS_UAM_SCRIPT` on every successful authentication with
the authenticated client's MAC as the first positional argument. Wrap it:

```bash
#!/bin/bash
# /etc/chilli/report-form.sh — called by CoovaChilli with $1 = client MAC
exec /opt/wn/report-session.sh \
  --mac "$1" \
  --ip "${HS_REMOTEIP:-}" \
  --auth form_capture
```

After installing the wrapper, restart chilli: `/etc/init.d/chilli restart`.
Once a device authenticates against the captive portal, the row appears in
your [Live Sessions](../provider-sessions.html) feed within 10s.

### 2. `cron` (works without CoovaChilli integration)

If you only have an idea of which devices are connecting (e.g. you scan
`/proc/net/arp` every minute), drop the script in cron:

```
* * * * * /opt/wn/report-session.sh --mac $(cat /tmp/last_mac) --auth voucher --location 7
```

### 3. Hotplug (on link-up events)

```
# /etc/hotplug.d/net/99-weird-network
[ "$ACTION" = "add" ] && /opt/wn/report-session.sh --mac "$MAC" --auth form_capture
```

## Manual smoke test

```bash
# From any host with curl + bash:
PROVIDER=42 LOCATION=7 \
  WEIRD_NETWORK_PROVIDER_ID=$PROVIDER WEIRD_NETWORK_LOCATION_ID=$LOCATION \
  ./report-session.sh \
    --mac AA:BB:CC:DD:EE:FF \
    --auth form_capture \
    --router 3
# expect:  PASS mac=AA:BB:CC:DD:EE:FF ...
# then:    GET /api/sessions/recent?limit=20  →  returns the row
```

Or one-shot via env override:

```bash
./report-session.sh --api-url http://localhost:3000/api/sessions/start \
                    --mac AA:BB:CC:DD:EE:FF --auth form_capture --provider 42 --location 7
```

## Exit codes

| Code | Meaning                                                  |
| ---- | -------------------------------------------------------- |
| 0    | HTTP 2xx — server accepted the event                     |
| 1    | Network/server error — see stderr                        |
| 2    | Missing required argument                                |
| 3    | Validation error (bad MAC format, bad auth_method)       |

## Forward pointers

- Install guide: [`/guides/coovachilli-openwrt`](../guides/coovachilli-openwrt.html) — full
  OpenWrt + CoovaChilli install walkthrough.
- Live dashboard: [`/provider/sessions`](../provider-sessions.html)
  — auto-refreshes every 10s; new rows flash for 2s.

## Validation matrix

The script enforces the exact same MAC regex as
`routes/captivePortalSessions.js` (`/^[0-9a-f]{2}([:][0-9a-f]{2}){5}$/i`) and
the same `auth_method` enum (`form_capture`, `social_gate`, `voucher`).
Anything else exits non-zero without polluting the database.