Netbird package doesn't start

[JeGr]

Important notices Before you add a new report, we ask you kindly to acknowledge the following:

• [x] I have read the contributing guide lines at https://github.com/opnsense/plugins/blob/master/CONTRIBUTING.md
• [x] I have searched the existing issues, open and closed, and I'm convinced that mine is new.
• [x] The title contains the plugin to which this issue belongs

Describe the bug The new Netbird package doesn't start when configured and set up with an appropriate key.

To Reproduce Steps to reproduce the behavior:

1. Go to 'VPN / Netbird'
2. Insert setup key, save
3. See "red stop" in the upper right corner, click start, won't start.
4. See error in general log file (netbird itself doesn't log anything)

Expected behavior Netbird plugin should start and register at their control plane with the setup key provided.

Relevant log files

[cf80a216-e515-45cc-acc1-a3cf1899ed2c] Script action failed with Command '/usr/local/bin/netbird up -m '[https://api.netbird.io:443](https://api.netbird.io/)' -k '22BCF562-xxxx-xxxx-xxxx-1CA4723CC26B'' returned non-zero exit status 1. at Traceback (most recent call last): File "/usr/local/opnsense/service/modules/actions/script_output.py", line 78, in execute [subprocess.run](https://subprocess.run/)(script_command, env=self.config_environment, shell=True, File "/usr/local/lib/python3.11/subprocess.py", line 571, in run raise CalledProcessError(retcode, process.args, subprocess.CalledProcessError: Command '/usr/local/bin/netbird up -m '[https://api.netbird.io:443](https://api.netbird.io/)' -k '22BCF562-xxxx-xxxx-xxxx-1CA4723CC26B'' returned non-zero exit status 1.

Environment OPNsense 25.7.3_7 (amd64) (latest) VM Environment Virtual NICs (vtnet) Clean DualStack setup with public IPs.

[JeGr]

Edit:

Did a bit more poking around on a second instance. It seems the problem stemms from

/usr/local/bin/netbird up -m 'https://api.netbird.io:443' -k '22BCF562-xxxx-xxxx-xxxx-1CA4723CC26B'

as that is what configd is stumbling over. I checked on the console that the binary itself can be run. That was fine. Upping with the parameters like in the error threw those errors on the console:

2025-09-12T16:42:41+02:00 INFO ./caller_not_available:0: 2025/09/12 16:42:41 WARNING: [core] [Channel #1 SubChannel #2]grpc: addrConn.createTransport failed to connect to {Addr: "/var/run/netbird.sock", ServerName: "localhost", Attributes: {"<%!p(networktype.keyType=grpc.internal.transport.networktype)>": "unix" }, }. Err: connection error: desc = "transport: Error while dialing: dial unix /var/run/netbird.sock: connect: no such file or directory"
2025-09-12T16:42:42+02:00 INFO ./caller_not_available:0: 2025/09/12 16:42:42 WARNING: [core] [Channel #1 SubChannel #2]grpc: addrConn.createTransport failed to connect to {Addr: "/var/run/netbird.sock", ServerName: "localhost", Attributes: {"<%!p(networktype.keyType=grpc.internal.transport.networktype)>": "unix" }, }. Err: connection error: desc = "transport: Error while dialing: dial unix /var/run/netbird.sock: connect: no such file or directory"
2025-09-12T16:42:44+02:00 INFO ./caller_not_available:0: 2025/09/12 16:42:44 WARNING: [core] [Channel #1 SubChannel #2]grpc: addrConn.createTransport failed to connect to {Addr: "/var/run/netbird.sock", ServerName: "localhost", Attributes: {"<%!p(networktype.keyType=grpc.internal.transport.networktype)>": "unix" }, }. Err: connection error: desc = "transport: Error while dialing: dial unix /var/run/netbird.sock: connect: no such file or directory"
Error: failed to connect to daemon error: context deadline exceeded
Error: failed to connect to daemon error: context deadline exceeded

If the daemon is not running please run:
netbird service install
netbird service start

So I checked the service. It is installed and set up but - of course - not started. Starting it does nothing as it gets stopped immediatly. But the CLI for netbird service shows that the global flag -k for key registration can be send with the service keyword, too. Not only with the up command (which should only bring it up when configured). So my guess was, that the service has to register with netbird service reconfigure -k <key> & netbird service start instead with up -k <key> and I tried that.

Upping the service with the key worked and showed status "running". GUI also switched to "green" and could stop/start without problems. So I guess the problem is the initial setup that has to be done with the service keyword, not with the up one?`

Cheers!

[JeGr]

Played around with the options, mainly service reconfigure, service start and up and it seems, the intial setup with up isn't working(?), because for some reason the service isn't starting up cleanly or is not called properly?

So manually bringing it up with the other two options seems to kick it in gear. As there's no real reset/uninstall for the package as the OPNsense config is remaining and when uninstalling/reinstalling the package is already there, a real test from scratch wasn't possible without having to reset the box to a state from yesterday. But somewhere in there the service start seems borked.

Cheers

[JeGr]

Redid from scratch:

• installed plugin "netbird"
• Go to NetBird/Authentication -- Setup Key with 0s is "preconfigured" -- change to real one and "Connect" -- page takes some time, shows checkmark but nothing else
• Go to NetBird/Settings -- Enable toggle, then Apply -- Service Icons on upper right show up, nothing else. Service is stopped/red. -- Starting service manually in the GUI won't work!
• Go back to Authentication -- page takes a bit to load until all elements show up -- pasting the key again and connect again: again the little checkmark, but nothing else. Service state still stopped.

Head to CLI:

root@opn-ce-257:~ # netbird service status
NetBird service status: Stopped

Manually starting the service doesn't work. It's immediatly stopped again.

root@opn-ce-257:~ # netbird service start
NetBird service has been started
root@opn-ce-257:~ # netbird service status
NetBird service status: Stopped

Running the service reconfiguration:

root@opn-ce-257:~ # netbird service status
NetBird service status: Stopped
root@opn-ce-257:~ # netbird service reconfigure
Removing existing service configuration...
Installing service with new configuration...
NetBird service has been reconfigured
root@opn-ce-257:~ # netbird service status
NetBird service status: Stopped
root@opn-ce-257:~ # netbird service start
NetBird service has been started
root@opn-ce-257:~ # netbird service status
NetBird service status: Running

Now that got it into gear and running! If we now head to the GUI and the Authentication section again and hit "Connect" again, we'll see that the service is actually up and running and after a bit the box on top shows "Netbird is online" as the registration now finally worked as the backend service was running to handle it.

So it seems there's either some misconfiguration after the package installation or it needs a "netbird service reconfigure" after the install to make it work? Don't exactly know but that did the trick on our test systems.

[sopex]

Same here :(

PHP error: [13-Sep-2025 10:47:00 Europe/Athens] PHP Warning: file_get_contents(/var/db/netbird/config.json): Failed to open stream: No such file or directory in /usr/local/opnsense/mvc/app/models/OPNsense/Netbird/Settings.php on line 40 [13-Sep-2025 10:57:27 Europe/Athens] ErrorException: Undefined array key "wt0" in /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php:118 Stack trace: #0 /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php(118): {closure}(2, 'Undefined array...', '/usr/local/opns...', 118) #1 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Dispatcher.php(166): OPNsense\Wireguard\Api\ServiceController->showAction() #2 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(156): OPNsense\Mvc\Dispatcher->dispatch(Object(OPNsense\Mvc\Request), Object(OPNsense\Mvc\Response), Object(OPNsense\Mvc\Session)) #3 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(139): OPNsense\Mvc\Router->performRequest(Object(OPNsense\Mvc\Dispatcher)) #4 /usr/local/opnsense/www/api.php(36): OPNsense\Mvc\Router->routeRequest('/api/wireguard/...', Array) #5 {main} [13-Sep-2025 10:57:38 Europe/Athens] ErrorException: Undefined array key "wt0" in /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php:118 Stack trace: #0 /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php(118): {closure}(2, 'Undefined array...', '/usr/local/opns...', 118) #1 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Dispatcher.php(166): OPNsense\Wireguard\Api\ServiceController->showAction() #2 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(156): OPNsense\Mvc\Dispatcher->dispatch(Object(OPNsense\Mvc\Request), Object(OPNsense\Mvc\Response), Object(OPNsense\Mvc\Session)) #3 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(139): OPNsense\Mvc\Router->performRequest(Object(OPNsense\Mvc\Dispatcher)) #4 /usr/local/opnsense/www/api.php(36): OPNsense\Mvc\Router->routeRequest('/api/wireguard/...', Array) #5 {main}

[fichtner]

CC @bcmmbaga @Gauss23

[bcmmbaga]

Same here :(

PHP error: [13-Sep-2025 10:47:00 Europe/Athens] PHP Warning: file_get_contents(/var/db/netbird/config.json): Failed to open stream: No such file or directory in /usr/local/opnsense/mvc/app/models/OPNsense/Netbird/Settings.php on line 40 [13-Sep-2025 10:57:27 Europe/Athens] ErrorException: Undefined array key "wt0" in /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php:118 Stack trace: #0 /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php(118): {closure}(2, 'Undefined array...', '/usr/local/opns...', 118) #1 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Dispatcher.php(166): OPNsense\Wireguard\Api\ServiceController->showAction() #2 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(156): OPNsense\Mvc\Dispatcher->dispatch(Object(OPNsense\Mvc\Request), Object(OPNsense\Mvc\Response), Object(OPNsense\Mvc\Session)) #3 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(139): OPNsense\Mvc\Router->performRequest(Object(OPNsense\Mvc\Dispatcher)) #4 /usr/local/opnsense/www/api.php(36): OPNsense\Mvc\Router->routeRequest('/api/wireguard/...', Array) #5 {main} [13-Sep-2025 10:57:38 Europe/Athens] ErrorException: Undefined array key "wt0" in /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php:118 Stack trace: #0 /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php(118): {closure}(2, 'Undefined array...', '/usr/local/opns...', 118) #1 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Dispatcher.php(166): OPNsense\Wireguard\Api\ServiceController->showAction() #2 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(156): OPNsense\Mvc\Dispatcher->dispatch(Object(OPNsense\Mvc\Request), Object(OPNsense\Mvc\Response), Object(OPNsense\Mvc\Session)) #3 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(139): OPNsense\Mvc\Router->performRequest(Object(OPNsense\Mvc\Dispatcher)) #4 /usr/local/opnsense/www/api.php(36): OPNsense\Mvc\Router->routeRequest('/api/wireguard/...', Array) #5 {main}

Hi @sopex , are you managing NetBird with WireGuard plugin? Also, how did you install the NetBird plugin and OPNsense version running? I noticed that /usr/local/opnsense/mvc/app/models/OPNsense/Netbird/Settings.php is missing, but it should normally be present after installation.

[bcmmbaga]

Redid from scratch:

• installed plugin "netbird"
• Go to NetBird/Authentication -- Setup Key with 0s is "preconfigured" -- change to real one and "Connect" -- page takes some time, shows checkmark but nothing else
• Go to NetBird/Settings -- Enable toggle, then Apply -- Service Icons on upper right show up, nothing else. Service is stopped/red. -- Starting service manually in the GUI won't work!
• Go back to Authentication -- page takes a bit to load until all elements show up -- pasting the key again and connect again: again the little checkmark, but nothing else. Service state still stopped.

Head to CLI:

root@opn-ce-257:~ # netbird service status
NetBird service status: Stopped

Manually starting the service doesn't work. It's immediatly stopped again.

root@opn-ce-257:~ # netbird service start
NetBird service has been started
root@opn-ce-257:~ # netbird service status
NetBird service status: Stopped

Running the service reconfiguration:

root@opn-ce-257:~ # netbird service status
NetBird service status: Stopped
root@opn-ce-257:~ # netbird service reconfigure
Removing existing service configuration...
Installing service with new configuration...
NetBird service has been reconfigured
root@opn-ce-257:~ # netbird service status
NetBird service status: Stopped
root@opn-ce-257:~ # netbird service start
NetBird service has been started
root@opn-ce-257:~ # netbird service status
NetBird service status: Running

Now that got it into gear and running! If we now head to the GUI and the Authentication section again and hit "Connect" again, we'll see that the service is actually up and running and after a bit the box on top shows "Netbird is online" as the registration now finally worked as the backend service was running to handle it.

So it seems there's either some misconfiguration after the package installation or it needs a "netbird service reconfigure" after the install to make it work? Don't exactly know but that did the trick on our test systems.

Hi @JeGr , Could you please share the /var/log/netbird/client.log file? We need to check what was causing the service to stop

[sopex]

Same here :(

PHP error: [13-Sep-2025 10:47:00 Europe/Athens] PHP Warning: file_get_contents(/var/db/netbird/config.json): Failed to open stream: No such file or directory in /usr/local/opnsense/mvc/app/models/OPNsense/Netbird/Settings.php on line 40 [13-Sep-2025 10:57:27 Europe/Athens] ErrorException: Undefined array key "wt0" in /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php:118 Stack trace: #0 /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php(118): {closure}(2, 'Undefined array...', '/usr/local/opns...', 118) #1 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Dispatcher.php(166): OPNsense\Wireguard\Api\ServiceController->showAction() #2 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(156): OPNsense\Mvc\Dispatcher->dispatch(Object(OPNsense\Mvc\Request), Object(OPNsense\Mvc\Response), Object(OPNsense\Mvc\Session)) #3 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(139): OPNsense\Mvc\Router->performRequest(Object(OPNsense\Mvc\Dispatcher)) #4 /usr/local/opnsense/www/api.php(36): OPNsense\Mvc\Router->routeRequest('/api/wireguard/...', Array) #5 {main} [13-Sep-2025 10:57:38 Europe/Athens] ErrorException: Undefined array key "wt0" in /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php:118 Stack trace: #0 /usr/local/opnsense/mvc/app/controllers/OPNsense/Wireguard/Api/ServiceController.php(118): {closure}(2, 'Undefined array...', '/usr/local/opns...', 118) #1 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Dispatcher.php(166): OPNsense\Wireguard\Api\ServiceController->showAction() #2 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(156): OPNsense\Mvc\Dispatcher->dispatch(Object(OPNsense\Mvc\Request), Object(OPNsense\Mvc\Response), Object(OPNsense\Mvc\Session)) #3 /usr/local/opnsense/mvc/app/library/OPNsense/Mvc/Router.php(139): OPNsense\Mvc\Router->performRequest(Object(OPNsense\Mvc\Dispatcher)) #4 /usr/local/opnsense/www/api.php(36): OPNsense\Mvc\Router->routeRequest('/api/wireguard/...', Array) #5 {main}

Hi @sopex , are you managing NetBird with WireGuard plugin? Also, how did you install the NetBird plugin and OPNsense version running? I noticed that /usr/local/opnsense/mvc/app/models/OPNsense/Netbird/Settings.php is missing, but it should normally be present after installation.

Hi,

I installed netbird normally? From the opnsense gui and the opnsense is also installed the normal way. No other VPNs are configured.

I made it work with the method mentioned above.

Let me know if I can help somehow.

[bcmmbaga]

@sopex Can you share the /var/log/netbird/client.log file and mask any sensitive info?

EDIT: you can send the complete file directly to [email protected]

[sopex]

@bcmmbaga Yes, I emailed you. I am not redacting 2000 lines ;)

[KeenanFalcon]

Hi. Try looking at this first, and replace it with "/service/reconfigure"

https://github.com/opnsense/plugins/blob/d3d38c928c28acec3aeb390ad13a4cefaa6ad444/security/netbird/src/opnsense/mvc/app/views/OPNsense/Netbird/settings.volt#L57

[bcmmbaga]

Hi. Try looking at this first, and replace it with "/service/reconfigure"

plugins/security/netbird/src/opnsense/mvc/app/views/OPNsense/Netbird/settings.volt

Line 57 in d3d38c9

{{ partial('layout_partials/base_apply_button', {'data_endpoint': '/api/netbird/settings/sync', 'data_service_widget': 'netbird'}) }}

This is more of a client issue than an OPNsense plugin. Changing this will break things as these settings need to be propagated to the client configuration.

[KeenanFalcon]

I'm not sure exactly what your mean, but the service will start and get updated when that is changed, as the template will be triggered.

[sopex]

Also, the service fails to restart after an OPNsense restart. You need to manually start it and then manually connect from the authentication page.

This assumes you have followed @JeGr guide, otherwise, the service just never starts.

[bcmmbaga]

Also, the service fails to restart after an OPNsense restart. You need to manually start it and then manually connect from the authentication page.

This assumes you have followed @JeGr guide, otherwise, the service just never starts.

I was able to reproduce this issue and am working on a fix. When you restart and enable the service from the UI, does it start successfully or not?

[sopex]

Also, the service fails to restart after an OPNsense restart. You need to manually start it and then manually connect from the authentication page.

This assumes you have followed @JeGr guide, otherwise, the service just never starts.

I was able to reproduce this issue and am working on a fix. When you restart and enable the service from the UI, does it start successfully or not?

Great news!

Yes, after initially manually starting with the commands above the GUI is fully functional.

But obviously it should auto-start and auto-connect on opnsense boot.

Thanks

[bcmmbaga]

@sopex I did some additional testing on a clean install. By default, the rc configuration file created under /usr/local/etc/rc.d/netbird enables the NetBird service to auto-start on boot.

However, running commands like netbird service reconfigure, netbird service uninstall, or netbird service install will overwrite this default rc configuration with a new one, which prevents NetBird from starting automatically on boot.

Can you confirm with these steps:

1. Remove the NetBird plugin and reinstall it.

2. Open the plugin settings page, tick Enable, and click Apply.

3. Verify that the service is running — you should see the green status icon at the top.

   • If it’s not started, please use the Start button in the GUI (not the netbird service command).

4. Once running, connect your device and then restart OPNsense to confirm that the service starts automatically on boot.

[sopex]

Hello @bcmmbaga

Yes, following the above steps, it started automatically. However, I had to create a new key to connect, as the one the plugin read after the re-installation no longer worked.

I understand that I probably broke that with netbird service reconfigure but I believe you need to focus on what caused the plugin to not be able to start the first time around through the GUI and required a startup by commands.

Thank you

[KeenanFalcon]

Hi @bcmmbaga

It appears you have changed the "/usr/local/etc/rc.d/netbird" and removed all the default settings. But if you look at my suggestion from previous post, you will see that it will call an reconfigure to pluginctl and that triggers the template in "/usr/local//opnsense/service/templates/OPNsense/Netbird/netbird" to update the file in "/etc/rc.conf.d/netbird".

And that small change made the plugin run as expected on my test machine, i could start and stop the plugin, and it also survived an reboot.

[bcmmbaga]

Hi @bcmmbaga

It appears you have changed the "/usr/local/etc/rc.d/netbird" and removed all the default settings. But if you look at my suggestion from previous post, you will see that it will call an reconfigure to pluginctl and that triggers the template in "/usr/local//opnsense/service/templates/OPNsense/Netbird/netbird" to update the file in "/etc/rc.conf.d/netbird".

And that small change made the plugin run as expected on my test machine, i could start and stop the plugin, and it also survived an reboot.

The current problem is that /etc/rc.conf.d/netbird is not updated after a settings update. Replacing /api/netbird/settings/sync with /api/netbird/service/reconfigure would work, but it would break other settings (SSH, routing, client firewall, etc.). The solution is to reload the template with configdRun after syncing the other settings to /var/db/netbird/config.json.

[bcmmbaga]

Hello @bcmmbaga

Yes, following the above steps, it started automatically. However, I had to create a new key to connect, as the one the plugin read after the re-installation no longer worked.

I understand that I probably broke that with netbird service reconfigure but I believe you need to focus on what caused the plugin to not be able to start the first time around through the GUI and required a startup by commands.

Thank you

This was just to confirm the behavior,but the fix for the service not starting the first time is ready

[KeenanFalcon]

I see what you mean, but i have to check tomorrow, because i have another test machine i played with. And there are the config.json, (still placed in the old location "/usr/local/etc/netbird" though), getting updated correct and i use "service/reconfigure" on that one too.

[KeenanFalcon]

I looked at my other machine i played on, and found whats different. i put the call to sync action in the template as recommended by @fichtner as best practice, as i tried to build the plugin with the kea plugin as basis.

This is what my "/usr/local/opnsense/service/templates/OPNsense/Netbird/netbird" looks like.

netbird_enable="YES"
netbird_setup="/usr/local/sbin/pluginctl -c netbird_sync"
{% else %}
netbird_enable="NO"
{% endif %}
netbird_config="/usr/local/etc/netbird/config.json"
netbird_logfile="syslog"
netbird_loglevel="{% if helpers.exists('OPNsense.Netbird.settings.syslog.log_level') %}{{ OPNsense.Netbird.settings.syslog.log_level }}{% else %}info{% endif %}"

[bcmmbaga]

@KeenanFalcon This looks good! One tweak after netbird_sync, we should check if the client is connected. If yes, run netbird down then netbird up so settings apply right away. Otherwise users will need to restart the service manually which is not ideal. Not sure if this can be done within the template.

[KeenanFalcon]

@bcmmbaga yes netbird are connected after applying the changed settings.

But i'm not sure it will be necessary to do an netbird down/up, because if do an "netbird status --yaml" before and and after changing some setting in ui. it reflect the change when i try to enable or disable rosenpass, as this is one of the settings you can view when doing an "netbird status"

And if you look at the system logs for backend, it also shows that netbird actually are being restarted.

[bcmmbaga]

@bcmmbaga yes netbird are connected after applying the changed settings.

But i'm not sure it will be necessary to do an netbird down/up, because if do an "netbird status --yaml" before and and after changing some setting in ui. it reflect the change when i try to enable or disable rosenpass, as this is one of the settings you can view when doing an "netbird status"

And if you look at the system logs for backend, it also shows that netbird actually are being restarted.

That’s correct, no extra restart is needed since the service already restarted. Thanks for help! I’ll go ahead and open the PR.