Add Orange Pi Zero 3 specific deployment guide

2026-04-08 21:56:03 -04:00
parent a54acf32b8
commit 424b4f4552
1 changed files with 214 additions and 0 deletions
@@ -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": "<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