# Net Alerter Daemon Deployment to Orange Pi Zero 3 (10.0.0.0)

## Target Device
- **IP**: 10.0.0.0
- **OS**: Orange Pi OS (Debian-based)
- **User**: root (required for CAP_NET_RAW and Netlink access)

## Pre-Deployment Checklist

- [ ] Verify SSH access: `ssh root@10.0.0.0 "uname -a"`
- [ ] Verify Python 3: `ssh root@10.0.0.0 "python3 --version"`
- [ ] Verify device is on network and has Ethernet/WiFi
- [ ] Have Matrix bot credentials ready (homeserver, token, room ID)

## Step 1: Prepare Matrix Credentials

Get a fresh access token for the net-alerter bot account:

```bash
curl -X POST https://m.example.org/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "identifier": {"type": "m.id.user", "user": "net-alerter"},
    "password": "<password>"
  }' | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])"
```

You should get a token like `syt_...`. Save this.

## Step 2: Deploy Using Deployment Script (Recommended)

From your local machine (where you have SSH configured):

```bash
cd ~/tools/bigbrother/net_alerter

# Deploy and configure automatically
./deploy-daemon.sh root@10.0.0.0

# Script will prompt you to update .env with MATRIX_ACCESS_TOKEN
ssh root@10.0.0.0 "cat > /opt/net_alerter/.env <<EOF
MATRIX_HOMESERVER=https://m.example.org
MATRIX_ACCESS_TOKEN=<your_token_from_step_1>
MATRIX_ROOM_ID=!REDACTED:example.org
EOF
chmod 600 /opt/net_alerter/.env"

# Restart service to pick up new credentials
ssh root@10.0.0.0 "systemctl restart net_alerter"
```

## Step 3: Manual Deployment (if script fails)

```bash
# Create directory
ssh root@10.0.0.0 "mkdir -p /opt/net_alerter"

# Copy daemon
scp ~/tools/bigbrother/net_alerter/net_alerter.py root@10.0.0.0:/opt/net_alerter/

# Copy systemd unit
scp ~/tools/bigbrother/net_alerter/net_alerter.service root@10.0.0.0:/etc/systemd/system/

# Create config file
ssh root@10.0.0.0 "cat > /opt/net_alerter/.env <<EOF
MATRIX_HOMESERVER=https://m.example.org
MATRIX_ACCESS_TOKEN=<your_token>
MATRIX_ROOM_ID=!REDACTED:example.org
EOF
chmod 600 /opt/net_alerter/.env"

# Remove old cron entries
ssh root@10.0.0.0 "crontab -l 2>/dev/null | grep -v net_alerter | crontab -"

# Enable and start
ssh root@10.0.0.0 "
systemctl daemon-reload && \
systemctl enable net_alerter && \
systemctl restart net_alerter
"
```

## Step 4: Verify Deployment

```bash
# Check service status
ssh root@10.0.0.0 "systemctl status net_alerter --no-pager"

# View startup logs (should see "Seeded X devices")
ssh root@10.0.0.0 "journalctl -u net_alerter -n 30 --no-pager"

# Monitor in real-time (Ctrl+C to stop)
ssh root@10.0.0.0 "journalctl -u net_alerter -f --no-pager"
```

Expected startup log:
```
2025-04-08T12:34:56 [INFO] Net alerter starting on interface eth0
2025-04-08T12:34:57 [INFO] Seeded 8 devices from ARP cache
2025-04-08T12:34:57 [INFO] DHCP sniffer started on eth0
2025-04-08T12:34:57 [INFO] Netlink neighbor watcher started
2025-04-08T12:34:57 [INFO] Net alerter running — DHCP sniffer + Netlink neighbor watcher active
```

## Step 5: Test Alerting

Connect a test device (laptop, phone) to the network and watch for alerts:

```bash
# In one terminal, monitor logs:
ssh root@10.0.0.0 "journalctl -u net_alerter -f"

# In another, connect your test device and look for:
# [NET] ARRIVED: test-device (192.168.1.XX) [Vendor] MAC:xx:xx:xx:xx:xx:xx
```

Also check Matrix room — alerts should appear in the configured room.

## Troubleshooting

### Service not running
```bash
ssh root@10.0.0.0 "systemctl status net_alerter"
```
If failed, check logs:
```bash
ssh root@10.0.0.0 "journalctl -u net_alerter -n 50 | tail -20"
```

### No devices detected
- Check ARP cache: `ssh root@10.0.0.0 "ip neigh show"`
- Check interface: `ssh root@10.0.0.0 "ip link show"`
- Ensure interface is up and connected

### Alerts not reaching Matrix
- Verify token: `curl -s https://m.example.org/_matrix/client/v3/account/whoami -H "Authorization: Bearer <token>"` should return user info
- Verify bot is in room (check Matrix room members)
- Check logs for HTTP errors: `journalctl -u net_alerter -e`

### High CPU/Memory
- Unlikely — monitor with: `ssh root@10.0.0.0 "top -b -n 1 -p $(pgrep -f net_alerter)"`
- Check for spam in logs (malformed packets?)

## Logs and Debugging

### View Recent Logs
```bash
ssh root@10.0.0.0 "journalctl -u net_alerter --since '30 min ago'"
```

### Follow Live Logs
```bash
ssh root@10.0.0.0 "journalctl -u net_alerter -f"
```

### Check Daemon Log File
```bash
ssh root@10.0.0.0 "tail -f /opt/net_alerter/net_alerter.log"
```

## Maintenance

### Reload Configuration
After updating `.env`:
```bash
ssh root@10.0.0.0 "systemctl restart net_alerter"
```

### View Tracked Devices
The daemon tracks known devices in memory (not persisted). Check active count in logs:
```bash
ssh root@10.0.0.0 "journalctl -u net_alerter | grep 'Tracking.*devices' | tail -5"
```

### Stop Service
```bash
ssh root@10.0.0.0 "systemctl stop net_alerter"
```

### Restart Service
```bash
ssh root@10.0.0.0 "systemctl restart net_alerter"
```

## Uninstall

To remove net_alerter and restore cron (if needed):

```bash
ssh root@10.0.0.0 "
systemctl stop net_alerter
systemctl disable net_alerter
rm /etc/systemd/system/net_alerter.service
systemctl daemon-reload
rm -rf /opt/net_alerter
"
```

## Performance Characteristics

| Metric | Value |
|--------|-------|
| CPU Usage | <1% idle (thread sleeping on socket reads) |
| Memory | ~15-20 MB (Python + loaded OUI database) |
| Network Traffic | Passive only (no active probing) |
| Startup Time | ~2 seconds (ARP cache seed) |
| Detection Latency | <100ms (Netlink events) or ~5-10min (ARP timeout) |

## Next Steps

- Set up monitoring/alerting for service health
- Configure retention policy for logs (logrotate)
- Document any custom configuration in site-specific notes