SVI/netbird
1
0
Fork 0
mirror of https://github.com/netbirdio/netbird.git synced 2026-07-01 03:33:13 -04:00
Code Issues 3.0k Packages Projects Releases 10 Wiki Activity

Inconsistent Docker usage commands #2361

New Issue
Open
opened 2025-11-20 07:08:32 -05:00 by saavagebueno · 5 comments
saavagebueno commented 2025-11-20 07:08:32 -05:00
Owner
Copy Link

Originally created by @mitchplze on GitHub (Oct 10, 2025).

Edited for clarity

Hello,

The NetBird management UI seems to provide convenient docker run commands for copy/pasting that are contrary to the current NetBird documentation and other discussions.

Image

Currently in NetBird 'create setup key' wizard ❌

The copy/paste widget provides:

docker run --rm -d \
 --cap-add=NET_ADMIN \
 -e NB_SETUP_KEY=XXXXXX \
 -v netbird-client:/var/lib/netbird \
 -e NB_MANAGEMENT_URL=https://net.mynetwork.com \
 netbirdio/netbird:latest

Currently in NetBird 'add peer' wizard ❌

The copy/paste widget provides:

docker run --rm -d \
 --cap-add=NET_ADMIN \
 -e NB_SETUP_KEY=SETUP_KEY \
 -v netbird-client:/var/lib/netbird \
 -e NB_MANAGEMENT_URL=https://net.mynetwork.com \
 netbirdio/netbird:latest

Currently in NetBird documentation

From: https://docs.netbird.io/how-to/installation/docker

NetBird makes use of eBPF and raw sockets, therefore to guarantee the client software functionality, we recommend adding the flags --cap-add=SYS_ADMIN and --cap-add=SYS_RESOURCE for docker clients. The experience may vary depending on the docker daemon, operating system, or kernel version.

The official example given is:

docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/var/lib/netbird netbirdio/netbird:latest

Further, the Docker example linked also references the above usage.

Confusion

The wizards are:

  • not adding the SYS_ADMIN capability
  • not adding the SYS_RESOURCE capability
  • not adding network_mode: host capability
  • not adding privileged: true capability
  • maybe: not adding [NB_USE_NETSTACK_MODE](https://github.com/netbirdio/docs/issues/449) capability

The copy/paste value provided by the two wizards are what I have used 95% of the time to deploy a node, and only just realized the official docs are different.

This is undoubtedly possibly causing a degraded experience with my nodes, and I'm sure others have ran into this too.

Less importantly, the wizards are:

  • not setting the hostname, so a random name ends up joining your network (this is possibly unavoidable)
  • not naming the container, so it cannot be easily found in the future (like with docker rm netbird -f)

IMO there should be consistent Docker usage that is officially documented, to offer the best experience.

I'm super happy to help out if possible!

Thank you.

Originally created by @mitchplze on GitHub (Oct 10, 2025). _Edited for clarity_ Hello, The NetBird management UI seems to provide convenient `docker run` commands for copy/pasting that are contrary to the current NetBird documentation and other [discussions](https://github.com/netbirdio/netbird/issues/1139#issuecomment-1716014501). <img width="330" height="330" alt="Image" src="https://github.com/user-attachments/assets/2e39e7b9-7be6-44af-88cb-ae41c8ffa175" /> ## Currently in NetBird 'create setup key' wizard ❌ The copy/paste widget provides: ```bash docker run --rm -d \ --cap-add=NET_ADMIN \ -e NB_SETUP_KEY=XXXXXX \ -v netbird-client:/var/lib/netbird \ -e NB_MANAGEMENT_URL=https://net.mynetwork.com \ netbirdio/netbird:latest ``` ## Currently in NetBird 'add peer' wizard ❌ The copy/paste widget provides: ```bash docker run --rm -d \ --cap-add=NET_ADMIN \ -e NB_SETUP_KEY=SETUP_KEY \ -v netbird-client:/var/lib/netbird \ -e NB_MANAGEMENT_URL=https://net.mynetwork.com \ netbirdio/netbird:latest ``` ## Currently in NetBird documentation From: https://docs.netbird.io/how-to/installation/docker > NetBird makes use of eBPF and raw sockets, therefore to guarantee the client software functionality, we recommend adding the flags --cap-add=SYS_ADMIN and --cap-add=SYS_RESOURCE for docker clients. The experience may vary depending on the docker daemon, operating system, or kernel version. The official example given is: `docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/var/lib/netbird netbirdio/netbird:latest` Further, the [Docker example linked](https://docs.netbird.io/how-to/examples#net-bird-client-in-docker) also references the above usage. ## Confusion The wizards are: - not adding the `SYS_ADMIN` capability - not adding the `SYS_RESOURCE` capability - not adding `network_mode: host` capability - not adding `privileged: true` capability - **maybe:** not adding `[NB_USE_NETSTACK_MODE]`(https://github.com/netbirdio/docs/issues/449) capability The copy/paste value provided by the two wizards are what I have used 95% of the time to deploy a node, and only just realized the official docs are different. This is ~undoubtedly~ possibly causing a degraded experience with my nodes, and I'm sure others have ran into this too. Less importantly, the wizards are: - not setting the hostname, so a random name ends up joining your network (this is possibly unavoidable) - not naming the container, so it cannot be easily found in the future (like with `docker rm netbird -f`) IMO there should be consistent Docker usage that is officially documented, to offer the best experience. I'm super happy to help out if possible! Thank you.
saavagebueno added the triage-needed label 2025-11-20 07:08:32 -05:00
saavagebueno commented 2025-11-20 07:08:33 -05:00
Author
Owner
Copy Link

@mitchplze commented on GitHub (Oct 10, 2025):

I also just noticed that network_mode: host is provided in the official Compose, but that mode doesn't appear in any other example (docker run --net host).

Can we get some clarification on whether network host mode is needed or not?

@mitchplze commented on GitHub (Oct 10, 2025): I also just noticed that `network_mode: host` is provided in the [official Compose](https://docs.netbird.io/how-to/installation/docker#docker-compose), but that mode doesn't appear in any other example (`docker run --net host`). Can we get some clarification on whether network host mode is needed or not?
saavagebueno commented 2025-11-20 07:08:33 -05:00
Author
Owner
Copy Link

@PowershellScripter commented on GitHub (Oct 10, 2025):

@mitchplze I have netbird setup in my linux docker container host behind traefik reverse proxy and it runs directly on traefik's network. Host mode network is not required, except for coturn which I believe does need to stay as network_mode: host

@PowershellScripter commented on GitHub (Oct 10, 2025): @mitchplze I have netbird setup in my linux docker container host behind traefik reverse proxy and it runs directly on traefik's network. Host mode network is not required, except for coturn which I believe does need to stay as network_mode: host
saavagebueno commented 2025-11-20 07:08:33 -05:00
Author
Owner
Copy Link

@mitchplze commented on GitHub (Oct 10, 2025):

Thanks. I don't think its needed either, but would be nice to confirm.

There is actually yet a third different example given on the same page, further down.

Very confused.

@mitchplze commented on GitHub (Oct 10, 2025): Thanks. I don't think its needed either, but would be nice to confirm. There is actually yet a [third](https://docs.netbird.io/how-to/installation/docker#running-net-bird-with-a-setup-key) different example given on the same page, further down. Very confused.
saavagebueno commented 2025-11-20 07:08:33 -05:00
Author
Owner
Copy Link

@PowershellScripter commented on GitHub (Oct 10, 2025):

@mitchplze you know what, I just relaized I was talking about the docker server install, not the client. I believe the client is needed if you want to use that docker client to expose the network the client is on. Otherwise, it can only expose the network inside the container. Network_mode: host exposes the local network to the client instead of the containerized network.

@PowershellScripter commented on GitHub (Oct 10, 2025): @mitchplze you know what, I just relaized I was talking about the docker server install, not the client. I believe the client is needed if you want to use that docker client to expose the network the client is on. Otherwise, it can only expose the network inside the container. Network_mode: host exposes the local network to the client instead of the containerized network.
saavagebueno commented 2025-11-20 07:08:34 -05:00
Author
Owner
Copy Link

@mitchplze commented on GitHub (Oct 21, 2025):

I hate to be that guy and ask if there's any update - but is there? The main documentation that users see for NetBird, currently has multiple inconsistent ways of deploying on Docker, and virtually no details or information on any of the flags.

@mitchplze commented on GitHub (Oct 21, 2025): I hate to be that guy and ask if there's any update - but is there? The main documentation that users see for NetBird, currently has _multiple inconsistent ways of deploying on Docker,_ and virtually no details or information on any of the flags.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
2021 Q4
2022 Q1
2022 Q1
accessibility
acl
agent
agent
Android
Android
api
authentik
automation
azure
battery-usage
bug
cache
client
client-ui
cloud
cloud-only
cloudflare
community
compatibility
config-idp
config-issue
connection
contribution
coturn
cross-vpn
dashboard
data-usage
distribution
dns
docker
documentation
duplicate
enhancement
enhancement
event-stream
feature-request
freebsd
getting-started
go
good first issue
gui
help wanted
home-assistant
idp
inconsistency
integration
integrations
ios
ipv6
jwt
k8s
keycloak
linux
login
macos
management-service
missing-docs
mobile
moved-internal
needs-review
netbird-ui
networking
new-platform
nginx
notification
okta
openwrt
packaging
peer-management
peer-management
peer-management
performance
postgres
posture-checks
psk
pull-request
Mirrored from GitHub Pull Request
 question
refactor
relay
release
rfc
routes
security
security-related
self-hosting
server
signal
sleep-issue
ssh
ssl
status
store
synology
system-compatibility-issue
test-suite
third-party-integration
triage
triage-needed
troubleshooting
UX
waiting-feedback
windows
wontfix
zitadel
No Label triage-needed
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
saavagebueno
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: SVI/netbird#2361
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?