netbird-iac/watcher/README.md

NetBird Peer Renamer Watcher

Automatically renames NetBird peers after enrollment based on setup key names.

How It Works

1. Engineer creates setup key named after the desired peer name (e.g., pilot-ivanov)
2. Operator enrolls using the setup key
3. Peer appears with random hostname (e.g., DESKTOP-ABC123)
4. Watcher detects the consumed setup key and renames peer to pilot-ivanov

Logic

The watcher polls NetBird API every 30 seconds:

1. Fetches all setup keys
2. Finds keys with used_times > 0 that haven't been processed
3. For each consumed key:
   • Looks up last_used timestamp
   • Finds peer created around that time (within 60 seconds)
   • Renames peer to match setup key name
4. Marks key as processed to avoid re-processing

Installation

Via Ansible

cd ansible/netbird-watcher
ansible-playbook -i poc-inventory.yml playbook.yml -e vault_netbird_token=<TOKEN>

Manual

# Copy script
sudo cp netbird_watcher.py /opt/netbird-watcher/
sudo chmod +x /opt/netbird-watcher/netbird_watcher.py

# Create config
sudo mkdir -p /etc/netbird-watcher
sudo cat > /etc/netbird-watcher/config.json << EOF
{
  "url": "https://netbird-poc.networkmonitor.cc",
  "token": "nbp_YOUR_TOKEN"
}
EOF
sudo chmod 600 /etc/netbird-watcher/config.json

# Create state directory
sudo mkdir -p /var/lib/netbird-watcher

# Install service
sudo cp netbird-watcher.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now netbird-watcher

Usage

Check status

systemctl status netbird-watcher
journalctl -u netbird-watcher -f

Run manually (one-shot)

./netbird_watcher.py \
  --url https://netbird-poc.networkmonitor.cc \
  --token nbp_xxx \
  --once \
  --verbose

State file

Processed keys are tracked in /var/lib/netbird-watcher/state.json:

{
  "processed_keys": ["key-id-1", "key-id-2"]
}

To reprocess a key, remove its ID from this file.

Troubleshooting

Peer not renamed

1. Check if setup key was consumed: used_times > 0
2. Check watcher logs: journalctl -u netbird-watcher
3. Ensure peer enrolled within 60 seconds of key consumption
4. Check if key was already processed (in state.json)

Reset state

sudo rm /var/lib/netbird-watcher/state.json
sudo systemctl restart netbird-watcher