Add Orange Pi Zero 3 specific deployment guide
This commit is contained in:
Cobra
@@ -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
|
||||
Reference in New Issue
Block a user