Re-binding

Each device has a cryptographic identity — a private key on the firewall and a matching public key registered with NetDefense. Re-binding is the operator workflow for rotating that identity: the agent generates a new keypair and NetDefense replaces the public key on file with the new one.

When to re-bind

Re-binding is not part of routine upgrades. The key survives pkg upgrade. You re-bind only when one of these is true:

• You suspect the device’s private key may have been compromised (theft, accidental exposure, employee turnover with administrative access).
• You replaced the firewall hardware and want the new device to take over the old device’s identity in NetDefense.
• You restored OPNsense from a backup that predates the current key, or wiped /var/db/ndagent/ directly.
• You’re moving the device between channels (os-netdefense ↔ os-netdefense-qa ↔ os-netdefense-dev) — switching channels involves a pkg remove which discards the key.

If your only goal is to upgrade NDAgent to a newer version on the same channel, just pkg upgrade and skip this page.

How it works

A re-bind ceremony pairs two halves: a one-time token issued by NetDefense, and a fresh keypair generated by the device. Pasting the token into the OPNsense GUI tells the agent “this rotation is authorized” — it generates the new key, sends the new public half along with the token, and NetDefense binds the new key after verifying the token.

The token is single-use, expires in 24 hours, and is invalid as soon as the rotation is complete.

The procedure

1. Issue the re-bind token from your workstation:

   ndcli device rebind-token <device-name> --org <organization>

   ndcli prints the token once. Copy it — it’s not recoverable.

2. Disable the plugin in the OPNsense web UI:

   Services → NetDefense → uncheck Enabled → Save.

   This stops the running agent so it doesn’t try to register before the new token is in place.

3. Replace or upgrade the package on the device. SSH in and run the variant for your situation:

   # If you're staying on the same channel and just want fresh state:
   sudo pkg upgrade -y os-netdefense
   
   # If you're switching channels, replace the package:
   sudo pkg remove -y <current-package-name>
   sudo sh -c 'curl -sSL https://repo.netdefense.io/install.sh | sh'

   Tip

   Re-binding doesn’t strictly require a package change — if you just need to rotate the key on an existing install, you can skip this step. But it’s the most common context, so the ceremony usually pairs with one.

4. Re-enable the plugin and paste the token, in the same Save action:

   Services → NetDefense → check Enabled → toggle Show advanced fields → paste the token into Re-bind Token → Save.

   The agent picks up the token, generates the new keypair, and sends the new public key to NetDefense.

5. Approve the device from your workstation:

   ndcli device approve <device-name> --org <organization>
   ndcli device list --org <organization>

   The device should show ENABLED with a fresh heartbeat. If it still shows UNREGISTERED, run ndcli device approve again — the bind already succeeded server-side and approval is the final transition.

6. (NDAgent ≥ 1.7.0) The agent clears the Re-bind Token field for you on its first successful registration after the rotation, so the field should already be empty when you open the GUI again. No manual action is required.

   On older NDAgent versions you must clear the field by hand: Services → NetDefense → Show advanced → clear Re-bind Token → Save. The token was single-use and is already inert; this is purely housekeeping.

Verification

After a successful re-bind:

ndcli task create <device-name> PING --target 8.8.8.8 --org <organization>
ndcli task describe <task-code> --org <organization>

The PING task should COMPLETE. If it FAILS with broker: response signature verification failed, the keypair on the device doesn’t match what’s bound on the server side — repeat the procedure with a fresh token.

Troubleshooting

Symptom	Action
ndcli device list shows UNREGISTERED after step 5	Re-run ndcli device approve <device> --org <org>. The re-bind succeeded server-side; the device just needs the final approval transition.
Agent log shows repeated 429 errors during step 4	Expected briefly. The agent has its own backoff and self-recovers within ~1 minute. If it persists past 5 minutes, sudo service ndagent restart.
Repeated PING failures with signature verification failed	The device’s current key doesn’t match the server’s. Issue a fresh token and run the procedure again from step 1.
Multiple devices on the same WAN failing simultaneously	They share an external rate limit. Stagger the re-binds — one device at a time, ~1 minute apart.

Note

The token expires 24 hours after issuance. If you don’t paste it within that window, run ndcli device rebind-token again to get a fresh one. Tokens are not stored anywhere recoverable on the NetDefense side — they’re computed once, hashed, and the original is shown to you only at issuance.