diff --git a/src/pages/help/troubleshooting-client.mdx b/src/pages/help/troubleshooting-client.mdx index 4c998c16..3f5b2b92 100644 --- a/src/pages/help/troubleshooting-client.mdx +++ b/src/pages/help/troubleshooting-client.mdx @@ -576,7 +576,7 @@ Testing the functionality in practice involves: #### Are Netbird's network routing resources configured? -For Netbird network routing resources configurations you can use either (new) _Networks_ or (old) _Network Routes_. +For Netbird network routing resources configurations you can use either (new) _Networks_ or (old) _Routes_. A Network `net-a` should have at minimum: diff --git a/src/pages/manage/access-control/manage-network-access.mdx b/src/pages/manage/access-control/manage-network-access.mdx index c7f5f656..de6fc785 100644 --- a/src/pages/manage/access-control/manage-network-access.mdx +++ b/src/pages/manage/access-control/manage-network-access.mdx @@ -166,7 +166,7 @@ Navigate to `Access Control` > `Groups` and then click on any group name to view - **Peers**: Manage which peers are assigned to this group - **Policies**: See policies where this group is used as a source or destination - **Network Resources**: View associated resources from networks -- **Network Routes**: See network routes using this group (either part of the distribution, access control, or routing peer group) +- **Routes**: See routes using this group (either part of the distribution, access control, or routing peer group) - **Nameservers**: View nameservers using this group as a distribution group - **Setup Keys**: See setup keys with this group as an auto-assigned group diff --git a/src/pages/manage/access-control/posture-checks/connecting-from-the-office.mdx b/src/pages/manage/access-control/posture-checks/connecting-from-the-office.mdx index f3eee9df..34bb170a 100644 --- a/src/pages/manage/access-control/posture-checks/connecting-from-the-office.mdx +++ b/src/pages/manage/access-control/posture-checks/connecting-from-the-office.mdx @@ -1,5 +1,5 @@ # Connecting from the office -A typical scenario administrators have is accessing their office networks remotely. With [Network routes](https://docs.netbird.io/manage/network-routes), NetBird makes this easy. Still, administrators often want to avoid routing their users’ traffic via NetBird when they are in the office. +A typical scenario administrators have is accessing their office networks remotely. With [Routes](https://docs.netbird.io/manage/network-routes), NetBird makes this easy. Still, administrators often want to avoid routing their users’ traffic via NetBird when they are in the office. To solve this, administrators can leverage the power of [Posture Checks](https://docs.netbird.io/manage/access-control/posture-checks) and create policies that allow connection to the routing peers only if they are outside the office by using a [Peer Network Range](/manage/access-control/posture-checks#peer-network-range) posture check with a block action. diff --git a/src/pages/manage/dns/dns-aliases-for-routed-networks.mdx b/src/pages/manage/dns/dns-aliases-for-routed-networks.mdx index cf5e32ba..3b8152ae 100644 --- a/src/pages/manage/dns/dns-aliases-for-routed-networks.mdx +++ b/src/pages/manage/dns/dns-aliases-for-routed-networks.mdx @@ -144,7 +144,7 @@ Next, add a routing peer that has access to your private network. Add Routing Peer -After completing the wizard, your network routing is configured, and the DNS names you created will now work seamlessly with the network routes. +After completing the wizard, your network routing is configured, and the DNS names you created will now work seamlessly with the routes. You can view your fully configured network in the Networks dashboard: @@ -156,7 +156,7 @@ With the DNS zone and records configured, your developers can now access the ser #### Verify Network Routes -First, confirm that peers in the `dev` group have received the network routes for `wiki.netbird.internal` and `postgres.netbird.internal`. +First, confirm that peers in the `dev` group have received the routes for `wiki.netbird.internal` and `postgres.netbird.internal`. On a peer device in the `dev` group, run: diff --git a/src/pages/manage/network-routes/access-control.mdx b/src/pages/manage/network-routes/access-control.mdx index 20afeea5..b2a51380 100644 --- a/src/pages/manage/network-routes/access-control.mdx +++ b/src/pages/manage/network-routes/access-control.mdx @@ -4,7 +4,7 @@ This feature requires NetBird version 0.30.0 or later. -By default, network routes allow unrestricted access when no access control groups are assigned. When you assign access control groups to a route, only traffic that matches the defined policies can access the routed network. +By default, Routes allow unrestricted access when no access control groups are assigned. When you assign access control groups to a route, only traffic that matches the defined policies can access the routed network. For the mental model — see [How Routing Peers Work — Access control behavior](/manage/networks/how-routing-peers-work#access-control-behavior). diff --git a/src/pages/manage/network-routes/advanced-configuration.mdx b/src/pages/manage/network-routes/advanced-configuration.mdx index 508a76e4..829d6495 100644 --- a/src/pages/manage/network-routes/advanced-configuration.mdx +++ b/src/pages/manage/network-routes/advanced-configuration.mdx @@ -2,9 +2,9 @@ import { Warning } from '@/components/mdx' # Advanced Configuration -This page covers masquerade trade-offs, a Networks-vs-Network-Routes comparison, and troubleshooting. +This page covers masquerade trade-offs, a Networks-vs-Routes comparison, and troubleshooting. -For the basics — masquerade behavior, ACL Groups, HA — see [Network Routes Concepts](/manage/network-routes#key-concepts). For ACL Group setup, see [Access Control](/manage/network-routes/access-control). For Site-to-Site walkthroughs, see [Site-to-Site](/manage/network-routes/use-cases/site-to-site). +For the basics — masquerade behavior, ACL Groups, HA — see [Routes Concepts](/manage/network-routes#key-concepts). For ACL Group setup, see [Access Control](/manage/network-routes/access-control). For Site-to-Site walkthroughs, see [Site-to-Site](/manage/network-routes/use-cases/site-to-site). ## Masquerade: when to enable or disable @@ -23,7 +23,7 @@ For the basics — masquerade behavior, ACL Groups, HA — see [Network Routes C See [Masquerade](/manage/networks/masquerade) for persistent return-route configuration on the destination host. -ACL Groups on **Network Routes** (this page) match against peer NetBird IPs only, which limits source-IP-preserving access control on this path. For masquerade-off deployments with policy-layer ACLs, use the newer **Networks** path — see [Masquerade](/manage/networks/masquerade). +ACL Groups on **Routes** (this page) match against peer NetBird IPs only, which limits source-IP-preserving access control on this path. For masquerade-off deployments with policy-layer ACLs, use the newer **Networks** path — see [Masquerade](/manage/networks/masquerade). ### Choosing the right approach @@ -31,15 +31,15 @@ ACL Groups on **Network Routes** (this page) match against peer NetBird IPs only | Requirement | Approach | |---|---| | Simple remote access | [Networks](/manage/networks) with masquerade | -| Site-to-Site with access control | Network Routes with masquerade + ACL Groups | -| Audit trail needs source IPs | Network Routes without masquerade + OS firewall on the remote network | +| Site-to-Site with access control | Routes with masquerade + ACL Groups | +| Audit trail needs source IPs | Routes without masquerade + OS firewall on the remote network | | Compliance requirements | Depends on the specific framework | -## Networks vs Network Routes +## Networks vs Routes -| Aspect | Networks | Network Routes | +| Aspect | Networks | Routes | |--------|----------|----------------| -| Supported scenarios | VPN-to-Site only | All (VPN-to-Site, Site-to-VPN, Site-to-Site) | +| Supported scenarios | All (VPN-to-Site, Site-to-VPN, Site-to-Site) | All (VPN-to-Site, Site-to-VPN, Site-to-Site) | | Access control | Per-resource policies | Per-route with ACL Groups | | Masquerade | Always enabled | Configurable | | Setup complexity | Simpler | More manual configuration | @@ -100,7 +100,7 @@ ACL Groups on **Network Routes** (this page) match against peer NetBird IPs only 3. Incorrect subnet configuration **Solution:** -- Review all Network Routes for overlaps — see [Overlapping Routes](/manage/network-routes/overlapping-routes) +- Review all Routes for overlaps — see [Overlapping Routes](/manage/network-routes/overlapping-routes) - Use more specific routes where needed - Verify subnet CIDR notation is correct diff --git a/src/pages/manage/network-routes/index.mdx b/src/pages/manage/network-routes/index.mdx index bd8fb927..4e24639c 100644 --- a/src/pages/manage/network-routes/index.mdx +++ b/src/pages/manage/network-routes/index.mdx @@ -7,18 +7,18 @@ import { Tiles } from '@/components/Tiles' Routes are deprecated. Every use case except [exit nodes](/manage/network-routes/use-cases/exit-nodes) has moved to [Networks](/manage/networks). Use Networks for all new configurations. For a side-by-side comparison of the two models, see [How Routing Peers Work](/manage/networks/how-routing-peers-work). -Network Routes let you route traffic from NetBird peers to private networks without installing the NetBird client on every device. A routing peer forwards packets between your NetBird mesh network and your internal networks (LANs, VPCs, data centers). +Routes let you route traffic from NetBird peers to private networks without installing the NetBird client on every device. A routing peer forwards packets between your NetBird mesh network and your internal networks (LANs, VPCs, data centers).

- Network Routes diagram + Routes diagram

-Network Routes require NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later. +Routes require NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later. -By default, Network Routes bypass Access Control rules. Traffic flows freely to routed networks unless you [configure access control explicitly](/manage/network-routes/access-control). See [Network Routes caveats](#network-routes-caveats) for details. +By default, Routes bypass Access Control rules. Traffic flows freely to routed networks unless you [configure access control explicitly](/manage/network-routes/access-control). See [Routes caveats](#network-routes-caveats) for details. ## Key Concepts @@ -202,7 +202,7 @@ This requires configuring your external network router with a return route to yo ## Network Routes Caveats -Unless [configured explicitly](/manage/network-routes/access-control), Network Routes ignore Access Control rules. This can lead to unexpected access. +Unless [configured explicitly](/manage/network-routes/access-control), Routes ignore Access Control rules. This can lead to unexpected access. This limitation led to the creation of [Networks](/manage/networks), which uses mandatory Groups for both access control and advertisement. Clients do not see a resource until they have access to its Group. @@ -220,7 +220,7 @@ After creating an Access Policy granting only `ICMP` access from `Group A` to `G ICMP policy from group A to R

-You might expect only ICMP traffic to work. However, all traffic to the routed network succeeds because Network Routes only require connectivity to the Routing Peer to activate: +You might expect only ICMP traffic to work. However, all traffic to the routed network succeeds because Routes only require connectivity to the Routing Peer to activate: ```shell root@brys-vm-nbt-ubuntu-01:~# netbird networks ls @@ -242,7 +242,7 @@ OK ### Mixing Network Routes and Networks -When using both Network Routes and Networks with the same Routing Peer, permissions can overflow unexpectedly. +When using both Routes and Networks with the same Routing Peer, permissions can overflow unexpectedly. In this example, a Network Resource for `*.nb.test` uses ACL group `manual:srvs`: @@ -310,7 +310,7 @@ The Routing Peer belongs to both routing groups: The Network Route grants unrestricted access to the network range, bypassing the HTTP-only restriction on the Network Resource. -To prevent permission overflow, use dedicated Routing Peers for Network Routes and never use them for Networks. This separation is achievable but easy to overlook during configuration. +To prevent permission overflow, use dedicated Routing Peers for Routes and never use them for Networks. This separation is achievable but easy to overlook during configuration. Route selection requires NetBird client version 0.27.4 or later. diff --git a/src/pages/manage/network-routes/use-cases/site-to-site.mdx b/src/pages/manage/network-routes/use-cases/site-to-site.mdx index bdee98c2..2e2fbc1e 100644 --- a/src/pages/manage/network-routes/use-cases/site-to-site.mdx +++ b/src/pages/manage/network-routes/use-cases/site-to-site.mdx @@ -1,9 +1,15 @@ -import { Note } from '@/components/mdx' +import { Note, Warning } from '@/components/mdx' # Site-to-Site Site-to-Site connects two networks through routing peers at each end. Neither end-device needs NetBird installed — the routing peers forward traffic across the NetBird tunnel. + +Routes are deprecated. For new site-to-site setups, use [Networks Site-to-Site](/manage/networks/use-cases/site-to-site) instead — it has per-Resource access control and is the actively developed system. + +Routes remains the only option when you need site-to-site without any Policy gating traffic — the legacy "wide open" mode with empty Access Control Groups. Networks requires at least one Policy per Resource and has no equivalent. + + ## Architecture
@@ -16,10 +22,6 @@ Site A device ──► Routing Peer ──► NetBird Tunnel ──► Routing
-For most site-to-site setups, prefer [Networks Site-to-Site](/manage/networks/use-cases/site-to-site) — it has per-Resource access control and is the actively developed system. - -Network Routes is still the right choice when you need site-to-site without any Policy gating traffic — the legacy "wide open" mode with empty Access Control Groups. Networks requires at least one Policy per Resource and has no equivalent. - For the reverse — clientless devices at a site initiating connections to NetBird peers — see [Site-to-VPN](/manage/networks/use-cases/site-to-vpn). @@ -92,16 +94,69 @@ Destination: 10.1.0.0/24 # remote network Gateway: 10.0.0.50 # local routing peer ``` -**Per-device fallback** — Linux: +**Per-device fallback** — if you can't touch the router, add the route on each device instead. + +**Windows** (PowerShell as Administrator) — `-p` makes it persistent: + +```powershell +route -p add 10.1.0.0 mask 255.255.255.0 10.0.0.50 +``` + +**Linux** — first test the route (this form disappears on the next reboot): ```bash sudo ip route add 10.1.0.0/24 via 10.0.0.50 ``` -Windows (PowerShell, persistent): +Once a peer at the other site is reachable, make it permanent. The method depends on which network manager the device uses — check with: -```powershell -route -p add 10.1.0.0 mask 255.255.255.0 10.0.0.50 +```bash +ls /etc/netplan/ +``` + +Follow **only one** of the two methods below — the one that matches what `ls` showed. They're alternatives, not consecutive steps: if you see `.yaml` files use Netplan (most Ubuntu hosts); if the directory is empty or missing use systemd-networkd (Debian, minimal installs). Don't mix them — on Netplan hosts, systemd-networkd config you add by hand is silently ignored. + +Both methods need your LAN interface name — find it with `ip -br addr` (look for the connection carrying the device's local IP, e.g. `eth0` or `ens18`). Substitute it wherever the steps below show ``. + +**Option A — Netplan** (you saw `.yaml` files) — open the file `ls` showed (e.g. `50-cloud-init.yaml`) in a text editor. `nano` is the simplest; this command opens the file in it (run `sudo apt install nano` first if it's missing): + +```bash +sudo nano /etc/netplan/50-cloud-init.yaml +``` + +Find your interface under `ethernets:` and add the route. If a `routes:` list is already there, add the `- to:` lines to it — don't create a second `routes:` key: + +```yaml +network: + version: 2 + ethernets: + : # your interface, from ip -br addr + dhcp4: true # whatever was already here + routes: # add this block (or reuse an existing routes: list) + - to: 10.1.0.0/24 # remote network + via: 10.0.0.50 # local routing peer +``` + +Save and exit. In nano: press `Ctrl+O` then `Enter` to write the file, then `Ctrl+X` to quit. Then apply the change: + +```bash +sudo netplan apply +``` + + +Recent Netplan needs `0600` permissions on files under `/etc/netplan/`. Run `sudo chmod 0600 /etc/netplan/*.yaml` if `netplan apply` warns. + + +**Option B — systemd-networkd** (the `/etc/netplan/` directory was empty) — create a drop-in for your interface. Replace both `` below with your interface name, then paste the block — it creates the file and reloads in one go: + +```bash +sudo mkdir -p /etc/systemd/network/.network.d +sudo tee /etc/systemd/network/.network.d/100-netbird.conf > /dev/null <<'EOF' +[Route] +Destination=10.1.0.0/24 +Gateway=10.0.0.50 +EOF +sudo networkctl reload ``` ## Step 6: Verify diff --git a/src/pages/manage/networks/how-routing-peers-work.mdx b/src/pages/manage/networks/how-routing-peers-work.mdx index 7bff5fe6..1b6c88a0 100644 --- a/src/pages/manage/networks/how-routing-peers-work.mdx +++ b/src/pages/manage/networks/how-routing-peers-work.mdx @@ -29,7 +29,7 @@ NetBird offers two ways to configure routing peers. Both are actively maintained - Resources are typed: IP, IP range, or domain. - Access control is built in from the start. -**[Network Routes](/manage/network-routes) (legacy, still supported)** +**[Routes](/manage/network-routes) (legacy, deprecated)** - Distribution Groups and ACL Groups are configured separately. - ACL Groups are optional, which means a route without them grants unrestricted access to the destination CIDR for every peer in the Distribution Group. - Only needed today for [exit node](/manage/network-routes/use-cases/exit-nodes) setups. Use Networks for everything else, including [site-to-site](/manage/networks/use-cases/site-to-site). @@ -137,7 +137,7 @@ This is the subtlest part of the model and the source of most policy mistakes. ### Two chains, two policy types -- **Forward chain.** Packets routed *through* the peer to backend resources. Network resource policies (Networks) and ACL Groups (Network Routes) apply here. +- **Forward chain.** Packets routed *through* the peer to backend resources. Network resource policies (Networks) and ACL Groups (Routes) apply here. - **Input chain.** Packets destined to the routing peer's own IP. [Peer-to-peer policies](/manage/access-control/manage-network-access) apply here. If users need to reach both the resources behind a routing peer **and** services running on the routing peer itself (Pi-hole, monitoring, jump-host SSH), you need one policy of each kind. @@ -242,12 +242,12 @@ Specifics: }, { href: '/manage/network-routes', - name: 'Network Routes', - description: 'Legacy routing peer feature still supported for scenarios Networks does not yet cover', + name: 'Routes', + description: 'Legacy routing peer feature, now deprecated — use Networks except for exit nodes', }, { href: '/manage/network-routes/access-control', - name: 'Access Control on Network Routes', + name: 'Access Control on Routes', description: 'Use ACL Groups to restrict who reaches a routed network', }, { diff --git a/src/pages/manage/networks/index.mdx b/src/pages/manage/networks/index.mdx index 960cde93..16c76e29 100644 --- a/src/pages/manage/networks/index.mdx +++ b/src/pages/manage/networks/index.mdx @@ -173,7 +173,7 @@ Before you depend on a Network in production, work through these: Networks is the default for **every** remote-access scenario: VPN-to-Site, [Site-to-Site](/manage/networks/use-cases/site-to-site) (two clientless networks reaching each other through a routing peer at each end), and [Site-to-VPN](/manage/networks/use-cases/site-to-vpn) (a clientless device initiating connections to your overlay network). -The only case that still requires [Network Routes](/manage/network-routes) is **[exit nodes](/manage/network-routes/use-cases/exit-nodes)**, which send a group's internet-bound traffic out through a chosen peer. For everything else, use Networks: it enforces access by default, while a Network Route without ACL Groups grants unrestricted access. +The only case that still requires [Routes](/manage/network-routes) is **[exit nodes](/manage/network-routes/use-cases/exit-nodes)**, which send a group's internet-bound traffic out through a chosen peer. For everything else, use Networks: it enforces access by default, while a Route without ACL Groups grants unrestricted access. ## Recap diff --git a/src/pages/manage/networks/masquerade.mdx b/src/pages/manage/networks/masquerade.mdx index 89f882c7..54f94002 100644 --- a/src/pages/manage/networks/masquerade.mdx +++ b/src/pages/manage/networks/masquerade.mdx @@ -72,14 +72,28 @@ sudo ip route del 100.64.0.0/10 via ## Persistent configuration -Pick **one** of the methods below — your host uses one network manager, not both: +Follow **only one** of the two methods below — they're alternatives, not consecutive steps. Check which network manager your host uses: -- **Netplan** if `/etc/netplan/` already has yaml files (most Ubuntu hosts). -- **systemd-networkd** otherwise (Debian Server, minimal installs, or hosts using systemd-networkd directly without a netplan frontend). +```bash +ls /etc/netplan/ +``` + +- If you see `.yaml` files, use **Netplan** (most Ubuntu hosts). +- If the directory is empty or missing, use **systemd-networkd** (Debian Server, minimal installs, or hosts using systemd-networkd directly without a netplan frontend). + +Don't mix them — on Netplan hosts, systemd-networkd config you add by hand is silently ignored. + +Both methods need the destination host's LAN interface name — find it with `ip -br addr` (e.g. `eth0` or `ens18`). Substitute it wherever the steps below show ``. ### Netplan (Ubuntu 18.04+) -On Ubuntu Server, `/etc/netplan/` usually already has a yaml from cloud-init (`50-cloud-init.yaml`) or the installer (`00-installer-config.yaml`). Append a new entry to the interface's `routes:` list (don't add a second `routes:` key — YAML won't accept that). The `addresses:` and default-route values shown below are placeholders for whatever is already in your file — not values to copy as-is: +On Ubuntu Server, `/etc/netplan/` usually already has a yaml from cloud-init (`50-cloud-init.yaml`) or the installer (`00-installer-config.yaml`). Open the file `ls` showed in a text editor — `nano` is the simplest (run `sudo apt install nano` first if it's missing): + +```bash +sudo nano /etc/netplan/50-cloud-init.yaml +``` + +Append the new route to the interface's existing `routes:` list (don't add a second `routes:` key — YAML won't accept that). The `addresses:` and default-route values shown below are placeholders for whatever is already in your file — not values to copy as-is: ```yaml network: @@ -96,7 +110,7 @@ network: If `/etc/netplan/` is empty (uncommon, but possible on minimal installs or when netplan was just `apt install`ed), create `/etc/netplan/01-netbird.yaml` with the full stanza, substituting real values for `addresses:` and the default gateway. -Apply: +Save and exit. In nano: press `Ctrl+O` then `Enter` to write the file, then `Ctrl+X` to quit. Then apply the change: ```bash sudo netplan apply @@ -108,17 +122,15 @@ Recent netplan versions require `0600` permissions on yaml files under `/etc/net ### systemd-networkd -Either append to the relevant `.network` file in `/etc/systemd/network/`, or drop a snippet into `/etc/systemd/network/.network.d/100-netbird.conf`: +Create a drop-in for your interface (replace `` with your LAN interface, e.g. `eth0`). This block creates the file and reloads in one paste: -```ini +```bash +sudo mkdir -p /etc/systemd/network/.network.d +sudo tee /etc/systemd/network/.network.d/100-netbird.conf > /dev/null <<'EOF' [Route] Destination=100.64.0.0/10 Gateway= -``` - -Apply: - -```bash +EOF sudo networkctl reload ``` diff --git a/src/pages/manage/networks/use-cases/access-home-devices.mdx b/src/pages/manage/networks/use-cases/access-home-devices.mdx index f36fd4ef..ca2747f0 100644 --- a/src/pages/manage/networks/use-cases/access-home-devices.mdx +++ b/src/pages/manage/networks/use-cases/access-home-devices.mdx @@ -167,5 +167,5 @@ You can now access your home devices from anywhere. ## Next Steps -- **Need Site-to-Site?** If you want to connect two home networks together, see [Site-to-Site](/manage/network-routes/use-cases/site-to-site) -- **Advanced configuration:** See [Advanced Configuration](/manage/network-routes/advanced-configuration) for masquerade options and access control details +- **Need Site-to-Site?** If you want to connect two home networks together, see [Site-to-Site](/manage/networks/use-cases/site-to-site) +- **Advanced configuration:** See [Masquerade](/manage/networks/masquerade) for masquerade options and persistent return-route configuration diff --git a/src/pages/manage/networks/use-cases/cloud-to-on-premise.mdx b/src/pages/manage/networks/use-cases/cloud-to-on-premise.mdx index 7d5050c4..664a51dd 100644 --- a/src/pages/manage/networks/use-cases/cloud-to-on-premise.mdx +++ b/src/pages/manage/networks/use-cases/cloud-to-on-premise.mdx @@ -216,5 +216,5 @@ Your cloud application can now securely access the on-premise database. ## Next Steps -- **Need Multi-Cloud Site-to-Site?** If you need to connect cloud VPCs across providers, see [Site-to-Site](/manage/network-routes/use-cases/site-to-site) -- **Advanced configuration:** See [Advanced Configuration](/manage/network-routes/advanced-configuration) for masquerade options and detailed access control +- **Need Multi-Cloud Site-to-Site?** If you need to connect cloud VPCs across providers, see [Site-to-Site](/manage/networks/use-cases/site-to-site) +- **Advanced configuration:** See [Masquerade](/manage/networks/masquerade) for masquerade options and persistent return-route configuration diff --git a/src/pages/manage/networks/use-cases/site-to-site.mdx b/src/pages/manage/networks/use-cases/site-to-site.mdx index 88dd7b23..43b21554 100644 --- a/src/pages/manage/networks/use-cases/site-to-site.mdx +++ b/src/pages/manage/networks/use-cases/site-to-site.mdx @@ -18,8 +18,6 @@ Site A device ──► Routing Peer ──► NetBird Tunnel ──► Routing Networks is the recommended way to build site-to-site. It has per-Resource access control, is Zero Trust by default, and is the actively developed system. -Use [Network Routes](/manage/network-routes/use-cases/site-to-site) instead only when you need site-to-site without any Policy gating traffic — the legacy "wide open" mode with empty Access Control Groups. Networks requires at least one Policy per Resource and has no equivalent. - For the reverse — clientless devices at a site initiating connections to NetBird peers — see [Site-to-VPN](/manage/networks/use-cases/site-to-vpn). @@ -96,25 +94,74 @@ Destination: 10.1.0.0/24 # remote network Gateway: 10.0.0.50 # local routing peer ``` -**Per-device fallback** — Linux: +**Per-device fallback** — if you can't touch the router, add the route on each device instead. -```bash -sudo ip route add 10.1.0.0/24 via 10.0.0.50 -``` - -Windows (PowerShell, persistent): +**Windows** (PowerShell as Administrator) — `-p` makes it persistent: ```powershell route -p add 10.1.0.0 mask 255.255.255.0 10.0.0.50 ``` +**Linux** — first test the route (this form disappears on the next reboot): + +```bash +sudo ip route add 10.1.0.0/24 via 10.0.0.50 +``` + +Once a peer at the other site is reachable, make it permanent. The method depends on which network manager the device uses — check with: + +```bash +ls /etc/netplan/ +``` + +Follow **only one** of the two methods below — the one that matches what `ls` showed. They're alternatives, not consecutive steps: if you see `.yaml` files use Netplan (most Ubuntu hosts); if the directory is empty or missing use systemd-networkd (Debian, minimal installs). Don't mix them — on Netplan hosts, systemd-networkd config you add by hand is silently ignored. + +Both methods need your LAN interface name — find it with `ip -br addr` (look for the connection carrying the device's local IP, e.g. `eth0` or `ens18`). Substitute it wherever the steps below show ``. + +**Option A — Netplan** (you saw `.yaml` files) — open the file `ls` showed (e.g. `50-cloud-init.yaml`) in a text editor. `nano` is the simplest; this command opens the file in it (run `sudo apt install nano` first if it's missing): + +```bash +sudo nano /etc/netplan/50-cloud-init.yaml +``` + +Find your interface under `ethernets:` and add the route. If a `routes:` list is already there, add the `- to:` lines to it — don't create a second `routes:` key: + +```yaml +network: + version: 2 + ethernets: + : # your interface, from ip -br addr + dhcp4: true # whatever was already here + routes: # add this block (or reuse an existing routes: list) + - to: 10.1.0.0/24 # remote network + via: 10.0.0.50 # local routing peer +``` + +Save and exit. In nano: press `Ctrl+O` then `Enter` to write the file, then `Ctrl+X` to quit. Then apply the change: + +```bash +sudo netplan apply +``` + -The Linux `ip route add` form above applies only until the next reboot. For persistent Linux routes (Netplan or systemd-networkd), follow the same pattern shown in [Persistent configuration](/manage/networks/masquerade#persistent-configuration), substituting your remote site's CIDR (`10.1.0.0/24` in this example) for the destination shown there. The Windows `route -p add` form is already persistent. +Recent Netplan needs `0600` permissions on files under `/etc/netplan/`. Run `sudo chmod 0600 /etc/netplan/*.yaml` if `netplan apply` warns. +**Option B — systemd-networkd** (the `/etc/netplan/` directory was empty) — create a drop-in for your interface. Replace both `` below with your interface name, then paste the block — it creates the file and reloads in one go: + +```bash +sudo mkdir -p /etc/systemd/network/.network.d +sudo tee /etc/systemd/network/.network.d/100-netbird.conf > /dev/null <<'EOF' +[Route] +Destination=10.1.0.0/24 +Gateway=10.0.0.50 +EOF +sudo networkctl reload +``` + Repeat this on the other site with the values swapped, so Site B's router or devices know to reach `10.0.0.0/24` via the local Site B routing peer. Bidirectional site-to-site needs the static routes on both sides. -This step assumes Masquerade is enabled on both routing peers (the default in Step 3). Site-to-site over Networks requires Masquerade to be on — disabling it on a routing peer causes the WireGuard tunnel to drop traffic whose source isn't the peer's NetBird IP, so source-IP preservation isn't currently supported for site-to-site. If you need to preserve source IPs end to end, use the [Network Routes site-to-site setup](/manage/network-routes/use-cases/site-to-site) instead, which supports running with Masquerade disabled. +This step assumes Masquerade is enabled on both routing peers (the default in Step 3). Site-to-site over Networks requires Masquerade to be on — disabling it on a routing peer causes the WireGuard tunnel to drop traffic whose source isn't the peer's NetBird IP, so source-IP preservation isn't currently supported for site-to-site. If you need to preserve source IPs end to end, use the [Routes site-to-site setup](/manage/network-routes/use-cases/site-to-site) instead, which supports running with Masquerade disabled. ## Step 6: Verify @@ -139,4 +186,4 @@ When the routing peer is a cloud instance, the VPC needs to allow it to forward - [Masquerade](/manage/networks/masquerade) — how source NAT works on routing peers - [Site-to-VPN](/manage/networks/use-cases/site-to-vpn) — clientless devices initiating connections to NetBird peers - [Access Home Devices](/manage/networks/use-cases/access-home-devices) — reach a single site from your NetBird peers -- [Network Routes Site-to-Site](/manage/network-routes/use-cases/site-to-site) — the legacy approach, for wide-open no-policy setups +- [Routes Site-to-Site](/manage/network-routes/use-cases/site-to-site) — legacy approach for scenarios that require source-IP preservation or Routes-specific behavior diff --git a/src/pages/manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments.mdx b/src/pages/manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments.mdx index 9f8e8205..bfaf7197 100644 --- a/src/pages/manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments.mdx +++ b/src/pages/manage/peers/access-infrastructure/access-internal-resources-from-autoscaled-environments.mdx @@ -30,7 +30,7 @@ To replicate this use case, you'll need: With these prerequisites in place, you'll be prepared to set up a secure network connection for autoscaled resources using NetBird by: 1. Creating a NetBird Setup Key for Kubernetes -2. Configuring Network Routes for Internal Resource Access +2. Configuring Routes for Internal Resource Access 3. Setting Up Access Policies for Secure Communication 4. Deploying a Sample Application with NetBird Agent 5. Configuring Horizontal Pod Autoscaler (HPA) diff --git a/src/pages/manage/settings/ipv6.mdx b/src/pages/manage/settings/ipv6.mdx index 6aa9a997..b663b31a 100644 --- a/src/pages/manage/settings/ipv6.mdx +++ b/src/pages/manage/settings/ipv6.mdx @@ -54,7 +54,7 @@ When an exit node route (`0.0.0.0/0`) is configured and the peer supports IPv6, ### Network Routes -[Network routes](/manage/network-routes) accept IPv6 CIDRs (for example `fd11:2::/64`) the same way as IPv4 subnets. When a route has masquerade enabled, the routing peer SNATs IPv6 egress traffic to its backend-side address, matching the IPv4 behavior. +[Routes](/manage/network-routes) accept IPv6 CIDRs (for example `fd11:2::/64`) the same way as IPv4 subnets. When a route has masquerade enabled, the routing peer SNATs IPv6 egress traffic to its backend-side address, matching the IPv4 behavior. ### Domain Routes diff --git a/src/pages/use-cases/cloud/index.mdx b/src/pages/use-cases/cloud/index.mdx index be63d664..b06d1f4b 100644 --- a/src/pages/use-cases/cloud/index.mdx +++ b/src/pages/use-cases/cloud/index.mdx @@ -45,7 +45,7 @@ For connecting cloud VPCs to on-premise networks, see the [Site-to-Site Connecti description: 'Connect cloud workloads to on-premise databases and services', }, { - href: '/manage/network-routes/use-cases/site-to-site', + href: '/manage/networks/use-cases/site-to-site', name: 'Multi-Cloud Site-to-Site', description: 'Bridge cloud VPCs across providers using Site-to-Site routing', }, diff --git a/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx b/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx index 97d00a6d..1d67cfbc 100644 --- a/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx +++ b/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx @@ -142,7 +142,7 @@ kubectl apply -f deployment.yml ### Step 5: Make the deployment highly available -NetBird network routes support multiple routing peers running in a fail-over mode, where one routing peer will be select +NetBird Routes support multiple routing peers running in a fail-over mode, where one routing peer will be select as gateway for a network and when this peer becomes unavailable other routing peer will be select for the role, proving a highly available network route. diff --git a/src/pages/use-cases/homelab/index.mdx b/src/pages/use-cases/homelab/index.mdx index 18541c22..01262026 100644 --- a/src/pages/use-cases/homelab/index.mdx +++ b/src/pages/use-cases/homelab/index.mdx @@ -30,7 +30,7 @@ For connecting entire home networks (accessing devices that don't have NetBird i description: 'Set up VPN-to-Site access to reach home network devices from anywhere', }, { - href: '/manage/network-routes/use-cases/site-to-site', + href: '/manage/networks/use-cases/site-to-site', name: 'Connect Home Networks', description: 'Link multiple home networks together using Site-to-Site routing', }, @@ -43,10 +43,10 @@ For most homelabbers, we recommend: 1. **Install NetBird on your devices** - Laptop, phone, and any servers you access directly 2. **Set up a routing peer** - Use a Raspberry Pi, NAS with Docker, or dedicated device -3. **Configure network access** - Use Networks (simpler) or Network Routes (more flexible) +3. **Configure network access** - Use Networks (recommended) or Routes (legacy) | Scenario | Recommended Feature | |----------|---------------------| | Access home devices from laptop/phone | [Networks](/manage/networks) | -| Connect two home networks | [Network Routes](/manage/network-routes) | +| Connect two home networks | [Networks](/manage/networks/use-cases/site-to-site) | | Run NetBird on router | [MikroTik Guide](/use-cases/homelab/client-on-mikrotik-router) | diff --git a/src/pages/use-cases/security/implement-zero-trust.mdx b/src/pages/use-cases/security/implement-zero-trust.mdx index c88c9076..26300813 100644 --- a/src/pages/use-cases/security/implement-zero-trust.mdx +++ b/src/pages/use-cases/security/implement-zero-trust.mdx @@ -90,7 +90,7 @@ This section defines how terms are used in this guide and in NetBird. - **Network (NetBird object)** - A NetBird configuration object that maps your internal networks (such as VPCs, LANs, or office networks) and organizes routing peers and resources. [Networks](/manage/networks) group routing peers that provide access to the same internal subnets. Resources within Networks (IP addresses, ranges, or DNS names) serve as destinations in access policies. Networks replaced the older "Network Routes" concept starting with NetBird v0.35.0. Resources within a Network must be assigned to groups, and access is controlled through policies. Resources only become visible to peers after a policy explicitly grants access. + A NetBird configuration object that maps your internal networks (such as VPCs, LANs, or office networks) and organizes routing peers and resources. [Networks](/manage/networks) group routing peers that provide access to the same internal subnets. Resources within Networks (IP addresses, ranges, or DNS names) serve as destinations in access policies. Networks replaced the older "Routes" concept starting with NetBird v0.35.0. Resources within a Network must be assigned to groups, and access is controlled through policies. Resources only become visible to peers after a policy explicitly grants access. - **Posture check** @@ -500,7 +500,7 @@ Broken DNS is the most common cause of "NetBird is broken" complaints. For every Use routing peers and Networks when you need to reach private subnets (LAN, VPC, on-premises) rather than only NetBird overlay peers. -**Network Routes vs Networks:** Legacy [Network Routes](/manage/network-routes) bypass Access Control policies by default unless [Access Control Groups are explicitly configured](/manage/network-routes/access-control). The newer [Networks](/manage/networks) feature (v0.35.0+) handles this automatically—resources only become visible to peers after a policy explicitly grants access. For Zero Trust implementations, we recommend using Networks instead of legacy Network Routes. +**Routes vs Networks:** Legacy [Routes](/manage/network-routes) bypass Access Control policies by default unless [Access Control Groups are explicitly configured](/manage/network-routes/access-control). The newer [Networks](/manage/networks) feature (v0.35.0+) handles this automatically—resources only become visible to peers after a policy explicitly grants access. For Zero Trust implementations, we recommend using Networks instead of legacy Routes. ### 5.1 Requirements for a routing peer @@ -824,7 +824,7 @@ Common causes: - Routing peer flapping: - One of several routing peers is unhealthy, and clients sometimes pick the bad one. - Overlapping routes: - - Two Network routes share the same CIDR, and the client sometimes picks the wrong one. + - Two routes share the same CIDR, and the client sometimes picks the wrong one. - Unstable underlying network: - Wireless or mobile networks dropping connectivity. @@ -837,7 +837,7 @@ What to do: # Networks (v0.35.0+) - recommended for Zero Trust netbird networks ls - # Legacy Network Routes + # Legacy Routes netbird routes ls ``` @@ -994,7 +994,7 @@ netbird status -d # Networks (v0.35.0+) - the newer feature with policy-based access control netbird networks ls -# Legacy Network Routes - may bypass Access Control unless explicitly configured +# Legacy Routes - may bypass Access Control unless explicitly configured netbird routes ls ``` diff --git a/src/pages/use-cases/site-to-site/index.mdx b/src/pages/use-cases/site-to-site/index.mdx index 0e659073..f2e1a104 100644 --- a/src/pages/use-cases/site-to-site/index.mdx +++ b/src/pages/use-cases/site-to-site/index.mdx @@ -1,3 +1,4 @@ +import { Note } from '@/components/mdx' import { Tiles } from '@/components/Tiles' # Site-to-Site Connectivity @@ -5,7 +6,7 @@ import { Tiles } from '@/components/Tiles' Site-to-site connectivity allows you to connect entire networks together, enabling devices to communicate across locations without installing the NetBird client on every device. -For the mental model — see [How Routing Peers Work — Networks vs Network Routes](/manage/networks/how-routing-peers-work#networks-vs-network-routes). +For the mental model — see [How Routing Peers Work — Networks vs Routes](/manage/networks/how-routing-peers-work#networks-vs-network-routes). ## Understanding Remote Access Scenarios @@ -26,7 +27,7 @@ Your Laptop ──────► NetBird Tunnel ──────► Routing P - Reach office servers while traveling - Connect to IoT devices on a remote network -**Implementation:** Use [Networks](/manage/networks) (recommended) or [Network Routes](/manage/network-routes) +**Implementation:** Use [Networks](/manage/networks) ### Site-to-VPN @@ -58,7 +59,7 @@ Home NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer - Link home networks of family members - Bridge on-premise data centers with cloud VPCs -**Implementation:** Requires [Network Routes](/manage/network-routes) (Networks does not currently support this) +**Implementation:** Use [Networks](/manage/networks/use-cases/site-to-site) ### Exit Nodes @@ -74,7 +75,7 @@ Your Laptop ──────► NetBird Tunnel ──────► Exit Node - Route traffic through a trusted network for compliance - Mask your location for privacy -**Implementation:** Requires [Network Routes](/manage/network-routes/use-cases/exit-nodes) +**Implementation:** Requires [Routes](/manage/network-routes/use-cases/exit-nodes) ## Which Scenario Do I Need? @@ -83,10 +84,10 @@ Your Laptop ──────► NetBird Tunnel ──────► Exit Node | Access home devices from my laptop | VPN-to-Site | [Networks](/manage/networks/use-cases/access-home-devices) | | Access office resources while traveling | VPN-to-Site | [Networks](/manage/networks) | | Let an office server connect to my laptop | Site-to-VPN | [Networks](/manage/networks/use-cases/site-to-vpn) | -| Connect two home networks together | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/site-to-site) only | -| Link branch offices | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/site-to-site) only | -| Bridge cloud VPC with on-premise network | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/site-to-site) only | -| Route all internet traffic through a specific peer | Exit Node | [Network Routes](/manage/network-routes/use-cases/exit-nodes) only | +| Connect two home networks together | Site-to-Site | [Networks](/manage/networks/use-cases/site-to-site) | +| Link branch offices | Site-to-Site | [Networks](/manage/networks/use-cases/site-to-site) | +| Bridge cloud VPC with on-premise network | Site-to-Site | [Networks](/manage/networks/use-cases/site-to-site) | +| Route all internet traffic through a specific peer | Exit Node | [Routes](/manage/network-routes/use-cases/exit-nodes) only | ## How It Works @@ -114,17 +115,17 @@ All scenarios use a routing peer—a device running NetBird that forwards traffi /> @@ -137,25 +138,25 @@ All scenarios use a routing peer—a device running NetBird that forwards traffi | Clientless device | A device that doesn't run NetBird (printers, IoT, legacy systems) | | Masquerade | NAT that hides source IPs behind the routing peer's IP (simplifies routing configuration on clientless devices) | -## Networks vs Network Routes +## Networks vs Routes -NetBird offers two features for routing traffic to private networks: [Networks](/manage/networks) (newer, simpler) and [Network Routes](/manage/network-routes) (original, more flexible). Both are fully supported and will continue to be maintained. +NetBird offers two ways to route traffic to private networks: [Networks](/manage/networks) (newer, recommended) and [Routes](/manage/network-routes) (original, now deprecated). Existing Routes configurations keep working, but every use case except [exit nodes](/manage/network-routes/use-cases/exit-nodes) has moved to Networks — use Networks for new setups. -**Use Networks** for VPN-to-Site scenarios where you want a guided setup experience and per-resource access policies. +**Use Networks** for all routing scenarios — VPN-to-Site, Site-to-VPN, and Site-to-Site — with a guided setup and per-resource access policies. -**Use Network Routes** when you need Site-to-Site connectivity, or require advanced options like disabling masquerade. +**Use Routes** only for exit nodes, or to preserve source IPs by disabling masquerade. ### Scenario Support -| Scenario | Networks | Network Routes | +| Scenario | Networks | Routes | |----------|----------|----------------| | VPN-to-Site | Yes | Yes | | Site-to-VPN | Yes | Yes | -| Site-to-Site | No | Yes | +| Site-to-Site | Yes | Yes | ### Detailed Comparison -| Capability | Networks | Network Routes | +| Capability | Networks | Routes | |-----------|----------|----------------| | Setup complexity | Simpler, guided UI | More manual configuration | | Distribution groups | Automatic (from policy sources) | Explicit configuration required | @@ -168,4 +169,4 @@ NetBird offers two features for routing traffic to private networks: [Networks]( ### Future Direction -The goal is to migrate all routing functionality into Networks for a unified experience. **Network Routes will not be deprecated without advance notice**, and any migration path will be documented. For now, use whichever feature fits your scenario. +The goal is to migrate all routing functionality into Networks for a unified experience. **Routes are now deprecated** — every use case except [exit nodes](/manage/network-routes/use-cases/exit-nodes) has moved to Networks, and existing Routes configurations continue to work. Use Networks for all new configurations.