[GH-ISSUE #5692] NetBird advertises private IP instead of public IP for gateway behind NAT (Self-hosted) #11651

Open
opened 2026-08-05 01:30:16 -04:00 by saavagebueno · 8 comments
Owner

Originally created by @gretzelandreas-droid on GitHub (Mar 25, 2026).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/5692

Hello NetBird Team,

I am running a self-hosted NetBird setup and encountering an issue with incorrect endpoint advertisement for a gateway behind NAT.

Environment:

  • NetBird self-hosted (management, signal, relay, coturn in Docker)

  • Gateway: Windows Server 2025

  • Firewall: FortiGate

  • Multiple public IPs available on the same firewall

  • Internal networks:

    • NetBird server: 192.168.111.10 (public IP: 37.61.184.6)
    • NetBird gateway: 192.168.177.10 (public IP: 37.61.184.10)

Problem:
The NetBird gateway is being advertised with its private IP address (192.168.177.10) instead of its public IP (37.61.184.10).

As a result:

  • External peers cannot establish a direct connection to the gateway
  • No UDP responses are received on port 51820
  • Connections either fail or fall back to relay

Observed behavior:

  • Outbound traffic from the gateway is correctly NATed to 37.61.184.10
  • However, the endpoint/candidate distributed by NetBird appears to be the internal IP
  • This makes the gateway unreachable from external peers

Additional context:

  • The NetBird server and the gateway are located behind the same firewall (different VLANs)
  • Internal routing between subnets is possible
  • I suspect NetBird/ICE/STUN detects the gateway as "locally reachable" and therefore prefers the private IP instead of the public one

Questions:

  1. Is there a way to force NetBird to advertise the public IP for a gateway?
  2. Is there a configuration option to control ICE candidate preference (public vs private)?
  3. Could this behavior be caused by running server and gateway behind the same firewall/public IP range?
  4. Are there recommended best practices for this topology (self-hosted + multiple public IPs + same firewall)?

Goal:
Ensure that the gateway is reachable via its public IP (37.61.184.10) so that direct connections (UDP 51820) can be established.

If needed, I can provide logs (netbird status -d, management logs, coturn logs).

Thanks in advance!

Originally created by @gretzelandreas-droid on GitHub (Mar 25, 2026). Original GitHub issue: https://github.com/netbirdio/netbird/issues/5692 Hello NetBird Team, I am running a self-hosted NetBird setup and encountering an issue with incorrect endpoint advertisement for a gateway behind NAT. **Environment:** * NetBird self-hosted (management, signal, relay, coturn in Docker) * Gateway: Windows Server 2025 * Firewall: FortiGate * Multiple public IPs available on the same firewall * Internal networks: * NetBird server: 192.168.111.10 (public IP: 37.61.184.6) * NetBird gateway: 192.168.177.10 (public IP: 37.61.184.10) **Problem:** The NetBird gateway is being advertised with its **private IP address (192.168.177.10)** instead of its **public IP (37.61.184.10)**. As a result: * External peers cannot establish a direct connection to the gateway * No UDP responses are received on port 51820 * Connections either fail or fall back to relay **Observed behavior:** * Outbound traffic from the gateway is correctly NATed to 37.61.184.10 * However, the endpoint/candidate distributed by NetBird appears to be the internal IP * This makes the gateway unreachable from external peers **Additional context:** * The NetBird server and the gateway are located behind the same firewall (different VLANs) * Internal routing between subnets is possible * I suspect NetBird/ICE/STUN detects the gateway as "locally reachable" and therefore prefers the private IP instead of the public one **Questions:** 1. Is there a way to force NetBird to advertise the public IP for a gateway? 2. Is there a configuration option to control ICE candidate preference (public vs private)? 3. Could this behavior be caused by running server and gateway behind the same firewall/public IP range? 4. Are there recommended best practices for this topology (self-hosted + multiple public IPs + same firewall)? **Goal:** Ensure that the gateway is reachable via its public IP (37.61.184.10) so that direct connections (UDP 51820) can be established. If needed, I can provide logs (`netbird status -d`, management logs, coturn logs). Thanks in advance!
Author
Owner

@lixmal commented on GitHub (Mar 25, 2026):

Please stick to the issue template.

What is a "NetBird gateway"?
Maybe you're looking for the --external-ip-map flag?

<!-- gh-comment-id:4126488260 --> @lixmal commented on GitHub (Mar 25, 2026): Please stick to the issue template. What is a "NetBird gateway"? Maybe you're looking for the [--external-ip-map](https://docs.netbird.io/get-started/cli#flags) flag?
Author
Owner

@gretzelandreas-droid commented on GitHub (Mar 25, 2026):

Hello, sorry.
In my understanding, a “NetBird gateway” is the peer that acts as a routing endpoint for other peers.
It is responsible for advertising and providing access to one or more internal networks, allowing remote peers to reach those networks through it.

In other words, the gateway is the peer that other clients use as their entry point to access internal subnets (e.g., 192.168.10.0/24) via NetBird.
And your hint with "Maybe you're looking for the --external-ip-map flag?" was the solution i was searching for.
My Netbird Server Gui (Screenshot) still shows the internal ip 192.168.177.10, but my peers now connecting in P2P and not in relayed.

Thanks a lot!!

Image
<!-- gh-comment-id:4128013729 --> @gretzelandreas-droid commented on GitHub (Mar 25, 2026): Hello, sorry. In my understanding, a “NetBird gateway” is the peer that acts as a routing endpoint for other peers. It is responsible for advertising and providing access to one or more internal networks, allowing remote peers to reach those networks through it. In other words, the gateway is the peer that other clients use as their entry point to access internal subnets (e.g., 192.168.10.0/24) via NetBird. And your hint with "Maybe you're looking for the [--external-ip-map](https://docs.netbird.io/get-started/cli#flags) flag?" was the solution i was searching for. My Netbird Server Gui (Screenshot) still shows the internal ip 192.168.177.10, but my peers now connecting in P2P and not in relayed. Thanks a lot!! <img width="727" height="730" alt="Image" src="https://github.com/user-attachments/assets/149be303-1982-41c5-b60b-1583783c5d65" />
Author
Owner

@wizdude commented on GitHub (Mar 26, 2026):

i had this exact same problem because my routing-peer (netbird) and netbird management docker stack are both internally hosted on the same network. the issue here is that netbird talks to the STUN server and thus the "external" ip address is discovered as the internal address.

the solution is to configure the external IP manually on the netbird server.

assuming you have netbird installed on a linux box, first check and confirm your external IP address using:
curl ident.me

confirm this matches the external WAN IP you expect. in my case I had multiple WAN IP addresses and needed to configure an outbound NAT rule on my firewall so that the netbird server was speaking out on the same IP i had configured for it to come in on.

then you configure the IP addresses manually via:

netbird down
netbird up --external-ip-map <YOUR_PUBLIC_WAN_IP>/<YOUR_INTERNAL_IP>

eg:
netbird up --external-ip-map 203.0.123.55/192.168.177.10

if you then reconnect with an external peer you should see that you have a p2p connection instead of a relay connection.

netbird automatically writes this configuration back to it's json file, so it will automatically use these settings next time it is launched.

<!-- gh-comment-id:4132382624 --> @wizdude commented on GitHub (Mar 26, 2026): i had this exact same problem because my routing-peer (netbird) and netbird management docker stack are both internally hosted on the same network. the issue here is that netbird talks to the STUN server and thus the "external" ip address is discovered as the internal address. the solution is to configure the external IP manually on the netbird server. assuming you have netbird installed on a linux box, first check and confirm your external IP address using: curl ident.me confirm this matches the external WAN IP you expect. in my case I had multiple WAN IP addresses and needed to configure an outbound NAT rule on my firewall so that the netbird server was speaking out on the same IP i had configured for it to come in on. then you configure the IP addresses manually via: netbird down netbird up --external-ip-map <YOUR_PUBLIC_WAN_IP>/<YOUR_INTERNAL_IP> eg: netbird up --external-ip-map 203.0.123.55/192.168.177.10 if you then reconnect with an external peer you should see that you have a p2p connection instead of a relay connection. netbird automatically writes this configuration back to it's json file, so it will automatically use these settings next time it is launched.
Author
Owner

@gretzelandreas-droid commented on GitHub (Mar 26, 2026):

Hello Wizdude,
Thank you so much for your reply. Yes, that did indeed help. But what I still find strange is that the peer is displayed with the internal IP address in the Netbird Management GUI. Is this behavior normal? What does it look like for you? It's displayed exactly as in my screenshot above.

By "the solution is to configure the external IP manually on the Netbird server," do you mean the peer or the actual Netbird server (Sign, STUN, Management)?

<!-- gh-comment-id:4136015075 --> @gretzelandreas-droid commented on GitHub (Mar 26, 2026): Hello Wizdude, Thank you so much for your reply. Yes, that did indeed help. But what I still find strange is that the peer is displayed with the internal IP address in the Netbird Management GUI. Is this behavior normal? What does it look like for you? It's displayed exactly as in my screenshot above. By "the solution is to configure the external IP manually on the Netbird server," do you mean the peer or the actual Netbird server (Sign, STUN, Management)?
Author
Owner

@ramphex commented on GitHub (Mar 27, 2026):

I have the same issue and the --external-ip-map does work when set on each client manually, but that is an awfully tedious way to do it as some devices do change public IPs. There has to be a better solution to do this.

<!-- gh-comment-id:4145990996 --> @ramphex commented on GitHub (Mar 27, 2026): I have the same issue and the --external-ip-map does work when set on each client manually, but that is an awfully tedious way to do it as some devices do change public IPs. There has to be a better solution to do this.
Author
Owner

@ramphex commented on GitHub (Mar 28, 2026):

I resolved the STUN/P2P issue with a more permanent fix than force writing the external IP (which could change) into the client config. These rules in OpnSense make the STUN server return the correct WAN in order for P2P to work. This does not solve the dashboard Public IP for local clients issue though.

Image
<!-- gh-comment-id:4149113936 --> @ramphex commented on GitHub (Mar 28, 2026): I resolved the STUN/P2P issue with a more permanent fix than force writing the external IP (which could change) into the client config. These rules in OpnSense make the STUN server return the correct WAN in order for P2P to work. This does not solve the dashboard Public IP for local clients issue though. <img width="1829" height="508" alt="Image" src="https://github.com/user-attachments/assets/ab23cab8-fc3c-40fc-a931-0f1e8494bdeb" />
Author
Owner

@wizdude commented on GitHub (Mar 29, 2026):

By "the solution is to configure the external IP manually on the Netbird server," do you mean the peer or the actual Netbird server (Sign, STUN, Management)?

the netbird proxy. not the management server.

the naming is confusing - for clarity i think it's best to say where you run the management stack should be referred to as the "netbird management server", not just "netbird server", since the "netbird proxy" is actually the "netbird server".

<!-- gh-comment-id:4149722330 --> @wizdude commented on GitHub (Mar 29, 2026): > By "the solution is to configure the external IP manually on the Netbird server," do you mean the peer or the actual Netbird server (Sign, STUN, Management)? the netbird proxy. not the management server. the naming is confusing - for clarity i think it's best to say where you run the management stack should be referred to as the "netbird management server", not just "netbird server", since the "netbird proxy" is actually the "netbird server".
Author
Owner

@wizdude commented on GitHub (Mar 29, 2026):

I have the same issue and the --external-ip-map does work when set on each client manually, but that is an awfully tedious way to do it as some devices do change public IPs. There has to be a better solution to do this.

you only need to do this on the netbird proxy and when it's located on the same internal network as your netbird management server. i only did this in one place. i don't need to change the configuration of any external peers, because they are able to determine their WAN IP's with no issues.

<!-- gh-comment-id:4149724606 --> @wizdude commented on GitHub (Mar 29, 2026): > I have the same issue and the --external-ip-map does work when set on each client manually, but that is an awfully tedious way to do it as some devices do change public IPs. There has to be a better solution to do this. you only need to do this on the netbird proxy and when it's located on the same internal network as your netbird management server. i only did this in one place. i don't need to change the configuration of any external peers, because they are able to determine their WAN IP's with no issues.
Sign in to join this conversation.
No Label
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#11651