bigbrother/net_alerter/ORANGE_PI_DEPLOYMENT.md

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:

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):

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)

# 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

# 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:

# 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

ssh root@10.0.0.0 "systemctl status net_alerter"

If failed, check logs:

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

ssh root@10.0.0.0 "journalctl -u net_alerter --since '30 min ago'"

Follow Live Logs

ssh root@10.0.0.0 "journalctl -u net_alerter -f"

Check Daemon Log File

ssh root@10.0.0.0 "tail -f /opt/net_alerter/net_alerter.log"

Maintenance

Reload Configuration

After updating .env:

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:

ssh root@10.0.0.0 "journalctl -u net_alerter | grep 'Tracking.*devices' | tail -5"

Stop Service

ssh root@10.0.0.0 "systemctl stop net_alerter"

Restart Service

ssh root@10.0.0.0 "systemctl restart net_alerter"

Uninstall

To remove net_alerter and restore cron (if needed):

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