From a194642941200b5ed172b093bd8f469d05cae58a Mon Sep 17 00:00:00 2001 From: Cobra Date: Wed, 8 Apr 2026 21:56:03 -0400 Subject: [PATCH] Add Orange Pi Zero 3 specific deployment guide --- net_alerter/ORANGE_PI_DEPLOYMENT.md | 214 ++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 net_alerter/ORANGE_PI_DEPLOYMENT.md diff --git a/net_alerter/ORANGE_PI_DEPLOYMENT.md b/net_alerter/ORANGE_PI_DEPLOYMENT.md new file mode 100644 index 0000000..cf9456b --- /dev/null +++ b/net_alerter/ORANGE_PI_DEPLOYMENT.md @@ -0,0 +1,214 @@ +# 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": "" + }' | 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 < +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 < +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 "` 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