sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-15 23:16:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Routing corrections clarity brandon (#481)

Browse Source 
* Update titles and enhance clarity in routing documentation

- Capitalized section titles for consistency, including "Configuring Routes with Access Control" and "Routing Traffic to Private Networks."
- Improved phrasing and clarity throughout the documents, including warnings and explanations regarding access control and network routes.
- Fixed minor grammatical issues and formatting for better readability.

* Update links and improve phrasing in routing traffic documentation

- Changed the link reference for "Network Routes caveats" to a more concise anchor.
- Combined two sentences in the note about the managed version of the Network Routes feature for better readability.

* Enhance formatting and clarity in routing traffic documentation

- Updated section headers to bold for improved visibility and consistency.
- Reformatted descriptions for "Network identifiers and ranges," "Routing peer," "Routing group," "High availability routes," "Masquerade," and "DNS Routes" for better readability.
- Added emphasis to the note regarding route configuration when masquerade is not enabled.
This commit is contained in:
Brandon Hopkins
2025-11-19 12:28:51 -08:00
committed by GitHub
parent 5e2652090b
commit 745ae6ba3a
2 changed files with 72 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
src/pages/how-to/configuring-routes-with-access-control.mdx
View File

@@ -1,4 +1,4 @@
# Configuring routes with access control
# Configuring Routes with Access Control
<Note>
This feature is available from NetBird version 0.30.0 onwards.
@@ -6,17 +6,18 @@
By default, network routes allow unrestricted access, meaning any traffic can
flow through the routes without limitations. This behavior occurs when access
control groups are not associated with a route. However, when access control
groups are set, the route inherits access restrictions based on the defined
control groups are not associated with a route.
However, when access control groups are set, the route inherits access restrictions based on the defined
policies. Only traffic that meets the criteria specified in these policies can
access the internal services, ensuring that your network remains secure and that
access the internal services. This ensures that your network remains secure and that
only authorized users can reach sensitive resources.
## Route Access Policies and Access Control Groups
Route access policies are unidirectional, applying only from routing
client to routing peer. Consequently, the access control group only takes effect
if used as a destination group in the policy.
Route access policies are unidirectional, applying only from the routing
client to the routing peer. Consequently, the access control group only takes effect
when used as a destination group in the policy.
If an empty group (containing no peers) is used for the access control group
(and subsequently in the policy), then only the routed network will be affected
@@ -29,10 +30,10 @@ by the access policy, not the routing peer itself.
which case all traffic is permitted.
</Note>
## Creating a network route with access control group
## Creating a Network Route with Access Control Group
Since release `0.30.0`, the management service and dashboard support access control groups for network routes.
To add a Network route with access control groups, access the menu `Network Routes` tab and click the `Add Route` button to create a new route.
To add a Network Route with access control groups, access the `Network Routes` tab and click the `Add Route` button to create a new route.
In the example below, we are creating a route with the following information
(see [Concepts](routing-traffic-to-private-networks#concepts) to learn more about the fields):
@@ -66,12 +67,13 @@ Because you used an access control group, you will be prompted to create a new p
Click on the `Create Policy` button to proceed.
## Creating Access Control Policy
If you didn't use the prompt, you can create a new policy by accessing the `Access Control` > `Policies` tab, click on the `Add policy` button to create a new policy.
## Creating an Access Control Policy
If you did not use the prompt, you can create a new policy by accessing the `Access Control` > `Policies` tab, then clicking the `Add policy` button to create a new policy.
In the popup, specify source and destination groups, and add Posture Checks if needed. Make sure to set traffic
direction only when TCP or UDP protocols are selected. Finally, provide a name and description for your policy.
In the example below, we are creating a one direction policy with the following information:
In the example below, we are creating a unidirectional policy with the following information:
- Name: `Devs to Servers`
- Description: `Devs are allowed to access servers`
- Protocol: `TCP`
@@ -84,32 +86,31 @@ In the example below, we are creating a one direction policy with the following
</p>
If necessary, you can create new groups simply by entering new names in the input box for either the source or destination lists.
If necessary, you can create new groups by entering new names in the input box for either the source or destination lists.
Once you have finished configuring the policy, click `Add Policy` to save it. You will then see your new policy in the table.
<p>
<img src="/docs-static/img/how-to-guides/network-acl-new-policy.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Done! Now, every peer connected to your routing peer can only access port 80 services on the routed network,
The route has been created successfully. Now, every peer connected to your routing peer can only access port 80 services on the routed network,
as specified by the defined policy.
## Site-to-Site Traffic Configuration
For site-to-site traffic (where routes are set up in both directions with one
peer in the distribution group and the other as the routing peer, and vice
For site-to-site traffic, where routes are set up in both directions with one
peer in the distribution group and the other as the routing peer (and vice
versa), there are two configuration scenarios:
1. With Masquerading Enabled:
### With Masquerading Enabled
- To subject site-to-site traffic to route access policies, ensure masquerading
is enabled.
- You'll need to set up two policies, one for each direction/site.
To subject site-to-site traffic to route access policies, ensure masquerading
is enabled. You'll need to set up two policies, one for each direction/site.
2. Without Masquerading:
### Without Masquerading
- If masquerading is disabled, access control groups need not be applied.
- This configuration allows unrestricted access in both directions.
If masquerading is disabled, access control groups need not be applied.
This configuration allows unrestricted access in both directions.
Choose the appropriate configuration based on your security requirements and
network setup.
@@ -140,7 +141,7 @@ To allow traffic initiated from the routed network in version 0.30.0 and later:
2. Add a peer access policy to allow specific traffic from the routing peer to
the routing client. This is required whether route access policies are set up
or not. The traffic flow should be:
Routing Client (Peer A) < -- Routing Peer (Peer B)
Routing Client (Peer A) ← Routing Peer (Peer B)
This configuration allows the routing client (Peer A) to accept incoming traffic
from the routing peer (Peer B), which may originate from the routed network.

101
src/pages/how-to/routing-traffic-to-private-networks.mdx
View File

@@ -1,5 +1,5 @@
# Routing traffic to private networks
# Routing Traffic to Private Networks
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/VQuPuBOAknQ" allow="fullscreen;"></iframe>
@@ -8,16 +8,16 @@
<Note>
WARNING: `Network Routes` will allow any traffic to pass through to the routed networks without regard for
**WARNING:** `Network Routes` will allow any traffic to pass through to the routed networks without regard for
the Access Control rules, unless you [configure those explicitly](./configuring-routes-with-access-control).
See [Caveats](#caveats) below for more detailed explanation.
See [Network Routes caveats](#caveats) below for a more detailed explanation.
</Note>
NetBird provides fast and reliable end-to-end encryption between peers in your network. You can install the agent on every desktop, VM, container, or physical server and have a fast, secure peer-to-peer mesh network. That is the desired configuration, but some cases do not allow for agent installation or can slow down migration from legacy systems:
NetBird provides fast and reliable end-to-end encryption between peers in your network. You can install the agent on every desktop, VM, container, or physical server to create a fast, secure peer-to-peer mesh network. This is the desired configuration, but some cases do not allow for agent installation or can slow down migration from legacy systems:
- Side-by-side migrations where part of your network is already using NetBird but needs to access services that are not.
- Systems that have limited operating system access. e.g., IoT devices, printers, and managed services.
- Systems that have limited operating system access, such as IoT devices, printers, and managed services.
- Legacy networks where an administrator is unable to install the agent on all nodes.
In these cases, you can configure network routes assigning routing peers to connect existing infrastructure. Routing peers will forward packets between your NetBird peers and your other networks; they can masquerade traffic going to your data centers or embedded devices, reducing the need for external route configuration and agent installation.
@@ -27,9 +27,7 @@ In these cases, you can configure network routes assigning routing peers to conn
</p>
<Note>
If you want to see the Network Routes feature in action, try our managed version at https://app.netbird.io/routes.
It's free and simple! :)
If you want to see the Network Routes feature in action, try our managed version at https://app.netbird.io/routes. It's free and easy to use.
</Note>
## Concepts
@@ -41,26 +39,20 @@ A network route describes the network you want to connect with your NetBird peer
Network routes are available in NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
#### Network identifiers and ranges
Network identifiers are names for each network you want to route traffic from your peers, and ranges are IP ranges declared in CIDR notation which refers to an external network. The combination of identifiers and these ranges makes a single network.
**Network identifiers and ranges** Network identifiers are names for each network you want to route traffic from your peers, and ranges are IP ranges declared in CIDR notation which refers to an external network. The combination of identifiers and these ranges makes a single network.
#### Routing peer
A routing peer is a peer that routes packets between your routed network and the other NetBird peers.
**Routing peer**: A routing peer is a peer that routes packets between your routed network and the other NetBird peers.
#### Routing group
A routing group is a set of routing peers. Each will route packets between your routed network and the other NetBird peers.
**Routing group**: A routing group is a set of routing peers. Each will route packets between your routed network and the other NetBird peers.
#### High availability routes
A highly available route is a combination of multiple routes with the same network identifier and ranges. They have different routing peers or routing peer groups offering highly available paths for communication between your peers and external networks.
**High availability routes**: A highly available route is a combination of multiple routes with the same network identifier and ranges. They have different routing peers or routing peer groups offering highly available paths for communication between your peers and external networks.
Nodes connected to routing peers will choose one of them to route packets to external networks based on connection type and defined metrics.
#### Masquerade
Masquerade hides other NetBird network IPs behind the routing peer local address when accessing the target Network range. This option allows access to your private networks without configuring routes on your local routers or other devices.
**Masquerade**: Masquerade hides other NetBird network IPs behind the routing peer local address when accessing the target network range. This option allows access to your private networks without configuring routes on your local routers or other devices.
If you don't enable this option, you must configure a route to your NetBird network in your external network infrastructure.
_If you do not enable this option, you must configure a route to your NetBird network in your external network infrastructure._
### DNS Routes
An alternative to specifying a network range directly is to use DNS routes. Instead of adding the network directly, you can add multiple domains in a route that will be dynamically resolved on the client. The resolved IP addresses for these domains will be added as routes. For example, a network administrator can ensure that traffic to `website.com` or `api.website.com` is routed through a specific machine. So they configure DNS routes for these domains instead of specifying the IP ranges.
**DNS Routes**: An alternative to specifying a network range directly is to use DNS routes. Instead of adding the network directly, you can add multiple domains in a route that will be dynamically resolved on the client. The resolved IP addresses for these domains will be added as routes. For example, a network administrator can ensure that traffic to `website.com` or `api.website.com` is routed through a specific machine. So they configure DNS routes for these domains instead of specifying the IP ranges.
By default, DNS routes are resolved every 60 seconds. You can adjust this interval using the `--dns-router-interval` flag:
@@ -69,7 +61,7 @@ By default, DNS routes are resolved every 60 seconds. You can adjust this interv
netbird up --dns-router-interval 30s
```
Additionally, a keep routes switch is enabled by default.
Additionally, the keep routes switch is enabled by default.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-dns-routes.png" alt="high-level-dia" className="imagewrapper-big"/>
@@ -99,29 +91,29 @@ Outside of high availability routes, the metric has no effect.
### Distribution groups
Distribution groups define that peers that belong to these groups set in this field will receive the network route.
Distribution groups specify which peers will receive the network route. Peers that belong to the groups specified in this field will automatically receive the network route configuration.
<Note>
It doesn't remove the need for the routing peer to be connected to these peers
This does not remove the need for the routing peer to be connected to these peers.
</Note>
### Access Control Groups
These groups provide granular control over internal services within your network. They are used as the destination
Access Control Groups provide granular control over internal services within your network. They are used as destination
groups in access control policies, allowing you to precisely define which internal services can be accessed by
different network entities.
When you associate these groups with specific routes, the routes will inherit the access control policies where
the groups are defined as part of destination groups. This setup enforces access restrictions based on the policies,
When you associate these groups with specific routes, the routes inherit the access control policies where
the groups are defined as destination groups. This setup enforces access restrictions based on the policies,
ensuring that only authorized traffic can reach the designated services.
Routes that do not incorporate these groups will permit unrestricted access, allowing all traffic to pass through
without any limitations.
## Managing network routes
## Managing Network Routes
A network route describes a network you want to connect with your NetBird peers. It has an identifier, a network range, a routing peer or set of peer groups, and some parameters available for managing priority and masquerading.
### Creating a network route
### Creating a Network Route
Access the `Network Routes` tab and click the `Add Route` button to create a new route.
That will open a route configuration screen where you can add the information about the network you want to route:
This will open a route configuration screen where you can add the information about the network you want to route:
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-add-button.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
@@ -144,9 +136,9 @@ Once you fill in the route information, you can click on the `Add Route` button
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-saved-new.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Done! Now every peer connected to your routing peer will be able to send traffic to your external network.
The route has been created successfully. Now every peer connected to your routing peer will be able to send traffic to your external network.
### Creating a network route with routing group
### Creating a Network Route with Routing Group
You can use a peer group to automatically add any Linux peers from the groups as routing peers. To do so, follow the steps above but select the `Peer group` tab.
Ensure that the peer groups have Linux peers, as traffic routing is only supported on Linux machines.
Groups with multiple peers automatically provide [high availability routing](#high-availability-routes).
@@ -161,7 +153,7 @@ Once you fill in the route information, you can click on the `Add Route` button
<img src="/docs-static/img/how-to-guides/netbird-network-routes-groups-saved-new.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Done! Now every peer connected to the peer member of the groups will be able to send traffic to your external network.
The route has been created successfully. Now every peer connected to the peer members of the groups will be able to send traffic to your external network.
### Creating highly available routes
To avoid a single point of failure when managing your network, we recommend installing NetBird on every resource. However, when running NetBird on every machine is not feasible, you still want to ensure a reliable connection to your private network. The NetBird Network Routes feature has a High Availability (HA) mode, allowing one or more NetBird peers to serve as routing peers for the same private network.
@@ -203,7 +195,7 @@ add access control rules ensuring connectivity between these peers and the routi
In the following example (see column `Distribution Groups`), peers that belong to the group `berlin-office` will use
the `aws-nb-europe-router-az-a` routing peer to access the `aws-eu-central-1-vpc` network.
While peers that belong to the `london-office` group will use the `aws-nb-europe-router-az-b` routing peer.
Peers that belong to the `london-office` group will use the `aws-nb-europe-router-az-b` routing peer.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-groups-attribution.png" alt="high-level-dia" className="imagewrapper-big"/>
@@ -211,10 +203,10 @@ While peers that belong to the `london-office` group will use the `aws-nb-europe
### Routes without masquerading
If you want more transparency and would like to manage your external network routers, you may choose to disable masquerade for your network routes.
In this case, the routing peer won't hide any NetBird peer IP and will forward the packets to the target network transparently.
In this case, the routing peer will not hide any NetBird peer IP and will forward the packets to the target network transparently.
That will require a routing configuration on your external network router pointing your NetBird network back to your routing peer.
This way, devices that don't have the agent installed can communicate with your NetBird peers.
This will require a routing configuration on your external network router pointing your NetBird network back to your routing peer.
This way, devices that do not have the agent installed can communicate with your NetBird peers.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-masquerading.png" alt="high-level-dia" className="imagewrapper-big"/>
@@ -223,14 +215,15 @@ This way, devices that don't have the agent installed can communicate with your
## Network Routes caveats
Unless [configured explicitly](./configuring-routes-with-access-control), the **Network Routes** feature will not take into
consideration any of the Access Control rules. Which might lead to surprising outcomes, appearing to be security bugs
at the first glance.
consideration any of the Access Control rules. This might lead to surprising outcomes, which may initially appear to be security vulnerabilities.
This has lead us to creating another, more intuitive, design of **Networks** with their **Resources**, **Routers** and
**Important:** Understanding these caveats is essential for properly securing your network routes.
This has led us to create another, more intuitive design of **Networks** with their **Resources**, **Routers** and
mandatory **Groups** used for both access control and advertisement: your client will not "see" the resource
until it has access to its **Group**.
### Innocently looking Network Route
### Example: Network Route Configuration
Let's assume a **Network Route** is distributed through `Group R` (Routing Peer) to `Group A` (intended client):
@@ -244,8 +237,8 @@ After creating an **Access Policy** granting `ICMP` access from `Group A` to `Gr
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/policy-icmp-group-r.png" alt="ICMP policy from group A to R" className="imagewrapper-big"/>
</p>
you will be able to access everything on it without any restrictions.
This is because **Network Route** requires access to the **Routing Peer** to activate at all, adding to the confusion.
You will be able to access everything on the routed network without any restrictions.
This is because **Network Route** requires access to the **Routing Peer** to activate at all, which can be confusing.
```shell
root@brys-vm-nbt-ubuntu-01:~# netbird networks ls
@@ -267,7 +260,7 @@ OK
### Setting up a Network Resource secured by HTTP policy
Unknowingly from above we are setting up a **Network Resource** for a `*.nb.test` wildcard domain
In the following example, we set up a **Network Resource** for a `*.nb.test` wildcard domain
using ACL group `manual:srvs`:
<p>
@@ -280,7 +273,7 @@ Granting HTTP-only access to that resource from group `manual:client`:
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/policy-http.png" alt="a HTTP-only policy from manual:client group" className="imagewrapper-big"/>
</p>
Everything seems to be set up correctly, we have the HTTP access and we can confirm the domain was resolved:
Everything appears to be set up correctly. We have HTTP access and can confirm the domain was resolved:
```shell
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
@@ -302,7 +295,7 @@ Available Networks:
[srv.nb.test.]: 192.168.100.10
```
Before finishing, let's confirm it's just the HTTP access:
Before finishing, let's verify that only HTTP access is granted:
```shell
root@brys-vm-nbt-ubuntu-02:~# ping -c1 srv.nb.test
@@ -314,14 +307,14 @@ PING srv.nb.test (192.168.100.10) 56(84) bytes of data.
rtt min/avg/max/mdev = 0.242/0.242/0.242/0.000 ms
```
Wait... what?
However, this reveals an unexpected behavior:
```shell
root@brys-vm-nbt-ubuntu-02:~# ssh srv.nb.test
root@srv.nb.test: Permission denied (publickey).
```
Did we grant ourselves access to the **Network Route** by mistake?
Did we inadvertently grant access to the **Network Route**?
```shell
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
@@ -334,9 +327,9 @@ Available Networks:
[srv.nb.test.]: 192.168.100.10
```
Doesn't look like it...
This does not appear to be the case.
### Why did we get ping and ssh access for the domain?
### Why did we get ping and SSH access for the domain?
Unrestricted access to the `srv.nb.test` domain was granted, because we have used the same **Routing Peer**
for both **Network Route** and the newly created **Network**:
@@ -351,15 +344,15 @@ Here are this specific **Routing Peer**'s details:
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/routing-peer-groups.png" alt="Routing Peer's detail page with Network Route handling" className="imagewrapper-big"/>
</p>
As you can see, it is a member of both routing groups:
It is a member of both routing groups:
1. `m:group-r` to advertise the **Network Route**,
2. `manual:router:srvs` to advertise the **Network** and it's domain **Resource**,
2. `manual:router:srvs` to advertise the **Network** and its domain **Resource**,
<Note>
You can still address the "overflowing permissions" issue, by setting up a dedicated set **Routing Peers**
You can address the "overflowing permissions" issue by setting up a dedicated set of **Routing Peers**
to handle the **Network Routes** and never using those for anything else (especially **Networks**).
As you can see this is doable, but extremely easy to miss.
While this is achievable, it is extremely easy to miss during configuration.
</Note>
## Get started