How to Install NetBird on GL.iNet Routers and Route Traffic Through an Exit Node

Background

The official NetBird binary installer can install the NetBird client on GL.iNet routers, including models based on OpenWrt 21/23 branches. Two additional details need to be handled on these systems:

  • Some firmware versions do not provide the service command expected by the installer.
  • NetBird stores its default profile under /var/lib/netbird. On GL.iNet firmware, /var is stored in RAM, so the profile can be lost after a reboot.

This guide uses the official NetBird binary installer, then adds a separate OpenWrt procd service named gl-netbird. The NetBird profile is stored at /etc/netbird/config.json, while frequently changing runtime files remain under /var.

The installation, persistent service, enrollment, update, reboot, and removal flow was tested with NetBird 0.81.2 on:

  • Brume 3 (GL-MT5000), firmware 4.9.0, OpenWrt 21.02 base.
  • Slate 7 (GL-BE3600), firmware 4.10.1, OpenWrt 23.05 base.

Important Notes

  • This is a command-line installation. It does not add NetBird controls to the GL.iNet Admin Panel.
  • NetBird is third-party software. These steps are provided on a best-effort basis.
  • Coexistence with Tailscale and the effect on normal Internet access were not tested. Running multiple VPN clients can cause routing, DNS, or firewall conflicts. Test locally before enabling them at the same time.
  • The Exit Node section configures the router to use an existing NetBird Exit Node. It does not turn the GL.iNet router itself into an Exit Node.
  • Exit Node routing can interrupt remote access if the route or firewall is configured incorrectly. Perform that section while you have local access to the router.
  • For comparison, see the previous Exit Node guide:

Step 1: Install the Official NetBird Binary

SSH into the router and run:

curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird version

On some GL.iNet firmware versions, the installer may report that the service executable was not found. This is expected at this stage and will be addressed below.

Step 2: Add the service Compatibility Helper If Needed

Some firmware versions already include a service command, while others do not. Run the block below to check for it. The compatibility helper is created only when the command is missing, and is used during NetBird updates.

if ! command -v service >/dev/null 2>&1; then
    mkdir -p /etc/netbird/bin

    cat > /etc/netbird/bin/service <<'EOF'
#!/bin/sh
# Managed by the GL.iNet NetBird tutorial.
# Created only when the firmware does not provide a service command.
# Used while the official installer updates NetBird.

service_name="$1"
[ -n "$service_name" ] || {
    echo "Usage: service <name> <action>" >&2
    exit 1
}
shift

case "$service_name" in
    *[!A-Za-z0-9_.-]*)
        echo "Invalid service name: $service_name" >&2
        exit 1
        ;;
esac

# Keep the installer-managed netbird service file disposable. All NetBird
# start/stop requests are handled by the persistent procd service instead.
if [ "$service_name" = "netbird" ] && [ -x /etc/init.d/gl-netbird ]; then
    service_name="gl-netbird"
fi

init_script="/etc/init.d/$service_name"
[ -x "$init_script" ] || {
    echo "Service not found: $service_name" >&2
    exit 1
}

exec "$init_script" "$@"
EOF

    chmod 755 /etc/netbird/bin/service
fi

Step 3: Create the procd Service

Run:

cat > /etc/init.d/gl-netbird <<'EOF'
#!/bin/sh /etc/rc.common

START=99
STOP=10
USE_PROCD=1

PROG="/usr/bin/netbird"
INSTALL_URL="https://pkgs.netbird.io/install.sh"

extra_command "update" "Update NetBird with the official binary installer"

start_service() {
    [ -x "$PROG" ] || {
        echo "NetBird binary not found: $PROG" >&2
        return 1
    }

    mkdir -p /etc/netbird /var/lib/netbird /var/log/netbird
    chmod 700 /etc/netbird

    procd_open_instance
    procd_set_param command "$PROG"
    procd_append_param command service run
    procd_append_param command --log-level info
    procd_append_param command --daemon-addr unix:///var/run/netbird.sock
    procd_append_param command --log-file /var/log/netbird/client.log
    procd_set_param env NB_CONFIG=/etc/netbird/config.json
    procd_append_param env NB_DISABLE_SSH_CONFIG=1
    procd_append_param env NB_DNS_STATE_FILE=/var/lib/netbird/state.json
    procd_set_param respawn 3600 5 5
    procd_set_param stdout 1
    procd_set_param stderr 1
    procd_close_instance
}

update() {
    local installer="/tmp/netbird-install.$$"
    local helper_path
    local update_rc

    [ -x "$PROG" ] || {
        echo "NetBird is not installed." >&2
        return 1
    }

    if command -v service >/dev/null 2>&1; then
        helper_path=""
    elif [ -x /etc/netbird/bin/service ]; then
        helper_path="/etc/netbird/bin"
    else
        echo "NetBird service compatibility helper is missing." >&2
        return 1
    fi

    if ! curl -fsSL "$INSTALL_URL" -o "$installer"; then
        echo "Failed to download the NetBird installer." >&2
        return 1
    fi
    chmod 700 "$installer"

    /etc/init.d/gl-netbird stop

    if [ -n "$helper_path" ]; then
        PATH="$helper_path:$PATH" sh "$installer" --update
    else
        sh "$installer" --update
    fi
    update_rc=$?
    rm -f "$installer"

    # The official installer may recreate its own service file. Keep it disabled;
    # gl-netbird is the only NetBird service that should start at boot.
    if [ -x /etc/init.d/netbird ]; then
        /etc/init.d/netbird stop >/dev/null 2>&1
        /etc/init.d/netbird disable >/dev/null 2>&1
    fi
    rm -f /etc/rc.d/S??netbird /etc/rc.d/K??netbird

    /etc/init.d/gl-netbird start

    [ "$update_rc" -eq 0 ] || return "$update_rc"
    "$PROG" version
}
EOF

chmod 755 /etc/init.d/gl-netbird

# Keep the installer-generated service disabled to avoid duplicate processes.
/etc/init.d/netbird disable >/dev/null 2>&1 || true
rm -f /etc/rc.d/S??netbird /etc/rc.d/K??netbird

/etc/init.d/gl-netbird enable
/etc/init.d/gl-netbird start

Step 4: Connect the Router to NetBird

Replace YOUR_SETUP_KEY with the setup key from the NetBird dashboard:

netbird up --setup-key "YOUR_SETUP_KEY"

Check the connection:

netbird status

The status should show that the management and signal connections are connected.

Step 5: Verify Automatic Startup

Reboot the router:

reboot

After the router is available again, reconnect through SSH and run:

/etc/init.d/gl-netbird running && echo "gl-netbird is running"
netbird status
ls -l /etc/netbird/config.json

The gl-netbird service should be running, NetBird should reconnect without another setup key, and /etc/netbird/config.json should still exist.

Step 6: Use an Existing NetBird Exit Node

This section assumes an Exit Node has already been configured in the NetBird network. In the example used for this guide, the existing Exit Node is located in Macao.

6.1 Check the Exit Node in the NetBird Dashboard

In the NetBird dashboard:

  1. Open Peers and confirm that the Macao routing peer is online and marked as an Exit Node.

  2. Open the Exit Node configuration and confirm that its distribution groups include the group containing this GL.iNet router.

  3. Decide whether to enable Auto Apply:

    • When enabled, eligible peers use the Exit Node automatically unless a user previously made a manual selection.
    • When disabled, the Exit Node is offered to the router but must be selected manually.

Configure a reachable NetBird DNS server for the same peer group with the match domain set to ALL if DNS queries should also use the Exit Node path. Otherwise, DNS may continue to use the router's local resolver.

If the Exit Node is selected but domain names stop resolving, check netbird status and the dashboard DNS configuration. Nameservers: 0/0 Available means that no NetBird nameserver is currently available to the router. To keep using the router's existing DNS instead, run:

netbird up --disable-dns

This disables NetBird DNS management but does not disable NetBird routing. DNS requests may then leave through the router's original DNS path rather than the Exit Node. To re-enable NetBird DNS after a reachable nameserver has been configured, run:

netbird up --disable-dns=false

An Exit Node route also covers networks reachable behind the Exit Node. If the Macao peer is dedicated to Internet egress and its local LAN should not be reachable, enable Block LAN access for that routing peer or isolate it on a dedicated network segment.

6.2 Select the Exit Node on the Router

List the available NetBird networks and their selection status:

netbird networks list

If the Macao Exit Node is already shown as selected, no additional command is required. If it is available but not selected, copy its identifier and run:

netbird networks select -a "<EXIT_NODE_ID>"

The -a option preserves any other networks that are already selected.

Confirm that the default route was received:

netbird status -d

The selected Exit Node should be associated with 0.0.0.0/0 in the output.

6.3 Allow LAN Devices to Use the Exit Node

Selecting the Exit Node changes the router's NetBird route. To send traffic from devices connected to the GL.iNet router through the same route, add the NetBird tunnel to the OpenWrt firewall.

First, confirm that the NetBird tunnel device exists:

ip link show wt0

Use either LuCI or the UCI commands below. Both methods create the same netbird firewall zone and lan → netbird forwarding path.

Option A: Configure the Firewall with LuCI

Then open GL.iNet Admin Panel → SYSTEM → Advanced Settings to enter LuCI, and go to Network → Firewall → General Settings.

  1. Click Add to create a zone named netbird.
  2. Set Output and Forward to accept. Set Input to accept only if NetBird peers should be able to reach services on the router; otherwise use reject.
  3. Enable Masquerading.
  4. Leave Covered networks unspecified.
  5. Under Allow forward from source zones, select lan. Select guest as well only if Guest-network clients should use the Exit Node.
  6. Open Advanced Settings and select Ethernet Adapter: wt0 under Covered devices.
  7. Click Save, then Save & Apply.

Adding WAN as a source zone is not required for routing normal LAN clients through the Exit Node. Add only the local source zones whose clients should use NetBird.

Option B: Configure the Firewall with UCI

Instead of using LuCI, run the following commands over SSH. The named UCI sections make the configuration repeatable and allow it to be removed precisely later.

uci -q delete firewall.netbird
uci -q delete firewall.lan_to_netbird

uci set firewall.netbird='zone'
uci set firewall.netbird.name='netbird'
uci set firewall.netbird.input='REJECT'
uci set firewall.netbird.output='ACCEPT'
uci set firewall.netbird.forward='ACCEPT'
uci set firewall.netbird.masq='1'
uci add_list firewall.netbird.device='wt0'

uci set firewall.lan_to_netbird='forwarding'
uci set firewall.lan_to_netbird.src='lan'
uci set firewall.lan_to_netbird.dest='netbird'

uci commit firewall
/etc/init.d/firewall restart

The default above rejects connections from NetBird peers to services on the router. If those peers should be allowed to reach the router itself, change the zone's Input policy:

uci set firewall.netbird.input='ACCEPT'
uci commit firewall
/etc/init.d/firewall restart

To let Guest-network clients use the Exit Node as well, add a separate forwarding only when required:

uci -q delete firewall.guest_to_netbird
uci set firewall.guest_to_netbird='forwarding'
uci set firewall.guest_to_netbird.src='guest'
uci set firewall.guest_to_netbird.dest='netbird'
uci commit firewall
/etc/init.d/firewall restart

Check the resulting UCI sections:

uci show firewall.netbird
uci show firewall.lan_to_netbird
uci -q show firewall.guest_to_netbird

6.4 Verify the Exit Location

From the router, check the public IPv4 address:

curl -4 https://ipinfo.io

Run the same check from a device connected to the router. Both results should match the public IP address of the Macao Exit Node.

If the router shows the Macao address but a LAN client does not, recheck the netbird firewall zone, the wt0 covered device, Masquerading, and the lan → netbird forwarding permission.

To stop using the Exit Node while keeping NetBird connected, run:

netbird networks deselect "<EXIT_NODE_ID>"

Manual selection or deselection is remembered by the client and takes precedence over Auto Apply. To use the Exit Node again, repeat the netbird networks select -a command.

Updating NetBird

Use the following command to check for and install the latest binary with the official installer:

/etc/init.d/gl-netbird update
/etc/init.d/gl-netbird running && echo "gl-netbird is running"
netbird status

The update command downloads the official installer, stops gl-netbird, and uses the firmware's existing service command or the compatibility helper created in Step 2. It then disables the installer-generated service and starts gl-netbird again. The configuration under /etc/netbird is preserved. If the installed version is already current, the installer reports that it is up to date and the same gl-netbird service is restarted.

Some older OpenWrt builds may display ps: unrecognized option: e while the official installer checks for the desktop UI process. On a headless router, this warning does not prevent the binary update. Confirm the version and connection status with the commands above.

Do not rerun the plain installation command to update an existing installation. The official installer requires its --update mode, which the command above handles.

Common Commands

# Show status
netbird status

# Stop NetBird
/etc/init.d/gl-netbird stop

# Start NetBird
/etc/init.d/gl-netbird start

# Restart NetBird
/etc/init.d/gl-netbird restart

# Disconnect without uninstalling
netbird down

# Reconnect
netbird up

Uninstalling NetBird

If you also want to remove this router from your NetBird account, run the following command first:

netbird deregister

If you skip this command, the local client will still be removed, but the peer entry will remain in the NetBird dashboard until you delete it there.

Then remove the optional firewall configuration before deleting NetBird. If you used LuCI, delete the netbird zone in LuCI → Network → Firewall and click Save & Apply. If you used the UCI method in this guide, run:

uci -q delete firewall.guest_to_netbird
uci -q delete firewall.lan_to_netbird
uci -q delete firewall.netbird
uci commit firewall
/etc/init.d/firewall restart

This prevents a stale wt0 firewall reference after NetBird is removed. Then remove the service, binary, configuration, and runtime files:

/etc/init.d/gl-netbird stop >/dev/null 2>&1 || true
/etc/init.d/gl-netbird disable >/dev/null 2>&1 || true
/etc/init.d/netbird stop >/dev/null 2>&1 || true
/etc/init.d/netbird disable >/dev/null 2>&1 || true
rm -f /etc/rc.d/S??netbird /etc/rc.d/K??netbird

rm -f /etc/init.d/gl-netbird /etc/init.d/netbird
rm -f /usr/bin/netbird
rm -rf /etc/netbird /var/lib/netbird /var/log/netbird
rm -f /var/run/netbird.sock /var/run/netbird.pid

The official NetBird binary installer currently provides an update option but not a complete uninstall option, so the manual cleanup above is required.

Notes

  • The installer-generated /etc/init.d/netbird file may be recreated during an update. This is normal. It remains disabled; gl-netbird is the startup service used by this guide.
  • The compatibility helper under /etc/netbird/bin is created only on firmware that does not already provide a service command.
  • A firmware upgrade may remove custom binaries or scripts. If NetBird is missing afterward, repeat the installation steps and reconnect only if the existing configuration was not preserved.
  • The NetBird setup key is required only for the initial enrollment unless the router is deregistered or its persistent configuration is removed.

References

NetBird installation script:

https://pkgs.netbird.io/install.sh

NetBird CLI documentation:

NetBird client environment variables:

NetBird OpenWrt configuration persistence discussion:

NetBird Exit Node documentation:

OpenWrt NetBird procd service implementation:

OpenWrt firewall configuration reference:

OpenWrt UCI reference:

what is the correct way of giving a multi line command CLI 9n a small Brume3?

do you recommend to copy the complete block to a .txt file on the windows machine and then paste it in the ssh?

or can the Brume handle a multi line command?

Dear Support team thanks for the great help.

in case i want to install on the Brume an exit node that shall be used by remote devices connected to netbird, what sections of paragraph 6 shall i use?

i guess just 6.4?

Hi,

Regarding how to copy and paste the command block: Yes, you can directly copy the entire block, paste it into SSH, and press Enter to run it—there is no need to copy each command separately.

Regarding configuring Brume 2 as a NetBird Exit Node:

  1. Follow the steps in 6.1 to configure Brume as an Exit Node.
  2. Follow the steps in 6.3, but instead of setting “Allow forward from source zones” to LAN, set “Allow forward from destination zones” to WAN. (If you need to access LAN clients, still check “Allow forward from source zones” and set it to LAN.)

thanks for the clarification about the multiple line entries.

however for section 6 i am confused in case that the brume is used as exit node.

so only sections 6.1 and 6.3 are applicable.

6.3 needs some modifications: could you post a modified graphical configuration like the one in the original post?

this would allow me avoiding errors thanks