NetBird: the script module (automation)

NetBird is a WireGuard mesh: servers connect to each other directly, while a management server hands out addresses and keys. Once connected, the panel reaches its nodes at network addresses instead of public ones: node management stops depending on public ports and IPs, while the public 2222 path stays open as a backup. If the NetBird cloud is unreachable, the panel still reaches the nodes.

Everything below is done by the script module, the NetBird: overlay network for nodes and panel item in the main menu. The manual, script-free way is described in a separate article and works for everyone.

What you need

Panel and NetBird account

A Remnawave panel installed on this server and a NetBird account: the cloud at app.netbird.io or your own management server.

Setup key

From the NetBird account, needed for the first connection.

SSH access to the servers

To move nodes and to work with the subscription page: SSH access from the panel to those servers, configured with the SSH access extension.

Token for API mode

For API mode (recommended): an access token of a NetBird service user.

How it is built

The module moves service traffic into a private network without breaking the public path. Each connection has its own route:

Connection	Public path	Through NetBird
Panel → nodes (management)	public address, port 2222	the node’s network address, same port
Subscription page → panel	panel’s public address	a dedicated panel port from the 3100+ range, closed to the internet
Checker → panel (subscription)	public subscription	same port, /api/sub/ only
Panel → checker metrics	public port 2112	the checker’s network address, password-protected

Guarantees the module keeps at every step:

The public path stays a backup

Each node’s public path stays as a backup and is never closed by the move.

Nothing binds to the network address

Nothing is bound to a network address and no Docker ports are published on it: a service bound to such an address would not survive a server reboot.

Checked before the move

Moving a node changes its panel address only after a live path check from inside the panel container.

Every step is reversible

An emergency one-command rollback for nodes, dedicated menu items for the subscription page and the checker.

Preparing the NetBird account

1. Register at app.netbird.io.

2. In Settings → Setup Keys create a key:

   • type Reusable, any expiry: the key is needed only at connection time, the module never needs it afterwards, so a permanent key is unnecessary.
   • the key is shown once, copy it.

3. If you plan API mode (recommended): in Team → Service Users click Create Service User, pick a name and the Admin role. Then open the user and click Create Access Token. The token is shown once, copy it. Pick the largest available expiry (Expires in): the token is stored on the panel server and used by the module constantly, and when it expires API mode stops working until you enter a fresh token in the module settings.

The Default policy

A fresh account has the Default policy active (All↔All): every peer can reach every port of every server. In API mode the module creates one-way policies (panel → nodes, tcp/2222 and friends) and, on your command, disables Default after first checking that all needed paths are alive. The policy body is saved and restored by one command. In basic mode disable Default manually after setting up the groups.

Connecting the panel

Run on the panel server:

remnawave_reverse

1. Select NetBird: overlay network for nodes and panel.

2. Select Connect this server to NetBird.

3. Paste the setup key (hidden input) and confirm the server name:

   root@server: ~

   Setup-key (input hidden):
    Create the key in the NetBird dashboard: Settings → Setup Keys → Create Setup Key.
    Type Reusable works, the default expiry is enough
   Server name in NetBird [panel]: panel
   Your self-hosted NetBird server address (Enter = NetBird cloud): 
    Only for self-hosted management; for the cloud just press Enter

4. The module installs the NetBird client, pins the package version, disables lazy connections and registers the server in the network:

   root@server: ~

   [ * ] Installing the NetBird client
   NetBird client installed
   [ * ] Disabling lazy connections (NB_LAZY_CONN=off)
   Lazy connections disabled
   [ * ] Registering the server in the network
   Waiting for the management connection and a wt0 address (up to 60s)
   Connected, overlay address 100.88.10.7/16
   The server is connected to NetBird

5. The module then offers to enable API mode right away: it creates the groups and one-way policies itself, and then asks whether to disable the Default policy (after checking that the paths to the nodes are alive). You can decline: the module prints a short manual policy guide, and API mode can be enabled later via Module settings.

   root@server: ~

   Set up API mode now? (y/n): y

The client connects with mandatory settings: NetBird DNS is off (the host /etc/resolv.conf is untouched), the client’s routes and firewall do not interfere with the server, and the connection is kept alive. If the server was connected manually before the module, the Restore the correct client settings item reapplies them.

Why the version is pinned

The package version is pinned right after install so background updates never restart the client on their own: a restart recreates the network interface and briefly cuts management to all moved nodes at once, at a random moment. Updates live in the menu, one server at a time.

API mode: groups, keys, the Default policy

In the Module settings (access token, API mode) menu, enter the service user’s access token. The module will:

• create the groups rrp-…-panel, rrp-…-nodes and a one-way policy panel → nodes tcp/2222;
• issue one-time keys for every server and revoke them right after use, so keys never need pasting again;
• in the Policies and Default item, show the access state and disable Default on confirmation (with an automatic restore if the paths do not survive).

Without API mode the module still works, but keys for new servers must be created and pasted manually, and policies configured yourself.

Moving nodes into the NetBird network

Every node needs SSH access from the panel (the SSH access extension). The module only connects servers by their public address: after the move, the network address becomes the panel’s main path to the node.

1. In the NetBird menu select Nodes: move to the NetBird network, import manual setup, status, then Move a node to the NetBird network and pick the node.

2. Confirm the plan. The module connects the server to NetBird, checks the path to 2222 right from inside the panel container, and only then switches the node’s panel address to the network one:

   root@server: ~

   Moving a node to the NetBird network
   Pick a node (0-4): 1
   Plan: NetBird on de-fra-01 → path check → PATCH address → wait up to 120s for the confirmed reconnect
   Proceed? (y/n): y
   [ * ] SSH to 203.0.113.20
   DNS guard: remnanode resolver check
   remnanode resolves through the host resolver
   [ * ] NetBird client on de-fra-01
   de-fra-01 connected, overlay address 100.88.4.12
   Fallback wt0 rule on the node
   Fallback rule added
   [ * ] Path check from the panel container to 100.88.4.12:2222
   Path confirmed (TCP + TLS, PMTU fine)
   Overlay alias in the SSH target
   Alias recorded, machine identity verified
   PATCH address → 100.88.4.12
   Address updated
   Waiting for the confirmed reconnect (up to 120s + 45s stability)
   The node reconnected over the overlay

3. Wait for the confirmed reconnect. The public 2222 rule stays as the backup path.

If the path check fails, the node’s address is not changed and the module hints at likely causes (policies, lazy connections, node plugins). Any unfinished move can be continued or rolled back from the same menu item.

Nodes already connected to NetBird manually are adopted via Import nodes… in the same submenu.

A node born in the network

When adding a new node to the panel (automatic mode), the module offers to deploy it straight into the network: the client is installed on the node server, the panel record appears with the network address, and the public 2222 opens as a backup. It saves one move if the server is known in advance.

Subscription page

The Subscription page on a separate server item targets a subscription page already running on its own server. The module:

• opens a dedicated port from the 3100+ range on the panel, closed to the internet, and allows only the subscription server’s network address on it;
• connects the subscription server to NetBird if the client is not there yet;
• rewrites its compose to the panel’s network address: EGAMES_COOKIE and auth gates leave the compose, and the panel configuration no longer crosses the public internet;
• saves a snapshot of the public configuration before changing anything and verifies the result live: the container holds, the panel answers.

While the page runs through the network, the same item offers a return to the public path (the configuration is restored from the snapshot, the access cookie is refreshed to the current panel, the public path is verified) or a re-move after manual edits.

Xray Checker

The Xray Checker through the NetBird network item moves the checker inside the network:

• the checker takes the subscription from the panel through /api/sub/ only, the public subscription is not needed;
• metrics and the monitoring page answer under a password and only to network servers, invisible from the internet;
• before the move the module saves a snapshot of the checker’s public configuration, if there was one.

The return to the public path goes through the same item: the found public checker snapshot is restored and verified; with no snapshot, the module’s checker container is stopped and removed, and the public checker is then brought up by the Xray Checker module.

Emergency rollback and diagnostics

• The Emergency return of nodes to public addresses item returns all nodes to their public addresses in one command; NetBird itself stays connected.
• Diagnostics and address verification compares the addresses recorded in the module with the actual ones (an address may change after a reconnect) and shows the client and path state.

Disabling

Disable NetBird (full rollback) stops the client on this server; the installation and module state are kept. When folding the setup down: first return the nodes to public addresses (emergency rollback or one by one), then move the subscription page and checker back, and disconnect the panel last. While the panel has nodes at network addresses, or the subscription or checker run through the network, the module refuses to disconnect the panel.

Full removal

The Remove NetBird completely (client and module state) item tears the whole setup down, not just one panel server. While anything still runs through the network (panel nodes, subscription server, checker), the module refuses and tells you what to return to the public path first. Then, optionally, the client is removed from the nodes where the module installed it: over SSH it disconnects, leaves the network and purges the package, and the old records of those servers are cleaned from the account. The same then happens on the panel itself: the client, the registration and the module state (mode, access token, node records). Groups and policies stay in the account. The only manual leftover: the client on the subscription or checker server, if they ran through the network and were already returned to the public path (the module no longer knows their addresses after the return); run apt purge netbird there. This is the way to start from scratch: after removal, Connect this server to NetBird offers the first-time setup again.

The module menu: what each item does

The menu depends on the server’s state: before the client is installed only the connect item is visible, and some items appear only on the panel or in API mode. The header shows the client (version and pin), the network address, the management link and the mode. On a connected panel in API mode the menu looks like this:

root@server: ~

NetBird
 Details in the wiki: https://wiki.egam.es/configuration/netbird-module/

 Client: 0.59.0 · overlay: 100.88.10.7/16 · management: connected
 Mode: API

1.Nodes: move to the NetBird network, import manual setup, status
2.Emergency return of nodes to public addresses
3.Subscription page on a separate server
4.Xray Checker through the NetBird network
5.Diagnostics and address verification
6.Policies and the Default policy (API mode)
7.Module settings (access token, API mode)
8.Restore the correct client settings
9.Update the NetBird client (one server at a time)
10.Disable NetBird (full rollback)
11.Remove NetBird completely (client and module state)

0.Exit

Select action (0-11):

Manual setup (without the module)

If the module is unavailable, the minimal set of steps is (with all the caveats the module closes automatically):

# on the panel and on the node
curl -fsSL https://pkgs.netbird.io/install.sh | sh
apt-mark hold netbird

# pass the key only through a file, never on the command line (a key in argv is visible in ps and history)
install -m600 /dev/null /run/nbkey
printf '%s' 'YOUR-SETUP-KEY' > /run/nbkey
netbird up --setup-key-file /run/nbkey --disable-dns=true --disable-client-routes=true \
    --disable-server-routes=true --block-inbound=false --disable-firewall=false
rm -f /run/nbkey
netbird service reconfigure --service-env NB_LAZY_CONN=off

Then set the node’s network address in the “Address” field of its card in the panel. Remember: without one-way policies, traffic between peers is unrestricted (Default = all to all), and UFW rules do not apply on the wt0 interface: access is filtered only by NetBird policies.

Summary

• The panel and nodes are tied by a protected tunnel, with public 2222 as the backup path.
• The subscription and monitoring travel the NetBird network, their ports closed to the internet.
• Everything can return to public addresses at any moment: nodes in one command, the subscription and checker with their own menu items.

NetBird manuallyThe same result without the script: client setup, keys and policies by hand, for any server.

SSH access to serversKeys and targets for the second server: the NetBird module needs them for moving nodes and the subscription page.