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

Streamlined site-to-site docs in new dedicated section. Removed old u… (#585)

Browse Source 
* Streamlined site-to-site docs in new dedicated section. Removed old use-case guide and added redirects

* restructure use-cases, move network use cases to network sections

* Reorganize network routes and networks documentation structure

- Restructure use cases into by-scenario and by-configuration folders
- Reorganize images to match new doc structure (concepts, by-scenario, by-resource-type)
- Add screenshots for site-to-site guides (home, office, cloud)
- Add policy screenshots for networks use cases
- Update site-to-site docs to use two separate policies instead of bidirectional
- Fix Access Control Groups to use correct destination groups
- Move "Self-Hosted vs Cloud" page to about section
- Update navigation and add redirects for moved pages
- Add CLAUDE.md for Claude Code guidance

* cleaned up network docs/image folder structure

* Align site-to-site use case links and redirects

Co-authored-by: Cursor <cursoragent@cursor.com>

* Update CLAUDE.md with accurate project details

Fix Next.js version (14 → 16), add React 19/Tailwind/Pages Router
details, document MDX page conventions, image paths, and note
absence of test suite.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix broken images and hydration error on networks page

- Restore 6 network index images accidentally deleted in 4116092
- Fix keycloak image filename typo (keycloack -> keycloak)
- Fix hydration mismatch by replacing invalid <p><div> nesting with <div>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix 4 broken internal links found in PR review

- Fix missing by-scenario/ segment in site-to-site-home and
  site-to-site-office Tile hrefs (network-routes use-cases index)
- Fix lazy-connections typo to lazy-connection (implement-zero-trust)
- Update stale redirect link to direct path for access-control

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shuuri-labs
2026-02-13 15:35:44 +01:00
committed by GitHub
parent 2e1c05a655
commit f69c55b9c2
177 changed files with 3761 additions and 2561 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
src/components/Button.jsx
View File

@@ -55,8 +55,12 @@ export function Button({
)
if (variant === 'primary' || variant === 'outline-arrow') {
const divProps = {}
if (!props.href && props.onClick) {
divProps.onClick = props.onClick
}
return (
<div className="relative inline-flex group transition-all" onClick={props.href ? undefined : props.onClick}>
<div className="relative inline-flex group transition-all" {...divProps}>
{variant === 'primary' && (
<span className="absolute h-full w-full left-0 top-0 blur-sm bg-netbird z-0 transition-all duration-200 transform-gpu opacity-0 group-hover:opacity-100 pointer-events-none"></span>
)}

114
src/components/NavigationDocs.jsx
View File

@@ -18,6 +18,7 @@ export const docsNavigation = [
links: [
{ title: 'How NetBird Works', href: '/about-netbird/how-netbird-works' },
{ title: 'NetBird vs. Traditional VPN', href: '/about-netbird/netbird-vs-traditional-vpn' },
{ title: 'Self-Hosted vs. Cloud', href: '/about-netbird/self-hosted-vs-cloud' },
{ title: 'Understanding NAT and Connectivity', href: '/about-netbird/understanding-nat-and-connectivity' },
{ title: 'Why WireGuard with NetBird', href: '/about-netbird/why-wireguard-with-netbird' },
{ title: 'Browser Client Architecture', href: '/about-netbird/browser-client-architecture' },
@@ -93,16 +94,6 @@ export const docsNavigation = [
},
]
},
{
title: 'Connect Site-to-Site',
isOpen: true,
links: [
{
title: 'Simplify Workload Migrations',
href: '/manage/peers/site-to-site/db-workload-migration'
},
]
},
{ title: 'Auto Update', href: '/manage/peers/auto-update' },
]
},
@@ -138,26 +129,64 @@ export const docsNavigation = [
isOpen: false,
links: [
{ title: 'Concept', href: '/manage/networks' },
{ title: 'Route Traffic to Multiple IP resources', href: '/manage/networks/routing-traffic-to-multiple-resources' },
{ title: 'Access Restricted Website Domain Resources', href: '/manage/networks/accessing-restricted-domain-resources' },
{ title: 'Access Entire Domains Within Networks', href: '/manage/networks/accessing-entire-domains-within-networks' },
{
title: 'Homelab',
isOpen: true,
title: 'Use Cases',
isOpen: false,
links: [
{ title: 'Access Home Network', href: '/manage/networks/homelab/access-home-network' },
{ title: 'Overview', href: '/manage/networks/use-cases' },
{
title: 'By Scenario',
isOpen: false,
links: [
{ title: 'Access Home Devices', href: '/manage/networks/use-cases/by-scenario/access-home-devices' },
{ title: 'Remote Worker Access', href: '/manage/networks/use-cases/by-scenario/remote-worker-access' },
{ title: 'Cloud to On-Premise', href: '/manage/networks/use-cases/by-scenario/cloud-to-on-premise' },
]
},
{
title: 'By Resource Type',
isOpen: false,
links: [
{ title: 'Multiple IP Resources', href: '/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources' },
{ title: 'Domain Resources', href: '/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources' },
{ title: 'Wildcard Domains', href: '/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks' },
]
},
]
},
}
]
},
{
title: 'Network Routes',
isOpen: false,
links: [
{ title: 'Route Traffic to Private Networks', href: '/manage/network-routes/routing-traffic-to-private-networks' },
{ title: 'Configure Default Routes for Internet Traffic', href: '/manage/network-routes/configuring-default-routes-for-internet-traffic' },
{ title: 'Configure Routes with Access control', href: '/manage/network-routes/configuring-routes-with-access-control' },
{ title: 'Resolve Overlapping Routes', href: '/manage/network-routes/resolve-overlapping-routes' },
{ title: 'Concept', href: '/manage/network-routes' },
{
title: 'Use Cases',
isOpen: false,
links: [
{ title: 'Overview', href: '/manage/network-routes/use-cases' },
{
title: 'By Scenario',
isOpen: false,
links: [
{ title: 'Site-to-Site: Home', href: '/manage/network-routes/use-cases/by-scenario/site-to-site-home' },
{ title: 'Site-to-Site: Office', href: '/manage/network-routes/use-cases/by-scenario/site-to-site-office' },
{ title: 'Site-to-Site: Cloud', href: '/manage/network-routes/use-cases/by-scenario/site-to-site-cloud' },
{ title: 'Exit Nodes', href: '/manage/network-routes/use-cases/by-scenario/exit-nodes' },
]
},
{
title: 'By Configuration',
isOpen: false,
links: [
{ title: 'Access Control', href: '/manage/network-routes/use-cases/by-configuration/access-control' },
{ title: 'Overlapping Routes', href: '/manage/network-routes/use-cases/by-configuration/overlapping-routes' },
{ title: 'Advanced Configuration', href: '/manage/network-routes/use-cases/by-configuration/advanced-configuration' },
]
},
]
}
]
},
{
@@ -354,14 +383,41 @@ export const docsNavigation = [
{
title: 'USE CASES',
links: [
{ title: 'Site-to-Site and Site-to-VPN', href: '/use-cases/setup-site-to-site-access' },
{ title: 'Serverless and NetBird', href: '/use-cases/netbird-on-faas' },
{ title: 'Routing peers and Kubernetes', href: '/use-cases/routing-peers-and-kubernetes' },
{ title: 'Implement Zero Trust with NetBird', href: '/use-cases/implement-zero-trust' },
{ title: 'NetBird Client on AWS ECS', href: '/use-cases/examples' },
{ title: 'NetBird on Mikrotik Router', href: '/use-cases/client-on-mikrotik-router' },
{ title: 'Distributed AI on Kubernetes', href: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm' },
{ title: 'Self-hosted vs. Cloud-hosted NetBird', href: '/selfhosted/self-hosted-vs-cloud-netbird' },
{ title: 'Overview', href: '/use-cases' },
{
title: 'Remote Access',
isOpen: false,
links: [
{ title: 'Overview', href: '/use-cases/site-to-site' },
]
},
{
title: 'Homelab',
isOpen: false,
links: [
{ title: 'Overview', href: '/use-cases/homelab' },
{ title: 'NetBird on MikroTik Router', href: '/use-cases/homelab/client-on-mikrotik-router' },
]
},
{
title: 'Cloud',
isOpen: false,
links: [
{ title: 'Overview', href: '/use-cases/cloud' },
{ title: 'NetBird on AWS ECS', href: '/use-cases/cloud/aws-ecs-terraform' },
{ title: 'NetBird on Serverless (FaaS)', href: '/use-cases/cloud/netbird-on-faas' },
{ title: 'Routing Peers and Kubernetes', href: '/use-cases/cloud/routing-peers-and-kubernetes' },
{ title: 'Distributed Multi-Cloud AI', href: '/use-cases/cloud/distributed-multi-cloud-ai' },
]
},
{
title: 'Security',
isOpen: false,
links: [
{ title: 'Overview', href: '/use-cases/security' },
{ title: 'Implement Zero Trust', href: '/use-cases/security/implement-zero-trust' },
]
},
],
},
{

4
src/pages/about-netbird/faq.mdx
View File

@@ -16,10 +16,10 @@ all outgoing traffic, and that may affect how NetBird clients connect to the [co
and negotiate the peer-to-peer connections.
<Note>
Allowing the outbound **P2P (STUN)** service below is **recommended** in more restricted networks for reliable peer connections. This will also improve the reliability of your [High Availability Routes](https://docs.netbird.io/manage/network-routes/routing-traffic-to-private-networks#high-availability-routes).
Allowing the outbound **P2P (STUN)** service below is **recommended** in more restricted networks for reliable peer connections. This will also improve the reliability of your [High Availability Routes](https://docs.netbird.io/manage/network-routes#high-availability).
</Note>
<Note>
Allowing the outbound **Relay (TURN)** service below is **recommended** in more restricted networks for reliable peer connections. This will also improve the reliability of your [High Availability Routes](https://docs.netbird.io/manage/network-routes/routing-traffic-to-private-networks#high-availability-routes).
Allowing the outbound **Relay (TURN)** service below is **recommended** in more restricted networks for reliable peer connections. This will also improve the reliability of your [High Availability Routes](https://docs.netbird.io/manage/network-routes#high-availability).
</Note>
<Note>
If using `fail2ban` or similar, you should whitelist each netbird.io endpoint below.

0
src/pages/selfhosted/self-hosted-vs-cloud-netbird.mdx → src/pages/about-netbird/self-hosted-vs-cloud.mdx
View File

2
src/pages/get-started/index.mdx
View File

@@ -126,7 +126,7 @@ Next, you'll define the private network you want your users to be able to access
![NetBird Subnet Setup](/docs-static/img/get-started/onboarding/11_entire-subnet.jpeg)
### Add and Configure a Routing Peer
A [routing peer](https://docs.netbird.io/manage/network-routes/routing-traffic-to-private-networks) is a NetBird peer that lives inside your private network and acts as a gateway, forwarding traffic between your remote users and the internal resources.
A [routing peer](https://docs.netbird.io/manage/network-routes) is a NetBird peer that lives inside your private network and acts as a gateway, forwarding traffic between your remote users and the internal resources.
![Adding a routing peer](/docs-static/img/get-started/onboarding/12_add-routing-peer.jpeg)

4
src/pages/get-started/install/android-tv.mdx
View File

@@ -81,6 +81,6 @@ the SSO flow, the QR code dialog in the NetBird app will automatically dismiss i
## What's next?
- Manage your device's [access](/manage/access-control/manage-network-access) to the network
- Use your device for [remote access access to your home network](/manage/networks/homelab/access-home-network)
- Use your device as an [exit node](/manage/network-routes/configuring-default-routes-for-internet-traffic#make-the-peer-an-exit-node-routing-peer)
- Use your device for [remote access access to your home network](/manage/networks/use-cases/by-scenario/access-home-devices)
- Use your device as an [exit node](/manage/network-routes/use-cases/by-scenario/exit-nodes#make-the-peer-an-exit-node-routing-peer)

4
src/pages/get-started/install/tvos.mdx
View File

@@ -54,5 +54,5 @@ the SSO flow, after a few seconds the authentication dialog in the NetBird app w
## What's next?
- Manage your device's [access](/manage/access-control/manage-network-access) to the network
- Use your device for [remote access access to your home network](/manage/networks/homelab/access-home-network)
- Use your device as an [exit node](/manage/network-routes/configuring-default-routes-for-internet-traffic#make-the-peer-an-exit-node-routing-peer)
- Use your device for [remote access access to your home network](/manage/networks/use-cases/by-scenario/access-home-devices)
- Use your device as an [exit node](/manage/network-routes/use-cases/by-scenario/exit-nodes#make-the-peer-an-exit-node-routing-peer)

6
src/pages/introduction.mdx
View File

@@ -16,7 +16,7 @@ behind the hassle of opening ports, complex firewall rules, VPN gateways, etc.
<Note>
NetBird is an **[open-source](https://github.com/netbirdio/netbird)** project and can be self-hosted.
See a comparison between the self-hosted and cloud-hosted versions [here](/selfhosted/self-hosted-vs-cloud-netbird).
See a comparison between the self-hosted and cloud-hosted versions [here](/about-netbird/self-hosted-vs-cloud).
</Note>
There is no centralized VPN server with NetBird - your computers, devices, machines, and servers connect to each other directly over a fast encrypted tunnel.
@@ -55,13 +55,13 @@ It literally takes less than 5 minutes to deploy a secure point-to-point VPN wit
description: 'Discover how to add team members to your NetBird network and manage user access.',
},
{
href: '/manage/network-routes/routing-traffic-to-private-networks',
href: '/manage/network-routes',
name: 'Route Traffic to Private Networks',
description:
'Learn how to provide secure access to LANs, VPS instances, and corporate private networks.',
},
{
href: '/manage/network-routes/configuring-default-routes-for-internet-traffic',
href: '/manage/network-routes/use-cases/by-scenario/exit-nodes',
name: 'Configure Default Routes',
description: 'Set up default routes for internet traffic and configure exit nodes for your network.',
},

4
src/pages/manage/access-control/posture-checks/connecting-from-the-office.mdx
View File

@@ -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/routing-traffic-to-private-networks), 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 [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.
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.
@@ -51,7 +51,7 @@ We are now ready for the final step of creating the office route.
### Create a Network Route
Now, let's create a [Network Route](https://docs.netbird.io/manage/network-routes/routing-traffic-to-private-networks) that will expose the local office subnet `192.168.1.0/24`,
Now, let's create a [Network Route](https://docs.netbird.io/manage/network-routes) that will expose the local office subnet `192.168.1.0/24`,
which will be distributed to all peers members of the group `route-users`. In this example, we will be using a routing peer named `router-01`,
which is a member of the group `route-nodes`, this way, the policy we just created goes into effect, and all peers from the group `route-users` will be able to reach
`router-01` only if they are not in the office network, due to our posture check.

4
src/pages/manage/dns/private-dns-behind-routing-peers.mdx
View File

@@ -37,7 +37,7 @@ Set up a NetBird Network so clients can reach the DNS server:
- Routing peer: The always-on peer that can access this network
<Note>
For detailed instructions on creating network routes, see [Routing Traffic to Private Networks](/manage/network-routes/routing-traffic-to-private-networks).
For detailed instructions on creating network routes, see [Routing Traffic to Private Networks](/manage/network-routes).
</Note>
### Step 3: Configure Access Control
@@ -67,6 +67,6 @@ This forwarder port is internal to NetBird's routing mechanism - you don't need
## Next Steps
- **[Configuring Nameservers](/manage/dns/nameserver-groups)** - Learn more about DNS configuration
- **[Network Routes](/manage/network-routes/routing-traffic-to-private-networks)** - Understand routing to private networks
- **[Network Routes](/manage/network-routes)** - Understand routing to private networks
- **[Access Control](/manage/access-control/manage-network-access)** - Configure network access policies
- **[DNS Troubleshooting](/manage/dns/troubleshooting)** - Fix common DNS issues

129
src/pages/manage/network-routes/configuring-default-routes-for-internet-traffic.mdx
View File

@@ -1,129 +0,0 @@
# Configuring default routes for Internet traffic
NetBird introduces a way to redirect a peer's internet traffic through what is commonly known as exit nodes.
This setup allows you to direct all internet-bound traffic from your devices through a specified routing
peer.
<Note>
This feature is available from Netbird version v0.27.0 onwards.
</Note>
## Concepts
### Default Routes
A default route, specified with the network address `0.0.0.0/0` for IPv4 and `::/0` for IPv6, directs internet-bound
traffic from your devices
through a designated routing peer.
<Note>
Currently, IPv6 traffic is not supported and is blocked to prevent unintentional traffic leakage.
</Note>
### Routing Peer
The routing peer functions as the exit node for the Internet traffic. Once configured, it automatically handles traffic
it receives from connected peers, applying masquerading to ensure traffic appears to originate from the routing peer's
public IP address.
### Distribution Groups
Peers within the specified distribution group are configured to send their Internet traffic to the routing peer over the
VPN.
This setup is activated as soon as the routing peer is connected.
### Exit Node Selection and Auto Apply Behavior
Administrators configure exit nodes from the dashboard, and can optionally mark the default route (0.0.0.0/0) as selected by default. Clients will then auto-apply the selected exit node if the route is configured with **Auto Apply** or the user has made a local choice on the device.
- **Auto Apply**: when enabled on an exit node route, clients will auto-apply that exit node. Users can still manually disable it from the client if they choose to use that exit node.
- **Client override**: if a user selects or deselects an exit node on their device, that local choice takes precedence over the management server’s preference. This includes the ability to deselect a forced/selected route sent by management.
<Note>
Management can provide preferences for exit node selection, but the client user’s explicit selection or deselection is always respected on that device.
</Note>
<Note>
Exit node auto-apply feature requires NetBird client **v0.55.0** or later.
</Note>
### Existing exit node routes
Exit node routes that existed before the Auto Apply feature are treated as if **Auto Apply** is enabled by default. This preserves previous behavior where exit nodes were applied automatically when distributed.
- Clients running v0.55.0 or later will auto-apply these existing routes unless the user has explicitly selected/deselected an exit node on the device.
- Administrators can edit any exit node route in the dashboard to change its Auto Apply setting at any time.
## Configuration Steps
### Access the Dashboard peers tab
Navigate to the NetBird dashboard to begin the configuration process.
<p>
<img src="/docs-static/img/manage/network-routes/configuring-default-routes-for-internet-traffic/netbird-peers.png" alt="dashboard-peers-view"
className="imagewrapper-big"/>
</p>
### Select the designated routing peer
<p>
<img src="/docs-static/img/manage/network-routes/configuring-default-routes-for-internet-traffic/netbird-peers-routing-peer.png" alt="routing-peer-view"
className="imagewrapper-big"/>
</p>
### Make the peer an exit node routing peer
Hit the `Add Exit Node` button to configure the peer as an exit node routing peer.
In the opened window, specify which peers should use the default route by assigning one or more distribution groups.
These peers will automatically route their internet traffic through the routing peer upon its connection.
<p>
<img src="/docs-static/img/manage/network-routes/configuring-default-routes-for-internet-traffic/netbird-peers-add-exit-node.png" alt="add-exit-node-view"
className="imagewrapper-big"/>
</p>
If you want exit nodes to be available without being automatically enabled on clients, disable the **Auto Apply** option. When Auto Apply is on, clients will auto-apply the exit node, but users can manually disable it from the client.
<p>
<img src="/docs-static/img/manage/network-routes/configuring-default-routes-for-internet-traffic/exit-node-auto-apply.png" alt="exit-node-auto-apply" className="imagewrapper-big"/>
</p>
Then hit the `Add Exit Node` button to complete the configuration.
The routing peer is automatically set up to handle and route traffic it receives from connected peers. Masquerading
remains enabled by default to mask the original source IP addresses.
### Verify the configuration
Verify the configuration in the peer view. The routing peer should now be marked as an exit node.
<p>
<img src="/docs-static/img/manage/network-routes/configuring-default-routes-for-internet-traffic/netbird-peers-routing-peer-exit-node.png" alt="routing-peer-exit-node-view"
className="imagewrapper-big"/>
</p>
### DNS Configuration
Add a DNS server with the match domain set to `ALL`.
This is important, as locally configured DNS servers might not be accessible from the routing peer.
This also helps to avoid leaking the client's location.
See [Manage DNS in your network](/manage/dns).
## High Availability
Like for other network routes, high availability configurations are supported for default
routes. Refer to
the [Creating Highly Available Routes](/manage/network-routes/routing-traffic-to-private-networks#creating-highly-available-routes)
section for more information.
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

147
src/pages/manage/network-routes/configuring-routes-with-access-control.mdx
View File

@@ -1,147 +0,0 @@
# Configuring Routes with Access Control
<Note>
This feature is available from NetBird version 0.30.0 onwards.
</Note>
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
policies. Only traffic that meets the criteria specified in these policies can
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 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
by the access policy, not the routing peer itself.
<Note>
If an access control group was applied to the route but no route access policies are
enabled or none exist, all routed traffic will be dropped.
This contrasts with scenarios where no access control group is applied, in
which case all traffic is permitted.
</Note>
## 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 `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](/manage/network-routes/routing-traffic-to-private-networks#concepts) to learn more about the fields):
- Network identifier: `aws-eu-central-1-vpc`
- Description: `Production VPC in Frankfurt`
- Network range: `10.10.0.0/16`
- Routing peer: `server`
- Distribution Groups: `devs`
- Access Control Groups: `servers`
<p>
<img src="/docs-static/img/manage/network-routes/configuring-routes-with-access-control/network-route-acl.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Click on `Continue` to proceed.
<p>
<img src="/docs-static/img/manage/network-routes/configuring-routes-with-access-control/network-route-acl-group-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Once you fill in the route information, you can click on the `Add Route` button to save your new route.
<p>
<img src="/docs-static/img/manage/network-routes/configuring-routes-with-access-control/network-route-acl-saved.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Because you used an access control group, you will be prompted to create a new policy.
<p>
<img src="/docs-static/img/manage/network-routes/configuring-routes-with-access-control/network-route-acl-prompt.png" alt="high-level-dia" className="imagewrapper"/>
</p>
Click on the `Create Policy` button to proceed.
## 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 unidirectional policy with the following information:
- Name: `Devs to Servers`
- Description: `Devs are allowed to access servers`
- Protocol: `TCP`
- Ports: `80`
- Source Groups: `devs`
- Destination Groups: `servers`
<p>
<img src="/docs-static/img/manage/network-routes/configuring-routes-with-access-control/network-acl-create-policy.png" alt="high-level-dia" className="imagewrapper"/>
</p>
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/manage/network-routes/configuring-routes-with-access-control/network-acl-new-policy.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
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
versa), there are two configuration scenarios:
### 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.
### Without Masquerading
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.
## Behavior Changes in Version 0.30.0
Prior to version 0.30.0, routing clients would accept any traffic initiated from
routed networks behind routing peers. From version 0.30.0 onwards, routing
clients only accept return traffic for connections initiated by routing clients.
To illustrate this change, consider the following example:
```mermaid
graph LR
A[NetBird Peer A<br>Routing Client] --- B[NetBird Peer B<br>Routing Peer]
B --- C[Routed Network]
```
Pre-0.30.0: Peer A would accept connections initiated from the Routed Network
through Peer B.
Post-0.30.0: Peer A only accepts return traffic for connections it initiates to
the Routed Network through Peer B.
To allow traffic initiated from the routed network in version 0.30.0 and later:
1. Ensure masquerade is enabled for the route.
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)
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.

344
src/pages/manage/network-routes/index.mdx Normal file
View File

@@ -0,0 +1,344 @@
import { Note, Warning, Button } from '@/components/mdx'
import { Tiles } from '@/components/Tiles'
# Network Routes
Network Routes let you route traffic from NetBird peers to private networks without installing the NetBird agent on every device. A routing peer forwards packets between your NetBird mesh network and your internal networks (LANs, VPCs, data centers).
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes.png" alt="Network Routes diagram" className="imagewrapper-big"/>
</p>
<Note>
Network Routes require NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
<Warning>
By default, Network Routes bypass Access Control rules. Traffic flows freely to routed networks unless you [configure access control explicitly](/manage/network-routes/use-cases/by-configuration/access-control). See [Network Routes caveats](#network-routes-caveats) for details.
</Warning>
## Network Routes vs Networks
[Networks](/manage/networks) is the newer, simpler replacement for Network Routes. We recommend using Networks where possible; however, Networks do not yet support all remote access scenarios. Network Routes will continue to be maintained, so choose whichever fits your use case.
For a detailed comparison, see our [site-to-site documentation](/use-cases/site-to-site).
## Key Concepts
### Network Identifiers and Ranges
A **network identifier** is a name for the network you want to route. A **range** is an IP address block in CIDR notation representing the external network. Together, an identifier and its ranges form a single network route.
### Routing Peer
A routing peer is a NetBird device that forwards traffic between the NetBird network and a private network. It must have network access to the resources you want to reach.
### Routing Group
A routing group is a set of routing peers. Each peer in the group routes packets between your routed network and other NetBird peers. Using a routing group provides automatic high availability.
### Masquerade
When enabled (the default), the routing peer performs NAT on forwarded traffic, hiding the original source IP. This simplifies setup by eliminating the need for return routes on the remote network.
Disable masquerade when you need source IP visibility for auditing or compliance. In this case, you must configure a return route to your NetBird network in your external network infrastructure.
### Distribution Groups
Distribution Groups specify which peers receive the network route configuration. Peers belonging to these groups automatically receive the route.
<Note>
Peers must still be connected to the routing peer to use the route.
</Note>
### ACL Groups
Access Control Groups provide granular control over services within your routed network. When you associate these groups with routes, the routes inherit access control policies where the groups are defined as destinations.
Routes without ACL Groups permit unrestricted access.
### Metric
Metric determines routing peer priority in high availability configurations. Lower values indicate higher priority. Outside high availability setups, the metric has no effect.
### High Availability
A highly available route combines multiple routes with the same network identifier and ranges but different routing peers or peer groups. This provides redundant paths between your peers and external networks.
Connected peers select a routing peer based on connection type and metric priority.
### DNS Routes
Instead of specifying network ranges directly, you can use DNS routes. Add domains to a route, and the client dynamically resolves them. The resolved IP addresses become routes.
For example, route traffic to `website.com` or `api.website.com` through a specific machine by configuring DNS routes for these domains instead of specifying IP ranges.
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-dns-routes.png" alt="DNS Routes diagram" className="imagewrapper"/>
</p>
By default, DNS routes resolve every 60 seconds. Adjust this interval with the `--dns-router-interval` flag:
```bash
netbird up --dns-router-interval 30s
```
The **Keep routes** option is enabled by default. When enabled, if a domain stops resolving to an IP address, the existing route remains (and new resolved addresses are added). When disabled, routes are replaced with newly resolved addresses only.
This preserves connections during IP changes, such as DNS-based load balancing where long-running connections to a previous IP remain valid.
<Note>
DNS Routes require NetBird [v0.28.0](https://github.com/netbirdio/netbird/releases) or later. Wildcard domains are not supported.
</Note>
<Note>
Starting with NetBird v0.59.0, the local DNS forwarder port changed from `5353` to `22054` to avoid collisions. The Management Service applies the new port only when all peers in the account run v0.59.0 or newer.
</Note>
## Managing Network Routes
A network route describes a network you want to connect with your NetBird peers. It includes an identifier, network range, routing peer or peer groups, and parameters for priority and masquerading.
### Creating a Network Route
Access the **Network Routes** tab and click **Add Route**.
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-add-button.png" alt="Add route button" className="imagewrapper-big"/>
</p>
Enter your route details. In this example:
- **Network identifier:** `aws-eu-central-1-vpc`
- **Description:** `Production VPC in Frankfurt`
- **Network range:** `172.31.0.0/16`
- **Routing peer:** `ec2-demo-node`
- **Distribution Groups:** `All`
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-create.png" alt="Create network route form" className="imagewrapper" width="70%"/>
</p>
Click **Add Route** to save.
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-saved-new.png" alt="Saved network route" className="imagewrapper-big"/>
</p>
Peers connected to your routing peer can now send traffic to your external network.
### Creating a Network Route with Routing Group
Select the **Peer group** tab when creating a route to use a peer group as your routing peers. Ensure the groups contain Linux peers, as traffic routing is only supported on Linux.
Groups with multiple peers automatically provide [high availability](#high-availability).
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-groups-create.png" alt="Create route with peer group" className="imagewrapper" width="70%"/>
</p>
Click **Add Route** to save.
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-groups-saved-new.png" alt="Saved route with peer group" className="imagewrapper-big"/>
</p>
### Creating Highly Available Routes
To avoid single points of failure, we recommend installing NetBird on every resource. When that is not feasible, use high availability mode to ensure reliable connections. Multiple NetBird peers can serve as routing peers for the same private network.
Enable high availability in two ways:
1. Use a peer group with multiple peers
2. Add individual peers to the route
The first option is covered [above](#creating-a-network-route-with-routing-group).
To add individual peers, click **Add Peer** in the High Availability column. Select a peer in the **Routing Peer** field, choose the **Distribution Groups**, and click **Add Route**.
This example adds `aws-nb-europe-router-az-b` to the `aws-eu-central-1-vpc` route:
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-create-ha.png" alt="Add HA peer to route" className="imagewrapper" width="70%"/>
</p>
Peers connected to either `aws-nb-europe-router-az-a` or `aws-nb-europe-router-az-b` now have highly available access to `172.31.0.0/16`.
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-saved-new-ha.png" alt="Saved HA route" className="imagewrapper-big"/>
</p>
<Note>
You can add unlimited routing peers to a highly available route. Each connected peer selects one routing peer based on metric priority (lower = higher priority) and connection type (direct or relayed).
</Note>
### Applying Different Routes to Peers with Group Attribution
Select multiple distribution groups to control which peers use each routing peer. Peers in the specified groups automatically use the route.
Ensure access control rules allow connectivity between these peers and the routing peers.
In this example, peers in `berlin-office` use `aws-nb-europe-router-az-a` to access `aws-eu-central-1-vpc`, while peers in `london-office` use `aws-nb-europe-router-az-b`:
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-groups-attribution.png" alt="Group attribution for routes" className="imagewrapper-big"/>
</p>
### Routes Without Masquerading
Disable masquerade when you need source IP transparency or want to manage routing on your external network. The routing peer forwards packets with the original NetBird peer IP intact.
This requires configuring your external network router with a return route to your NetBird network through the routing peer. Devices without the agent can then communicate with your NetBird peers.
<p>
<img src="/docs-static/img/manage/network-routes/concepts/netbird-network-routes-masquerading.png" alt="Routes without masquerading" className="imagewrapper-big"/>
</p>
## Network Routes Caveats
Unless [configured explicitly](/manage/network-routes/use-cases/by-configuration/access-control), Network 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.
### Example: Unexpected Access Through Network Routes
Consider a Network Route distributed through `Group R` (Routing Peer) to `Group A` (intended client):
<p>
<img src="/docs-static/img/manage/network-routes/concepts/route-ip-address.png" alt="Route IP address configuration" className="imagewrapper-big"/>
</p>
After creating an Access Policy granting only `ICMP` access from `Group A` to `Group R`:
<p>
<img src="/docs-static/img/manage/network-routes/concepts/policy-icmp-group-r.png" alt="ICMP policy from group A to R" className="imagewrapper-big"/>
</p>
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:
```shell
root@brys-vm-nbt-ubuntu-01:~# netbird networks ls
Available Networks:
- ID: network-route-srvs-site
Network: 192.168.100.0/24
Status: Selected
root@brys-vm-nbt-ubuntu-01:~# ping -c1 192.168.100.10
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=63 time=0.521 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.521/0.521/0.521/0.000 ms
root@brys-vm-nbt-ubuntu-01:~# curl 192.168.100.10/health && echo
OK
```
### Mixing Network Routes and Networks
When using both Network 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`:
<p>
<img src="/docs-static/img/manage/network-routes/concepts/resource-domain.png" alt="Wildcard domain resource" className="imagewrapper-big"/>
</p>
An HTTP-only policy grants access from `manual:client`:
<p>
<img src="/docs-static/img/manage/network-routes/concepts/policy-http.png" alt="HTTP-only policy" className="imagewrapper-big"/>
</p>
HTTP access works as expected:
```shell
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
Available Networks:
- ID: *.nb.test
Domains: *.nb.test
Status: Selected
Resolved IPs: -
root@brys-vm-nbt-ubuntu-02:~# curl srv.nb.test/health; echo
OK
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
Available Networks:
- ID: *.nb.test
Domains: *.nb.test
Status: Selected
Resolved IPs:
[srv.nb.test.]: 192.168.100.10
```
However, ICMP and SSH also work, which violates the HTTP-only policy:
```shell
root@brys-vm-nbt-ubuntu-02:~# ping -c1 srv.nb.test
PING srv.nb.test (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=63 time=0.242 ms
--- srv.nb.test ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.242/0.242/0.242/0.000 ms
root@brys-vm-nbt-ubuntu-02:~# ssh srv.nb.test
root@srv.nb.test: Permission denied (publickey).
```
### Why Does This Happen?
The Routing Peer belongs to both routing groups:
1. `m:group-r` for the Network Route
2. `manual:router:srvs` for the Network and its domain Resource
<p>
<img src="/docs-static/img/manage/network-routes/concepts/network-routers.png" alt="Network routers configuration" className="imagewrapper-big"/>
</p>
<p>
<img src="/docs-static/img/manage/network-routes/concepts/routing-peer-groups.png" alt="Routing peer groups" className="imagewrapper-big"/>
</p>
The Network Route grants unrestricted access to the network range, bypassing the HTTP-only restriction on the Network Resource.
<Note>
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.
</Note>
<Tiles
title="Use Cases"
items={[
{
href: '/manage/network-routes/use-cases',
name: 'Use Cases Overview',
description: 'Site-to-Site, Site-to-VPN, and configuration scenarios',
},
{
href: '/manage/network-routes/use-cases/by-scenario/exit-nodes',
name: 'Exit Nodes',
description: 'Route all internet traffic through a specific peer',
},
{
href: '/manage/network-routes/use-cases/by-configuration/access-control',
name: 'Access Control',
description: 'Use ACL Groups to control who can access routed networks',
},
{
href: '/manage/network-routes/use-cases/by-configuration/overlapping-routes',
name: 'Overlapping Routes',
description: 'Handle scenarios where multiple routes have the same CIDR',
},
]}
/>
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

93
src/pages/manage/network-routes/resolve-overlapping-routes.mdx
View File

@@ -1,93 +0,0 @@
# Resolve overlapping routes with the route selection feature
NetBird [Network Routes](/manage/network-routes/routing-traffic-to-private-networks) feature enables peers to access external networks such as VPCs, LANs,
or office networks seamlessly.
In most scenarios, network administrators connect their NetBird peers to these external networks by defining a network route,
which includes specifying a network range, such as `172.17.0.0/16`, and assigning a routing peer.
However, challenges arise when multiple networks have overlapping network ranges. To solve this, NetBird introduces
a route selection feature. This feature allows users to explicitly choose which routes to apply on the client side, ensuring
that peers connect to the correct network without conflicts.
<Note>
The route selection feature is available in the NetBird client version `v0.27.4` and later.
</Note>
## How to use the route selection feature
There are two ways to use the route selection feature:
- Command line interface (CLI) via the `netbird routes` command.
- GUI via the NetBird system tray application.
### Select routes using the CLI
To list available routes using the CLI, you can use the `netbird routes list` command:
```bash
demo@netbird:~$ netbird routes list
Available Routes:
- ID: aws-vpc-ireland
Network: 172.17.0.0/16
Status: Selected
- ID: aws-vpc-ohio
Network: 172.17.0.0/16
Status: Selected
```
In the example above, we have two routes with overlapping network ranges. Both of them are selected, which means that they are active on the client side and conflicting.
To select a specific route, you can use the `netbird routes select` command. You can provide a list of routes
```bash
demo@netbird:~$ netbird routes select aws-vpc-ireland
Routes selected successfully.
```
<Note>
When running the `netbird routes select` command, the NetBird client will automatically deselect all other routes by default.
</Note>
Below are some examples of how to use the `netbird routes select` command:
```bash
# select all routes
netbird routes select all
# select multiple routes
netbird routes select route1 route2
# append a route to the selected routes without deselecting the others
netbird routes select -a route3
```
### Select routes using the GUI
To select routes using the GUI, you can open the NetBird system tray application and navigate to the `Network Routes` menu.
You can select or deselect routes by clicking on the checkbox next to the route name.
<p>
<img src="/docs-static/img/manage/network-routes/resolve-overlapping-routes/select-network-routes.png" alt="select-network-routes" className="imagewrapper-big"/>
</p>
### Enabling All Routes
When using the command `netbird routes select all` in the CLI or the button in the GUI,
all currently available routes are selected. This action includes any new routes that become available in the future.
This basically restores the default behavior of the NetBird client, where all routes are selected by default.
### Disabling All Routes
When using the command `netbird routes deselect all` in the CLI or the button GUI, all routes are deselected.
This applies not only to the currently available routes but also to any routes that might be added in the future.
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

364
src/pages/manage/network-routes/routing-traffic-to-private-networks.mdx
View File

@@ -1,364 +0,0 @@
# Routing Traffic to Private Networks
<YouTube videoId="VQuPuBOAknQ" />
<br/><br/>
<Note>
**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](/manage/network-routes/configuring-routes-with-access-control).
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 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, 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.
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes.png" alt="high-level-dia" className="imagewrapper-big"/>
</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 easy to use.
</Note>
## Concepts
### Network routes
A network route describes the network you want to connect with your NetBird peers. It has an identifier, a network range or list of domains, a routing peer, and some parameters available for managing priority and masquerading.
<Note>
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.
**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.
**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.
_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.
By default, DNS routes are resolved every 60 seconds. You can adjust this interval using the `--dns-router-interval` flag:
```bash
netbird up --dns-router-interval 30s
```
Additionally, the keep routes switch is enabled by default.
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-dns-routes.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
When the keep routes switch is on, and a domain no longer resolves to an IP address, the corresponding route will still be maintained (and any new resolved IP addresses will be added).
If the switch is off, the routes will be replaced with the newly resolved IP addresses.
The purpose of the keep routes functionality is to retain previously resolved routes after IP address updates, in order to maintain stable connections. For example, long-running connections to an IP address that are still valid even if the DNS now resolves to a different IP address (e.g., DNS-based load balancing).
<Note>
DNS Routes are available for NetBird [v0.28.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
<Note>
Currently, wildcard domains are not supported for DNS routes.
</Note>
<Note>
DNS Forwarder port change: starting with NetBird v0.59.0, the local DNS forwarder used for routed DNS routes switches from port <code>5353</code> to <code>22054</code> to avoid collisions on client devices. For backward compatibility, the Management Service applies the new port only when <strong>all peers in the account</strong> run v0.59.0 or newer. If any peer is below v0.59.0, port <code>5353</code> will be used for all peers in that account.
</Note>
### Metric and priority
Metric defines prioritization when choosing the main routing peer in a high availability network. Lower metrics have higher priority.
Outside of high availability routes, the metric has no effect.
### Distribution groups
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>
This does not remove the need for the routing peer to be connected to these peers.
</Note>
### Access Control Groups
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 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
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
Access the `Network Routes` tab and click the `Add Route` button to create a new 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/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-add-button.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Now you can enter the details of your route.
In the example below, we are creating a route with the following information:
- Network identifier: `aws-eu-central-1-vpc`
- Description: `Production VPC in Frankfurt`
- Network range: `172.31.0.0/16`
- Routing peer: `ec2-demo-node`
- Distribution Groups: `All`
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-create.png" alt="high-level-dia" className="imagewrapper" width="70%"/>
</p>
Once you fill in the route information, you can click on the `Add Route` button to save your new route.
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-saved-new.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
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
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).
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-groups-create.png" alt="high-level-dia" className="imagewrapper" width="70%"/>
</p>
Once you fill in the route information, you can click on the `Add Route` button to save your new route.
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-groups-saved-new.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
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.
There are two options to enable HA routes:
1. Use a peer group with more than one peer in it.
2. Add more individual peers to the route.
The first option is covered [above](#creating-a-network-route-with-routing-group).
To enable the high-availability mode by adding individual peers, click on `Add Peer` in the High Availability column in the Network Routes
table and select a peer in the `Routing Peer` field. Then select the `Distribution Groups` and click on `Add Route`. This
routing configuration will be distributed to machines in the selected groups `Distribution Groups`.
In the following example, we are adding the peer `aws-nb-europe-router-az-b` to the `aws-eu-central-1-vpc` route:
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-create-ha.png" alt="high-level-dia" className="imagewrapper" width="70%"/>
</p>
This way, peers connected to `aws-nb-europe-router-az-a` and `aws-nb-europe-router-az-b` will have highly available access to the `172.31.0.0/16` network.
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-saved-new-ha.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
<Note>
The number of routes that form a highly available route is unlimited.
Each connected peer will pick one routing peer to use as the router for a network.
NetBird agent bases this decision on metric prioritization (lower the metric, higher the priority) and connection attributes like direct or relayed connections.
</Note>
### Apply different routes to peers with group attribution
You can select as many distribution groups as you want for your network route.
Peers that belong to the specified group will use the route automatically to connect to the underlying network.
Remember to link groups to peers that need to access the route and, if required,
add access control rules ensuring connectivity between these peers and the routing peers.
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.
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/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-groups-attribution.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### 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 will not hide any NetBird peer IP and will forward the packets to the target network transparently.
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/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes-masquerading.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
## Network Routes caveats
Unless [configured explicitly](/manage/network-routes/configuring-routes-with-access-control), the **Network Routes** feature will not take into
consideration any of the Access Control rules. This might lead to surprising outcomes, which may initially appear to be security vulnerabilities.
**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**.
### Example: Network Route Configuration
Let's assume a **Network Route** is distributed through `Group R` (Routing Peer) to `Group A` (intended client):
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/route-ip-address.png" alt="route-ip-address" className="imagewrapper-big"/>
</p>
After creating an **Access Policy** granting `ICMP` access from `Group A` to `Group R`:
<p>
<img src="/docs-static/img/manage/network-routes/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 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
Available Networks:
- ID: network-route-srvs-site
Network: 192.168.100.0/24
Status: Selected
root@brys-vm-nbt-ubuntu-01:~# ping -c1 192.168.100.10
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=63 time=0.521 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.521/0.521/0.521/0.000 ms
root@brys-vm-nbt-ubuntu-01:~# curl 192.168.100.10/health && echo
OK
```
### Setting up a Network Resource secured by HTTP policy
In the following example, we set up a **Network Resource** for a `*.nb.test` wildcard domain
using ACL group `manual:srvs`:
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/resource-domain.png" alt="*.nb.test domain Resource" className="imagewrapper-big"/>
</p>
Granting HTTP-only access to that resource from group `manual:client`:
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/policy-http.png" alt="a HTTP-only policy from manual:client group" className="imagewrapper-big"/>
</p>
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
Available Networks:
- ID: *.nb.test
Domains: *.nb.test
Status: Selected
Resolved IPs: -
root@brys-vm-nbt-ubuntu-02:~# curl srv.nb.test/health; echo
OK
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
Available Networks:
- ID: *.nb.test
Domains: *.nb.test
Status: Selected
Resolved IPs:
[srv.nb.test.]: 192.168.100.10
```
Before finishing, let's verify that only HTTP access is granted:
```shell
root@brys-vm-nbt-ubuntu-02:~# ping -c1 srv.nb.test
PING srv.nb.test (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=63 time=0.242 ms
--- srv.nb.test ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.242/0.242/0.242/0.000 ms
```
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 inadvertently grant access to the **Network Route**?
```shell
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
Available Networks:
- ID: *.nb.test
Domains: *.nb.test
Status: Selected
Resolved IPs:
[srv.nb.test.]: 192.168.100.10
```
This does not appear to be the case.
### 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**:
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/network-routers.png" alt="Network's `manual:router:srvs` router" className="imagewrapper-big"/>
</p>
Here are this specific **Routing Peer**'s details:
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/routing-peer-groups.png" alt="Routing Peer's detail page with Network Route handling" className="imagewrapper-big"/>
</p>
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 its domain **Resource**,
<Note>
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**).
While this is achievable, it is extremely easy to miss during configuration.
</Note>
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

119
src/pages/manage/network-routes/use-cases/by-configuration/access-control.mdx Normal file
View File

@@ -0,0 +1,119 @@
# Configuring Routes with Access Control
<Note>
This feature requires NetBird version 0.30.0 or later.
</Note>
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.
## How Route Access Policies Work
Route access policies are unidirectional and apply only from routing clients to routing peers. The access control group takes effect only when used as a destination group in a policy.
If you assign an empty group (one containing no peers) as the access control group, only the routed network is affected by the policy, not the routing peer itself.
<Note>
If you assign an access control group to a route but no route access policies exist or are enabled, all routed traffic will be dropped. This differs from routes without an access control group, which permit all traffic.
</Note>
## Creating a Network Route with Access Control
To create a network route with access control groups, navigate to **Network Routes** and click **Add Route**.
In this example, we create a route with the following settings (see [Key Concepts](/manage/network-routes#key-concepts) for field descriptions):
- **Network identifier:** `aws-eu-central-1-vpc`
- **Description:** `Production VPC in Frankfurt`
- **Network range:** `10.10.0.0/16`
- **Routing peer:** `server`
- **Distribution Groups:** `devs`
- **Access Control Groups:** `servers`
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-configuration/access-control/network-route-acl.png" alt="Network route configuration with access control" className="imagewrapper-big"/>
</p>
Click **Continue** to proceed.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-configuration/access-control/network-route-acl-group-settings.png" alt="Network route group settings" className="imagewrapper-big"/>
</p>
Complete the configuration and click **Add Route** to save.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-configuration/access-control/network-route-acl-saved.png" alt="Saved network route" className="imagewrapper-big"/>
</p>
Because you assigned an access control group, you will be prompted to create a policy:
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-configuration/access-control/network-route-acl-prompt.png" alt="Policy creation prompt" className="imagewrapper"/>
</p>
Click **Create Policy** to continue.
## Creating an Access Control Policy
If you skipped the prompt, navigate to **Access Control** > **Policies** and click **Add policy**.
Specify source and destination groups, configure protocol settings, and add Posture Checks if needed. Traffic direction applies only when TCP or UDP is selected.
In this example, we create a policy with:
- **Name:** `Devs to Servers`
- **Description:** `Devs are allowed to access servers`
- **Protocol:** `TCP`
- **Ports:** `80`
- **Source Groups:** `devs`
- **Destination Groups:** `servers`
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-configuration/access-control/network-acl-create-policy.png" alt="Create access control policy" className="imagewrapper"/>
</p>
You can create new groups by typing a name in the source or destination input fields.
Click **Add Policy** to save. The policy appears in the table.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-configuration/access-control/network-acl-new-policy.png" alt="New policy in table" className="imagewrapper-big"/>
</p>
With this configuration, peers connected to your routing peer can only access port 80 on the routed network.
## Site-to-Site Traffic Configuration
For site-to-site traffic where routes exist in both directions (with each peer serving as both a distribution group member and a routing peer), configuration depends on masquerading:
### With Masquerading Enabled
Enable masquerading to apply route access policies to site-to-site traffic. Create two policies, one for each direction.
### Without Masquerading
When masquerading is disabled, access control groups are not required. Traffic flows unrestricted in both directions.
Choose the configuration that matches your security requirements.
## Behavior Changes in Version 0.30.0
Before version 0.30.0, routing clients accepted any traffic initiated from routed networks. From version 0.30.0 onwards, routing clients only accept return traffic for connections they initiated.
**Example:**
```mermaid
graph LR
A[NetBird Peer A<br>Routing Client] --- B[NetBird Peer B<br>Routing Peer]
B --- C[Routed Network]
```
- **Pre-0.30.0:** Peer A accepted connections initiated from the routed network through Peer B.
- **Post-0.30.0:** Peer A only accepts return traffic for connections it initiates.
To allow traffic initiated from the routed network in version 0.30.0 and later:
1. Enable masquerade for the route.
2. Add a peer access policy allowing traffic from the routing peer to the routing client (Peer B to Peer A). This is required whether or not route access policies exist.
This allows the routing client (Peer A) to accept incoming traffic from the routing peer (Peer B) that originates from the routed network.

301
src/pages/manage/network-routes/use-cases/by-configuration/advanced-configuration.mdx Normal file
View File

@@ -0,0 +1,301 @@
import { Note, Warning } from '@/components/mdx'
# Advanced Configuration
This guide covers technical details for site-to-site connectivity, including masquerade options, access control, and troubleshooting.
## Understanding Masquerade
Masquerade determines how source IP addresses are handled when traffic passes through a routing peer.
### With Masquerade (Default)
The routing peer performs NAT on forwarded traffic:
- Source IP is replaced with the routing peer's NetBird IP
- Return traffic is automatically translated back
- No additional routing configuration is needed on remote networks
```
Device A (192.168.1.50) → Routing Peer → [Source becomes 100.64.0.10] → Remote Network
```
**Advantages:**
- Works out of the box
- No configuration needed on the remote network
- Compatible with Networks and Network Routes
**Disadvantages:**
- Original source IP is hidden
- Access control is limited to the routing peer level
- Audit logs show the routing peer IP, not the original device
### Without Masquerade
Original source IPs are preserved:
- Traffic appears to come from the original device
- Remote network must have routes back to the source network
- Required for some compliance and auditing scenarios
```
Device A (192.168.1.50) → Routing Peer → [Source stays 192.168.1.50] → Remote Network
```
**Advantages:**
- Source IP preserved for auditing
- More accurate traffic analysis
- Required for certain network configurations
**Disadvantages:**
- Requires manual route configuration on both ends
- NetBird access control cannot restrict individual source devices
- More complex setup
<Warning>
Without masquerade, traffic from unknown source IPs is rejected by NetBird's policy engine. You cannot use ACL Groups or Network Resources without masquerade enabled.
</Warning>
## Choosing the Right Approach
| Requirement | Recommended Approach |
|------------|---------------------|
| Simple remote access | Networks with masquerade |
| Site-to-site with access control | Network Routes with masquerade and ACL Groups |
| Audit trail needs source IPs | Network Routes without masquerade + OS firewall |
| Compliance requirements | Depends on specific requirements |
## Network Routes with ACL Groups
ACL Groups provide route-level access control when using Network Routes with masquerade.
### How ACL Groups Work
1. Create a Network Route with an ACL Group assigned
2. Create access policies that grant access to the ACL Group
3. Only peers with matching policies can use the route
### Configuration Example
**Step 1: Create the Network Route**
1. Go to **Network Routes**
2. Add a route for `192.168.100.0/24`
3. Select your routing peer
4. Enable Masquerade
5. Add ACL Group: `remote-resources`
**Step 2: Create Access Policies**
For the route to be active, create a policy granting access to the routing peer:
```
Source: any-group → Destination: routing-peer-group (any protocol)
```
To grant access to the routed network:
```
Source: authorized-users → Destination: remote-resources (TCP, specific ports)
```
<Note>
The routing peer must be accessible via a policy for the route to activate. The route itself is controlled by policies targeting the ACL Group.
</Note>
## Site-to-Site Configuration
### Bidirectional Route Setup
Site-to-site requires routes in both directions:
**Site A to Site B:**
- Network Route: Site B's subnet
- Routing Peer: Site A's routing peer
- Masquerade: Enabled (recommended)
**Site B to Site A:**
- Network Route: Site A's subnet
- Routing Peer: Site B's routing peer
- Masquerade: Enabled (recommended)
### Access Policies for Site-to-Site
At minimum, routing peers need connectivity:
```
Source: site-a-routing-peers → Destination: site-b-routing-peers (All)
```
For ACL Group-controlled access:
```
Source: site-a-resources → Destination: site-b-resources (specific protocols)
Source: site-b-resources → Destination: site-a-resources (specific protocols)
```
### Configuring Clientless Devices
Devices without NetBird need routes to remote networks through the local routing peer.
**Linux:**
```bash
# Temporary route
sudo ip route add 192.168.200.0/24 via 192.168.100.10
# Persistent route (Ubuntu/Debian with Netplan)
# Edit /etc/netplan/01-netcfg.yaml
network:
ethernets:
eth0:
routes:
- to: 192.168.200.0/24
via: 192.168.100.10
```
**Windows (PowerShell as Administrator):**
```powershell
# Temporary route
route add 192.168.200.0 mask 255.255.255.0 192.168.100.10
# Persistent route
route -p add 192.168.200.0 mask 255.255.255.0 192.168.100.10
```
**macOS:**
```bash
# Temporary route
sudo route add -net 192.168.200.0/24 192.168.100.10
# Persistent routes require a launch daemon or network configuration tool
```
**Router-level (recommended):**
Configure your router to advertise routes via DHCP or add static routes for all devices on the network.
## Networks vs Network Routes
| Aspect | Networks | Network Routes |
|--------|----------|----------------|
| Supported scenarios | VPN-to-Site only | 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 |
| Routing peer redundancy | Built-in | Manual configuration |
| Policy requirement | Resource policies only | Routing peer + ACL Group policies |
## Troubleshooting
### Route Not Active
**Symptoms:** Peers do not see the route; `netbird routes list` shows nothing
**Causes:**
1. No access policy grants access to the routing peer
2. Routing peer is offline
3. ACL Group has no policies granting access
**Solution:**
- Ensure at least one policy connects to the routing peer's group
- Verify routing peer status in the dashboard
- Check that ACL Group policies exist
### Traffic Times Out
**Symptoms:** Ping or connections hang with no response
**Causes:**
1. Routing peer cannot reach the destination network
2. Masquerade is disabled and no return route exists
3. Firewall is blocking traffic
**Solution:**
- Test from the routing peer: `ping <destination>` directly
- If masquerade is off, verify return routes are configured
- Check the OS firewall on the routing peer: `iptables -L -n` or equivalent
### Connection Works One Way
**Symptoms:** Can reach the remote site but responses do not return
**Causes:**
1. Missing reverse route (site-to-site)
2. Asymmetric policies
3. Stateful firewall issues
**Solution:**
- Ensure routes exist in both directions
- Verify policies allow return traffic
- Check firewall state tracking
### Wrong Traffic Routed
**Symptoms:** Unexpected traffic going through NetBird
**Causes:**
1. Overlapping routes
2. Route priority issues
3. Incorrect subnet configuration
**Solution:**
- Review all Network Routes for overlaps
- Use more specific routes where needed
- Verify subnet CIDR notation is correct
### Debugging Commands
**On the routing peer:**
```bash
# Check NetBird status
netbird status
# List active routes
netbird routes list
# Check system routes
ip route show
# Monitor traffic (Linux)
sudo tcpdump -i any -n host 192.168.200.50
# Check forwarding is enabled
cat /proc/sys/net/ipv4/ip_forward
```
**On a client peer:**
```bash
# Check which route is being used
netbird networks ls
# Trace the path
traceroute 192.168.200.50
```
## Performance Considerations
### Routing Peer Placement
- Place routing peers on machines with good network connectivity
- Avoid routing through bandwidth-constrained links
- Consider dedicated hardware for high-traffic scenarios
### Multiple Routing Peers
For high availability or load distribution:
- Deploy multiple routing peers for the same route
- NetBird distributes traffic across available peers
- Monitor peer health and remove failed peers promptly
### Monitoring
Track these metrics for routing peers:
- CPU and memory usage
- Network throughput
- Connection count
- Packet loss and latency
Use NetBird's [activity logging](/manage/activity) to monitor access patterns and troubleshoot issues.

72
src/pages/manage/network-routes/use-cases/by-configuration/overlapping-routes.mdx Normal file
View File

@@ -0,0 +1,72 @@
# Resolving Overlapping Routes
NetBird [Network Routes](/manage/network-routes) enable peers to access external networks such as VPCs, LANs, or office networks. When multiple networks have overlapping IP ranges, NetBird's route selection feature lets you choose which routes to apply on the client side.
<Note>
Route selection requires NetBird client version 0.27.4 or later.
</Note>
## Using Route Selection
You can select routes through the CLI or the system tray GUI.
### CLI
List available routes:
```bash
netbird routes list
```
Example output:
```
Available Routes:
- ID: aws-vpc-ireland
Network: 172.17.0.0/16
Status: Selected
- ID: aws-vpc-ohio
Network: 172.17.0.0/16
Status: Selected
```
In this example, both routes have the same network range and are both selected, causing a conflict. To resolve this, select only one route:
```bash
netbird routes select aws-vpc-ireland
```
<Note>
Running `netbird routes select` deselects all other routes by default.
</Note>
Additional examples:
```bash
# Select all routes
netbird routes select all
# Select multiple routes
netbird routes select route1 route2
# Append a route without deselecting others
netbird routes select -a route3
```
### GUI
Open the NetBird system tray application and navigate to **Network Routes**. Click the checkbox next to each route to select or deselect it.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-configuration/overlapping-routes/select-network-routes.png" alt="Route selection in system tray" className="imagewrapper"/>
</p>
### Enabling All Routes
Use `netbird routes select all` in the CLI or the corresponding button in the GUI to select all available routes, including any added in the future. This restores the default behavior.
### Disabling All Routes
Use `netbird routes deselect all` in the CLI or the GUI button to deselect all routes, including any added in the future.

98
src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx Normal file
View File

@@ -0,0 +1,98 @@
# Configuring Exit Nodes for Internet Traffic
Exit nodes route all internet-bound traffic from your devices through a designated routing peer. This guide explains how to configure default routes for internet traffic.
<Note>
This feature requires NetBird version 0.27.0 or later.
</Note>
## Concepts
### Default Routes
A default route (`0.0.0.0/0` for IPv4) directs all internet traffic through a designated routing peer.
<Note>
IPv6 traffic is currently not supported and is blocked to prevent unintentional leakage.
</Note>
### Routing Peer
The routing peer acts as the exit node for internet traffic. It applies masquerading so that traffic appears to originate from the routing peer's public IP address.
### Distribution Groups
Peers in the distribution groups send their internet traffic through the routing peer once it connects.
### Exit Node Selection and Auto Apply
Administrators configure exit nodes from the dashboard and can enable **Auto Apply** to have clients automatically use the exit node.
- **Auto Apply:** When enabled, clients automatically use the exit node. Users can still disable it manually on their device.
- **Client override:** If a user selects or deselects an exit node on their device, that choice takes precedence over the server configuration.
<Note>
The client user's explicit selection or deselection always takes precedence on that device.
</Note>
<Note>
Auto Apply requires NetBird client version 0.55.0 or later.
</Note>
### Existing Exit Node Routes
Exit node routes created before the Auto Apply feature was introduced are treated as having Auto Apply enabled. This preserves the previous behavior where exit nodes were applied automatically.
Clients running v0.55.0 or later auto-apply these routes unless the user has explicitly selected or deselected an exit node. Administrators can change the Auto Apply setting at any time.
## Configuration Steps
### 1. Open the Peers Tab
Navigate to the NetBird dashboard and select the **Peers** tab.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/exit-nodes/netbird-peers.png" alt="Dashboard peers view" className="imagewrapper-big"/>
</p>
### 2. Select the Routing Peer
Choose the peer that will serve as your exit node.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/exit-nodes/netbird-peers-routing-peer.png" alt="Routing peer selection" className="imagewrapper-big"/>
</p>
### 3. Configure the Exit Node
Click **Add Exit Node**. In the dialog, assign one or more distribution groups to specify which peers should use this exit node.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/exit-nodes/netbird-peers-add-exit-node.png" alt="Add exit node dialog" className="imagewrapper-big"/>
</p>
To make the exit node available without automatic activation, disable **Auto Apply**. Users can then enable it manually.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/exit-nodes/exit-node-auto-apply.png" alt="Auto Apply option" className="imagewrapper-big"/>
</p>
Click **Add Exit Node** to complete the configuration. Masquerading is enabled by default.
### 4. Verify the Configuration
Check the peer view to confirm the routing peer is marked as an exit node.
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/exit-nodes/netbird-peers-routing-peer-exit-node.png" alt="Exit node confirmation" className="imagewrapper-big"/>
</p>
### 5. Configure DNS
Add a DNS server with the match domain set to `ALL`. Local DNS servers may not be accessible from the routing peer, and this also prevents DNS-based location leaks.
See [Manage DNS in your network](/manage/dns) for details.
## High Availability
Exit nodes support high availability configurations. See [Creating Highly Available Routes](/manage/network-routes#creating-highly-available-routes) for more information.

244
src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-cloud.mdx Normal file
View File

@@ -0,0 +1,244 @@
import { Note } from '@/components/mdx'
# Site-to-Site: Cloud Environments
This guide shows how to connect cloud VPCs across providers or bridge cloud and on-premise networks using Network Routes.
## What You'll Achieve
After following this guide, workloads across different cloud providers (AWS, GCP, Azure) or between cloud and on-premise can communicate without exposing traffic to the public internet.
```
AWS VPC ────► Routing Peer ────► NetBird ────► Routing Peer ────► GCP VPC
(10.0.0.0/16) (peer) (peer) (10.1.0.0/16)
```
<Note>
Multi-cloud Site-to-Site requires Network Routes because the Networks feature doesn't yet support this scenario.
</Note>
## Prerequisites
- A [NetBird cloud account](https://app.netbird.io/) or [self-hosted instance](/selfhosted/selfhosted-quickstart)
- Access to deploy VMs in your cloud environments
- Network configuration permissions in your cloud VPCs
## Example: Multi-Cloud Connectivity
Connect workloads across AWS and GCP:
- **AWS VPC**: `10.0.0.0/16`
- **GCP VPC**: `10.1.0.0/16`
## Step 1: Create Setup Keys with Groups
Before deploying routing peers, create setup keys with auto-assigned groups:
1. Go to **Setup Keys** in the NetBird dashboard
2. Click **Create Setup Key**
3. For AWS:
- Name: "AWS Routing Peer"
- Auto-assigned groups: Create and add `aws-routing-peers`
- Click **Create**
4. For GCP:
- Name: "GCP Routing Peer"
- Auto-assigned groups: Create and add `gcp-routing-peers`
<Note>
You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**.
</Note>
## Step 2: Deploy Routing Peers in Each Cloud
**AWS:**
Launch an EC2 instance in your VPC with NetBird installed. Use the following user data:
```bash
#!/bin/bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --setup-key YOUR_AWS_SETUP_KEY
```
**GCP:**
Launch a Compute Engine instance in your VPC:
```bash
#!/bin/bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --setup-key YOUR_GCP_SETUP_KEY
```
## Step 3: Create Network Routes
**For AWS VPC:**
1. Go to **Network Routes**
2. Click **Add Route**
3. Network range: `10.0.0.0/16`
4. Routing Peer: Select your AWS instance (or use "aws-routing-peers" Peer Group)
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-cloud/add-route-aws-vpc.png" alt="Create route for AWS VPC" className="imagewrapper"/>
</p>
5. Distribution Groups: "gcp-routing-peers"
6. Access Control Groups: "aws-routing-peers" (required for route-level policies—this group becomes the destination in access policies; without it, policies targeting this route won't apply)
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-cloud/add-route-aws-groups.png" alt="AWS route distribution and access control groups" className="imagewrapper"/>
</p>
7. Network Identifier: `aws-vpc`
8. Enable **Masquerade** (in Additional Settings)
9. Click **Add Route**
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-cloud/add-route-masquerade.png" alt="Enable masquerade in additional settings" className="imagewrapper"/>
</p>
**For GCP VPC:**
1. Click **Add Route**
2. Network range: `10.1.0.0/16`
3. Routing Peer: Select your GCP instance (or use "gcp-routing-peers" Peer Group)
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-cloud/add-route-gcp-vpc.png" alt="Create route for GCP VPC" className="imagewrapper"/>
</p>
4. Distribution Groups: "aws-routing-peers"
5. Access Control Groups: "gcp-routing-peers" (required for route-level policies—this group becomes the destination in access policies; without it, policies targeting this route won't apply)
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-cloud/add-route-gcp-groups.png" alt="GCP route distribution and access control groups" className="imagewrapper"/>
</p>
6. Network Identifier: `gcp-vpc`
7. Enable **Masquerade** (in Additional Settings)
8. Click **Add Route**
## Step 4: Create Access Policies
Create two policies allowing the routing peers to communicate in both directions:
1. Go to **Access Control > Policies**
2. Create policies between the routing peer groups:
```
Source: aws-routing-peers → Destination: gcp-routing-peers (All)
Source: gcp-routing-peers → Destination: aws-routing-peers (All)
```
For route-level access control (if Access Control Groups configured), you can restrict by protocol and port:
```
Source: aws-routing-peers → Destination: gcp-routing-peers (specific protocols)
Source: gcp-routing-peers → Destination: aws-routing-peers (specific protocols)
```
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-cloud/add-policy-aws-to-gcp-tcp.png" alt="AWS to GCP policy with TCP port 443" className="imagewrapper"/>
</p>
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-cloud/add-policy-gcp-to-aws-udp.png" alt="GCP to AWS policy with UDP port 53" className="imagewrapper"/>
</p>
## Step 5: Configure VPC Routing
**AWS VPC:**
Add a route in your route table:
- Destination: `10.1.0.0/16` (GCP CIDR)
- Target: Your NetBird routing peer instance (ENI)
**GCP VPC:**
Add a custom route:
- Destination: `10.0.0.0/16` (AWS CIDR)
- Next hop: Your NetBird routing peer instance
<Note>
Enable IP forwarding on routing peer instances in both clouds.
</Note>
## Step 6: Test Connectivity
From an AWS instance:
```bash
ping 10.1.0.100 # GCP instance
```
From a GCP instance:
```bash
ping 10.0.0.100 # AWS instance
```
## Cloud-Specific Considerations
### AWS
- Security groups must allow traffic from the NetBird routing peer
- Enable source/destination check disabled on the routing peer instance
- Consider using an Auto Scaling group for the routing peer with a static ENI
### GCP
- Firewall rules must allow traffic from the routing peer's internal IP
- Enable IP forwarding on the routing peer instance
- Use managed instance groups for high availability
### Azure
- Network security groups must allow traffic from the routing peer
- Enable IP forwarding on the routing peer NIC
- Consider using a Virtual Machine Scale Set for HA
## Secure Workload Migration
Use Site-to-Site connectivity for migrating workloads between environments:
### Example: Migrating from On-Premise to Cloud
1. **Before migration**: Application and database both on-premise
2. **During migration**: Application in cloud, database still on-premise (use VPN-to-Site via [Networks](/manage/networks/use-cases/by-scenario/cloud-to-on-premise))
3. **Cutover**: Switch traffic to the cloud application
4. **After migration**: Once database is also migrated, update connection strings and remove NetBird if no longer needed
## Best Practices
### Security
- Use dedicated setup keys per environment (dev, staging, production)
- Restrict access policies to specific ports and protocols
- Enable [activity logging](/manage/activity) for compliance
### High Availability
- Deploy multiple routing peers and configure failover
- Monitor routing peer health with your existing tools
- Use cloud-native load balancing where appropriate
### Performance
- Place routing peers close to the resources they serve
- Use direct peering where possible (NetBird will automatically optimize paths)
- Monitor latency and throughput between environments
## Troubleshooting
**Multi-cloud connectivity issues:**
1. Confirm both routing peers are connected to NetBird
2. Check VPC routing tables have correct entries
3. Verify security groups/firewall rules allow traffic
**High latency:**
1. Check routing peer placement and network connectivity
2. Verify traffic is using direct peer-to-peer connections (not relays)
3. Review cloud network configuration for bottlenecks
## Advanced Configuration
For masquerade options, ACL Groups, and detailed troubleshooting, see [Advanced Configuration](/manage/network-routes/use-cases/by-configuration/advanced-configuration).

192
src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-home.mdx Normal file
View File

@@ -0,0 +1,192 @@
import { Note } from '@/components/mdx'
# Site-to-Site: Home Networks
This guide shows how to connect two home networks together so devices can communicate across locations—without installing NetBird on every device.
## What You'll Achieve
After following this guide, devices on one home network can communicate with devices on another home network. For example:
- Your home NAS can back up to your parents' NAS
- Family members can access shared media servers
- IoT devices can communicate across homes
```
Home A: NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer ──► Parents' NAS
(no NetBird) (peer) (peer) (no NetBird)
```
<Note>
Site-to-Site requires Network Routes because the Networks feature doesn't yet support bidirectional routing between sites.
</Note>
## Prerequisites
- A [NetBird cloud account](https://app.netbird.io/) or [self-hosted instance](/selfhosted/selfhosted-quickstart)
- An always-on device at each home to serve as routing peers (Raspberry Pi, NAS with Docker, etc.)
- Different subnets at each location (if both use `192.168.1.0/24`, see [Resolve Overlapping Routes](/manage/network-routes/use-cases/by-configuration/overlapping-routes))
## Example Scenario
- **Your home**: `192.168.1.0/24` with routing peer "home-rpi"
- **Parents' home**: `192.168.2.0/24` with routing peer "parents-rpi"
## Step 1: Create Setup Keys with Groups
Before installing NetBird on your routing peers, create setup keys with auto-assigned groups:
1. Go to **Setup Keys** in the NetBird dashboard
2. Click **Create Setup Key**
3. For your home routing peer:
- Network Identifier: "Home Routing Peer"
- Auto-assigned groups: Create and add `home-routing-peers`
- Click **Create**
4. Repeat for parents' home:
- Network Identifier: "Parents Routing Peer"
- Auto-assigned groups: Create and add `parents-routing-peers`
<Note>
You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**.
</Note>
## Step 2: Install NetBird on Routing Peers
**At your home:**
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_HOME_SETUP_KEY
```
**At parents' home:**
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_PARENTS_SETUP_KEY
```
## Step 3: Create Network Routes
1. Go to **Network Routes** in the dashboard
2. Click **Add Route**
**For your home network:**
- Network range: `192.168.1.0/24`
- Routing Peer: Select "home-rpi" (or use "home-routing-peers" Peer Group)
- Distribution Groups: "parents-routing-peers"
- Access Control Groups: "home-routing-peers" (optional—for route-level policies, this group becomes the destination in access policies; without it, policies targeting this route won't apply)
- Network Identifier: `home-lan`
- Enable **Masquerade** in Additional Settings (recommended for simplicity)
- Click **Add Route**
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-home/add-new-route-home-rpi.png" alt="Create route for home network" className="imagewrapper"/>
</p>
**For parents' home network:**
- Network range: `192.168.2.0/24`
- Routing Peer: Select "parents-rpi" (or use "parents-routing-peers" Peer Group)
- Distribution Groups: "home-routing-peers"
- Access Control Groups: "parents-routing-peers" (optional—for route-level policies, this group becomes the destination in access policies; without it, policies targeting this route won't apply)
- Network Identifier: `parents-lan`
- Enable **Masquerade** in Additional Settings (recommended)
- Click **Add Route**
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-home/add-new-route-parents-rpi.png" alt="Create route for parents network" className="imagewrapper"/>
</p>
## Step 4: Create Access Policies
Create two policies that allow the routing peers to communicate in both directions:
1. Go to **Access Control > Policies**
2. Add first policy:
- Network Identifier: "Home to Parents"
- Source: "home-routing-peers"
- Destination: "parents-routing-peers"
- Protocol: All (or restrict as needed)
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-home/add-policy-home-to-parents.png" alt="Create policy for home to parents" className="imagewrapper"/>
</p>
3. Add second policy:
- Network Identifier: "Parents to Home"
- Source: "parents-routing-peers"
- Destination: "home-routing-peers"
- Protocol: All (or restrict as needed)
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-home/add-policy-parents-to-home.png" alt="Create policy for parents to home" className="imagewrapper"/>
</p>
## Step 5: Configure Clientless Devices
For devices without NetBird to reach the other network, add a static route pointing to the local routing peer.
**On a Linux device at your home:**
```bash
# Route to parents' network through your routing peer
sudo ip route add 192.168.2.0/24 via 192.168.1.100
```
Where `192.168.1.100` is your routing peer's local IP.
**On a Windows device:**
```powershell
route add 192.168.2.0 mask 255.255.255.0 192.168.1.100
```
<Note>
For persistent routes, configure them in your router's DHCP settings or the device's network configuration.
</Note>
**Router-level configuration (recommended):**
Configure your router to advertise routes via DHCP or add a static route that applies to all devices:
```
# On your home router
Destination: 192.168.2.0/24
Gateway: 192.168.1.100 (your routing peer's IP)
```
## Step 6: Test Cross-Network Access
From a device at your home:
```bash
ping 192.168.2.1 # Parents' router
ping 192.168.2.50 # Parents' NAS
```
From a device at parents' home:
```bash
ping 192.168.1.1 # Your router
ping 192.168.1.50 # Your NAS
```
## Troubleshooting
**Site-to-site not working:**
1. Verify both routing peers are online and connected: check `netbird status` on each
2. Check that static routes are configured on clientless devices
3. Ensure access policies allow traffic in both directions
**Can't reach specific devices:**
1. Verify the device has a route to the remote network
2. Check firewall rules on the target device
3. Ensure the routing peer can reach the target on its local network
**Traffic works one way but not the other:**
1. Check that both network routes exist
2. Verify access policies exist for both directions
3. Ensure static routes are configured at both ends
## Advanced Configuration
For masquerade options, ACL Groups for access control, and detailed troubleshooting, see [Advanced Configuration](/manage/network-routes/use-cases/by-configuration/advanced-configuration).

232
src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-office.mdx Normal file
View File

@@ -0,0 +1,232 @@
import { Note } from '@/components/mdx'
# Site-to-Site: Office Networks
This guide shows how to connect multiple office locations so all devices can communicate—including those without NetBird installed.
## What You'll Achieve
After following this guide, devices at different office locations can communicate with each other:
- Branch office servers can access headquarters databases
- Printers and IoT devices can be managed from any location
- Legacy systems can communicate across sites
```
HQ Server ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer ──► Branch Server
(no NetBird) (peer) (peer) (no NetBird)
```
<Note>
Site-to-Site requires Network Routes because the Networks feature doesn't yet support bidirectional routing between sites.
</Note>
## Prerequisites
- A [NetBird cloud account](https://app.netbird.io/) or [self-hosted instance](/selfhosted/selfhosted-quickstart)
- Admin access to network infrastructure at each location
- A server or VM at each location to serve as routing peers
## Example Setup
- **Headquarters**: `10.0.0.0/24` with routing peer "hq-router"
- **Branch Office**: `10.1.0.0/24` with routing peer "branch-router"
## Step 1: Create Setup Keys with Groups
Before installing NetBird on your routing peers, create setup keys with auto-assigned groups:
1. Go to **Setup Keys** in the NetBird dashboard
2. Click **Create Setup Key**
3. For headquarters:
- Name: "HQ Routing Peer"
- Auto-assigned groups: Create and add `hq-routing-peers`
- Click **Create**
4. For branch office:
- Name: "Branch Routing Peer"
- Auto-assigned groups: Create and add `branch-routing-peers`
<Note>
You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**.
</Note>
## Step 2: Deploy Routing Peers
Install NetBird on a server at each location:
**At headquarters:**
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_HQ_SETUP_KEY
```
**At branch office:**
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_BRANCH_SETUP_KEY
```
## Step 3: Create Network Routes
**For headquarters:**
1. Go to **Network Routes**
2. Click **Add Route**
3. Network range: `10.0.0.0/24`
4. Routing Peer: Select "hq-router" (or use "hq-routing-peers" Peer Group)
5. Distribution Groups: "branch-routing-peers"
6. Access Control Groups: "hq-routing-peers" (required for route-level policies—this group becomes the destination in access policies; without it, policies targeting this route won't apply)
7. Network Identifier: `hq-network`
8. Enable **Masquerade** (in Additional Settings)
9. Click **Add Route**
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-office/add-route-hq-network.png" alt="Create route for headquarters network" className="imagewrapper"/>
</p>
**For branch office:**
1. Click **Add Route**
2. Network range: `10.1.0.0/24`
3. Routing Peer: Select "branch-router" (or use "branch-routing-peers" Peer Group)
4. Distribution Groups: "hq-routing-peers"
5. Access Control Groups: "branch-routing-peers" (required for route-level policies—this group becomes the destination in access policies; without it, policies targeting this route won't apply)
6. Network Identifier: `branch-network`
7. Enable **Masquerade** (in Additional Settings)
8. Click **Add Route**
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-office/add-route-branch-network.png" alt="Create route for branch network" className="imagewrapper"/>
</p>
## Step 4: Create Access Policies
Create two policies allowing the routing peers to communicate in both directions:
```
Source: hq-routing-peers → Destination: branch-routing-peers (All protocols)
Source: branch-routing-peers → Destination: hq-routing-peers (All protocols)
```
For route-level access control (if ACL Groups configured), you can restrict by protocol and port:
```
Source: hq-routing-peers → Destination: branch-routing-peers (specific protocols)
Source: branch-routing-peers → Destination: hq-routing-peers (specific protocols)
```
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-office/add-policy-hq-to-branch-tcp.png" alt="HQ to branch policy with TCP ports 8080 and 53" className="imagewrapper"/>
</p>
<p>
<img src="/docs-static/img/manage/network-routes/use-cases/by-scenario/site-to-site-office/add-policy-branch-to-hq-tcp.png" alt="Branch to HQ policy with TCP port 443" className="imagewrapper"/>
</p>
## Step 5: Configure Network Equipment
**Option A: Router-level routes (recommended)**
Configure your routers to advertise routes to the remote network via DHCP or add static routes:
```
# On HQ router, route to branch through routing peer
Destination: 10.1.0.0/24
Gateway: 10.0.0.50 (hq-router's IP)
# On Branch router, route to HQ through routing peer
Destination: 10.0.0.0/24
Gateway: 10.1.0.50 (branch-router's IP)
```
**Option B: Per-device routes**
Add routes on individual devices that need cross-site access:
```bash
# On HQ device (Linux)
sudo ip route add 10.1.0.0/24 via 10.0.0.50
# On Branch device (Linux)
sudo ip route add 10.0.0.0/24 via 10.1.0.50
```
**Windows (PowerShell):**
```powershell
# On HQ device
route -p add 10.1.0.0 mask 255.255.255.0 10.0.0.50
# On Branch device
route -p add 10.0.0.0 mask 255.255.255.0 10.1.0.50
```
## Step 6: Test Connectivity
From a device at headquarters:
```bash
ping 10.1.0.1 # Branch router
ping 10.1.0.100 # Branch server
```
From a device at branch office:
```bash
ping 10.0.0.1 # HQ router
ping 10.0.0.100 # HQ server
```
## Site-to-VPN: Office Systems Reaching Remote Workers
Some scenarios require office systems to initiate connections to remote workers (monitoring, management tools, etc.).
### Configuration
1. Create a network route for the office network (as above)
2. On the office system that needs to reach remote workers, add a route to the NetBird network:
```bash
# Route to NetBird network through the routing peer
sudo ip route add 100.64.0.0/10 via 10.0.0.50
```
Where `10.0.0.50` is the routing peer's office IP.
3. Create two access policies allowing traffic in both directions
## Best Practices for Business Deployments
### Access Control
- Create specific groups for different access levels (IT Admin, Sales, Engineering)
- Use protocol restrictions (e.g., only allow RDP to certain servers)
- Implement time-limited setup keys for contractor access
### High Availability
For critical connections:
- Deploy multiple routing peers at each location
- Use peer groups for automatic failover
- Monitor routing peer health
### Security
- Enable [Posture Checks](/manage/access-control/posture-checks) to verify device compliance
- Use [Activity Logging](/manage/activity) to audit access
- Implement MFA through your identity provider
## Troubleshooting
**Branch office connectivity issues:**
1. Confirm both routing peers show as connected in the dashboard
2. Verify static routes are configured correctly
3. Check firewall rules aren't blocking traffic
**Slow performance:**
1. Check routing peer placement—it should have good network connectivity
2. Consider enabling [lazy connections](/manage/peers/lazy-connection) for large deployments
3. Review network route priorities if multiple routes exist
## Advanced Configuration
For masquerade options, ACL Groups, and detailed troubleshooting, see [Advanced Configuration](/manage/network-routes/use-cases/by-configuration/advanced-configuration).

136
src/pages/manage/network-routes/use-cases/index.mdx Normal file
View File

@@ -0,0 +1,136 @@
import { Tiles } from '@/components/Tiles'
import { Note, Warning } from '@/components/mdx'
# Network Routes Use Cases
These guides show how to use [Network Routes](/manage/network-routes) for Site-to-Site and Site-to-VPN connectivity—scenarios where clientless devices need to communicate across networks.
## What Are Site-to-Site and Site-to-VPN?
Network Routes enables two connectivity patterns that go beyond standard VPN-to-Site access:
**Site-to-Site** connects two networks together, with neither end-device running NetBird. Each network has a routing peer that handles traffic forwarding.
```
Home NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer ──► Office Server
(no NetBird) (peer) (peer) (no NetBird)
```
**Site-to-VPN** allows clientless devices to initiate connections to NetBird peers—the reverse of VPN-to-Site.
```
Office Server ──────► Routing Peer ──────► NetBird Tunnel ──────► Your Laptop
(no NetBird) (peer) (peer)
```
<Note>
For VPN-to-Site (NetBird peers accessing clientless devices), you can use either [Networks](/manage/networks/use-cases) (recommended for simplicity) or Network Routes.
</Note>
## Understanding Key Concepts
Network Routes provides several features that differentiate it from Networks and enable more advanced scenarios:
### Masquerade
Masquerade controls whether the routing peer hides the original source IP address when forwarding traffic:
- **Enabled (default)** — The routing peer performs NAT, making traffic appear to originate from its own IP. Simpler setup since remote networks don't need return routes.
- **Disabled** — Original source IPs are preserved, enabling accurate audit trails. Requires manual route configuration on both ends.
Use masquerade when you want simple setup. Disable it when compliance or auditing requires source IP visibility.
### Distribution Groups
Distribution Groups determine which peers receive the network route configuration. When you add peers to a distribution group, they automatically get the route—no manual configuration on each client.
For site-to-site scenarios, each site's routing peer should be in the other site's distribution group to receive routes back.
### ACL Groups
ACL Groups provide route-level access control. When you assign an ACL Group to a Network Route:
1. The route inherits access restrictions from policies targeting that group
2. Only peers with policies granting access to the ACL Group can use the route
3. Without an ACL Group, routes allow unrestricted access
<Warning>
If an ACL Group is assigned but no policies grant access to it, all routed traffic will be dropped.
</Warning>
### High Availability
Deploy multiple routing peers for the same route to provide failover. NetBird clients automatically select the best available peer based on:
- Connection type (direct vs relayed)
- Defined metric priority (lower = higher priority)
- Connection quality
## Why Use Network Routes?
Network Routes is required when you need:
- **Site-to-Site connectivity** — Connect two networks together
- **Site-to-VPN connectivity** — Clientless devices initiating connections
- **Masquerade control** — Preserve source IPs for auditing
- **ACL Groups** — Route-level access control
<Tiles
title="By Scenario"
items={[
{
href: '/manage/network-routes/use-cases/by-scenario/site-to-site-home',
name: 'Site-to-Site: Home Networks',
description: 'Connect multiple home networks so devices can communicate across locations',
},
{
href: '/manage/network-routes/use-cases/by-scenario/site-to-site-office',
name: 'Site-to-Site: Office Networks',
description: 'Connect branch offices to headquarters and enable cross-site communication',
},
{
href: '/manage/network-routes/use-cases/by-scenario/site-to-site-cloud',
name: 'Site-to-Site: Cloud Environments',
description: 'Bridge cloud VPCs across providers or connect cloud to on-premise',
},
]}
/>
<Tiles
title="By Configuration"
items={[
{
href: '/manage/network-routes/use-cases/by-scenario/exit-nodes',
name: 'Exit Nodes',
description: 'Route all internet traffic through a specific peer',
},
{
href: '/manage/network-routes/use-cases/by-configuration/access-control',
name: 'Access Control',
description: 'Use ACL Groups to control who can access routed networks',
},
{
href: '/manage/network-routes/use-cases/by-configuration/overlapping-routes',
name: 'Overlapping Routes',
description: 'Handle scenarios where multiple routes share the same CIDR',
},
{
href: '/manage/network-routes/use-cases/by-configuration/advanced-configuration',
name: 'Advanced Configuration',
description: 'Masquerade options, troubleshooting, and detailed configuration',
},
]}
/>
## Configuration Pattern
All Site-to-Site and Site-to-VPN scenarios follow this pattern:
1. **Deploy routing peers** at each site
2. **Create network routes** for each site's subnet
3. **Create access policies** allowing routing peers to communicate
4. **Configure clientless devices** to route traffic through the local routing peer
For step-by-step instructions, choose your scenario above. For technical details and troubleshooting, see [Advanced Configuration](/manage/network-routes/use-cases/by-configuration/advanced-configuration).
## Need Simpler VPN-to-Site Access?
If you only need NetBird peers to access remote resources (not site-to-site or site-to-vpn), the [Networks](/manage/networks/use-cases) feature offers a simpler setup experience with per-resource access control.

230
src/pages/manage/networks/accessing-entire-domains-within-networks.mdx
View File

@@ -1,230 +0,0 @@
# Accessing entire domains within networks
Companies often operate internal environments using assigned domains that remain inaccessible to the public for security and compliance reasons. Creating routing resources for these environments can quickly become a problem for DevOps and Platform teams, especially as different stakeholders frequently request new resources. Moreover, when these resources span across different networks, managing them becomes even more challenging.
NetBird's [Networks](https://docs.netbird.io/manage/networks) streamlines this process, allowing organizations to configure secure access to internal resources efficiently using [Wildcard domain resources](https://docs.netbird.io/manage/networks#resources). This reduces the administrative burden on IT teams and enhances overall productivity.
## Example Use Case Scenario
In this scenario, an AI software company needs secure access to its internal domains, encompassing both development and AI model training environments. This integration is vital for maintaining robust internal network security while ensuring seamless domain access across the entire network infrastructure.
### Configuration Overview
1. **Development Environment**:
- Wildcard Domain: `*.dev.example.com`
- Purpose: Provides developers with access to a shared workspace for code development, testing, and collaboration.
2. **AI Model Training Environment**:
- Wildcard Domain: `*.ai.example.com`
- Purpose: Houses sensitive AI models and datasets, requiring restricted access to ensure security and integrity.
### Implementation Steps
- **Network Setup**: Using NetBird's Networks you can configure a secure network that connects local and remote users to these internal environments through routing peers. This involves configuring wildcard domains for both environments to enable seamless access while accommodating future growth.
- **Access Control**: NetBird's [Access Policies](https://docs.netbird.io/manage/access-control/manage-network-access) allow you to implement stringent policies that enforce zero trust principles, assigning different access permissions to developers and data scientists. For instance, you can grant developers access to `*.dev.example.com`, while data scientists gain access to `*.ai.example.com`. This clear separation ensures that team members only access the resources essential to their roles, maintaining a robust security posture.
- **Operational Benefits**: This configuration supports uninterrupted workflows, allowing developers and data scientists to work efficiently without connectivity issues. Furthermore, NetBird's centralized management of routing peers simplifies handling resources distributed across different networks, ensuring seamless connectivity and reducing complexity. Additionally, the process of creating new resources is streamlined, reducing administrative overhead and accelerating responses to frequent resource requests.
## Pre-requisites
To effectively access entire domains within your internal networks using NetBird, ensure the following pre-requisites are met:
- **NetBird Clients**: Install [NetBird clients](https://docs.netbird.io/get-started) on all devices used by developers and data scientists. This is essential to establish secure connectivity to your internal resources.
- **Routing Peers**: Configure [NetBird routing peers](https://docs.netbird.io/manage/networks#routing-peers) within your network infrastructure using [setup keys](https://docs.netbird.io/manage/peers/access-infrastructure/setup-keys-add-servers-to-network). Routing peers facilitate traffic routing across different network segments, ensuring seamless access to both internal domains.
- **Nameserver Configuration**: Ensure that your Nameservers are properly configured within your NetBird account to resolve all domain queries. This step is critical for enabling seamless domain name resolution across your network, facilitating efficient connectivity to both your development and AI model training environments. For detailed instructions, refer to the [Manage DNS in Your Network](https://docs.netbird.io/manage/dns).
## Enabling DNS Wildcard Routing
Enabling DNS wildcard routing is crucial for handling sub-domain requests across your development and AI model training environments, ensuring seamless access for developers and data scientists to all necessary subdomains without requiring additional configuration.
Note that enabling DNS wildcard routing shifts the DNS resolution responsibility from the local client system to the routing peer. Compared to the previous behavior of DNS routes via network routes, this transition facilitates enhanced access control rules available in newer NetBird client versions and optimizes traffic management by directing queries to the nearest routing peer service. This setup simplifies the DNS management process and bolsters security and network efficiency.
<Note>
(1) Support for more restricted rules will be available in future releases.
</Note>
To enable DNS wildcard routing in your NetBird account, follow these steps:
* Navigate to `Settings` > `Networks` within your NetBird account.
* `Enable DNS wildcard routing` by toggling the appropriate setting. This will allow your network to resolve all subdomains under a specified domain.
![Enabling DNS wildcard routing](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/01-domains-within-networks.png)
<Note>
The `Enable DNS wildcard routing` is supported by routing peers and routing clients running version `0.35.0` or later.
Once the feature is enabled, you may need to restart your routing peers and clients to apply the changes.
</Note>
<Note>
DNS Forwarder port change: starting with NetBird v0.59.0, the local DNS forwarder used for routed DNS routes switches from port <code>5353</code> to <code>22054</code> to avoid collisions on client devices. For backward compatibility, the Management Service applies the new port only when <strong>all peers in the account</strong> run v0.59.0 or newer. If any peer is below v0.59.0, port <code>5353</code> will be used for all peers in that account.
</Note>
## Setting Up Developers' Network Environment
To create a network for the developer environment:
* Navigate to `Networks` > `Networks` in NetBird's dashboard.
* Click the `Add Network` button.
* Give a descriptive name to the network, e.g., `Development Network`. Optionally, add a description.
* Click `Add Network` to continue.
![Creating Developers Domain Network](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/02-domains-within-networks.png)
### Adding Routing Peers
Click `Add Routing Peer` to make accessible the resources within this network to the developers.
![Add Routing Peers Window](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/03-domains-within-networks.png)
You will see two tabs: `Routing Peers` and `Peer Group`.
* Select `Routing Peers` to add one peer at a time to the network.
* Select `Peer Group` to enable high availability by adding multiple peers to the network.
* Click `Continue` once ready.
![Local Routing Peers](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/04-domains-within-networks.png)
In the `Advanced Settings` tab:
* Set `Masquerade` if you want to access private networks without configuring local routers or other devices.
* Set the `Metric` to prioritize routers, using lower values for higher priority peers.
* When ready, click `Add Routing Peer`.
![Masquerade and Metric](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/05-domains-within-networks.png)
### Adding a Wildcard Domain Resource
Click `Add Resource` to create the wildcard domain resource.
![Add Domain Resource](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/06-domains-within-networks.png)
* Give the resource a descriptive name, e.g., `Development Wildcard Domain`
* Enter the wildcard domain for this environment, e.g., `*.dev.example.com`.
* Under `Assigned Groups`, select or create a group, e.g., `Development Domain`. This group will be used to create an access policy to allow developers access to all subdomains ending with `.dev.example.com`.
* Click `Add Resource` when ready.
![Add Accounting Website Restricted Subdomain Resource](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/07-domains-within-networks.png)
### Creating an Access Policy
Click `Create Policy` to grant developers access to `*.dev.example.com`.
![Add Policy](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/08-domains-within-networks.png)
* Under `Protocol`, leave `ALL`.
* Under `Source` choose the group corresponding to developers, e.g., `Developers`.
* The `Destination` is automatically set to the group you used when creating the resource, e.g., `Development Domain`.
![Developers Policy](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/09-domains-within-networks.png)
* Click `Continue` to set `Posture Checks`. This step is optional, meaning you can click `Continue` for this example.
* Provide a descriptive name for the policy, e.g., `Development Wildcard Domain Policy`.
* Click `Add Policy` to finish.
![Developers Policy Name](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/10-domains-within-networks.png)
Now that the development environment is set up, you can streamline the process of creating new resources using NetBird.
### Adding a Regular Domain Resource
The wildcard domain you configured, `*.dev.example.com`, only covers subdomains following the `.` (dot). Therefore, you need to configure a primary domain alongside your wildcard domain within your network settings. This dual approach guarantees that all levels of your domain hierarchy are adequately resolved and accessible.
Suppose you want to create the regular domain `dev.example.com`.
* Navigate to `Networks` > `Development Network` and click `Add Resource`.
![Development Network](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/11-domains-within-networks.png)
* Provide an appropriate name for the resource, such as `Development Regular Domain`.
* In the `Address` field, enter the regular domain `dev.example.com`.
* Under `Assigned Groups` select the same group used for the wildcard domain, e.g., `Development Domain`.
* Click `Add Resource` to continue.
![Regular Domain Resource](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/12-domains-within-networks.png)
That's it! Since you used the group `Development Domain`, NetBird will automatically configure for you routing peers and access policies, granting your developers the necessary access permissions.
![Development Network Resources](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/13-domains-within-networks.png)
You can confirm the configuration by listing the available networks using the command `netbird networks ls` from any developer workstation. The output should resemble the following:
```bash
$ netbird networks ls
Available Networks:
- ID: Development Regular Domain
Domains: dev.example.com
Status: Selected
Resolved IPs:
[example.com]: 93.184.215.14, 2606:2800:21f:cb07:6820:80da:af6b:8b2c
- ID: Development Wildcard Domain
Domains: *.dev.example.com
Status: Selected
Resolved IPs: -
```
## Creating AI Model Training Network
For our use case, data scientists operate from different network segments or diverse geographical locations. Using the same steps previously outlined, you can overcome the challenges associated with this scenario by creating a new network with its corresponding routing peers, resources, and access policies.
From the `Networks` screen, click `Add Network` to set up an appropriate network for your data scientists:
![AI Network](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/14-domains-within-networks.png)
As with developers, you can configure a single routing peer or a group of routing peers for high availability:
![AI Routing Peers](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/15-domains-within-networks.png)
You can also set up a wildcard domain resource for this environment:
![AI Wildcard Domain Resource](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/16-domains-within-networks.png)
And establish an access policy tailored to your data scientists:
![AI Team Access Policy](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/17-domains-within-networks.png)
You will need a regular domain, too; simply create the corresponding resource. The overview of your new network might resemble the following:
![AI Network](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/18-domains-within-networks.png)
Need a new subdomain for testing the latest model? From NetBird's Networks screen, just click `Add Resource`, name it, enter the desired subdomain, and assign it to the appropriate group for this environment:
![New AI Model Resource](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/19-domains-within-networks.png)
In summary, you can easily add, remove, and edit network resources from the Networks dashboard.
![AI Training Model Network](/docs-static/img/manage/networks/accessing-entire-domains-within-networks/20-domains-within-networks.png)
With this setup, all members of the `Data Scientists` group have access to `ai.example.com` and its subdomains:
```bash
$ netbird networks ls
Available Networks:
- ID: AI Model Training Wildcard Domain
Domains: *.ai.example.com
Status: Selected
Resolved IPs: -
- ID: AI Regular Domain
Domains: ai.example.com
Status: Selected
Resolved IPs: -
- ID: DataSage Model
Domains: datasage.ai.example.com
Status: Selected
Resolved IPs: -
- ID: NeuroPulse Model
Domains: neuropulse.ai.example.com
Status: Selected
Resolved IPs: -
- ID: QuantumNet Model
Domains: quantumnet.ai.example.com
Status: Selected
Resolved IPs: -
```
However, using your newly acquired knowledge, you can create access policies for each subdomain or organize data scientists into teams with varied permissions. With NetBird, the possibilities are endless.

158
src/pages/manage/networks/accessing-restricted-domain-resources.mdx
View File

@@ -1,158 +0,0 @@
# Accessing restricted website domain resources
It is very common to find scenarios where you need to access restricted websites or services. This can be due to company policies, geographical restrictions, or even to avoid tracking. These resources are often located behind a cloud load balancer, which changes IP addresses frequently, making it hard to whitelist them. NetBird can help you access these resources by routing your traffic through a [routing peer](https://docs.netbird.io/manage/network-routes/routing-traffic-to-private-networks#routing-peer) configured with [Networks](https://docs.netbird.io/manage/networks) using [Domain resources](https://docs.netbird.io/manage/networks#resources).
## Example Use Case Scenario
Imagine a company that runs its accounting application at the subdomain `accounting.example.com`. The website is behind a load balancer and hosted on an EC2 instance within the company's AWS infrastructure in the EU Central region. To enhance security, the company decided to follow zero-trust principles by giving differentiated access to the finance and support teams tailored to their specific responsibilities and operational needs.
To this end, the company deployed [NetBird clients](https://docs.netbird.io/get-started) on the devices used by both the finance and support teams. Complementing this, [NetBird routing peers](https://docs.netbird.io/manage/networks#routing-peers) were configured within the AWS VPC using [setup keys](https://docs.netbird.io/manage/peers/access-infrastructure/setup-keys-add-servers-to-network). This configuration guarantees a solid foundation for streamlined and secure connectivity.
More importantly, this setup allows the company to use NetBird's Networks and [Access Policies](https://docs.netbird.io/manage/access-control/manage-network-access), to ensure that only authorized finance and support team members access the restricted website domain as follows:
- **Finance Team**: HTTP and HTTPS access to the website frontend at `accounting.example.com` over ports `80` and `443`, respectively.
- **Support Team**: SSH access to backend resources at `example.com` over port `22`, enabling server management, troubleshooting, and support tasks.
This configuration adds another layer of security within the AWS environment, thus reinforcing the company network security framework and enhancing operational efficiency.
## Creating a Network for the Restricted Website Domain
To create a new network for the accounting website subdomain:
* Go to `Networks` > `Networks` in NetBird's dashboard.
* Click the `Add Network` button.
* Give a memorable name to the network, such as `AWS EU Network`. Optionally, add a description.
* Click `Add Network` to proceed.
![Create Restricted Website Domain Network](/docs-static/img/manage/networks/accessing-restricted-domain-resources/01-restricted-domain.png)
### Adding Routing Peers
Continue the process by clicking `Add Routing Peer`. This step is necessary to enable the network's resources to be accessible to other peers.
![Add Routing Peers Window](/docs-static/img/manage/networks/accessing-restricted-domain-resources/02-restricted-domain.png)
In the next window, you will see two tabs: `Routing Peers` and `Peer Group`.
* Choose `Routing Peers` to add a single peer to the network, e.g., `aws-router`.
* Alternatively, you can select `Peer Group` to add multiple peers simultaneously for high availability.
* Click `Continue` once ready.
![Local Routing Peers](/docs-static/img/manage/networks/accessing-restricted-domain-resources/03-restricted-domain.png)
In the `Advanced Settings` tab:
* Set `Masquerade` if you want to access private networks without configuring local routers or other devices.
* Set the `Metric` to prioritize routers. Lower values indicate higher priority.
* Click `Add Routing Peer`.
![Masquerade and Metric](/docs-static/img/manage/networks/accessing-restricted-domain-resources/04-restricted-domain.png)
### Adding Network Resources
Next, click `Add Resource` to add the accounting website resource.
![Add Network Resource](/docs-static/img/manage/networks/accessing-restricted-domain-resources/05-restricted-domain.png)
* Give the network resource an appropriate name, e.g., `Accounting restricted subdomain`
* Enter the restricted website domain for the accounting website, in this example, `accounting.example.com`.
* Under `Assigned Groups`, select or create a group, like `Accounting Subdomain`. This group will be used to create an access policy to allow the finance team access to the restricted subdomain.
* Click `Add Resource` when done.
![Add Accounting Website Restricted Subdomain Resource](/docs-static/img/manage/networks/accessing-restricted-domain-resources/06-restricted-domain.png)
### Creating Access Policies
The last step consists of creating an access control policy. Click `Create Policy` to create a new policy for the finance team.
![Add Policy](/docs-static/img/manage/networks/accessing-restricted-domain-resources/07-restricted-domain.png)
Since the finance team only needs access to the web-based app at `accounting.example.com`, this policy will restrict access to ports: `TCP/80` for `HTTP` traffic and `TCP/443` for encrypted `HTTPS` traffic.
* Under `Protocol`, select `TCP`.
* Under `Source` choose the group corresponding to the finance team, e.g., `Finance`.
* The `Destination` is automatically set to the group of the newly created resource, e.g., `Accounting Subdomain`.
* Under `Ports`, enter `80` and `443`, the default ports for `HTTP` and `HTTPS` traffic.
![Finance Policy](/docs-static/img/manage/networks/accessing-restricted-domain-resources/08-restricted-domain.png)
* Click `Continue` to move to the `Posture Checks` tab, where you can optionally create or select posture checks for this policy.
* Click `Continue` again, and provide a descriptive name for the policy, e.g., `Accounting subdomain Policy`.
* Click `Add Policy` to finish.
![Finance Policy Name](/docs-static/img/manage/networks/accessing-restricted-domain-resources/09-restricted-domain.png)
### Setting Up Additional Resources and Access Policies
Contrary to the finance team, the support team does not need access to the front end of the restricted accounting app but to the back end of the top-level domain: `example.com`, meaning you must add a new network resource and access policy for this team.
To set up a new network resource:
* In the `AWS EU Network` screen, click `Add Resource`.
* Give the resource a descriptive name, for example, `Restricted Website TLD`.
* Enter the domain, in our case, `example.com`.
* Under `Assigned Groups`, select or create the appropriate group such as `Webserver`. This group will be used to create a policy allowing the support team to access the TLD `example.com`.
![Add TLD Resource](/docs-static/img/manage/networks/accessing-restricted-domain-resources/10-restricted-domain.png)
Next, create an access policy for the support team. Usually, support teams only need SSH access to the website backend, meaning that they only need access to the `TCP/22` port:
* Click `Add Policy` next to the `Restricted Website TLD` resource.
* Under `Protocol`, select `TCP`.
* Set `Source` to `Support` and `Destination` to `Webserver`. This allows the support team to access the restricted website backend over SSH.
* Under `Ports`, enter `22`, the default port for SSH.
* Click `Continue`.
![Add Support Team Policy](/docs-static/img/manage/networks/accessing-restricted-domain-resources/11-restricted-domain.png)
* Optionally, select or create posture checks for this policy. Click `Continue`.
* Give a name to the policy on the final tab, such as `Restricted Website TLD Policy`.
![Name Support Team Policy](/docs-static/img/manage/networks/accessing-restricted-domain-resources/12-restricted-domain.png)
This completes the network setup. You have configured two network resources, their respective access policies, and routing peers.
![AWS EU Network](/docs-static/img/manage/networks/accessing-restricted-domain-resources/13-restricted-domain.png)
Now, you can review, select, or deselect available networks using NetBird's CLI.
Here's the output of the `netbird networks list` command from a Finance team client:
```bash
$ netbird networks list
Available Networks:
- ID: Accounting restricted subdomain
Domains: accounting.example.com
Status: Selected
Resolved IPs: -
- ID: Internal Web Services
Domains: *.company.internal
Status: Selected
Resolved IPs: -
```
As expected, finance members only have access to `accounting.example.com`.
Here's the output from a support team workstation:
```bash
$ netbird networks list
Available Networks:
- ID: Internal Web Services
Domains: *.company.internal
Status: Selected
Resolved IPs: -
- ID: Restricted Website TLD
Domains: example.com
Status: Selected
Resolved IPs:
[example.com]: 93.184.215.14, 2606:2800:21f:cb07:6820:80da:af6b:8b2c
```
As you can see, the support team only has access to the TLD `example.com`
That's it! Using NetBird's Networks feature, you can efficiently create and manage custom network traffic routes and access policies for restricted website domain resources.

166
src/pages/manage/networks/homelab/access-home-network.mdx
View File

@@ -1,166 +0,0 @@
import {Note} from "@/components/mdx";
# How to Set up NetBird to Access Your Home Network
This step-by-step guide describes how to quickly get started with NetBird and access your home network remotely.
You will achieve a secure connection between your entire home network and NetBird, enabling remote devices to access
local network resources through a routing peer using the [NetBird Networks feature](/manage/networks/homelab/access-home-network).
## Download and Install NetBird
<br/>
<Button href="https://app.netbird.io/install" arrow="right" children="Download NetBird" />
## Connect Your Laptop
NetBird comes with a Desktop UI application that can be found in the systray. If it hasn't automatically started, look for `NetBird` in the application list, run it, and click `Connect`:
<p>
<img src="/docs-static/img/get-started/systray.png" alt="login-to-netbird" className="imagewrapper"/>
</p>
<Note>
Alternatively, you can run the `netbird up` command in the terminal.
</Note>
At this point a browser window pops up starting an interactive SSO login session that will register your laptop. You will be prompt to sign up and confirm your device registration:
<p>
<img src="/docs-static/img/manage/networks/homelab/access-home-network/login-screen-dark.png" alt="login-to-netbird" className="imagewrapper"/>
</p>
After the registration is complete, proceed to the [**NetBird dashboard**](https://app.netbird.io/) to confirm that your laptop is in the network. You will see it in the `Peers` view.
## Create a New NetBird Network
1. Go to the **Networks** tab in the side bar
2. Click **Add Network** and give it a name such as “Home LAN", and optionally add a description.
<p>
<img src="/docs-static/img/manage/networks/homelab/access-home-network/add-network-home-lan.png" alt="add-network-home-lan" className="imagewrapper"/>
</p>
## Identify Your Local Subnet
Use the steps below to quickly identify your local subnet for use as a Network Resource.
### Windows
1. Open **Command Prompt**.
2. Run:
```bash
ipconfig
```
3. Look for your active network adapter.
4. Note the values for:
- `IPv4 Address`
- `Subnet Mask`
Example:
```
IPv4 Address. . . . . . . . . . . : 192.168.1.10
Subnet Mask . . . . . . . . . . : 255.255.255.0
```
The subnet is `192.168.1.0/24`.
### Linux
1. Open **Terminal**.
2. Run:
```bash
ip -c a
```
or
```bash
ip route
```
3. Identify the active interface (e.g., `eth0`, `wlan0`) and note the IP with CIDR suffix:
Example:
```
inet 192.168.1.10/24
```
The subnet is `192.168.1.0/24`.
### macOS
1. Open **Terminal**.
2. Run:
```bash
ifconfig
```
3. Locate the active interface (`en0`, `en1`, etc.).
4. Look for:
- `inet` (IP address)
- `netmask` (in hex)
Example:
```
inet 192.168.1.10 netmask 0xffffff00
```
Hex `0xffffff00` = `255.255.255.0`, which is `/24`.
The subnet is `192.168.1.0/24`.
## Define Your LAN as a Network Resource
1. Click **Add Resource**.
2. Enter a name like "Home Subnet" and the CIDR of your home network into the Address field (e.g., 192.168.1.0/24).
3. Assign it to a Destination Group, create one called "home-lan" so you can write access policies using this group.
4. Click **Add Resource**.
<p>
<img src="/docs-static/img/manage/networks/homelab/access-home-network/add-resource-home-network.png" alt="add-resource-home-network" className="imagewrapper"/>
</p>
<Note>
Alternatively, if you do not want to allow access your entire home subnet, you can get more granular by only
allowing
access to a single static IP address for your added resource (e.g., 192.168.1.50/32).
</Note>
## Create an Access Control Policy
To allow access to resources in your home network, you need to create an access control policy that defines which
peers can access the network.
1. After adding your resource, click **Create Policy**.
2. Set Source to the group of NetBird peers you want to allow access (e.g., "All Users" or a specific group like "Home Users").
3. Set **Destination** to the "home-lan" group you made.
4. For **Protocol**, choose All.
5. Name it "Home LAN Access" and click **Add Policy**.
<p>
<img src="/docs-static/img/manage/networks/homelab/access-home-network/add-policy-home-lan.png" alt="add-policy-home-lan" className="imagewrapper"/>
</p>
## Add Your User to the Home User Group
In order to access your home network, you need to add your users to a group that is used in the access control policy,
you've previously created.
1. Go to the **Team** tab in the side bar.
2. Find your user row and click on the **GROUPS** column in the table.
3. Add "Home Users" by typing it in the input box and pressing Enter.
<p>
<img src="/docs-static/img/manage/networks/homelab/access-home-network/add-user-group.png" alt="add-network-home-lan" className="imagewrapper"/>
</p>
## Choose or Add a Routing Peer in Your LAN
1. Click **Add Routing Peer**.
2. Pick any always-on machine on your home network (Windows, Linux, Mac, Docker, Raspberry Pi).
3. Install the NetBird agent on it using a [one-off setup key](/manage/peers/register-machines-using-setup-keys#types-of-setup-keys) using the CLI installer.
4. Ensure this machine has access to both the internet and your LAN subnet.
5. Choose this machine as your routing peer and click **Continue** and **Add Routing Peer**.
<p>
<img src="/docs-static/img/manage/networks/homelab/access-home-network/add-routing-peer-home-network.png" alt="add-routing-peer-home-network"
className="imagewrapper"/>
</p>
<p>
<img src="/docs-static/img/manage/networks/homelab/access-home-network/add-routing-peer.png" alt="add-routing-peer-home-network"
className="imagewrapper"/>
</p>
## Test the Connection
1. Pick any IP within your Home LAN, such as the IP of your NAS, printer, or another service and run:
```bash
ping 192.168.x.x
```
2. A successful ping response confirms that your routing peer is correctly routing traffic to resources in your home network.
That’s it! You’ve successfully mapped your entire home LAN into a NetBird Network. Any peer included in your access policy
can now securely access resources in your home subnet via your designated routing peer, without the need to open router ports or install software on every device.

177
src/pages/manage/networks/index.mdx
View File

@@ -1,177 +1,152 @@
# Networks
NetBird provides a fast and secure peer-to-peer mesh network with end-to-end encryption, enabling devices and machines
running the NetBird agent to connect directly. This setup allows for precise network segmentation,
isolation of individual machines, and secure remote access without the need to open ports or expose resources to the
internet. However, there are situations where installing the agent on every machine is not feasible or hasn't been
completed, requiring access to entire LANs, office networks, or cloud VPCs instead.
NetBird creates a secure peer-to-peer mesh network where devices running the NetBird agent connect directly with end-to-end encryption. This enables precise network segmentation and secure remote access without exposing resources to the internet.
Starting from version `0.35.0`, NetBird introduces Networks, a new concept that allows you to map your internal networks
such as LANs, VPCs, or office networks, and manage access to internal resources without installing NetBird agent.
However, installing the agent on every machine is not always feasible. Networks solve this by letting you route traffic to entire LANs, office networks, or cloud VPCs without requiring the NetBird agent on each device.
<p>
<img src="/docs-static/img/manage/networks/netbird-network-routes.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
<Note>
Networks replace the old [Network Routes](/manage/network-routes/routing-traffic-to-private-networks) concept, which is now deprecated.
Existing Network routes will continue to work as before, but we recommend migrating to Networks for better access
management to your resources.
</Note>
## Networks vs. Network Routes
Networks is the newer, simpler replacement for Network Routes. We encourage you to use Networks where possible; however, Networks do not yet support all remote access scenarios. Network Routes will continue to be actively maintained, so use whichever fits your use case.
For a detailed comparison, see our [site-to-site documentation](/use-cases/site-to-site).
## Concepts
### Networks
Networks are configuration containers that map your on-premise or cloud networks in a logical set of configurations,
making it easier to visualise and manage access to your internal resources. You can create multiple networks to represent your
different environments, such as office networks, cloud VPCs, or on-premise LANs.
A Network is a configuration container that maps your on-premise or cloud infrastructure into a logical set of resources and routing peers. You can create multiple networks to represent different environments such as office networks, cloud VPCs, or data center LANs.
<p>
<img src="/docs-static/img/manage/networks/index/new-network-2.png" alt="high-level-dia" className="imagewrapper"/>
</p>
### Routing peers
To access your internal resources, you need to route traffic from your NetBird peers to your internal networks.
Routing peers are machines that connect your NetBird peers and your internal networks.
You can add as many routing peers as you need using single peers or groups to ensure high availability and load balancing.
You can define masquerading and priority for each routing peer.
### Routing Peers
Routing peers are machines that bridge your NetBird peers to your internal networks. They forward traffic from NetBird clients to resources that do not have the NetBird agent installed.
You can add multiple routing peers using individual peers or groups to ensure high availability and load balancing. Each routing peer can be configured with masquerading and priority settings.
<p>
<img src="/docs-static/img/manage/networks/index/add-routing-peer-1.png" alt="high-level-dia" className="imagewrapper"/>
</p>
### Resources
Resources are individual machines, services, or subnets within your internal network. You can define resources as single
IP addresses, IP ranges, domain names, or wildcard domains (e.g., *.company.internal) when enabling [DNS wildcard routing](#enable-dns-wildcard-routing).
Resources are the machines, services, or subnets you want to access within your internal network. You can define resources as:
- Single IP addresses
- IP ranges
- Domain names (e.g., `example.com`)
- Wildcard domains (e.g., `*.company.internal`) when [DNS wildcard routing](#enable-dns-wildcard-routing) is enabled
<p>
<img src="/docs-static/img/manage/networks/index/resources-1.png" alt="resources" className="imagewrapper-big"/>
</p>
<Note>
Support to exit nodes and site-2-site VPNs may become available in future releases. In the meantime you can use [Network routes](/manage/network-routes/routing-traffic-to-private-networks) add your exit-node routes and site-2-site routes.
</Note>
### Domain Resources
In addition to routing IP addresses, NetBird also supports routing domain names. In the Dashboard you can just pass
a domain name (eg: `example.com`) or a wildcard domain (eg: `*.example.com`) in place where you would normally
put an IP address range. Then NetBird clients will start responding to and routing the given domain.
In addition to IP-based resources, NetBird supports routing domain names. In the Dashboard, you can enter a domain name (e.g., `example.com`) or wildcard domain (e.g., `*.example.com`) instead of an IP range. NetBird clients will then resolve and route traffic to that domain.
Please consult the
[Debugging access to Domain Resources](/help/troubleshooting-client#debugging-access-to-domain-resources)
documentation to troubleshoot common issues with this type of resources yourself.
For troubleshooting, see [Debugging access to Domain Resources](/help/troubleshooting-client#debugging-access-to-domain-resources).
<Note>
Due to a mix of a bug and initial design choice clients running `0.59.0` & `0.59.1` might not be able to resolve
domain Resources served by Routing Peers running versions `0.59.0` to `0.59.9` in case when all the Peers in the
NetBird organization are running versions `0.59.0` or newer.
Clients running versions `0.59.0` and `0.59.1` may fail to resolve domain resources served by routing peers running versions `0.59.0` to `0.59.9` when all peers in the organization are on version `0.59.0` or newer.
Installing client in versions `<= 0.58.2` or `>= 0.59.2` or upgrading a Routing Peer to version `0.59.10+` will
resolve this issue.
To fix this, either use client versions `<= 0.58.2` or `>= 0.59.2`, or upgrade the routing peer to version `0.59.10` or later.
</Note>
On a technical level the feature works as follows:
#### How Domain Resolution Works
1. Initially (when NetBird connects) the operating system is instructed to use NetBird to resolve the requested
domain(s). No routing rules are configured yet.
2. An Application (could be a web browser) requests a domain `example.com` from the Operating System
1. the Operating System requests a name from NetBird's Local DNS Forwarder, by default running on port `53` of:
- for MacOS & Windows: the highest available IP address in your NetBird range, usually `100.xxx.255.254:53`
- for other systems: local NetBird client's IP address, eg: `100.xxx.123.45`
2. the Local DNS Forwarder forwards the query to Remote DNS Resolver running on Routing Peer's address
and the following port:
- `22054` for version `0.59.0` and newer
- `5353` for versions below `0.58.x` and older
3. the Routing Peer resolves the domain name using its local configuration (often independent of NetBird) and returns
the result.
4. the Local DNS Forwarder sets up routing rules for IP addresses returned from the query,
before returning them to the Application
- see [Trigger the Domain Resource](/help/troubleshooting-client#trigger-the-domain-resource)
to observe this behaviour "in action".
3. the Application receives the result "as usual", except for a slight delay before all of the above takes place the
first time a domain name is requested,
4. all subsequent requests to `example.com` will be served instantly from the Local DNS Forwarder's cache
1. When NetBird connects, it configures the operating system to use NetBird for resolving the specified domains. No routing rules are set up yet.
2. When an application requests a domain (e.g., `example.com`):
- The OS sends the DNS query to NetBird's Local DNS Forwarder, which runs on:
- **macOS and Windows**: The highest available IP in your NetBird range (typically `100.xxx.255.254:53`)
- **Other systems**: Your local NetBird client IP (e.g., `100.xxx.123.45:53`)
- The Local DNS Forwarder sends the query to the Remote DNS Resolver on the routing peer using:
- Port `22054` for NetBird client versions `0.59.0` and newer
- Port `5353` for NetBird client versions `0.58.x` and older
- The routing peer resolves the domain using its local DNS configuration and returns the result.
- The Local DNS Forwarder creates routing rules for the returned IP addresses before sending them to the applicatioxn. See [Trigger the Domain Resource](/help/troubleshooting-client#trigger-the-domain-resource) to observe this behavior.
3. The application receives the response normally, with a slight delay on the first request.
4. Subsequent requests are served instantly from the Local DNS Forwarder's cache.
<Note>
NetBird tries its best to automatically open up DNS forwarder ports on Routing Peer's firewalls, but might fail on
some system configurations and you might need to open up above 2 ports manually.
NetBird attempts to automatically open DNS forwarder ports on routing peer firewalls, but this may fail on some systems. If you experience issues, manually open the required ports.
You can verify that firewall allows the DNS request in using following command issued from the clients device
`nslookup -port=22054 <routed-domain> <routing-peer-ip>`, eg: `nslookup -port=22054 example.com 100.123.45.67`.
To verify firewall access, run this command from the client device:
`nslookup -port=22054 <routed-domain> <routing-peer-ip>` (e.g., `nslookup -port=22054 example.com 100.123.45.67`).
This is by far the most common cause of issues with domain Resources.
Firewall blocking DNS requests is the most common cause of domain resource issues.
</Note>
## Manage access to resources
## Manage Access to Resources
To manage access to resources, you should assign them to groups and create [access control policies](/manage/access-control/manage-network-access#creating-policies) to grant access from the specific peer groups. A peer will "see" the resource only after a policy allows access from one of peer's (source) groups to one of the resource's (destination) groups.
To control access to resources, assign them to groups and create [access control policies](/manage/access-control/manage-network-access#creating-policies). A peer can only see a resource when a policy grants access from one of the peer's groups (source) to one of the resource's groups (destination).
See the image below with an example resource `CRM`:
Example resource `CRM` assigned to a group:
<p>
<img src="/docs-static/img/manage/networks/index/resources-2.png" alt="resource-group" className="imagewrapper"/>
</p>
Access control policies are rules that define which peers can access the resources in your network. You can create policies based on the source and destination groups, and the type of traffic allowed (e.g., TCP, UDP, ICMP).
The groups assigned to resources should always be placed in the destination input field of the policy.
The peers belonging to the source groups will receive the resources linked to the policy and the firewall rules will be applied according to what is defined.
Access control policies define which peers can access which resources based on source groups, destination groups, and allowed traffic types (TCP, UDP, ICMP). When creating a policy:
- Place the resource's group in the **destination** field
- Place the peer's group in the **source** field
- Peers in the source groups will receive the resource routes and corresponding firewall rules
<Note>
Unlike peers, resources are not members of the built-in `All` group by default. If you want to utilize `All` group rules with resources, you must explicitly add them to this group.
Unlike peers, resources are not automatically members of the built-in `All` group. To use `All` group rules with resources, you must explicitly add them to this group.
</Note>
See the example below with a policy that allows the group `Berlin Office` to access the internal CRM system:
Example policy allowing the `Berlin Office` group to access the internal CRM system:
<p>
<img src="/docs-static/img/manage/networks/index/resource-acl-1.png" alt="resource-acl" className="imagewrapper-big"/>
</p>
<Note>
Policies for domains or wildcard domains applied to peers with IP ranges might influence access control for those peers, as their destination ranges include any IPs. Therefore, we recommend creating networks with routing peers dedicated to domain and wildcard domains to prevent unwanted access. In upcoming releases, we will provide a fix for this behavior.
Policies for domain or wildcard domain resources may unintentionally affect peers with IP range resources, since IP ranges can match any address. We recommend using dedicated networks and routing peers for domain-based resources to prevent unwanted access. A fix for this behavior is planned for an upcoming release.
</Note>
## Enable DNS wildcard routing
When you configure wildcard domains as resources, you need to enable DNS wildcard routing. Which has an additional effect in comparison to the previous DNS routes behavior from Network routes; it switches the DNS resolution to the routing peer instead of the local client system.
This is also useful for regular DNS routes when you want to resolve the domain names using the routing peer's IP infrastructure, which will allow for more restricted access control rules in newer versions of the clients (**1**) and for the traffic to go to a near routing peer service.
<Note>
(1) Support for more restricted rules will be available in future releases.
</Note>
You can enable DNS resolution on the routing peer by accessing your account `Settings` > `Networks` > Enable DNS wildcard routing. See example below:
## Enable DNS Wildcard Routing
To use wildcard domains as resources, you must enable DNS wildcard routing. This setting changes how domains are resolved: instead of the client resolving domains locally, the routing peer performs DNS resolution.
This is also useful for regular domain resources when you want to:
- Resolve domain names using the routing peer's DNS infrastructure
- Route traffic through a geographically nearby routing peer
- Enable more restrictive access control rules (support coming in future releases)
To enable DNS wildcard routing, go to **Settings** > **Networks** > **Enable DNS wildcard routing**:
<p>
<img src="/docs-static/img/manage/networks/index/settings-1.png" alt="settings-acl" className="imagewrapper-big"/>
</p>
<Note>
The `Enable DNS wildcard routing` is supported by routing peers and routing clients running version 0.35.0 or later.
Once the feature is enabled, you may need to restart your routing peers and clients to apply the changes.
DNS wildcard routing requires routing peers and clients running version 0.35.0 or later. After enabling this feature, restart your routing peers and clients to apply the changes.
</Note>
<Note>
DNS Forwarder port change: starting with NetBird v0.59.0, the local DNS forwarder used for routed DNS routes switches from port <code>5353</code> to <code>22054</code> to avoid collisions on client devices. For backward compatibility, the Management Service applies the new port only when <strong>all peers in the account</strong> run v0.59.0 or newer. If any peer is below v0.59.0, port <code>5353</code> will be used for all peers in that account.
Starting with NetBird v0.59.0, the local DNS forwarder port changed from `5353` to `22054` to avoid port collisions. For backward compatibility, the new port is only used when **all peers in the account** run v0.59.0 or newer. If any peer is on an older version, port `5353` is used for all peers.
</Note>
## Differences between Networks and Network Routes
## Use Cases
| | Networks | Network routes |
|---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| **Requires extra policy connecting routing peers to distribution peers?** | No, the connection is implied when a policy is added to control access to resources | Yes, the routing peers need to have a policy that connects them to peers in the distribution groups |
| **Needs distribution groups?** | No, the source groups in the policies define the distribution groups | Yes, they need to be explicitly defined per network route configured |
| **Requires adding full sets of configurations per routed resource?** | No, the routing peers in a Network are used to route all resources in that network | Yes, every network route needs to have a routing peer, distribution group, access control group, and the network range or DNS route |
| **Allows edit routed resources?** | Yes, you can edit ranges or domains | No, you can't edit IP ranges or DNS routes once created |
| **Allows edit names?** | Yes, names are editable | No, names are defined once while creating the route |
| **Support to wildcard domains?** | Yes, wildcard domains are supported | No, network routes are limited to individual domains |
| **Support for exit-nodes?** | No, even though that exit-nodes can be linked to on-premises or cloud networks, they invalidate other resources | Yes, but the same note is valid when using an exit-node to route other traffic to the same resources |
| **Support for site-2-site IP ranges routing?** | No, but support is planned | Yes, when you create a network route without access control groups |
- [Routing traffic to multiple IP resources](/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources)
- [Accessing restricted website domain resources](/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources)
- [Accessing entire domains within networks](/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks)
## Get Started
## Use cases
- [Routing traffic to multiple IP resources](/manage/networks/routing-traffic-to-multiple-resources)
- [Accessing restricted website domain resources](/manage/networks/accessing-restricted-domain-resources)
- [Accessing entire domains within networks](/manage/networks/accessing-entire-domains-within-networks)
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
<div className="text-center">
<Button name="button" className="button-5" href="https://netbird.io/pricing">Use NetBird</Button>
</div>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)

111
src/pages/manage/networks/routing-traffic-to-multiple-resources.mdx
View File

@@ -1,111 +0,0 @@
# Routing traffic to multiple IP resources
Adding routes to resources within on-premises or cloud is a common scenario for DevOps and Platform teams. In this guide, we will show you how to route traffic to multiple IP resources using NetBird's [Networks](/manage/networks) using [IP resources](/manage/networks#resources).
## Example
In the following scenario, we will cover the case where all users have restricted access to internal DNS servers in the internal network, and the DevOps team has full access to the entire network.
The network address is `172.16.0.0/15` and DNS servers has the IPs `172.16.30.2` and `172.17.100.2`.
These IP ranges will be routed using [Routing peers](/manage/networks#routing-peers) running in the network.
### Create a Network
To create a Network, navigate to the `Networks` > `Networks` section in the NetBird dashboard:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/view-wild-network-1.png" alt="new-net-1" className="imagewrapper-big"/>
</p>
Click on `Add Network` to follow a Wizard that will guide you through the steps to create a network and add resources to it.
First, we fill out the network Name and Description as shown in the image below and click `Continue`:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/new-example-network-2.png" alt="new-net2" className="imagewrapper"/>
</p>
### Add a routing peer
Next we are asked to add a routing peer to the network. Let's click on `Add routing peer` and select a node from that VPC:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-routing-peer-1.png" alt="new-example-routing-peer-1" className="imagewrapper"/>
</p>
Click on `Continue` and then accept the defaults to add a routing peer by clicking on `Add Routing Peer`:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-routing-peer-2.png" alt="new-routing-peer-2" className="imagewrapper"/>
</p>
### Add the network resource
Following the guide, we are asked to add a new resource.
Click on `Add Resource` and enter the `Office network` name and use the IP range `172.16.0.0/15` as the address:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-resource-1.png" alt="new-example-resource-1" className="imagewrapper"/>
</p>
We can also assign a group to this resource; in this example, we will assign the group `office-network` to it. This way, we can create a policy that allows the DevOps team to access the entire IP range.
### Add an access control policy for the network resource
Next, in the guide, we will be asked to create an access control policy. Here, we will create a policy that allows all access to the `office-network` group of the IP range `172.16.0.0/15`
resource to peers in the `DevOps` group.
Click on `Create Policy` and fill out the fields as shown in the image below:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-resource-acl-1.png" alt="new-resource-acl-1" className="imagewrapper-big"/>
</p>
Click on `Continue` 2 times and then click on `Add Policy` to save the policy:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-resource-acl-2.png" alt="new-resource-acl-2" className="imagewrapper-big"/>
</p>
### Add the DNS server resources
Now, let's add the DNS servers resources to the network. Click on `Add Resource` and enter the IP address of the first DNS server:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-resource-2.png" alt="new-example-resource-2" className="imagewrapper"/>
</p>
We will use the same group, `office-dns-servers`, for both resources, allowing all users to access the DNS servers.
This time, when asked to create a policy, we will click on Later to skip it since we will create one more resource for this configuration.
Now, let's add another resource for the second DNS server:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-resource-3.png" alt="new-example-resource-3" className="imagewrapper"/>
</p>
### Add an access control policy for the DNS server resource
This time, we will create a policy that allows access to the `office-dns-servers` group of DNS IP resources to peers in
the `All users` group. They will be granted access only to the `UDP` port `53` of these servers.
Click on `Create Policy` and fill out the fields as shown in the image below:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-resource-acl-3.png" alt="new-resource-acl-3" className="imagewrapper-big"/>
</p>
Click on `Continue` 2 times and then click on `Add Policy` to save the policy:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/add-example-resource-acl-4.png" alt="new-resource-acl-4" className="imagewrapper-big"/>
</p>
This time, we made the Policy name a bit more generic to cover both DNS server addresses.
### View the network
After completing the wizard, you will be able to see the network you just created in the Networks list:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/view-example-network-1.png" alt="view-example-network-1" className="imagewrapper-big"/>
</p>
To access a detailed view of the network, click on the network name:
<p>
<img src="/docs-static/img/manage/networks/routing-traffic-to-multiple-resources/view-example-network-2.png" alt="view-example-network-2" className="imagewrapper-big"/>
</p>
You can edit or add more resources or routing peers to the network by clicking on the `Edit` buttons of each section in the detailed view.
With the steps above, we created resources that allow different levels of access to multiple user groups within a single organization network.
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

212
src/pages/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks.mdx Normal file
View File

@@ -0,0 +1,212 @@
# Accessing entire domains within networks
This guide shows how to provide access to entire internal domains using NetBird [Networks](/manage/networks) with [wildcard domain resources](/manage/networks#resources). Wildcard domains simplify access management when teams need to reach multiple subdomains under a common parent domain.
## Example scenario
An AI software company needs to provide secure access to two internal environments:
1. **Development environment** (`*.dev.example.com`): Shared workspace for code development, testing, and collaboration
2. **AI model training environment** (`*.ai.example.com`): Sensitive AI models and datasets with restricted access
Using wildcard domains, developers can access any subdomain under `*.dev.example.com`, while data scientists access `*.ai.example.com`. This separation ensures team members only reach resources relevant to their roles.
### Prerequisites
Before starting, ensure you have:
- [NetBird clients](/get-started) installed on developer and data scientist devices
- [Routing peers](/manage/networks#routing-peers) configured in your network using [setup keys](/manage/peers/access-infrastructure/setup-keys-add-servers-to-network)
- [Nameservers](/manage/dns) configured in NetBird to resolve domain queries
## Enable DNS wildcard routing
DNS wildcard routing allows NetBird to resolve subdomain requests through routing peers. This must be enabled before using wildcard domain resources.
<Note>
DNS wildcard routing shifts DNS resolution from the local client to the routing peer, enabling access control rules and optimized traffic routing.
</Note>
To enable DNS wildcard routing:
1. Navigate to `Settings` > `Networks` in NetBird
2. Toggle `Enable DNS wildcard routing`
![Enabling DNS wildcard routing](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/01-domains-within-networks.png)
<Note>
DNS wildcard routing requires routing peers and clients running version `0.35.0` or later. Restart your routing peers and clients after enabling this feature.
</Note>
<Note>
DNS Forwarder port change: Starting with NetBird v0.59.0, the local DNS forwarder switches from port <code>5353</code> to <code>22054</code> to avoid collisions. For backward compatibility, the Management Service applies the new port only when <strong>all peers in the account</strong> run v0.59.0 or newer.
</Note>
## Set up the development network
### Create the network
1. Navigate to `Networks` > `Networks` in the NetBird dashboard
2. Click `Add Network`
3. Enter a name (e.g., `Development Network`) and optional description
4. Click `Add Network`
![Creating Developers Domain Network](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/02-domains-within-networks.png)
### Add routing peers
Click `Add Routing Peer` to enable access to resources in this network.
![Add Routing Peers Window](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/03-domains-within-networks.png)
Choose your routing configuration:
- Select `Routing Peers` to add a single peer
- Select `Peer Group` to add multiple peers for high availability
- Click `Continue`
![Local Routing Peers](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/04-domains-within-networks.png)
In `Advanced Settings`:
- Enable `Masquerade` to access private networks without configuring local routers
- Set `Metric` to prioritize routers (lower values = higher priority)
- Click `Add Routing Peer`
![Masquerade and Metric](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/05-domains-within-networks.png)
### Add a wildcard domain resource
Click `Add Resource` to create the wildcard domain resource.
![Add Domain Resource](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/06-domains-within-networks.png)
Configure the resource:
- **Name**: `Development Wildcard Domain`
- **Address**: `*.dev.example.com`
- **Assigned Groups**: Select or create a group (e.g., `Development Domain`)
- Click `Add Resource`
![Add Development Wildcard Resource](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/07-domains-within-networks.png)
### Create an access policy
Click `Create Policy` to grant developers access to `*.dev.example.com`.
![Add Policy](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/08-domains-within-networks.png)
Configure the policy:
- **Protocol**: `ALL`
- **Source**: `Developers`
- **Destination**: `Development Domain` (auto-populated)
![Developers Policy](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/09-domains-within-networks.png)
Click `Continue` to optionally add posture checks, then `Continue` again. Enter a policy name (e.g., `Development Wildcard Domain Policy`) and click `Add Policy`.
![Developers Policy Name](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/10-domains-within-networks.png)
### Add the base domain resource
Wildcard domains (`*.dev.example.com`) only match subdomains, not the base domain itself. To also allow access to `dev.example.com`, add it as a separate resource.
1. Navigate to `Networks` > `Development Network` and click `Add Resource`
![Development Network](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/11-domains-within-networks.png)
2. Configure the resource:
- **Name**: `Development Regular Domain`
- **Address**: `dev.example.com`
- **Assigned Groups**: `Development Domain` (same group as the wildcard)
- Click `Add Resource`
![Regular Domain Resource](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/12-domains-within-networks.png)
Since you used the same group, NetBird automatically applies the existing routing peers and access policies.
![Development Network Resources](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/13-domains-within-networks.png)
Verify the configuration from a developer workstation:
```bash
$ netbird networks ls
Available Networks:
- ID: Development Regular Domain
Domains: dev.example.com
Status: Selected
Resolved IPs:
[example.com]: 93.184.215.14, 2606:2800:21f:cb07:6820:80da:af6b:8b2c
- ID: Development Wildcard Domain
Domains: *.dev.example.com
Status: Selected
Resolved IPs: -
```
## Set up the AI model training network
Follow the same steps to create a network for data scientists.
Create a new network named `AI Model Training Network`:
![AI Network](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/14-domains-within-networks.png)
Add routing peers (single or group for high availability):
![AI Routing Peers](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/15-domains-within-networks.png)
Add the wildcard domain resource for `*.ai.example.com`:
![AI Wildcard Domain Resource](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/16-domains-within-networks.png)
Create an access policy for the `Data Scientists` group:
![AI Team Access Policy](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/17-domains-within-networks.png)
Add the base domain `ai.example.com` as a separate resource. The completed network:
![AI Network](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/18-domains-within-networks.png)
### Add specific subdomain resources
You can add individual subdomain resources for more granular access control. For example, to add a specific AI model subdomain:
Click `Add Resource`, enter the subdomain name and address, and assign it to the appropriate group:
![New AI Model Resource](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/19-domains-within-networks.png)
The network now shows all resources:
![AI Training Model Network](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks/20-domains-within-networks.png)
Verify from a data scientist workstation:
```bash
$ netbird networks ls
Available Networks:
- ID: AI Model Training Wildcard Domain
Domains: *.ai.example.com
Status: Selected
Resolved IPs: -
- ID: AI Regular Domain
Domains: ai.example.com
Status: Selected
Resolved IPs: -
- ID: DataSage Model
Domains: datasage.ai.example.com
Status: Selected
Resolved IPs: -
- ID: NeuroPulse Model
Domains: neuropulse.ai.example.com
Status: Selected
Resolved IPs: -
- ID: QuantumNet Model
Domains: quantumnet.ai.example.com
Status: Selected
Resolved IPs: -
```
Data scientists now have access to `ai.example.com` and all its subdomains. You can create additional access policies for individual subdomains or organize data scientists into teams with different permissions as needed.

152
src/pages/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources.mdx Normal file
View File

@@ -0,0 +1,152 @@
# Accessing restricted domain resources
This guide shows how to access restricted websites or services using NetBird [Networks](/manage/networks) with [domain resources](/manage/networks#resources). Domain resources are useful when the target service is behind a load balancer with frequently changing IP addresses.
## Example scenario
A company hosts an accounting application at `accounting.example.com` on AWS infrastructure in the EU Central region. The application runs on an EC2 instance behind a load balancer.
The company wants to implement zero-trust access with role-based permissions:
- **Finance team**: HTTP/HTTPS access to `accounting.example.com` (ports 80 and 443)
- **Support team**: SSH access to the backend at `example.com` (port 22)
### Prerequisites
Before starting, ensure you have:
- [NetBird clients](/get-started) installed on finance and support team devices
- [Routing peers](/manage/networks#routing-peers) configured in the AWS VPC using [setup keys](/manage/peers/access-infrastructure/setup-keys-add-servers-to-network)
## Create a network
1. Navigate to `Networks` > `Networks` in the NetBird dashboard
2. Click `Add Network`
3. Enter a name (e.g., `AWS EU Network`) and optional description
4. Click `Add Network`
![Create Network](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/01-restricted-domain.png)
### Add routing peers
Click `Add Routing Peer` to enable access to the network's resources.
![Add Routing Peers Window](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/02-restricted-domain.png)
In the next window:
- Select `Routing Peers` to add a single peer (e.g., `aws-router`)
- Or select `Peer Group` to add multiple peers for high availability
- Click `Continue`
![Local Routing Peers](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/03-restricted-domain.png)
In `Advanced Settings`:
- Enable `Masquerade` to access private networks without configuring local routers
- Set `Metric` to prioritize routers (lower values = higher priority)
- Click `Add Routing Peer`
![Masquerade and Metric](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/04-restricted-domain.png)
### Add the accounting subdomain resource
Click `Add Resource` to add the accounting website.
![Add Network Resource](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/05-restricted-domain.png)
Configure the resource:
- **Name**: `Accounting restricted subdomain`
- **Address**: `accounting.example.com`
- **Assigned Groups**: Select or create a group (e.g., `Accounting Subdomain`)
- Click `Add Resource`
![Add Accounting Website Resource](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/06-restricted-domain.png)
### Create an access policy for the finance team
Click `Create Policy` to define access for the finance team.
![Add Policy](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/07-restricted-domain.png)
Configure the policy:
- **Protocol**: `TCP`
- **Source**: `Finance` (the finance team group)
- **Destination**: `Accounting Subdomain` (auto-populated)
- **Ports**: `80` and `443`
![Finance Policy](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/08-restricted-domain.png)
Click `Continue` to optionally add posture checks, then `Continue` again. Enter a policy name (e.g., `Accounting subdomain Policy`) and click `Add Policy`.
![Finance Policy Name](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/09-restricted-domain.png)
### Add the top-level domain resource for support
The support team needs SSH access to the backend at `example.com`. Add a new resource:
1. In the `AWS EU Network` screen, click `Add Resource`
2. Configure:
- **Name**: `Restricted Website TLD`
- **Address**: `example.com`
- **Assigned Groups**: Select or create a group (e.g., `Webserver`)
![Add TLD Resource](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/10-restricted-domain.png)
### Create an access policy for the support team
Create a policy for SSH access:
1. Click `Add Policy` next to the `Restricted Website TLD` resource
2. Configure:
- **Protocol**: `TCP`
- **Source**: `Support`
- **Destination**: `Webserver`
- **Ports**: `22`
3. Click `Continue`
![Add Support Team Policy](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/11-restricted-domain.png)
4. Optionally add posture checks, then click `Continue`
5. Enter a policy name (e.g., `Restricted Website TLD Policy`)
![Name Support Team Policy](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/12-restricted-domain.png)
## Verify the configuration
The completed network shows both resources with their access policies:
![AWS EU Network](/docs-static/img/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources/13-restricted-domain.png)
Use the NetBird CLI to verify access. From a finance team workstation:
```bash
$ netbird networks list
Available Networks:
- ID: Accounting restricted subdomain
Domains: accounting.example.com
Status: Selected
Resolved IPs: -
- ID: Internal Web Services
Domains: *.company.internal
Status: Selected
Resolved IPs: -
```
From a support team workstation:
```bash
$ netbird networks list
Available Networks:
- ID: Internal Web Services
Domains: *.company.internal
Status: Selected
Resolved IPs: -
- ID: Restricted Website TLD
Domains: example.com
Status: Selected
Resolved IPs:
[example.com]: 93.184.215.14, 2606:2800:21f:cb07:6820:80da:af6b:8b2c
```
Each team sees only the resources they have access to, with appropriate port restrictions enforced by the access policies.

125
src/pages/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources.mdx Normal file
View File

@@ -0,0 +1,125 @@
# Routing traffic to multiple IP resources
This guide shows how to route traffic to multiple IP resources using NetBird [Networks](/manage/networks) with [IP resources](/manage/networks#resources). This is a common scenario for DevOps and Platform teams who need to provide differentiated access to on-premises or cloud infrastructure.
## Example scenario
In this example, you will configure access to an internal network (`172.16.0.0/15`) with these requirements:
- All users need access to DNS servers at `172.16.30.2` and `172.17.100.2` (UDP port 53 only)
- The DevOps team needs full access to the entire network range
Traffic will be routed through [routing peers](/manage/networks#routing-peers) running inside the network.
### Create a network
Navigate to `Networks` > `Networks` in the NetBird dashboard:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/view-wild-network-1.png" alt="new-net-1" className="imagewrapper-big"/>
</p>
Click `Add Network` to open the setup wizard. Enter a name and description for the network, then click `Continue`:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/new-example-network-2.png" alt="new-net2" className="imagewrapper"/>
</p>
### Add a routing peer
Click `Add routing peer` and select a peer from your network:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-routing-peer-1.png" alt="new-example-routing-peer-1" className="imagewrapper"/>
</p>
Click `Continue`, then accept the defaults and click `Add Routing Peer`:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-routing-peer-2.png" alt="new-routing-peer-2" className="imagewrapper"/>
</p>
### Add the network resource
Click `Add Resource` and enter `Office network` as the name with IP range `172.16.0.0/15` as the address:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-resource-1.png" alt="new-example-resource-1" className="imagewrapper"/>
</p>
Assign the group `office-network` to this resource. This group will be used in the access policy for the DevOps team.
### Create an access policy for the network resource
Create a policy that grants the `DevOps` group full access to the `office-network` resource group.
Click `Create Policy` and configure the fields as shown:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-resource-acl-1.png" alt="new-resource-acl-1" className="imagewrapper-big"/>
</p>
Click `Continue` twice, then click `Add Policy`:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-resource-acl-2.png" alt="new-resource-acl-2" className="imagewrapper-big"/>
</p>
### Add the DNS server resources
Add the first DNS server as a resource. Click `Add Resource` and enter the IP address:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-resource-2.png" alt="new-example-resource-2" className="imagewrapper"/>
</p>
Assign the group `office-dns-servers` to this resource. When prompted to create a policy, click `Later` since you will add another DNS server first.
Add the second DNS server resource:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-resource-3.png" alt="new-example-resource-3" className="imagewrapper"/>
</p>
### Create an access policy for DNS servers
Create a policy that grants the `All users` group access to the `office-dns-servers` resource group on UDP port 53 only.
Click `Create Policy` and configure the fields:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-resource-acl-3.png" alt="new-resource-acl-3" className="imagewrapper-big"/>
</p>
Click `Continue` twice, then click `Add Policy`. Use a generic policy name to cover both DNS server addresses:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/add-example-resource-acl-4.png" alt="new-resource-acl-4" className="imagewrapper-big"/>
</p>
### View the network
After completing the wizard, the network appears in the Networks list:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/view-example-network-1.png" alt="view-example-network-1" className="imagewrapper-big"/>
</p>
Click the network name to view details:
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources/view-example-network-2.png" alt="view-example-network-2" className="imagewrapper-big"/>
</p>
From this view, you can edit or add resources and routing peers using the `Edit` buttons in each section.
You have now created a network with multiple resources that provide different access levels to different user groups within your organization.
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

166
src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx Normal file
View File

@@ -0,0 +1,166 @@
import { Note } from '@/components/mdx'
# Access Home Devices (VPN-to-Site)
This guide shows how to access your home network devices from anywhere using the Networks feature.
## What You'll Achieve
After following this guide, you'll be able to access your home NAS, media server, home automation, or any device on your home network from your laptop or phone—anywhere in the world.
```
Your Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Home NAS
(peer) (at home) (no NetBird)
```
## Prerequisites
- A [NetBird cloud account](https://app.netbird.io/) or [self-hosted instance](/selfhosted/selfhosted-quickstart)
- NetBird installed on your laptop or phone ([installation guide](/get-started/install))
- An always-on device at home to serve as the routing peer (Raspberry Pi, NAS with Docker, old laptop, etc.)
## Step 1: Connect Your Laptop to NetBird
If you haven't already, install NetBird on your laptop and connect:
1. Download NetBird from [app.netbird.io/install](https://app.netbird.io/install)
2. Run the application and click **Connect** in the system tray
3. Complete the sign-up process in your browser
4. Verify your device appears in the [NetBird dashboard](https://app.netbird.io/) under **Peers**
## Step 2: Add Your Laptop to a User Group
1. In the **Peers** section of the dashboard, select your laptop peer
2. Under **Assigned Groups**, add a new group: "Home Users"
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/access-home-devices/add-user-group.png" alt="Add user group" className="imagewrapper"/>
</p>
## Step 3: Find Your Home Subnet
Before configuring NetBird, identify your home network's subnet.
**On your routing peer device, run:**
```bash
# Linux
ip route | grep -E "^[0-9]"
# macOS
netstat -rn | grep default
```
Look for your local subnet, typically something like `192.168.1.0/24` or `192.168.0.0/24`.
## Step 4: Create a Network for Your Home LAN
1. Go to **Networks** in the NetBird dashboard
2. Click **Add Network**
3. Name it "Home LAN" and click **Save**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/access-home-devices/add-network-home-lan.png" alt="Add network" className="imagewrapper"/>
</p>
## Step 5: Add Your Home Subnet as a Resource
1. In your new network, click **Add Resource**
2. Enter a name like "Home Subnet"
3. Enter your home subnet (e.g., `192.168.1.0/24`)
4. Create a group called `home-lan` for the destination
5. Click **Add Resource**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/access-home-devices/add-resource-home-network.png" alt="Add resource" className="imagewrapper"/>
</p>
<Note>
For more granular access, add specific device IPs instead of the entire subnet. For example, add `192.168.1.50/32` to only allow access to your NAS.
</Note>
## Step 6: Create an Access Policy
1. After adding your resource, click **Create Policy**
2. Set **Source** to "Home Users"
3. Set **Destination** to `home-lan`
4. Set **Protocol** to All
5. Name it "Home LAN Access" and click **Add Policy**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/access-home-devices/add-policy-home-lan.png" alt="Add policy" className="imagewrapper"/>
</p>
## Step 7: Set Up the Routing Peer
The routing peer forwards traffic from NetBird to your local network. Use any always-on device:
- Raspberry Pi
- Synology NAS
- Apple TV/Android TV
- Home server
**Install NetBird on your routing peer:**
1. In the NetBird dashboard, go to **Setup Keys**
2. Create a new setup key (one-time use recommended). Add `home-lan` to **Auto-assigned groups** and click **Create Setup Key**.
<Note>
You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**.
</Note>
3. On your routing peer, run:
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_SETUP_KEY
```
4. In the Networks view, click **Add Routing Peer** on your Home LAN network
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/access-home-devices/add-routing-peer.png" alt="Add routing peer button" className="imagewrapper"/>
</p>
5. Select your new peer and click **Add Routing Peer**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/access-home-devices/add-routing-peer-home-network.png" alt="Add routing peer" className="imagewrapper"/>
</p>
## Step 8: Test the Connection
From your laptop (connected to a different network like mobile data or coffee shop WiFi):
```bash
ping 192.168.1.1 # Your router
ping 192.168.1.50 # Your NAS or other device
```
You can now access your home devices from anywhere.
## Common Home Devices to Access
| Device | Typical Access Method |
|--------|----------------------|
| Synology/QNAP NAS | Web UI (port 5000/5001), SMB shares |
| Home Assistant | Web UI (port 8123) |
| Plex/Jellyfin | Web UI (port 32400/8096) |
| Pi-hole | Web UI (port 80), DNS (port 53) |
| Security cameras | RTSP streams, web interfaces |
| Printers | IPP/AirPrint, web interfaces |
## Troubleshooting
**Can't reach home devices:**
1. Verify the routing peer is online: check `netbird status` on the routing peer
2. Ensure the routing peer can reach local devices: `ping 192.168.1.1` from the routing peer
3. Check that your access policy includes your user/device
**Intermittent connectivity:**
1. Ensure the routing peer has a stable internet connection
2. Check if your ISP blocks VPN traffic (try a different port or protocol)
## Next Steps
- **Need Site-to-Site?** If you want to connect two home networks together, see [Site-to-Site: Home Networks](/manage/network-routes/use-cases/by-scenario/site-to-site-home)
- **Advanced configuration:** See [Advanced Configuration](/manage/network-routes/use-cases/by-configuration/advanced-configuration) for masquerade options and access control details

215
src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx Normal file
View File

@@ -0,0 +1,215 @@
import { Note } from '@/components/mdx'
# Cloud to On-Premise Access (VPN-to-Site)
This guide shows how to connect cloud workloads to on-premise databases and services using the Networks feature.
## What You'll Achieve
After following this guide, your cloud applications will be able to securely access on-premise databases, APIs, and services without exposing them to the public internet.
```
Cloud VM ────► NetBird Tunnel ────► Routing Peer ────► Database Server
(peer) (on-prem) (no NetBird)
```
## Prerequisites
- A [NetBird cloud account](https://app.netbird.io/) or [self-hosted instance](/selfhosted/selfhosted-quickstart)
- Access to deploy VMs or containers in your cloud environment
- Network configuration permissions in your cloud VPC
## Step 1: Find Your On-Premise Subnet
Before configuring NetBird, identify your data center network's subnet.
**On your routing peer device, run:**
```bash
# Linux
ip route | grep -E "^[0-9]"
```
Look for your local subnet, typically something like `10.100.0.0/24`.
## Step 2: Create a Network for On-Premise Resources
1. Go to **Networks** in the NetBird dashboard
2. Click **Add Network**
3. Name it "On-Premise Data Center" and click **Save**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/cloud-to-on-prem/add-network-on-prem-datacenter.png" alt="Add network" className="imagewrapper"/>
</p>
## Step 3: Add Your Database as a Resource
1. In your new network, click **Add Resource**
2. Enter a name like "Database Servers"
3. Enter your database subnet or specific IP (e.g., `10.100.0.0/24` or `10.100.0.50/32`)
4. Create a group called `on-prem-databases` for the destination
5. Click **Add Resource**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/cloud-to-on-prem/add-resource-database-servers.png" alt="Add resource" className="imagewrapper"/>
</p>
<Note>
For more granular access, add specific database IPs instead of the entire subnet. For example, add `10.100.0.50/32` to only allow access to your production database.
</Note>
## Step 4: Create an Access Policy
1. After adding your resource, click **Create Policy**
2. Set **Source** to "`cloud-workloads`" (you'll create this group in the next step)
3. Set **Destination** to `on-prem-databases`
4. Set **Protocol** to TCP
5. Set **Ports** to the database ports (e.g., `5432` for PostgreSQL, `3306` for MySQL)
6. Name it "Cloud to Database Access" and click **Add Policy**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/cloud-to-on-prem/add-policy-on-prem-databases.png" alt="Add policy" className="imagewrapper"/>
</p>
## Step 5: Set Up the Routing Peer On-Premise
The routing peer forwards traffic from NetBird to your data center network. Install NetBird on a server that can reach the database:
1. In the NetBird dashboard, go to **Setup Keys**
2. Create a new setup key (one-time use recommended). Add `on-prem-databases` to **Auto-assigned groups** and click **Create Setup Key**.
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/cloud-to-on-prem/create-new-setup-key-on-prem-db.png" alt="Create setup key" className="imagewrapper"/>
</p>
<Note>
You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**.
</Note>
3. On your on-premise server, run:
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_SETUP_KEY
```
4. In the Networks view, click **Add Routing Peer** on your On-Premise Data Center network
5. Select your new peer and click **Add Routing Peer**
## Step 6: Deploy NetBird on `cloud-workloads`
Create a setup key for your cloud workloads:
1. In the NetBird dashboard, go to **Setup Keys**
2. Create a new setup key. Add "`cloud-workloads`" to **Auto-assigned groups** and click **Create Setup Key**.
**For VMs:**
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_CLOUD_SETUP_KEY
```
**For containers (Docker Compose):**
```yaml
services:
netbird:
image: netbirdio/netbird:latest
network_mode: host
cap_add:
- NET_ADMIN
environment:
- NB_SETUP_KEY=YOUR_SETUP_KEY
volumes:
- netbird-config:/etc/netbird
restart: unless-stopped
volumes:
netbird-config:
```
**For Kubernetes:**
Use the [NetBird Kubernetes Operator](/manage/integrations/kubernetes) for production deployments.
## Step 7: Verify Cloud Workload Group Assignment
After deploying NetBird on your cloud workloads:
1. Go to **Peers** in the NetBird dashboard
2. Verify your cloud workloads appear and are assigned to the "`cloud-workloads`" group
3. If using a setup key with auto-assigned groups, this happens automatically
## Step 8: Configure Your Application
Update your application's database connection to use the on-premise IP:
```python
# Example: Python with PostgreSQL
conn = psycopg2.connect(
host="10.100.0.50", # On-premise database IP
dbname="production",
user="app_user",
password="secure_password"
)
```
Your cloud application can now securely access the on-premise database.
## Cloud-Specific Considerations
### AWS
- Use VPC endpoints where possible for AWS services
- Security groups must allow traffic from the NetBird routing peer
- Consider using an Auto Scaling group for the routing peer with a static ENI
### GCP
- Firewall rules must allow traffic from the routing peer's internal IP
- Use instance groups for high availability
- Enable IP forwarding on the routing peer instance
### Azure
- Network security groups must allow traffic from the routing peer
- Consider using a Virtual Machine Scale Set for HA
- Enable IP forwarding on the routing peer NIC
## Best Practices
### Security
- Use dedicated setup keys per environment (e.g., `dev-workloads`, `staging-workloads`, `prod-workloads`)
- Restrict access policies to specific ports and protocols
- Enable [activity logging](/manage/activity) for compliance
### High Availability
- Deploy multiple routing peers and configure failover
- Monitor routing peer health with your existing tools
- Use cloud-native load balancing where appropriate
### Performance
- Place routing peers close to the resources they serve
- Use direct peering where possible (NetBird will automatically optimize paths)
- Monitor latency and throughput between environments
## Troubleshooting
**Cloud workload can't reach on-premise:**
1. Verify the routing peer is online: `netbird status`
2. Check the routing peer can reach the target: `ping 10.100.0.50`
3. Verify access policies are configured correctly
**High latency:**
1. Check routing peer placement and network connectivity
2. Verify traffic is using direct peer-to-peer connections (not relays)
3. Review cloud network configuration for bottlenecks
## Next Steps
- **Need Multi-Cloud Site-to-Site?** If you need to connect cloud VPCs across providers, see [Site-to-Site: Cloud](/manage/network-routes/use-cases/by-scenario/site-to-site-cloud)
- **Advanced configuration:** See [Advanced Configuration](/manage/network-routes/use-cases/by-configuration/advanced-configuration) for masquerade options and detailed access control

186
src/pages/manage/networks/use-cases/by-scenario/remote-worker-access.mdx Normal file
View File

@@ -0,0 +1,186 @@
import { Note } from '@/components/mdx'
# Remote Worker Access (VPN-to-Site)
This guide shows how to enable remote workers to securely access office resources using the Networks feature.
## What You'll Achieve
After following this guide, employees will be able to access office servers, applications, and services while working remotely—without exposing those resources to the internet.
```
Remote Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Office Server
(peer) (at office) (no NetBird)
```
## Prerequisites
- A [NetBird cloud account](https://app.netbird.io/) or [self-hosted instance](/selfhosted/selfhosted-quickstart)
- Admin access to office network infrastructure
- A server or VM at the office to serve as the routing peer
## Step 1: Connect a Remote Worker Device to NetBird
If you haven't already, install NetBird on a remote worker's laptop and connect:
1. Download NetBird from [app.netbird.io/install](https://app.netbird.io/install)
2. Run the application and click **Connect** in the system tray
3. Complete the sign-up process in your browser
4. Verify the device appears in the [NetBird dashboard](https://app.netbird.io/) under **Peers**
## Step 2: Add the Remote Worker to a User Group
1. In the **Peers** section of the dashboard, select the remote worker's device
2. Under **Assigned Groups**, add a new group: `remote-workers`
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/remote-worker-access/peer-remote-worker-assigned-group.png" alt="Add remote worker to group" className="imagewrapper"/>
</p>
## Step 3: Find Your Office Subnet
Before configuring NetBird, identify your office network's subnet.
**On your routing peer device, run:**
```bash
# Linux
ip route | grep -E "^[0-9]"
# Windows (PowerShell)
Get-NetRoute | Where-Object { $_.DestinationPrefix -like "*.*.*.*/*" }
```
Look for your local subnet, typically something like `10.0.0.0/24` or `192.168.1.0/24`.
## Step 4: Create a Network for Office Resources
1. Go to **Networks** in the NetBird dashboard
2. Click **Add Network**
3. Name it "Office LAN" and click **Save**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/remote-worker-access/add-network-office-lan.png" alt="Add network" className="imagewrapper"/>
</p>
## Step 5: Add Your Office Subnet as a Resource
1. In your new network, click **Add Resource**
2. Enter a name like "Office Subnet"
3. Enter your office subnet (e.g., `10.0.0.0/24`)
4. Create a group called `office-lan` for the destination
5. Click **Add Resource**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/remote-worker-access/add-resource-office-subnet.png" alt="Add resource" className="imagewrapper"/>
</p>
<Note>
For more granular access, add specific server IPs instead of the entire subnet. For example, add `10.0.0.50/32` to only allow access to a specific file server.
</Note>
## Step 6: Create an Access Policy
1. After adding your resource, click **Create Policy**
2. Set **Source** to "`remote-workers`"
3. Set **Destination** to `office-lan`
4. Set **Protocol** based on needs (TCP for most apps, All for full access)
5. Name it "Remote Worker Office Access" and click **Add Policy**
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/remote-worker-access/add-policy-remote-worker-office-access.png" alt="Create policy for remote worker office access" className="imagewrapper"/>
</p>
## Step 7: Set Up the Routing Peer
The routing peer forwards traffic from NetBird to your office network. Choose an always-on server at your office:
- A dedicated Linux VM
- A Windows Server
- A Docker container on an existing server
**Install NetBird on your routing peer:**
1. In the NetBird dashboard, go to **Setup Keys**
2. Create a new setup key (one-time use recommended). Add `office-lan` to **Auto-assigned groups** and click **Create Setup Key**.
<p>
<img src="/docs-static/img/manage/networks/use-cases/by-scenario/remote-worker-access/create-new-setup-key-office-lan.png" alt="Create setup key" className="imagewrapper"/>
</p>
<Note>
You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**.
</Note>
3. On your routing peer, run:
```bash
# Linux
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_SETUP_KEY
# Windows (PowerShell as Administrator)
Invoke-WebRequest -Uri "https://pkgs.netbird.io/install.ps1" -OutFile "install.ps1"; .\install.ps1
netbird up --setup-key YOUR_SETUP_KEY
```
4. In the Networks view, click **Add Routing Peer** on your Office LAN network
5. Select your new peer and click **Add Routing Peer**
## Step 8: Test the Connection
From the remote worker's laptop (connected outside the office network):
```bash
ping 10.0.0.1 # Your office router
ping 10.0.0.50 # Your file server or other device
```
Remote workers can now access office resources from any location.
## Step 9: Onboard Additional `remote-workers`
For additional remote workers:
1. Have employees install NetBird from [app.netbird.io/install](https://app.netbird.io/install)
2. After they connect, go to **Peers** and select their device
3. Under **Assigned Groups**, add them to the "`remote-workers`" group
Alternatively, create a setup key with "`remote-workers`" as an auto-assigned group for streamlined onboarding.
## Best Practices for Business Deployments
### Access Control
- Create specific groups for different access levels (e.g., `it-admins`, `sales`, `engineering`)
- Use protocol restrictions (e.g., only allow RDP to certain servers)
- Implement time-limited setup keys for contractor access
### High Availability
For critical connections, consider:
- Multiple routing peers at each location
- Monitoring routing peer health
- Automatic failover configuration
### Security
- Enable [Posture Checks](/manage/access-control/posture-checks) to verify device compliance
- Use [Activity Logging](/manage/activity) to audit access
- Implement MFA through your identity provider
## Troubleshooting
**Remote workers can't access office resources:**
1. Verify the routing peer is online and connected
2. Check access policies include the user's group
3. Ensure the routing peer can reach office resources locally
**Slow performance:**
1. Check routing peer placement—it should have good network connectivity
2. Consider enabling [lazy connections](/manage/peers/lazy-connection) for large deployments
3. Review network route priorities if multiple routes exist
## Next Steps
- **Need Site-to-VPN or Site-to-Site?** If office systems need to initiate connections to remote workers, or you need to connect branch offices, see [Network Routes Use Cases](/manage/network-routes/use-cases)
- **Advanced configuration:** See [Advanced Configuration](/manage/network-routes/use-cases/by-configuration/advanced-configuration) for masquerade options and detailed access control

89
src/pages/manage/networks/use-cases/index.mdx Normal file
View File

@@ -0,0 +1,89 @@
import { Tiles } from '@/components/Tiles'
import { Note } from '@/components/mdx'
# Networks Use Cases
These guides show how to use the [Networks](/manage/networks) feature for VPN-to-Site access—where NetBird peers access devices on remote networks that don't have NetBird installed.
## What is VPN-to-Site?
VPN-to-Site allows a device running NetBird (like your laptop) to access devices on a remote network (like your home or office) without installing NetBird on every device.
```
Your Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Target Device
(peer) (peer) (no NetBird)
```
**Example scenarios:**
- Access your home NAS from a coffee shop
- Reach office servers while traveling
- Connect to IoT devices on a remote network
<Note>
Networks supports VPN-to-Site only. For Site-to-VPN (clientless devices initiating connections) or Site-to-Site (connecting two networks), use [Network Routes](/manage/network-routes/use-cases).
</Note>
<Tiles
title="By Scenario"
items={[
{
href: '/manage/networks/use-cases/by-scenario/access-home-devices',
name: 'Access Home Devices',
description: 'Access your NAS, home automation, and media servers from anywhere',
},
{
href: '/manage/networks/use-cases/by-scenario/remote-worker-access',
name: 'Remote Worker Access',
description: 'Enable employees to access office resources while working remotely',
},
{
href: '/manage/networks/use-cases/by-scenario/cloud-to-on-premise',
name: 'Cloud to On-Premise',
description: 'Connect cloud workloads to on-premise databases and services',
},
]}
/>
## Understanding Resource Types
In Networks, a **resource** represents something you want to make accessible through the VPN tunnel—whether that's a single server, an entire subnet, or a domain-based service. Resources are what your routing peers make reachable to authorized NetBird clients.
NetBird supports three types of resources:
- **IP resources** — Single IP addresses (`192.168.1.10`) or CIDR ranges (`172.16.0.0/16`). Use these when you know the exact IP addresses of your target devices or want to grant access to an entire subnet.
- **Domain resources** — Specific fully-qualified domain names like `app.example.com`. Use these when the target service has a stable hostname but its IP address may change (common with cloud load balancers or dynamic DNS).
- **Wildcard domain resources** — Domain patterns like `*.internal.company.com` that match all subdomains. Use these when you have many services under a shared domain and want to avoid creating individual resources for each one.
Each resource can have its own access policy, allowing you to grant different levels of access to different teams—for example, giving developers full access to a development subnet while restricting everyone else to specific services.
<Tiles
title="By Resource Type"
items={[
{
href: '/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources',
name: 'Multiple IP Resources',
description: 'Route traffic to multiple IP resources with different access policies',
},
{
href: '/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources',
name: 'Domain Resources',
description: 'Access restricted websites and domain-based resources',
},
{
href: '/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks',
name: 'Wildcard Domains',
description: 'Access entire domains using wildcard DNS routing',
},
]}
/>
## Need More Than VPN-to-Site?
If your scenario requires:
- Clientless devices initiating connections (Site-to-VPN)
- Two networks communicating with each other (Site-to-Site)
- Disabling masquerade for source IP preservation
See [Network Routes Use Cases](/manage/network-routes/use-cases) instead.

375
src/pages/manage/peers/site-to-site/db-workload-migration.mdx
View File

@@ -1,375 +0,0 @@
# Simplify Connectivity During Workload Migrations
For DevOps and platform engineering teams, workload migration presents significant challenges, especially when transferring
data-intensive applications between different environments or cloud providers. Key challenges include:
* **Security Vulnerabilities**: Exposing databases or application servers to the public internet during migration increases
the risk of data breaches and unauthorized access.
* **Network Complexity**: Setting up VPNs or configuring firewall rules for temporary access complicates the migration
process and can lead to misconfigurations.
* **Performance Issues**: Traditional methods may suffer from latency and bandwidth limitations, slowing down large data
transfers.
This guide introduces NetBird as a solution for secure and efficient workload migration by:
* **Enhancing Security**: Creating a secure overlay network that implements zero-trust principles, ensuring data remains protected throughout the migration process.
* **Simplifying Network Configuration**: Eliminating the need for complex VPN setups or firewall rule changes, streamlining the migration workflow.
* **Optimizing Performance**: Using NetBird's decentralized, point-to-point connections to bypass central servers, potentially reducing network bottlenecks and, thus, latency.
To demonstrate how to use NetBird for securely migrating workloads to the cloud while maintaining access to on-premise databases, we'll walk through the following process:
* Set up a local PostgreSQL database with a sample table, simulating an on-premise data resource.
* Create a Python-based workload that interacts with this database, representing an on-premise application.
* Migrate the Python workload to a cloud instance, while keeping the database on-premise.
* Establish a secure connection between the cloud workload and on-premise database using NetBird.
* Verify that the migrated cloud workload can securely access and interact with the on-premise database.
This practical scenario illustrates how NetBird enables organizations to use cloud resources for workloads while maintaining secure access to sensitive on-premise data, facilitating a hybrid cloud approach to database workload migration.
## Prerequisites
To follow along with this use case, ensure you meet the following requisites:
* A [NetBird account](https://app.netbird.io/)
* [NetBird installed](https://docs.netbird.io/get-started/install) in your laptop or local machine.
* A cloud-based VM instance (e.g., AWS EC2, Google Compute Engine, or Azure VM) to serve as the destination for the migrated workload.
* Python 3.x installed on both source and destination instances.
* Ability to create and use Python virtual environments on both instances (optional but recommended to avoid OS conflicts).
* PostgreSQL and the corresponding client tools installed on the source (on-premise) instance.
* Sufficient permissions to create and modify database users and edit `postgresql.conf` and `pg_hba.conf` configuration files.
Now that you have the prerequisites ready let's outline the process for creating a secure pathway for workload migration between your local environment and the remote cloud VM:
1. Creating the Testing Environment (Local Database and Workload)
2. Installing and Configuring NetBird on Destination Instance(s)
3. Setting Up NetBird's Access Control for Secure Data Transfer
4. Preparing PostgreSQL Database for Remote Access via NetBird
5. Initiating Secure Connection for Database Workload Migration
This approach ensures a protected and efficient migration of your workload, leveraging NetBird's capabilities for enhanced security and simplified networking.
## 1. Creating the Testing Environment (Local Database and Workload)
Create a new database and user:
```bash
createdb demo_db
createuser -s demo_user
```
Connect to the database:
```bash
psql -d demo_db
```
Once connected, run the following SQL code to create the `employees` table and fill it with sample data:
```sql
CREATE TABLE employees (
id SERIAL PRIMARY KEY,
name VARCHAR(100),
department VARCHAR(100)
);
INSERT INTO employees (name, department) VALUES
('John Doe', 'IT'),
('Jane Smith', 'HR'),
('Mike Johnson', 'Sales');
```
Verify the table was created by printing it to the terminal:
```bash
$ psql -d demo_db -c "SELECT * FROM employees;"
```
The expected output is:
```bash
id | name | department
----+--------------+------------
1 | John Doe | IT
2 | Jane Smith | HR
3 | Mike Johnson | Sales
(3 rows)
```
With the database up and running, you are ready to create the local workload.
Create a new folder for the Python environment, then navigate to it and run:
```bash
python3 -m venv venv
```
Activate the `venv` virtual environment:
```bash
source venv/bin/activate
```
Install the dependencies for the demo workload:
```bash
pip install psycopg2-binary
```
Create the demo workload: `employee_workload.py`
```python
import psycopg2
def get_employees():
conn = psycopg2.connect(
dbname="demo_db",
user="demo_user",
password="",
host="localhost"
)
cur = conn.cursor()
cur.execute("SELECT * FROM employees")
rows = cur.fetchall()
cur.close()
conn.close()
return rows
if __name__ == "__main__":
employees = get_employees()
print("(On-Premise) Employee List:")
for employee in employees:
print(f"ID: {employee[0]}, Name: {employee[1]}, Department: {employee[2]}")
```
This is a simple workload that uses the `psycopg2` library to connect to the `demo_db` database you created a moment ago and then retrieve and print the values of the `employees` table to the terminal.
Run the script:
```bash
python3 employee_workload.py
```
Here's the expected output:
```bash
(On-Premise) Employee List:
ID: 1, Name: John Doe, Department: IT
ID: 2, Name: Jane Smith, Department: HR
ID: 3, Name: Mike Johnson, Department: Sales
```
Notice the `(On-Premise)` label in the code. You'll change this to `(Remote)` after migration to distinguish between local and remote workloads.
## 2. Installing and Configuring NetBird on Destination Instance(s)
With the on-premise environment ready, you can install NetBird on the destination instance.
Login to NetBird and navigate to `Peers`. Ensure the source instance, the one hosting the database, is connected.
![NetBird Local Peer](/docs-static/img/manage/peers/site-to-site/db-workload-migration/workload-migration-01.png)
Next, generate a setup key for enhanced security when connecting your remote workload to the NetBird network:
* Go to `Setup Keys` in the left menu
* Click `Create Setup Key`
* Enter a descriptive name for the setup key (e.g., "Remote Workload 01"). Also, set an expiration date and define auto-assigned groups (if required). You can find [more information regarding setup key options in the documentation](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys).
* Copy the generated key since you'll need it shortly
![NetBird Creating Setup Key](/docs-static/img/manage/peers/site-to-site/db-workload-migration/workload-migration-02.png)
To install the NetBird agent on the remote instance, run the following command:
```shell
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
The script automatically installs the NetBird agent and starts the corresponding service. Check the service is up and running:
```bash
sudo systemctl status netbird
```
The output should be similar to:
```bash
● netbird.service - A WireGuard-based mesh network that connects your devices i>
Loaded: loaded (/etc/systemd/system/netbird.service; enabled; preset: enab>
Active: active (running) since Thu 2024-09-19 15:52:27 UTC; 24s ago
Main PID: 2865 (netbird)
Tasks: 5 (limit: 1113)
Memory: 15.9M (peak: 16.1M)
CPU: 24ms
CGroup: /system.slice/netbird.service
└─2865 /usr/bin/netbird service run --config /etc/netbird/config.j>
```
To enable the service on startup, run:
```bash
sudo systemctl enable netbird
```
Now you can connect to the NetBird network using the setup key. Ensure to replace `<YOUR_SETUP_KEY>` with the key you generated:
```bash
netbird up --setup-key <YOUR_SETUP_KEY>
```
Check NetBird status by running:
```shell
sudo netbird status
```
The expected output is similar to the following:
```bash
OS: linux/amd64
Daemon version: 0.29.0
CLI version: 0.29.0
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 0/0 Available
FQDN: remote-workload.netbird.cloud
NetBird IP: 100.85.195.197/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 0/0 Connected
```
If everything goes as expected, you will see your remote workload in NetBird's `Peers` dashboard.
![NetBird Peers Network](/docs-static/img/manage/peers/site-to-site/db-workload-migration/workload-migration-03.png)
## 3. Setting Up NetBird's Access Control for Secure Data Transfer
NetBird's `Default` access control policy assigns all peers to the `All` group, enabling bidirectional access between devices and users. While this default setting allows immediate connectivity between your remote workload and on-premise database, it's recommended to implement stricter access controls. [NetBird Access Policies](https://docs.netbird.io/manage/access-control/manage-network-access) enable you to limit connections to the on-premise instance, ensuring only authorized users or devices can access it, thus enhancing security.
To create a new policy:
* Go to `Access Control > Policies`
* Click `Add Policy` to create a new policy. For more details on creating access policies, refer to [Managing Access with NetBird: Groups and Access Policies](https://docs.netbird.io/manage/access-control/manage-network-access).
For this use case, we disabled the `Default` policy and created the following one:
* **Source Group**: `On-Premise-DB`
* **Destination Group**: `Remote Workloads`
* **Protocol**: TCP
* **Port**: 5432 (default PostgreSQL port)
* **Action**: Allow
This policy restricts access to the local environment where the database is running by only allowing the members of the group `Remote Workloads` to connect.
![NetBird Access Policy](/docs-static/img/manage/peers/site-to-site/db-workload-migration/workload-migration-04.png)
The next step is to assign peers to their respective groups. To add the remote instance to the `Remote Workloads` group:
* Navigate to `Peers` in the left menu
* Click on `remote-workload` (or any name you gave to the remote instance)
* Find the `Assigned Groups` field and select `Remote Workloads` from the dropdown list.
![NetBird Remote Peer](/docs-static/img/manage/peers/site-to-site/db-workload-migration/workload-migration-05.png)
Follow a similar procedure to assign your local machine to the `On-Premise-DB` group:
* Locate and click on the local peer
* Find the `Assigned Groups` field and select `On-Premise-DB` from the dropdown list.
![NetBird Local User Peer](/docs-static/img/manage/peers/site-to-site/db-workload-migration/workload-migration-06.png)
Your network configuration is complete, enabling secure communication between the remote instance and your local machine via an encrypted WireGuard tunnel. However, additional adjustments are necessary to finalize the workload migration process.
## 4. Preparing PostgreSQL Database for Remote Access via NetBird
Your PostgreSQL database requires editing two files: `postgresql.conf` and `pg_hba.conf` to enable remote connections. Locate these files using the `psql` console, as their paths may vary based on your operating system and installation method:
```bash
$ psql postgres
```
Once logged, run the following commands:
```sql
SHOW config_file;
SHOW hba_file;
```
The output should be similar to:
```sql
config_file
-------------------------------------------------
/opt/homebrew/var/postgresql@14/postgresql.conf
(1 row)
hba_file
---------------------------------------------
/opt/homebrew/var/postgresql@14/pg_hba.conf
(1 row)
```
Now edit `postgresql.conf`. Uncomment and modify the line `listen_address` as follows:
```bash
listen_address = '*'
```
Next, edit `pg_hba.conf` and add the following line:
```bash
host all all 100.85.0.0/10 md5
```
These changes allow PostgreSQL to listen on all interfaces and accept connections from the NetBird IP range (100.85.0.0/10). While sufficient for this example, keep in mind that production environments should implement stronger authentication and security options.
## 5. Initiating Secure Connection for Database Workload Migration
To complete the migration, deploy your workload to the remote instance by recreating the local setup: establish a Python virtual environment, install the `psycopg2-binary` library, and create `employee_workload.py`. However, in the Python code, you must update the `host` parameter, replacing `localhost` with the NetBird-assigned IP address of the remote instance. You can find this IP address in your peers' list on your NetBird dashboard.
![NetBird IP Addresses](/docs-static/img/manage/peers/site-to-site/db-workload-migration/workload-migration-07.png)
Optionally, you can change the label `(On-Premise)` with `(Remote)` as mentioned earlier. The Python code should look similar to this:
```python
import psycopg2
def get_employees():
conn = psycopg2.connect(
dbname="demo_db",
user="demo_user",
password="",
host="NETBIRD_IP_OR_DOMAIN_NAME"
)
cur = conn.cursor()
cur.execute("SELECT * FROM employees")
rows = cur.fetchall()
cur.close()
conn.close()
return rows
if __name__ == "__main__":
employees = get_employees()
print("(Remote) Employee List:")
for employee in employees:
print(f"ID: {employee[0]}, Name: {employee[1]}, Department: {employee[2]}")
```
Now, run the script:
```bash
python3 employee_workload.py
```
Here's the output
```bash
(Remote) Employee List:
ID: 1, Name: John Doe, Department: IT
ID: 2, Name: Jane Smith, Department: HR
ID: 3, Name: Mike Johnson, Department: Sales
```
This simple script confirms the migration was successful. You just established a secure, firewall-free connection from your remote instance to your on-premise database via NetBird, which demonstrates its power in simplifying robust network security.

0
src/pages/use-cases/examples.mdx → src/pages/use-cases/cloud/aws-ecs-terraform.mdx
View File

60
src/pages/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm.mdx → src/pages/use-cases/cloud/distributed-multi-cloud-ai.mdx
View File

@@ -5,7 +5,7 @@ import {Note} from "@/components/mdx";
We are building a distributed AI infrastructure project that connects GPU clusters across many different cloud providers using Kubernetes orchestration. After some trial and error we got everything working. If you want to learn more about the process, the why, and how we got here check out our [article on the Knowledge Hub](https://netbird.io/knowledge-hub/multi-cloud-ai-mega-mesh). This setup uses ArgoCD as a GitOps control plane to manage workloads across multiple MicroK8s clusters, with NetBird providing secure zero-trust networking between all components.
<Note>
This document is actively being changed and tested. Please see 'Known Issues and Future Improvements' at the bottom of the page.
This document is actively being changed and tested. Please see 'Known Issues and Future Improvements' at the bottom of the page.
</Note>
<p>
@@ -23,7 +23,7 @@ We are building a distributed AI infrastructure project that connects GPU cluste
### Create the GKE Cluster
First, we'll create a Google Kubernetes Engine (GKE) cluster to host our ArgoCD control plane. This cluster will be the central management point for all our edge MicroK8s clusters. You don’t need to use GKE, but you will need to adapt these step to work with your provider.
First, we'll create a Google Kubernetes Engine (GKE) cluster to host our ArgoCD control plane. This cluster will be the central management point for all our edge MicroK8s clusters. You don't need to use GKE, but you will need to adapt these step to work with your provider.
```jsx
export GCP_PROJECT=netbird-demos
@@ -63,19 +63,19 @@ Add helm repository:
helm repo add netbirdio https://netbirdio.github.io/helms
```
Install [**cert-manager**](https://cert-manager.io/docs/installation/#default-static-install) for k8s API to communicate with the NetBird operator
Install [**cert-manager**](https://cert-manager.io/docs/installation/#default-static-install) for k8s API to communicate with the NetBird operator
```jsx
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.0/cert-manager.yaml
```
Add NetBird API token. You can create a PAT by following the steps [**here**](/manage/public-api#creating-a-service-user)
Add NetBird API token. You can create a PAT by following the steps [**here**](/manage/public-api#creating-a-service-user)
```jsx
kubectl create namespace netbirdkubectl -n netbird create secret generic netbird-mgmt-api-key --from-literal=NB_API_KEY=$(cat ~/nb-pat.secret)
```
Replace `~/nb-pat.secret` with your NetBird API key and create a [**`values.yaml`**](https://github.com/netbirdio/kubernetes-operator/blob/main/examples/ingress/values.yaml) file, check `helm show values netbirdio/kubernetes-operator` for more info
Replace `~/nb-pat.secret` with your NetBird API key and create a [**`values.yaml`**](https://github.com/netbirdio/kubernetes-operator/blob/main/examples/ingress/values.yaml) file, check `helm show values netbirdio/kubernetes-operator` for more info
```jsx
# managementURL: "https://netbird.example.io:443"
@@ -85,7 +85,7 @@ ingress:
enabled: true
netbirdAPI:
keyFromSecret:
keyFromSecret:
name: "netbird-mgmt-api-key"
key: "NB_API_KEY"
```
@@ -139,13 +139,13 @@ Now we need to integrate NetBird with ArgoCD and the statefulset service so that
kubectl -n argocd annotate svc/argocd-server netbird.io/expose="true" netbird.io/groups="argo-management-ui"
```
Next we will enable sidecars. **Why Sidecars?** The application controller needs to make API calls to remote MicroK8s clusters. The sidecar provides transparent network access to those clusters through the NetBird mesh.
Next we will enable sidecars. **Why Sidecars?** The application controller needs to make API calls to remote MicroK8s clusters. The sidecar provides transparent network access to those clusters through the NetBird mesh.
To enable sidecar functionality in your deployments, you first need to generate a setup key, either via the UI (enable the **Ephemeral Peers** options) or by following [**this guide**](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) for more details on setup keys. We will inject side-cars to ArgoCD application controller so it can communicate with remote MicroK8s clusters.
To enable sidecar functionality in your deployments, you first need to generate a setup key, either via the UI (enable the **Ephemeral Peers** options) or by following [**this guide**](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) for more details on setup keys. We will inject side-cars to ArgoCD application controller so it can communicate with remote MicroK8s clusters.
Note: We recommend checking out the section of our [Kubernetes Operator docs on using sidecars](/manage/integrations/kubernetes#accessing-remote-services-using-sidecars) for more context and detail.
Next, you'll create a secret in Kubernetes and add a new resource called `NBSetupKey`. The `NBSetupKey` name can then be referenced in your deployments or daemon sets to specify which setup key should be used when injecting a sidecar into your application pods. Below is an example of a secret and an `NBSetupKey` resource:
Next, you'll create a secret in Kubernetes and add a new resource called `NBSetupKey`. The `NBSetupKey` name can then be referenced in your deployments or daemon sets to specify which setup key should be used when injecting a sidecar into your application pods. Below is an example of a secret and an `NBSetupKey` resource:
```jsx
# secret.yaml
@@ -212,7 +212,7 @@ Each MicroK8s cluster represents a GPU enabled VM in our distributed AI infrastr
### VM Provisioning with User Data
When creating VMs in different cloud providers, use this user data script for automated provisioning. This script runs on first boot and configures everything needed for the node to join the Mega-Mesh infrastructure. Be sure to edit the `<SETUP-KEY>` variable.
When creating VMs in different cloud providers, use this user data script for automated provisioning. This script runs on first boot and configures everything needed for the node to join the Mega-Mesh infrastructure. Be sure to edit the `<SETUP-KEY>` variable.
```bash
#!/bin/bash
@@ -321,7 +321,7 @@ subjects:
- kind: ServiceAccount
name: argocd
namespace: kube-system
# Apply with:
microk8s.kubectl apply -f svc.yml
@@ -459,13 +459,13 @@ sudo certbot certonly --manual --preferred-challenges dns -d mega-mesh.net
- Manual mode with DNS challenge (you'll need to create a TXT record)
- Valid for mega-mesh.net domain
**Why DNS Challenge?** This allows us to get a certificate without needing HTTP server access, which is perfect for distributed infrastructure.
**Why DNS Challenge?** This allows us to get a certificate without needing HTTP server access, which is perfect for distributed infrastructure.
### Create Hugging Face Access Token
vLLM needs to download models from Hugging Face, so we need an access token.
Create one at: [https://huggingface.co/docs/hub/en/security-tokens](https://huggingface.co/docs/hub/en/security-tokens)
Create one at: [https://huggingface.co/docs/hub/en/security-tokens](https://huggingface.co/docs/hub/en/security-tokens)
### Create Kubernetes Secret for SSL and Tokens
@@ -508,14 +508,14 @@ microk8s.kubectl apply -f tls-secret.yaml
The application manifests are stored in a private GitHub repository. We need to give ArgoCD access to this repo.
**Repository Location:** [https://github.com/netbirdio/megamesh-argocd](https://github.com/netbirdio/megamesh-argocd)
**Repository Location:** [https://github.com/netbirdio/megamesh-argocd](https://github.com/netbirdio/megamesh-argocd)
**⚠️ Security Note:** This repository contains secrets and should NOT be public.
**Security Note:** This repository contains secrets and should NOT be public.
**Setup Steps:**
1. Generate an SSH key or GitHub Personal Access Token
2. Follow ArgoCD's guide: [https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/](https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/)
2. Follow ArgoCD's guide: [https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/](https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/)
3. Register the repository in ArgoCD UI or via CLI
### Understanding ApplicationSets
@@ -577,17 +577,17 @@ spec:
**How This Works:**
1. **Matrix Generator**: Combines two generators to create applications
- **Cluster Generator**: Finds all clusters with label `megamesh: "true"`
- **Git Generator**: Finds all directories under `apps/` in the repo
- **Cluster Generator**: Finds all clusters with label `megamesh: "true"`
- **Git Generator**: Finds all directories under `apps/` in the repo
2. **Template Variables**:
- `{{name}}`: Cluster name (e.g., "telekom-germany-cluster")
- `{{server}}`: Cluster API endpoint
- `{{path}}`: Directory path in Git (e.g., "apps/vllm")
- `{{path.basename}}`: Just the directory name (e.g., "vllm")
3. **Applications Created**:
- For each cluster with `megamesh: "true"` label
- For each cluster with `megamesh: "true"` label
- For each app directory in the repo
- Creates an Application named like: `aws-germany-cluster-vllm`
- Creates an Application named like: `aws-germany-cluster-vllm`
4. **Sync Policy**:
- **automated**: Automatically syncs changes from Git
- **prune: true**: Deletes resources not in Git
@@ -631,13 +631,13 @@ Geographic DNS routing ensures users connect to the nearest cluster for optimal
2. Create DNS policy with geolocation routing
3. Add A records for each cluster with region tags
**Reference:** [https://docs.cloud.google.com/dns/docs/routing-policies-overview](https://docs.cloud.google.com/dns/docs/routing-policies-overview)
**Reference:** [https://docs.cloud.google.com/dns/docs/routing-policies-overview](https://docs.cloud.google.com/dns/docs/routing-policies-overview)
### Verification Tools
**Check DNS propagation:** [https://www.whatsmydns.net/#A/mega-mesh.net](https://www.whatsmydns.net/#A/relay.netbird.io)
**Check DNS propagation:** [https://www.whatsmydns.net/#A/mega-mesh.net](https://www.whatsmydns.net/#A/relay.netbird.io)
**Global health monitoring:** [https://www.openstatus.dev/play/checker](https://www.openstatus.dev/play/checker)
**Global health monitoring:** [https://www.openstatus.dev/play/checker](https://www.openstatus.dev/play/checker)
### Test the Deployed Services
@@ -683,16 +683,16 @@ curl https://mega-mesh.net/v1/completions \
### Official Documentation
- **MicroK8s GPU Addon**: [https://microk8s.io/docs/addon-gpu](https://microk8s.io/docs/addon-gpu)
- **ArgoCD with MicroK8s**: [https://medium.com/@orangecola3/gitops-with-argocd-and-microk8s-4c70a92e43b2](https://medium.com/@orangecola3/gitops-with-argocd-and-microk8s-4c70a92e43b2)
- **External Cluster Registration**: [https://medium.com/pickme-engineering-blog/how-to-connect-an-external-kubernetes-cluster-to-argo-cd-using-bearer-token-authentication-d9ab093f081d](https://medium.com/pickme-engineering-blog/how-to-connect-an-external-kubernetes-cluster-to-argo-cd-using-bearer-token-authentication-d9ab093f081d)
- **MicroK8s GPU Addon**: [https://microk8s.io/docs/addon-gpu](https://microk8s.io/docs/addon-gpu)
- **ArgoCD with MicroK8s**: [https://medium.com/@orangecola3/gitops-with-argocd-and-microk8s-4c70a92e43b2](https://medium.com/@orangecola3/gitops-with-argocd-and-microk8s-4c70a92e43b2)
- **External Cluster Registration**: [https://medium.com/pickme-engineering-blog/how-to-connect-an-external-kubernetes-cluster-to-argo-cd-using-bearer-token-authentication-d9ab093f081d](https://medium.com/pickme-engineering-blog/how-to-connect-an-external-kubernetes-cluster-to-argo-cd-using-bearer-token-authentication-d9ab093f081d)
### NetBird Resources
- **Kubernetes Operator Deployment**: [/manage/integrations/kubernetes#deployment](/manage/integrations/kubernetes#deployment)
- **Service Mesh Sidecars**: [/manage/integrations/kubernetes#accessing-remote-services-using-sidecars](/manage/integrations/kubernetes#accessing-remote-services-using-sidecars)
- **Kubernetes Operator Deployment**: [/manage/integrations/kubernetes#deployment](/manage/integrations/kubernetes#deployment)
- **Service Mesh Sidecars**: [/manage/integrations/kubernetes#accessing-remote-services-using-sidecars](/manage/integrations/kubernetes#accessing-remote-services-using-sidecars)
### ArgoCD Resources
- **Private Repository Setup**: [https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/](https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/)
- **ApplicationSet Documentation**: [https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/)
- **Private Repository Setup**: [https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/](https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/)
- **ApplicationSet Documentation**: [https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/](https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/)

70
src/pages/use-cases/cloud/index.mdx Normal file
View File

@@ -0,0 +1,70 @@
import { Tiles } from '@/components/Tiles'
# Cloud Use Cases
Deploy NetBird across cloud environments to securely connect workloads, enable hybrid cloud connectivity, and simplify multi-cloud networking.
## Common Scenarios
- **Hybrid Cloud**: Connect cloud workloads to on-premise databases and services
- **Multi-Cloud**: Bridge AWS, GCP, and Azure environments without exposing traffic to the internet
- **Kubernetes**: Enable secure communication between clusters and external resources
- **Serverless**: Run NetBird on FaaS platforms for ephemeral, secure connectivity
- **Container Orchestration**: Deploy NetBird as a daemon set on ECS, EKS, or other container platforms
## Getting Started
For connecting cloud VPCs to on-premise networks, see the [Site-to-Site Connectivity Guide](/use-cases/site-to-site).
<Tiles
title="Guides"
items={[
{
href: '/use-cases/cloud/aws-ecs-terraform',
name: 'NetBird on AWS ECS',
description: 'Deploy NetBird as an ECS daemon set using Terraform',
},
{
href: '/use-cases/cloud/netbird-on-faas',
name: 'NetBird on Serverless (FaaS)',
description: 'Run NetBird on serverless platforms for ephemeral connectivity',
},
{
href: '/use-cases/cloud/routing-peers-and-kubernetes',
name: 'Routing Peers and Kubernetes',
description: 'Use routing peers to connect Kubernetes workloads to external networks',
},
{
href: '/use-cases/cloud/distributed-multi-cloud-ai',
name: 'Distributed Multi-Cloud AI',
description: 'Build distributed AI infrastructure across multiple clouds with ArgoCD and MicroK8s',
},
{
href: '/manage/networks/use-cases/by-scenario/cloud-to-on-premise',
name: 'Cloud to On-Premise Access',
description: 'Connect cloud workloads to on-premise databases and services',
},
{
href: '/manage/network-routes/use-cases/by-scenario/site-to-site-cloud',
name: 'Multi-Cloud Site-to-Site',
description: 'Bridge cloud VPCs across providers using Site-to-Site routing',
},
]}
/>
## Cloud Provider Considerations
### AWS
- Use VPC endpoints where possible for AWS services
- Security groups must allow traffic from NetBird routing peers
- Consider Auto Scaling groups with static ENIs for high availability
### GCP
- Enable IP forwarding on routing peer instances
- Firewall rules must allow traffic from routing peer internal IPs
- Use instance groups for redundancy
### Azure
- Enable IP forwarding on routing peer NICs
- Network security groups must allow routing peer traffic
- Consider Virtual Machine Scale Sets for HA

14
src/pages/use-cases/netbird-on-faas.mdx → src/pages/use-cases/cloud/netbird-on-faas.mdx
View File

@@ -1,12 +1,12 @@
# Running NetBird on serverless environments (FaaS)
Function as a Service (FaaS) is a cloud computing model where developers deploy small, specific-purpose code functions, managed by a cloud provider.
Function as a Service (FaaS) is a cloud computing model where developers deploy small, specific-purpose code functions, managed by a cloud provider.
FaaS environments, however, impose restrictions like limited access to the system's root, kernel, and network stack, crucial for security in shared cloud infrastructure.
Since [v0.25.3](https://github.com/netbirdio/netbird/releases), NetBird enables secure connectivity and access from serverless functions like AWS lambda and Azure Functions to cloud or on-premises servers,
containers, databases, and other internal resources. NetBird has adapted to the constraints of FaaS environments by leveraging netstack from
the [gVisor](https://github.com/google/gvisor) Go package, which is part of [Wireguard-go](https://github.com/netbirdio/wireguard-go),
Since [v0.25.3](https://github.com/netbirdio/netbird/releases), NetBird enables secure connectivity and access from serverless functions like AWS lambda and Azure Functions to cloud or on-premises servers,
containers, databases, and other internal resources. NetBird has adapted to the constraints of FaaS environments by leveraging netstack from
the [gVisor](https://github.com/google/gvisor) Go package, which is part of [Wireguard-go](https://github.com/netbirdio/wireguard-go),
enabling the WireGuard stack to run entirely in userspace. This approach circumvents the typical need for network or kernel-level access.
## How to enable netstack mode?
@@ -48,9 +48,9 @@ def Example():
# rest of the code...
```
## How to use NetBird in FaaS environments?
Cloud providers like AWS and Azure, allow you to configure custom runtime environments for their function services, in AWS this is called Lambda Layers,
Cloud providers like AWS and Azure, allow you to configure custom runtime environments for their function services, in AWS this is called Lambda Layers,
and in Azure, it's called containerized Azure Functions.
There are many ways that you can configure these environments with NetBird's client binary. We have created a simple example using containerized Azure Functions,
There are many ways that you can configure these environments with NetBird's client binary. We have created a simple example using containerized Azure Functions,
which you can find [Azure functions python db access example
](https://github.com/netbirdio/azure-functions-python-db-access).
](https://github.com/netbirdio/azure-functions-python-db-access).

2
src/pages/use-cases/routing-peers-and-kubernetes.mdx → src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx
View File

@@ -145,4 +145,4 @@ You can also verify that the agent is connected to the NetBird management dashbo
## Conclusion
By following these steps, you've successfully integrated Netbird within your Kubernetes cluster, enabling secure,
peer-to-peer networking between your Kubernetes pods and external services. This setup is particularly beneficial for
hybrid, multi-cloud environments and remote access, ensuring seamless connectivity and security across your infrastructure.
hybrid, multi-cloud environments and remote access, ensuring seamless connectivity and security across your infrastructure.

6
src/pages/use-cases/client-on-mikrotik-router.mdx → src/pages/use-cases/homelab/client-on-mikrotik-router.mdx
View File

@@ -53,7 +53,7 @@ Also, very few current MikroTik devices are optimized for running containers, so
### Prerequisites
1. RouterOS v7.5 or newer on MikroTik router, physical machine, or [CHR on a virtual machine](https://help.MikroTik.com/docs/display/ROS/Cloud+Hosted+Router%2C+CHR)
2. [Enabled container mode](https://help.MikroTik.com/docs/display/ROS/Container#Container-EnableContainermode)
3. [Installed RouterOS container package](https://help.MikroTik.com/docs/display/ROS/Container#Container-Containeruseexample)
3. [Installed RouterOS container package](https://help.MikroTik.com/docs/display/ROS/Container#Container-Containeruseexample)
from [extra packages](https://MikroTik.com/download)
4. Adequate storage, such as a good quality USB thumb drive or external SSD.
We should not put a container filesystem or container pull caches in the router's built-in flash storage.
@@ -154,7 +154,7 @@ Address will be 172.17.0.1/32 and routing peer will be our container. Don't forg
3. In firewall rules, enable logging for any dropp/reject rules to see if packets are being dropped.\
## Get a shell in the container
Assuming that our container keeps stopping because NetBird is crashing, we can override the container entrypoint
Assuming that our container keeps stopping because NetBird is crashing, we can override the container entrypoint
to get a shell in the container and investigate.
Setting the entrypoint to 600 gets us 10 minutes to investigate before the container stops.
```shell
@@ -166,7 +166,7 @@ When done revert the entrypoint back to NetBird:
/container/set entrypoint="" numbers=0
```
### NetBird starts and logs into management server but it doesn’t show up as online
### NetBird starts and logs into management server but it doesn't show up as online
Log shows something like this:
```
DEBG client/internal/login.go:93: connecting to the Management service https://api.netbird.io:443

52
src/pages/use-cases/homelab/index.mdx Normal file
View File

@@ -0,0 +1,52 @@
import { Tiles } from '@/components/Tiles'
# Homelab Use Cases
NetBird helps homelabbers securely access their home infrastructure from anywhere and connect multiple home networks together.
## Common Scenarios
- **Remote NAS Access**: Access your Synology, QNAP, or TrueNAS from anywhere
- **Home Automation**: Reach Home Assistant, smart home devices, and IoT systems remotely
- **Media Servers**: Stream from Plex, Jellyfin, or Emby while traveling
- **Family Network Sharing**: Connect your home network with family members' networks
- **Self-hosted Services**: Access Pi-hole, Nextcloud, and other self-hosted applications
## Getting Started
For connecting entire home networks (accessing devices that don't have NetBird installed), see the [Site-to-Site Connectivity Guide](/use-cases/site-to-site).
<Tiles
title="Guides"
items={[
{
href: '/use-cases/homelab/client-on-mikrotik-router',
name: 'NetBird on MikroTik Router',
description: 'Run NetBird directly on your MikroTik router for whole-network connectivity',
},
{
href: '/manage/networks/use-cases/by-scenario/access-home-devices',
name: 'Access Home Devices',
description: 'Set up VPN-to-Site access to reach home network devices from anywhere',
},
{
href: '/manage/network-routes/use-cases/site-to-site-home',
name: 'Connect Home Networks',
description: 'Link multiple home networks together using Site-to-Site routing',
},
]}
/>
## Recommended Setup
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)
| Scenario | Recommended Feature |
|----------|---------------------|
| Access home devices from laptop/phone | [Networks](/manage/networks) |
| Connect two home networks | [Network Routes](/manage/network-routes) |
| Run NetBird on router | [MikroTik Guide](/use-cases/homelab/client-on-mikrotik-router) |

31
src/pages/use-cases/index.mdx Normal file
View File

@@ -0,0 +1,31 @@
import { Tiles } from '@/components/Tiles'
# Use Cases
Explore practical examples and guides for deploying NetBird across different environments and scenarios.
<Tiles
title=""
items={[
{
href: '/use-cases/homelab',
name: 'Homelab',
description: 'Connect home networks, access NAS devices, and link family homes together',
},
{
href: '/use-cases/cloud',
name: 'Cloud',
description: 'Deploy NetBird on AWS, Kubernetes, serverless platforms, and multi-cloud environments',
},
{
href: '/use-cases/security',
name: 'Security',
description: 'Implement zero trust networking and secure access patterns',
},
{
href: '/use-cases/site-to-site',
name: 'Site-to-Site Connectivity',
description: 'Connect entire networks together for VPN-to-Site, Site-to-VPN, and Site-to-Site scenarios',
},
]}
/>

132
src/pages/use-cases/implement-zero-trust.mdx → src/pages/use-cases/security/implement-zero-trust.mdx
View File

@@ -87,19 +87,19 @@ This section defines how terms are used in this guide and in NetBird.
- **Overlay network and overlay IP**
The overlay network is a virtual network that NetBird creates on top of your existing infrastructure (a "network on top of a network"). For each NetBird tenant, the overlay is a random /16 CIDR block within the `100.64.0.0/10` range (a private IP range reserved for carrier-grade NAT). Each peer receives an overlay IP address from this /16 range for communication with other peers. Internal networks never see WireGuard encryption keys or tunnels directly. They only see overlay IPs or the routing peer's IP address, depending on whether masquerading is enabled (see Section 6.2).
- **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.
- **Posture check**
A rule that evaluates device state, such as OS version, client version, geographic location, local network range, or running processes. Policies can require one or more posture checks to pass before allowing traffic.
- **SIEM (Security Information and Event Management)**
A security platform that collects, analyzes, and stores security events from various sources. Examples include Datadog, AWS Firehose, and S3-based pipelines. SIEMs ingest NetBird events (traffic flows, policy changes, authentication events) for visibility, alerting, and compliance reporting.
### 1.2 Resources and scopes
@@ -110,7 +110,7 @@ This section defines how terms are used in this guide and in NetBird.
- **Scope**
A bounded set of users, groups, peers, and resources that belong together operationally. Examples include `prod-orders-app`, `prod-admin-portal`, or `dev-tooling`.
---
@@ -122,7 +122,7 @@ In this guide, "resources" refers to what you are protecting: applications, serv
### Phase 1: Select initial protected resources
Start with one or two concrete resources, not “our whole network”. For example:
Start with one or two concrete resources, not "our whole network". For example:
- Customer-facing admin portal
- Remote access to internal developer tools
@@ -138,7 +138,7 @@ You are not configuring anything yet. You are deciding what to bring under Zero
**Outcome of Phase 1**
- One to two clearly named resource scopes (for example, `prod-order-api`, `prod-admin-portal`)
- One to two clearly named resource scopes (for example, `prod-order-api`, `prod-admin-portal`)
- A simple inventory of who needs access (users, service accounts) and what they access (hosts, services, subnets) per scope
- A named owner for each resource who can confirm whether the rollout broke anything
@@ -177,7 +177,7 @@ Now decide how access should look under a Zero Trust posture.
For each flow identified in Phase 2:
- Is this flow required, or is it legacy or “nice to have”?
- Is this flow required, or is it legacy or "nice to have"?
- Which side should initiate the connection?
- Which protocol and port are actually required?
- Should the flow be allowed, restricted to a smaller group, or blocked?
@@ -212,7 +212,7 @@ Where to do this: [Integrations → Identity Provider Sync](/manage/team/idp-syn
Map:
- Your IdP groups (for example `DevOps`, `Support`, `Finance`) to NetBird groups where it makes sense
- Your IdP groups (for example `DevOps`, `Support`, `Finance`) to NetBird groups where it makes sense
- A small pilot set of users (for example DevOps and the owners of your Phase 1 resources)
Do not expose production Networks yet. At this stage, you only need authenticated identities and a few test peers.
@@ -240,20 +240,20 @@ Where to manage groups: [Access Control → Groups](/manage/access-control).
Recommended naming:
- `peer-<team>-<env>` for user devices
- `peer-devops-prod`, `peer-support`, `peer-contractors`
- `svc-<app>-<tier>-<env>` for services and hosts
- `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod`
- `net-<location>-<purpose>` for routed Networks
- `net-aws-euc1-prod`, `net-dc-dc1-lan`
- `peer-<team>-<env>` for user devices
- `peer-devops-prod`, `peer-support`, `peer-contractors`
- `svc-<app>-<tier>-<env>` for services and hosts
- `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod`
- `net-<location>-<purpose>` for routed Networks
- `net-aws-euc1-prod`, `net-dc-dc1-lan`
Use suffixes for environment:
- `dev`, `stage`, `prod`
- `dev`, `stage`, `prod`
The exact scheme is up to you. The important point is to pick a convention and stick with it. Without one, the group and policy list will become unmanageable.
See [Appendix A](#appendix-a-naming-and-object-cheat-sheet) for a quick naming cheat sheet.
See [Appendix A](#appendix-a-naming-and-object-cheat-sheet) for a quick naming cheat sheet.
### 3.3 Setup keys for automation and service accounts
@@ -263,13 +263,13 @@ See [Appendix A](#appendix-a-naming-and-object-cheat-sheet) for a quick naming
- Servers without human login (CI runners, Kubernetes nodes, headless Linux boxes)
- Automated deployment through MDM, RMM, or configuration management tools
Where to manage them: Setup Keys.
Where to manage them: Setup Keys.
Guidelines:
- Create scoped keys per environment:
- `setup-prod-servers` that auto-assigns `svc-*-prod` groups
- `setup-stage-servers` that auto-assigns `svc-*-stage` groups
- `setup-prod-servers` that auto-assigns `svc-*-prod` groups
- `setup-stage-servers` that auto-assigns `svc-*-stage` groups
- Prefer one-off keys for bulk enrollment and delete them after use.
- Restrict who can view or create setup keys.
@@ -326,7 +326,7 @@ NetBird posture checks evaluate device state before allowing traffic. They can v
- Network CIDR the peer is connected from
- Presence of specific processes
Where to configure them: [Access Control → Posture Checks](/manage/access-control/posture-checks).
Where to configure them: [Access Control → Posture Checks](/manage/access-control/posture-checks).
<Warning>
Posture checks are not a security boundary against compromised endpoints. They validate configuration and policy compliance, not trustworthiness. An attacker with admin rights on a device can bypass or spoof them. Design your policies assuming posture checks can be evaded.
@@ -335,7 +335,7 @@ Posture checks are not a security boundary against compromised endpoints. They v
Recommended posture checks per policy:
- **Client version**
- Enforce minimum NetBird version (for example `>= 0.45.0`) for critical access.
- Enforce minimum NetBird version (for example `>= 0.45.0`) for critical access.
- **OS and version**
- Block unsupported or unpatched OS versions on production access.
- **Geolocation or peer network range**
@@ -404,7 +404,7 @@ Resource groups:
- `svc-orders-app-prod`
- `svc-orders-db-prod`
- `svc-monitoring`
- `svc-dns-prod` (or a Network resource containing the DNS IPs)
- `svc-dns-prod` (or a Network resource containing the DNS IPs)
Diagram:
@@ -436,20 +436,20 @@ All Peers ──UDP,TCP/53──► Internal DNS (svc-dns-prod)
**Policies**
1. **Users to web**
- Source: `peer-devops-prod`, `peer-support`
- Destination: `svc-orders-web-prod`
- Source: `peer-devops-prod`, `peer-support`
- Destination: `svc-orders-web-prod`
- Protocol: TCP, Port: 443
2. **Web to app**
- Source: `svc-orders-web-prod`
- Destination: `svc-orders-app-prod`
- Source: `svc-orders-web-prod`
- Destination: `svc-orders-app-prod`
- Protocol: TCP, Port: 8443
3. **App to DB**
- Source: `svc-orders-app-prod`
- Destination: `svc-orders-db-prod`
- Source: `svc-orders-app-prod`
- Destination: `svc-orders-db-prod`
- Protocol: TCP, Port: 5432
4. **Monitoring**
- Source: `svc-monitoring`
- Destination: `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod`
- Source: `svc-monitoring`
- Destination: `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod`
- Protocol: TCP, Ports: 9100 and 9200
5. **DNS (critical, often forgotten)**
- Source: all peer groups that use this environment (`peer-devops-prod`, `peer-support`, `svc-*`)
@@ -478,7 +478,7 @@ The example above uses group names for readability. The actual API requires grou
**Deliberately not allowed**
- Any `peer-*` group to the database directly.
- Any `peer-*` group to the database directly.
- Database initiating connections to app or web tiers.
- Support laptops directly to the DB or app backend.
@@ -500,15 +500,15 @@ 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.
<Warning>
**Network Routes vs Networks:** Legacy [Network Routes](/manage/network-routes/routing-traffic-to-private-networks) bypass Access Control policies by default unless [Access Control Groups are explicitly configured](/manage/network-routes/configuring-routes-with-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.
**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/use-cases/by-configuration/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.
</Warning>
### 5.1 Requirements for a routing peer
A routing peer is a NetBird peer that:
- Has network access to one or more internal subnets (for example `10.10.0.0/16`)
- Is selected as a routing peer in a [Network](/manage/networks) or [Network Route](/manage/network-routes/routing-traffic-to-private-networks) configuration
- Has network access to one or more internal subnets (for example `10.10.0.0/16`)
- Is selected as a routing peer in a [Network](/manage/networks) or [Network Route](/manage/network-routes) configuration
<p>
<img src="/docs-static/img/manage/networks/netbird-network-routes.png" alt="high-level-dia" className="imagewrapper-big"/>
@@ -539,7 +539,7 @@ General rules:
- Create a Network that includes:
- IP ranges (for example `10.10.0.0/16` - the `/16` means the first 16 bits are the network portion, allowing 65,536 IP addresses)
- DNS resources (for example `db.internal.example.com` for a specific hostname, or `*.corp.internal` for all subdomains) where appropriate
- Add a DNS server in NetBird with the right match domain (for example `corp.internal`) under [DNS → Nameservers](/manage/dns/nameserver-groups).
- Add a DNS server in NetBird with the right match domain (for example `corp.internal`) under [DNS → Nameservers](/manage/dns/nameserver-groups).
- Add explicit policies allowing peers to reach the DNS servers themselves (UDP and TCP 53 to the resolver IPs).
<Note>
@@ -573,11 +573,11 @@ Practical recommendations:
- Backup or cross-region routing peer: metric 200
- For critical Networks, run at least two routing peers in separate failure domains (different zones, racks, or hosts).
- Monitor routing peers with your existing monitoring plus NetBird events. If one fails, verify that clients start using the other peers.
- Verify HA behavior by simulating a failure and checking route selection with `netbird status -d` and test traffic.
- Verify HA behavior by simulating a failure and checking route selection with `netbird status -d` and test traffic.
The same pattern applies to exit nodes that provide default routes for internet-bound traffic.
See [Appendix B](#appendix-b-quick-reference-and-commands) for a quick HA checklist.
See [Appendix B](#appendix-b-quick-reference-and-commands) for a quick HA checklist.
### 6.2 Masquerading versus return routes
@@ -588,29 +588,29 @@ Masquerading (also called NAT masquerading or source NAT) controls how routed tr
- Internal firewall log:
- `10.10.0.5 → 10.10.1.10:5432`
This usually works out of the box because internal firewalls already trust the routing peer’s subnet. NetBird enables masquerading by default.
This usually works out of the box because internal firewalls already trust the routing peer's subnet. NetBird enables masquerading by default.
**With masquerading disabled**, internal systems see the original NetBird overlay IP:
- Internal firewall log:
- `100.64.1.45 → 10.10.1.10:5432`
- where `100.64.1.45` is a NetBird overlay address (always within `100.64.0.0/10`)
- where `100.64.1.45` is a NetBird overlay address (always within `100.64.0.0/10`)
To make non-masqueraded traffic work you must:
1. Add a route for the overlay range in your internal router or firewall, pointing to the routing peer’s internal IP.
1. Add a route for the overlay range in your internal router or firewall, pointing to the routing peer's internal IP.
2. Allow that traffic in internal firewall rules.
Examples for non-masquerade mode:
- **Linux router:**
```bash
# Add a route: send all traffic destined for 100.64.0.0/10
# Add a route: send all traffic destined for 100.64.0.0/10
# through the gateway at 10.10.0.5 (the routing peer's internal IP)
ip route add 100.64.0.0/10 via 10.10.0.5
```
- **AWS VPC route table:**
- Destination: `100.64.0.0/10` (the NetBird overlay range)
- Target: ENI (Elastic Network Interface) of the routing peer instance (the network interface attached to your EC2 instance running the routing peer)
@@ -635,13 +635,13 @@ If you need real client IP visibility for logging while passing traffic through
At larger scale, you will care about:
- Overlapping routes to different environments (for example, multiple `172.17.0.0/16` networks)
- Overlapping routes to different environments (for example, multiple `172.17.0.0/16` networks)
- Connection overhead for many peers
NetBird has route selection tools and an experimental lazy connections feature for large networks. In practice:
- Use network/route selection to avoid accidental routing into the wrong VPC or site when CIDRs overlap. You can do this in the systray application or via the command line.
- [Lazy connections](/manage/peers/lazy-connections) reduce CPU and battery usage on devices by establishing tunnels only when traffic is sent, rather than maintaining keep-alive with every peer in the mesh. Note that lazy connections is an experimental feature that requires NetBird client version 0.50.1 or later and does NOT support accessing resources through routing peers (Networks). Review the current scaling guidance and lazy connections documentation before rolling out to thousands of peers.
- [Lazy connections](/manage/peers/lazy-connection) reduce CPU and battery usage on devices by establishing tunnels only when traffic is sent, rather than maintaining keep-alive with every peer in the mesh. Note that lazy connections is an experimental feature that requires NetBird client version 0.50.1 or later and does NOT support accessing resources through routing peers (Networks). Review the current scaling guidance and lazy connections documentation before rolling out to thousands of peers.
<Note>
**Verification checklist:**
@@ -737,7 +737,7 @@ For each pattern:
1. Apply it to dev first:
- Use the same group and policy structure (`peer-devops-dev → svc-orders-web-dev`, etc.).
2. Mirror to staging, refine there, then apply to prod.
3. Keep group and policy names aligned across environments, only changing the `dev`, `stage`, `prod` suffix.
3. Keep group and policy names aligned across environments, only changing the `dev`, `stage`, `prod` suffix.
This keeps cognitive load low and reduces surprises in production.
@@ -747,9 +747,9 @@ When you move from broad access to strict Zero Trust, have an explicit rollback
- Maintain one "break glass" access method (for example, a physical console or a separate VPN/bastion) that does *not* rely on NetBird during the initial setup phase.
- Keep a known good emergency broad policy, for example:
`peer-devops-prod → net-aws-euc1-prod [ALL]` but keep it disabled.
- If production breaks and you cannot immediately identify the cause:
1. Temporarily enable the emergency policy.
2. Confirm that service has recovered.
@@ -768,18 +768,18 @@ To keep the system healthy over time:
- Enforce group and policy naming consistently.
- Example policy name pattern:
`peer-devops-prod → svc-orders-db-prod [TCP/5432]`
- Use policy descriptions to record the business justification and owner:
- “Orders app backend to DB, owned by App Team X”
- "Orders app backend to DB, owned by App Team X"
- Periodically review:
- Unused groups
- Redundant policies
- Peers that have not connected recently
- Keep an eye on:
- NetBird client versions (enforce minimum via posture checks)
- Routing peers’ capacity and health
- Routing peers' capacity and health
<Note>
**Verification checklist:**
@@ -794,7 +794,7 @@ To keep the system healthy over time:
This section provides practical checks and commands you can run on peers.
### 9.1 “Policy exists but connection is still blocked”
### 9.1 "Policy exists but connection is still blocked"
Most often:
@@ -806,9 +806,9 @@ Most often:
What to do:
- Check the policy and its posture checks in **Access Control → Policies**.
- Confirm the peer’s group membership in the dashboard under **Peers**.
- Look at Traffic Events for explicit “blocked due to posture” or “no matching policy” entries.
- Check the policy and its posture checks in **Access Control → Policies**.
- Confirm the peer's group membership in the dashboard under **Peers**.
- Look at Traffic Events for explicit "blocked due to posture" or "no matching policy" entries.
Useful commands on the peer:
@@ -817,7 +817,7 @@ Useful commands on the peer:
netbird status -d
```
### 9.2 “Connection works sometimes”
### 9.2 "Connection works sometimes"
Common causes:
@@ -830,7 +830,7 @@ Common causes:
What to do:
- Check routing peers’ health and logs.
- Check routing peers' health and logs.
- Use network listing and selection on the client to see which routes are active:
```bash
@@ -852,9 +852,9 @@ What to do:
netbird routes deselect "route_id"
netbird routes select "route_id"
```
### 9.3 “After deleting the Default policy, nothing works”
### 9.3 "After deleting the Default policy, nothing works"
Cause:
@@ -863,7 +863,7 @@ Cause:
Fix:
- Create a broad but scoped policy:
- For example `peer-devops-prod → svc-orders-*` with required ports.
- For example `peer-devops-prod → svc-orders-*` with required ports.
- Test that critical access works.
- Only then delete the Default policy and tighten further.
@@ -888,16 +888,16 @@ Fix:
- Ports: UDP and TCP 53
- Verify DNS routing configuration in Networks and match domains.
- From a client, run DNS lookup commands and compare behavior with your expectations:
```bash
# nslookup: Basic DNS lookup tool (works on Windows, Linux, macOS)
nslookup db.internal.example.com
# dig: More detailed DNS query tool (Linux/macOS, or install on Windows)
# The @10.10.0.10 specifies which DNS server to query
dig @10.10.0.10 db.internal.example.com
```
- **Linux:** `resolvectl status` (systemd-resolved command to see if the NetBird interface has the right DNS domains configured)
- **Windows:** `Get-DnsClientNrptPolicy` (PowerShell command to see if Name Resolution Policy Table rules are active; these tell Windows which DNS server to use for specific domains)
@@ -1003,4 +1003,4 @@ netbird routes ls
- At least two routing peers per critical NetBird Network.
- Different failure domains (AZs, racks, hosts).
- Primary metric 100, backup metric 200.
- Monitor both NetBird health and OS-level metrics.
- Monitor both NetBird health and OS-level metrics.

53
src/pages/use-cases/security/index.mdx Normal file
View File

@@ -0,0 +1,53 @@
import { Tiles } from '@/components/Tiles'
# Security Use Cases
Implement zero trust networking and secure access patterns with NetBird.
## Zero Trust Principles
NetBird is built on zero trust principles:
- **Verify explicitly**: Every connection is authenticated and authorized
- **Least privilege**: Access is granted only to specific resources, not entire networks
- **Assume breach**: End-to-end encryption ensures traffic is protected even if networks are compromised
## Key Security Features
| Feature | Description |
|---------|-------------|
| [Access Control Policies](/manage/access-control) | Define who can access what resources |
| [Posture Checks](/manage/access-control/posture-checks) | Verify device compliance before granting access |
| [Activity Logging](/manage/activity) | Audit all access events |
| [MFA Integration](/manage/settings/multi-factor-authentication) | Enforce multi-factor authentication |
| [SSO](/manage/team/single-sign-on) | Integrate with identity providers |
<Tiles
title="Security Guides"
items={[
{
href: '/use-cases/security/implement-zero-trust',
name: 'Implement Zero Trust',
description: 'Step-by-step guide to implementing zero trust networking with NetBird',
},
{
href: '/manage/access-control/posture-checks',
name: 'Posture Checks',
description: 'Verify device compliance before allowing network access',
},
{
href: '/manage/access-control/endpoint-detection-and-response',
name: 'EDR/MDM Integration',
description: 'Integrate with CrowdStrike, Intune, SentinelOne, and other security tools',
},
]}
/>
## Security Best Practices
1. **Segment your network** - Create specific groups for different access levels
2. **Use protocol restrictions** - Only allow the protocols and ports needed
3. **Enable posture checks** - Verify device compliance before granting access
4. **Monitor activity** - Review audit logs regularly
5. **Implement MFA** - Require multi-factor authentication for all users
6. **Use time-limited access** - Create expiring setup keys for temporary access

529
src/pages/use-cases/setup-site-to-site-access.mdx
View File

@@ -1,529 +0,0 @@
import {Note} from "@/components/mdx";
# Setting up Site-to-Site/VPN access over NetBird
This page explains the characteristics of **Site-to-Site**, **Site-to-VPN**, and **VPN-to-Site** setups and how to configure them with NetBird. We'll start by defining key terminology and reviewing the available setup options before walking through concrete implementation examples.
## Overview
A **Site** in the context of this guide refers to any single network or subnet that is typically not exposed to the Internet nor directly accessible from other Sites.
Examples include:
- Home or office networks
- Internal networks at cloud providers or datacenters
- Restricted VLANs
- Internal container or VM networking ranges
- Other VPN networking ranges
- Another NetBird organization's resource ranges
A **device** in this guide refers to any physical computing device (PC, laptop, phone, datacenter server, etc.) or virtual computing device (VM, container, load balancer, etc.). A **device** can be either **clientless** or a **Peer**.
**Clientless devices** are **devices** that don't run a NetBird client themselves (they are not **Peers**).
A **Peer** is a **device** running the NetBird client directly on it:
- A laptop running the NetBird client directly on the system is a **Peer**
- A laptop running the NetBird client in a container using default (internal) networking mode is not a **Peer** - the container itself is the **Peer** in this case
- A laptop running the NetBird client in a container using host-networking mode could be considered a **Peer**
Other **bold** terms refer to NetBird-specific features or configuration options:
**Network Route**, **Network**, **Resource**, **Access Control Policy**, **ACL Group**.
Non-bold terms refer to context-specific concepts:
- route: a generic term for an operating system network route
- resource: a generic term for software or a machine listening on a specific IP address and port
### Site-to-Site
A **Site-to-Site** setup enables **clientless** devices from two or more **Sites** to reach each other. Each **Site** requires at least one **Peer** to route traffic over the VPN, but other on-site devices don't need to run (or even be aware of) the VPN software.
The **clientless** devices must be configured to route the remote **Site**'s IP address range through the local **Peer**. You can configure this manually using commands and persist it with your operating system's native tools, or automate it using DHCP route advertisements or device management software.
The remote **Peer** must also know how to route responses back to the local **Site**. Typically, you'll need to set up a pair of routes to enable site-to-site access:
1. A route from the local **Peer** to the remote **Site** for outbound traffic
2. A reverse route from the remote **Site** to the local **Peer** for return traffic
### Site-to-VPN
A **Site-to-VPN** setup enables a **clientless** device to reach **Peers** in the VPN network.
You can think of this as the 'local half' of a **Site-to-Site** setup. The **clientless** devices need to be configured to reach the VPN network, but typically no additional setup is required to route responses back from the VPN.
### VPN-to-Site
A **VPN-to-Site** setup enables a **Peer** to reach **clientless** devices on a network external to the VPN itself. This is the default mode of operation for most VPNs, but we're including it here for completeness. In NetBird, this scenario is achieved using **Networks** or the older **Network Routes** feature.
## NetBird implementations overview
While NetBird doesn't yet have explicit support for Site-to-VPN or Site-to-Site scenarios, you can achieve them using one of the following approaches, depending on your requirements:
1. Using a **Network Route** for each **Site** with Masquerade (with or without **ACL Groups**)
2. Using a **Network Route** for each **Site** without Masquerade (without **ACL Groups**)
3. Using a **Network** **Resource** with Masquerade
All of these options require the following:
- You must manually configure **clientless** devices to route traffic appropriately
- The easiest method is using device management software or DHCP route advertisements from your local router
- You can only have one routing **Peer** per **Site**
- Routing traffic correctly and reliably through multiple routing devices is extremely complex (if not impossible), so multi-peer routing is out of scope for this guide
You'll need to consider one of two primary tradeoffs:
1. **Forfeit source IP information to preserve basic access control** - Use Masquerade to maintain a basic form of access control
- Masqueraded traffic can only be controlled by **Access Control Policies** attached to the **Routing Peer**, with no way to restrict access for specific **clientless** devices
- You can still create coarse-grained access controls by setting up multiple **Network** **Routing Peers** for different purposes
2. **Forfeit access control to preserve source IP information** - Skip Masquerade to keep the original source IP addresses (this allows any traffic through)
- This approach may be required for specific networking setups
## Prerequisites and initial assumptions
For this guide, we'll use four `libvirt` Ubuntu virtual machines, split into two separate **Sites** (networks) as follows:
```shell
root@vms ~# virsh net-dhcp-leases local-site
... IP address Hostname ...
... ---------------------------------...
... 192.168.122.144/24 local-nb-01 ...
... 192.168.122.65/24 local-01 ...
root@vms ~# virsh net-dhcp-leases remote-site
... IP address Hostname ...
...------------------------------------...
... 192.168.100.189/24 remote-nb-01 ...
... 192.168.100.215/24 remote-01 ...
```
All VMs can be reached from the host `vms`:
```shell
kdn@pc ~> ssh vms.lan ping -c1 192.168.100.189
PING 192.168.100.189 (192.168.100.189) 56(84) bytes of data.
64 bytes from 192.168.100.189: icmp_seq=1 ttl=64 time=0.154 ms
--- 192.168.100.189 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.154/0.154/0.154/0.000 ms
kdn@pc ~> ssh vms.lan ping -c1 192.168.122.144
PING 192.168.122.144 (192.168.122.144) 56(84) bytes of data.
64 bytes from 192.168.122.144: icmp_seq=1 ttl=64 time=0.162 ms
--- 192.168.122.144 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.162/0.162/0.162/0.000 ms
```
Both **Sites** can reach the Internet, and devices within each site can communicate with each other, but they cannot directly reach devices on the other **Site**:
```shell
kdn@pc ~> ssh 192.168.100.189 -J vms.lan ping -c1 192.168.122.144
PING 192.168.122.144 (192.168.122.144) 56(84) bytes of data.
From 192.168.122.1 icmp_seq=1 Destination Port Unreachable
--- 192.168.122.144 ping statistics ---
1 packets transmitted, 0 received, +1 errors, 100% packet loss, time 0ms
kdn@pc ~ [1]>
```
The `local-site` network VMs are also directly attached to my LAN. The `remote-site` VMs are only attached to their network, so we'll reference them by IP address and use `vms` as an SSH jump host.
The devices `local-01` and `remote-01` are **clientless** for the purposes of this guide. Additionally, `remote-01` runs CoreDNS, which responds with `OK` to `http://192.168.100.10/health`.
The **Peers** are configured as follows:
| dns_label | netbird_ip | groups |
|----------------|------------------|---------------------|
| `local-nb-01` | `100.83.73.97` | `s2s: local peers` |
| `remote-nb-01` | `100.83.136.209` | `s2s: remote peers` |
We'll grant access between:
- `local-01` running on the `local-site` through **Routing Peer** `local-nb-01` using **Group** `s2s: local peers`
- `remote-01` running on the `remote-site` through **Routing Peer** `remote-nb-01` using **Group** `s2s: remote peers`
<Note>
This guide assumes the use of a Linux terminal, but the commands used are relatively simple and ubiquitous
and should easily translate to other operating systems.
</Note>
## Site-to-Site with Masquerade
The **Masquerade** option means that packets forwarded by a **Routing Peer** will:
- Have their source IP address replaced with the **Routing Peer**'s NetBird IP address when leaving the **Site**
- Be translated back from the **Routing Peer**'s IP address to the local **Site**'s IP address when returning
This is currently the easiest way to configure routing because it uses existing **Peer** forwarding and policy enforcement facilities.
The main downsides of this approach are:
- Loss of source IP addressing information, which may be required for auditing purposes
- Very coarse-grained access control limited to the **Routing Peer**'s permissions
### Site-to-Site using Network Routes with Masquerade and without Access Control
In this section, we'll set up Site-to-Site **Network Routes** with Masquerade but without access control. We'll start by configuring the required **Network Routes** and **Access Control Policies**, then manually configure a **clientless** device to route traffic through the local **Routing Peer**. Finally, we'll verify that everything works as expected.
#### Setting up a simple VPN-to-Site access
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/routes-noacl-vpn-to-site.png" alt="routes-noacl-vpn-to-site"
className="imagewrapper-big"/>
</p>
and an **Access Control Policy** that establishes connectivity between the (future) **Routing Peers**:
<p id="unidirectional-routing-peer-policy">
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-ping-to-local-only.png" alt="acl-ping-to-local-only"
className="imagewrapper-big"/>
</p>
<Note>
It doesn't matter that this is a unidirectional ICMP rule in the wrong direction - **Network Routes** are activated as soon as any **Access Control Policy** establishes connectivity to the **Routing Peer**, as explained in [Network Routes caveats](/manage/network-routes/routing-traffic-to-private-networks#network-routes-caveats).
</Note>
We can verify that the local **Peer** can reach the `remote-site` using both `ping` and `curl`:
```shell
kdn@pc ~> ssh local-nb-01.lan "netbird networks ls"
Available Networks:
- ID: network-route-srvs-site
Network: 192.168.122.0/24
Status: Selected
kdn@pc ~> ssh local-nb-01.lan "ping -c1 192.168.100.10"
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=63 time=0.475 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.475/0.475/0.475/0.000 ms
kdn@pc ~> ssh local-nb-01.lan "curl 192.168.100.10/health; echo"
OK
```
#### Setting up the clientless device
Now we'll manually configure the **clientless** `local-01` device to route traffic to the `remote-site` through `local-nb-01`'s local IP address `192.168.122.144`:
```shell
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
kdn@pc ~ [1]> ssh local-01.lan "sudo ip route add 192.168.100.0/24 via 192.168.122.144"
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
192.168.100.0/24 via 192.168.122.144 dev enp7s0
```
<Note>
This step is better handled via a DHCP server's route advertisement, but that's outside the scope of this guide.
</Note>
This won't work yet from a **clientless** device because we're missing the other half of the connection needed to route responses back:
```shell
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms
kdn@pc ~ [1]>
```
#### Closing the loop with a reverse Network Route
Now we can complete the setup by enabling the reverse **Network Route** (from `remote-site` to `local-site`):
<p id="routes-noacl-site-to-site">
<img src="/docs-static/img/use-cases/setup-site-to-site-access/routes-noacl-site-to-site.png" alt="routes-noacl-site-to-site"
className="imagewrapper-big"/>
</p>
Let's verify it's working for both ICMP and HTTP:
```shell
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.867 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.867/0.867/0.867/0.000 ms
kdn@pc ~> ssh local-01.lan "curl 192.168.100.10/health; echo"
OK
```
#### Confirming remote Site access to the local Site
Let's fetch the `local-01` IP address, perform the reverse setup on `remote-01`, and test access back from the `remote-site`:
```shell
kdn@pc ~> ssh local-01.lan "ip a | grep 192.168.122"
inet 192.168.122.65/24 metric 100 brd 192.168.122.255 scope global dynamic enp7s0
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
kdn@pc ~ [1]> ssh 192.168.100.215 -J vms.lan "sudo ip route add 192.168.122.0/24 via 192.168.100.189"
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
192.168.122.0/24 via 192.168.100.189 dev enp7s0
kdn@pc ~> ssh 192.168.100.189 -J vms.lan "ping -c1 192.168.122.65"
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
64 bytes from 192.168.122.65: icmp_seq=1 ttl=63 time=0.523 ms
--- 192.168.122.65 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.523/0.523/0.523/0.000 ms
kdn@pc ~>
```
### Site-to-Site using Network Routes with Masquerade and Access Control
We'll start by picking up where we left off in the previous example: [Site-to-Site using Network Routes with Masquerade and without Access Control](#site-to-site-using-network-routes-with-masquerade-and-without-access-control). Now we can restrict access to the remote **Site**'s resources to ICMP only and verify the restrictions are enforced. We'll set up and verify unidirectional access first, then enable bidirectional access.
First, let's add dedicated `* resources` Access Control Groups to the **Network Routes**:
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/routes-with-acl-site-to-site.png" alt="routes-with-acl-site-to-site"
className="imagewrapper-big"/>
</p>
Note that we're using a different Group to grant access to the **Network Route** than the one used for **Routing Peers**. Using the **Routing Peer**'s Group in **ACL Groups** would also work and be slightly simpler to manage.
<Note>
Granting access only to the **Network Route**'s **ACL Groups** still requires at least one **Access Control Policy** that grants any kind of access directly to the **Routing Peer**. This makes the **Network Route** visible to the **Peer** using the route.
This is in stark contrast to Network Resources, where:
- **Resource** **Groups** control both access and discovery in a single step
- **Routing Peer** permissions aren't required unless you want to access its LAN IPs
</Note>
Next, let's set up **Access Control Policies** for one-way access from `local-site` to `remote-site`:
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-unidirectional-site-to-site.png" alt="acl-unidirectional-site-to-site"
className="imagewrapper-big"/>
</p>
Now we can verify that `ping` (ICMP) is allowed while `curl` (HTTP) is blocked in the local-to-remote direction:
```shell
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
192.168.100.0/24 via 192.168.122.144 dev enp7s0
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.738 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.738/0.738/0.738/0.000 ms
kdn@pc ~> ssh local-01.lan "curl -sv -m 2 192.168.100.10/health; echo"
* Trying 192.168.100.10:80...
* Connection timed out after 2002 milliseconds
* closing connection #0
```
Let's also verify that reverse access (from `remote-site` to `local-site`) isn't possible yet:
```shell
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
192.168.122.0/24 via 192.168.100.189 dev enp7s0
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ping -c1 192.168.122.65"
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
--- 192.168.122.65 ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms
kdn@pc ~ [1]>
```
Finally, let's enable the `s2s: ping to local resources` **Access Control Policy**:
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-bidirectional-site-to-site-minus-routing-peer.png" alt="acl-bidirectional-site-to-site-minus-routing-peer"
className="imagewrapper-big"/>
</p>
<Note>
We don't need to enable the reverse ICMP policy to the **Routing Peer**, as explained [previously](#unidirectional-routing-peer-policy).
</Note>
Now let's verify that remote-to-local access is working:
```shell
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
192.168.122.0/24 via 192.168.100.189 dev enp7s0
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ping -c1 192.168.122.65"
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
64 bytes from 192.168.122.65: icmp_seq=1 ttl=62 time=0.755 ms
--- 192.168.122.65 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.755/0.755/0.755/0.000 ms
kdn@pc ~>
```
### Site-to-Site using Network Resources with Masquerade
In this section, we'll replicate the previous [Site-to-Site using Network Routes with Masquerade and Access Control](#site-to-site-using-network-routes-with-masquerade-and-access-control) configuration using **Network Resources** and verify that it works. We'll start by setting up a **Network** for each **Site**, enable the minimum set of **Access Control Policies** required (which already exist), and finally verify that access control is working as expected.
Let's start by creating two new **Networks**, one for each **Site**:
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/network-local-noacl.png" alt="network-local-noacl"
className="imagewrapper-big"/>
</p>
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/network-remote-noacl.png" alt="network-remote-noacl"
className="imagewrapper-big"/>
</p>
and enable the two required **Access Control Policies**:
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-networks-bidirectional.png" alt="acl-networks-bidirectional"
className="imagewrapper-big"/>
</p>
<Note>
Unlike **Network Routes**, you don't need policies granting access to the **Routing Peers**.
However, a reverse **Access Control Policy** is mandatory for **Resources** - the reverse route won't be advertised on the local client and response packets will be lost, otherwise.
</Note>
Let's verify it's working:
```shell
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
192.168.100.0/24 via 192.168.122.144 dev enp7s0
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.783 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.783/0.783/0.783/0.000 ms
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
192.168.122.0/24 via 192.168.100.189 dev enp7s0
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ping -c1 192.168.122.65"
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
64 bytes from 192.168.122.65: icmp_seq=1 ttl=62 time=0.925 ms
--- 192.168.122.65 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.925/0.925/0.925/0.000 ms
```
Let's also verify that no additional traffic is allowed:
```shell
kdn@pc ~> ssh local-01.lan "curl -m 2 192.168.100.10/health; echo"
curl: (28) Connection timed out after 2002 milliseconds
```
### Asymmetric Network Resource policies
The reverse **Access Control Policy** doesn't need to match the protocol and access level of the forward policy. Established connections will be routed back correctly as long as the reverse (operating system) route is registered on the remote end.
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-networks-bidirectional-assymetric.png" alt="acl-networks-bidirectional"
className="imagewrapper-big"/>
</p>
Now we can verify that `local-site` can reach `remote-site` only over ICMP:
```shell
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.836 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.836/0.836/0.836/0.000 ms
kdn@pc ~ [1]> ssh local-01.lan "nc -v -w 2 192.168.100.10 22"
nc: connect to 192.168.100.10 port 22 (tcp) failed: Connection timed out
kdn@pc ~ [1]>
```
while `remote-site` can only reach `local-site` over SSH:
```shell
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
192.168.122.0/24 via 192.168.100.189 dev enp7s0
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ping -c1 192.168.122.65"
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
--- 192.168.122.65 ping statistics ---
1 packets transmitted, 0 received, 100% packet loss, time 0ms
kdn@pc ~ [1]> ssh 192.168.100.215 -J vms.lan "nc -w 2 192.168.122.65 22"
SSH-2.0-OpenSSH_9.7p1 Ubuntu-7ubuntu4.3
kdn@pc ~>
```
## Site-to-Site without Masquerade
This approach preserves source IP addressing information, but the traffic will be immediately rejected by the remote **Routing Peer** if you try to enable any **Access Control Policies** (such as **Network Resources** or **ACL Groups** on **Network Routes**).
This happens because all access control in NetBird is currently based on **Peer** IP addresses. Packets arriving from different address spaces (without Masquerade) are unknown to the NetBird policy engine and are therefore immediately rejected by the receiving **Peer**/**Routing Peer**.
<Note>
We plan to address these limitations in the future by implementing dedicated facilities for setting up and applying granular policies to Site-to-Site and Site-to-VPN scenarios.
In the meantime, you can manually restrict forwarded traffic using your operating system's firewall - for example, by implementing `FORWARD` policies on Linux.
</Note>
### Site-to-Site using Network Routes without Masquerade
Simply disable Masquerade on each **Network Route** from [the first example](#site-to-site-using-network-routes-with-masquerade-and-without-access-control).
To summarize, you'll need:
- A pair of local and remote **Network Routes**
- An **Access Control Policy** to establish connectivity between **Routing Peers**
- Manual route configuration on **clientless** devices pointing to the respective **Routing Peers**
The **Network Routes** list will look just like [above](#routes-noacl-site-to-site):
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/routes-noacl-site-to-site.png" alt="routes-noacl-site-to-site"
className="imagewrapper-big"/>
</p>
but you'll need to turn off **Masquerade** in each **Network Route**'s update dialog:
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/route-without-masquerading.png" alt="route-without-masquerading"
className="imagewrapper-big"/>
</p>
Only one **Access Control Policy** is required, just like [above](#unidirectional-routing-peer-policy):
<p>
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-ping-to-local-only.png" alt="acl-ping-to-local-only"
className="imagewrapper-big"/>
</p>
With these two pieces of configuration in place, we can verify that `ping` works:
```shell
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
192.168.100.0/24 via 192.168.122.144 dev enp7s0
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.897 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.897/0.897/0.897/0.000 ms
```
and that packets arrive unmodified on the remote end:
```shell
kdn@pc ~> ssh 192.168.100.10 -J vms.lan "sudo tcpdump -nvv -i any --immediate-mode -l icmp"
tcpdump: WARNING: any: That device doesn't support promiscuous mode
(Promiscuous mode not supported on the "any" device)
tcpdump: data link type LINUX_SLL2
tcpdump: listening on any, link-type LINUX_SLL2 (Linux cooked v2), snapshot length 262144 bytes
17:32:17.845428 enp7s0 In IP (tos 0x0, ttl 62, id 56506, offset 0, flags [DF], proto ICMP (1), length 84)
192.168.122.65 > 192.168.100.10: ICMP echo request, id 4480, seq 1, length 64
17:32:17.845468 enp7s0 Out IP (tos 0x0, ttl 64, id 51781, offset 0, flags [none], proto ICMP (1), length 84)
192.168.100.10 > 192.168.122.65: ICMP echo reply, id 4480, seq 1, length 64
^C⏎
```

182
src/pages/use-cases/site-to-site/index.mdx Normal file
View File

@@ -0,0 +1,182 @@
import { Tiles } from '@/components/Tiles'
# Site-to-Site Connectivity
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.
## Understanding Remote Access Scenarios
NetBird supports three distinct remote access scenarios. Understanding which one you need is the first step to a successful setup.
### VPN-to-Site
A NetBird peer (device running the NetBird client) accesses devices on a remote network that don't have NetBird installed.
```
Your Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Office Printer
(peer) (peer) (clientless)
```
**Common use cases:**
- Access your home NAS from anywhere
- 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)
### Site-to-VPN
A device without NetBird initiates connections to NetBird peers. This is the reverse of VPN-to-Site—the clientless device starts the connection.
```
Office Server ──────► Routing Peer ──────► NetBird Tunnel ──────► Your Laptop
(clientless) (peer) (peer)
```
**Common use cases:**
- Office monitoring systems pushing data to remote analysts
- On-premise servers initiating backups to cloud peers
- Legacy systems that must initiate outbound connections
**Implementation:** Requires [Network Routes](/manage/network-routes) (Networks does not currently support this)
### Site-to-Site
Devices on separate networks communicate with each other, with neither running NetBird directly. Each network has a routing peer that handles traffic.
```
Home NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer ──► Office Server
(clientless) (peer) (peer) (clientless)
```
**Common use cases:**
- Connect branch office networks to headquarters
- 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)
### Exit Nodes
Exit nodes route all internet-bound traffic (`0.0.0.0/0`) through a designated peer, changing your apparent public IP address. Unlike the scenarios above, exit nodes handle internet egress rather than private network access.
```
Your Laptop ──────► NetBird Tunnel ──────► Exit Node ──────► Internet
(peer) (peer)
```
**Common use cases:**
- Access region-restricted content while traveling
- Route traffic through a trusted network for compliance
- Mask your location for privacy
**Implementation:** Requires [Network Routes](/manage/network-routes/use-cases/by-scenario/exit-nodes)
## Which Scenario Do I Need?
| I want to... | Scenario | Feature to Use |
|-------------|----------|----------------|
| Access home devices from my laptop | VPN-to-Site | [Networks](/manage/networks/use-cases/by-scenario/access-home-devices) or [Network Routes](/manage/network-routes) |
| Access office resources while traveling | VPN-to-Site | [Networks](/manage/networks/use-cases/by-scenario/remote-worker-access) or [Network Routes](/manage/network-routes) |
| Let an office server connect to my laptop | Site-to-VPN | [Network Routes](/manage/network-routes/use-cases/by-scenario/site-to-site-office) only |
| Connect two home networks together | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/by-scenario/site-to-site-home) only |
| Link branch offices | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/by-scenario/site-to-site-office) only |
| Bridge cloud VPC with on-premise network | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/by-scenario/site-to-site-cloud) only |
| Route all internet traffic through a specific peer | Exit Node | [Network Routes](/manage/network-routes/use-cases/by-scenario/exit-nodes) only |
## How It Works
All scenarios use a routing peer—a device running NetBird that forwards traffic for its local network:
1. **Deploy a routing peer** at each site (any device running NetBird with access to the local network)
2. **Configure routing** to advertise each site's subnet through NetBird
3. **Set access policies** to control which peers can reach which networks
4. **Configure clientless devices** to route traffic through the routing peer (for Site-to-VPN and Site-to-Site)
<Tiles
title="VPN-to-Site Guides (Networks)"
items={[
{
href: '/manage/networks/use-cases/by-scenario/access-home-devices',
name: 'Access Home Devices',
description: 'Access your NAS, home automation, and media servers from anywhere',
},
{
href: '/manage/networks/use-cases/by-scenario/remote-worker-access',
name: 'Remote Worker Access',
description: 'Enable employees to access office resources while working remotely',
},
{
href: '/manage/networks/use-cases/by-scenario/cloud-to-on-premise',
name: 'Cloud to On-Premise',
description: 'Connect cloud workloads to on-premise databases and services',
},
]}
/>
<Tiles
title="Site-to-Site Guides (Network Routes)"
items={[
{
href: '/manage/network-routes/use-cases/site-to-site-home',
name: 'Connect Home Networks',
description: 'Link multiple home networks so devices can communicate across locations',
},
{
href: '/manage/network-routes/use-cases/site-to-site-office',
name: 'Connect Office Networks',
description: 'Connect branch offices to headquarters and enable cross-site communication',
},
{
href: '/manage/network-routes/use-cases/by-scenario/site-to-site-cloud',
name: 'Connect Cloud Environments',
description: 'Bridge cloud VPCs across providers or connect cloud to on-premise',
},
{
href: '/manage/network-routes/use-cases/by-configuration/advanced-configuration',
name: 'Advanced Configuration',
description: 'Masquerade options, ACL Groups, and troubleshooting',
},
]}
/>
## Key Concepts
| Term | Description |
|------|-------------|
| Routing peer | A device running NetBird that forwards traffic for its local network |
| 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
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.
**Use Networks** for VPN-to-Site scenarios where you want a guided setup experience and per-resource access policies.
**Use Network Routes** when you need Site-to-VPN or Site-to-Site connectivity, or require advanced options like disabling masquerade.
### Scenario Support
| Scenario | Networks | Network Routes |
|----------|----------|----------------|
| VPN-to-Site | Yes | Yes |
| Site-to-VPN | No | Yes |
| Site-to-Site | No | Yes |
### Detailed Comparison
| Capability | Networks | Network Routes |
|-----------|----------|----------------|
| Setup complexity | Simpler, guided UI | More manual configuration |
| Distribution groups | Automatic (from policy sources) | Explicit configuration required |
| Extra routing peer policy | No (implied by resource policies) | Yes (must connect routing peers to distribution groups) |
| Per-route configuration | No (routing peers serve all resources) | Yes (each route needs peer, groups, range) |
| Edit resources after creation | Yes | No |
| Wildcard domains | Yes | No |
| Masquerade control | Always on | Configurable |
| Exit node support | No | Yes |
### 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.