[GH-ISSUE #5992] Rule Bases Routing (possibly GeoIP) #12620

Open
opened 2026-08-05 02:06:17 -04:00 by saavagebueno · 0 comments
Owner

Originally created by @MahdiBaghbani on GitHub (Apr 25, 2026).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/5992

Hi team,
First, thanks for NetBird -- the P2P mesh architecture and the recent
combined-server single-binary deployment have made self-hosting genuinely
pleasant.
I have been running NetBird alongside sing-box in a multi-region setup,
and I keep hitting a limitation that I think NetBird's architecture is
close to supporting but does not yet expose: rule-based routing for
exit nodes
.

What exists today

NetBird's exit node model works well for the "all traffic goes through
one exit" case. You create a 0.0.0.0/0 route, assign it to a peer
group, and every peer in that group tunnels everything through the
selected exit node. The same model works for subnet routes.
NetBird already has some building blocks that feel related:

  • GeoIP database (GeoLite2-City) downloaded during management
    service init (see #5200).
  • Posture checks with geo_location_check that can allow or deny
    peers based on country/city.
  • Reverse proxy access rules that can block or allow traffic by
    country or CIDR for exposed services
    (see #5709,
    #5430).

What is missing

None of the above building blocks let an operator decide which exit
node a packet should take based on the packet's destination
. Today,
exit node assignment is all-or-nothing per peer group.
Concrete use cases I cannot express:

  1. Geo-aware exit selection -- "Route traffic to US destinations
    through the US exit node, EU destinations through the EU exit node,
    everything else through the default exit node."
  2. Domain-aware exit selection -- "Route *.netflix.com,
    *.youtube.com through a streaming-optimized exit node, corporate
    domains through the office exit node."
  3. Port-aware exit selection -- "Route TCP/443 traffic through the
    low-latency exit node, bulk transfer ports through the cheap
    bandwidth exit node."
  4. Split-tunnel by category -- "Use direct internet for trusted
    SaaS ranges, use exit node for everything else."
    These are all common patterns in proxy platforms like sing-box, Xray,
    and Clash, where a rule-based router sits between the inbound traffic
    and the outbound tunnels.

Prior art: how sing-box does it

sing-box's router is action-based. Rules match on metadata (domain,
IP, GeoIP country code, port, process, network type) and produce an
action -- most commonly route to a specific outbound.
The key primitives are:

  • Rule items: domain, domain_suffix, ip_cidr, geoip,
    geosite, port, protocol, network, etc.
  • Rule-sets: Reusable collections of rules, often backed by GeoIP
    or domain-list databases.
  • Actions: route to an outbound tag, reject, hijack-dns,
    direct, bypass.
    A minimal config snippet looks like this:
{
  "route": {
    "rules": [
      { "geoip": ["us"], "outbound": "exit-us" },
      { "geoip": ["de", "fr"], "outbound": "exit-eu" },
      { "geosite": ["netflix"], "outbound": "exit-streaming" }
    ]
  }
}

NetBird already distributes network maps and routes to peers. I think
the missing piece is a routing rule layer that the management
server can evaluate when building the network map, so each peer
receives a personalized route table rather than a single static exit
node route.
What I am proposing
I am not asking for a full sing-box clone inside NetBird. A practical
first step could be:

  1. Route rules scoped to exit nodes -- A new "Routing Rules"
    section in the management API / dashboard, bound to a distribution
    group or peer group.
  2. Match criteria (prioritized list):
    • domain / domain_suffix
    • ip_cidr
    • geoip country code (leveraging the existing GeoLite2 database)
    • port / port_range
    • protocol (tcp, udp)
  3. Action: route_to a specific exit node peer or exit node
    group, with a fallback to the group's default exit node if no rule
    matches.
  4. Client-side enforcement -- The NetBird client already manages
    routes and firewall rules. It would receive the ordered rule list
    in the network map and install the corresponding routing policy
    (e.g., Linux policy routing with ip rule, nftables marks, or
    routing table selection).

Why this matters

For organizations running exit nodes in multiple regions, the current
group-based model forces them to create many small peer groups and
manually move peers between them to approximate region-aware routing.
That does not scale and is error-prone.
Rule-based routing would let a single peer group receive a smart route
table that adapts to destination geography or category, which is
exactly what operators expect from a modern overlay network.

Questions

  • Is this on the roadmap at all, or is the current group-based model
    the intended long-term design?
  • Would the team be open to a PR that adds a minimal rule-based route
    distribution layer to the management server and client?
  • If yes, is there a preferred design direction (policy-routing at the
    OS level vs. userspace packet classification)?
    If anything here does not match how NetBird's route distribution
    currently works, say so and I can narrow the scope.
    Thanks for considering it.
Originally created by @MahdiBaghbani on GitHub (Apr 25, 2026). Original GitHub issue: https://github.com/netbirdio/netbird/issues/5992 Hi team, First, thanks for NetBird -- the P2P mesh architecture and the recent combined-server single-binary deployment have made self-hosting genuinely pleasant. I have been running NetBird alongside sing-box in a multi-region setup, and I keep hitting a limitation that I think NetBird's architecture is close to supporting but does not yet expose: **rule-based routing for exit nodes**. ### What exists today NetBird's exit node model works well for the "all traffic goes through one exit" case. You create a `0.0.0.0/0` route, assign it to a peer group, and every peer in that group tunnels everything through the selected exit node. The same model works for subnet routes. NetBird already has some building blocks that feel related: - **GeoIP database** (`GeoLite2-City`) downloaded during management service init (see [#5200](https://github.com/netbirdio/netbird/issues/5200)). - **Posture checks** with `geo_location_check` that can allow or deny peers based on country/city. - **Reverse proxy access rules** that can block or allow traffic by country or CIDR for exposed services (see [#5709](https://github.com/netbirdio/netbird/issues/5709), [#5430](https://github.com/netbirdio/netbird/issues/5430)). ### What is missing None of the above building blocks let an **operator decide which exit node a packet should take based on the packet's destination**. Today, exit node assignment is all-or-nothing per peer group. Concrete use cases I cannot express: 1. **Geo-aware exit selection** -- "Route traffic to US destinations through the US exit node, EU destinations through the EU exit node, everything else through the default exit node." 2. **Domain-aware exit selection** -- "Route `*.netflix.com`, `*.youtube.com` through a streaming-optimized exit node, corporate domains through the office exit node." 3. **Port-aware exit selection** -- "Route TCP/443 traffic through the low-latency exit node, bulk transfer ports through the cheap bandwidth exit node." 4. **Split-tunnel by category** -- "Use direct internet for trusted SaaS ranges, use exit node for everything else." These are all common patterns in proxy platforms like sing-box, Xray, and Clash, where a rule-based router sits between the inbound traffic and the outbound tunnels. ### Prior art: how sing-box does it sing-box's router is action-based. Rules match on metadata (domain, IP, GeoIP country code, port, process, network type) and produce an action -- most commonly `route` to a specific outbound. The key primitives are: - **Rule items**: `domain`, `domain_suffix`, `ip_cidr`, `geoip`, `geosite`, `port`, `protocol`, `network`, etc. - **Rule-sets**: Reusable collections of rules, often backed by GeoIP or domain-list databases. - **Actions**: `route` to an outbound tag, `reject`, `hijack-dns`, `direct`, `bypass`. A minimal config snippet looks like this: ```json { "route": { "rules": [ { "geoip": ["us"], "outbound": "exit-us" }, { "geoip": ["de", "fr"], "outbound": "exit-eu" }, { "geosite": ["netflix"], "outbound": "exit-streaming" } ] } } ``` NetBird already distributes network maps and routes to peers. I think the missing piece is a routing rule layer that the management server can evaluate when building the network map, so each peer receives a personalized route table rather than a single static exit node route. What I am proposing I am not asking for a full sing-box clone inside NetBird. A practical first step could be: 1. Route rules scoped to exit nodes -- A new "Routing Rules" section in the management API / dashboard, bound to a distribution group or peer group. 2. Match criteria (prioritized list): - domain / domain_suffix - ip_cidr - geoip country code (leveraging the existing GeoLite2 database) - port / port_range - protocol (tcp, udp) 3. Action: route_to a specific exit node peer or exit node group, with a fallback to the group's default exit node if no rule matches. 4. Client-side enforcement -- The NetBird client already manages routes and firewall rules. It would receive the ordered rule list in the network map and install the corresponding routing policy (e.g., Linux policy routing with ip rule, nftables marks, or routing table selection). ### Why this matters For organizations running exit nodes in multiple regions, the current group-based model forces them to create many small peer groups and manually move peers between them to approximate region-aware routing. That does not scale and is error-prone. Rule-based routing would let a single peer group receive a smart route table that adapts to destination geography or category, which is exactly what operators expect from a modern overlay network. ### Questions - Is this on the roadmap at all, or is the current group-based model the intended long-term design? - Would the team be open to a PR that adds a minimal rule-based route distribution layer to the management server and client? - If yes, is there a preferred design direction (policy-routing at the OS level vs. userspace packet classification)? If anything here does not match how NetBird's route distribution currently works, say so and I can narrow the scope. Thanks for considering it.
saavagebueno added the feature-request label 2026-08-05 02:06:17 -04:00
Sign in to join this conversation.
No Label feature-request
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#12620