diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..72d856fe --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,70 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Documentation website for [NetBird](https://netbird.io), an open-source WireGuard-based Zero Trust Networking platform. Built with Next.js 16 (Pages Router), React 19, MDX, and Tailwind CSS 3. + +There is no test suite in this project. Validate changes with `npm run build`. + +## Common Commands + +```bash +npm install # Install dependencies +npm run dev # Start dev server (also runs gen:llm) +npm run build # Production build (also runs gen:llm) +npm run lint # ESLint (next/core-web-vitals) on src/ +npm run gen # Regenerate API docs from NetBird OpenAPI spec +npm run gen:llm # Regenerate LLM-friendly markdown (auto-runs with dev/build) +``` + +## Architecture + +### Content Structure +Documentation pages are MDX files in `src/pages/` using the Next.js Pages Router (not App Router). Key directories: +- `about-netbird/` - Conceptual docs +- `get-started/` - Installation and quickstart guides +- `manage/` - Feature documentation (peers, networks, DNS, access control, etc.) +- `selfhosted/` - Self-hosting deployment guides +- `ipa/` - API documentation (served at `/api` via rewrite) +- `use-cases/` - Tutorials and examples +- `client/` - Client configuration +- `help/` - Troubleshooting + +### MDX Page Conventions +- Page title comes from the first `# Heading` in the MDX file +- Optional `export const description = '...'` for meta description +- Import components as needed: `import {Note} from "@/components/mdx"` +- Images go in `public/docs-static/img/
/` and are referenced as `/docs-static/img/
/filename.png` + +### Navigation +`src/components/NavigationDocs.jsx` contains the `docsNavigation` array defining the sidebar. **Must be updated when adding or moving pages.** Supports nested `links` arrays for sub-navigation. + +### MDX Components +Custom components available in MDX files (see `README.md` for full usage examples): +- Alert boxes: ``, ``, `` (from `@/components/mdx`) +- Layout: ``, ``, `` (from `@/components/Tiles`), `` +- Media: `` (from `@/components/YouTube`) +- UI: ` -

- -- 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 diff --git a/src/pages/manage/network-routes/configuring-routes-with-access-control.mdx b/src/pages/manage/network-routes/configuring-routes-with-access-control.mdx deleted file mode 100644 index d9d953b4..00000000 --- a/src/pages/manage/network-routes/configuring-routes-with-access-control.mdx +++ /dev/null @@ -1,147 +0,0 @@ -# Configuring Routes with Access Control - - - This feature is available from NetBird version 0.30.0 onwards. - - -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. - - - 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. - - -## 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` - -

- high-level-dia -

- -Click on `Continue` to proceed. - -

- high-level-dia -

- -Once you fill in the route information, you can click on the `Add Route` button to save your new route. -

- high-level-dia -

- -Because you used an access control group, you will be prompted to create a new policy. -

- high-level-dia -

- -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` - -

- high-level-dia -

- - -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. -

- high-level-dia -

- -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
Routing Client] --- B[NetBird Peer B
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. \ No newline at end of file diff --git a/src/pages/manage/network-routes/index.mdx b/src/pages/manage/network-routes/index.mdx new file mode 100644 index 00000000..4e42cc0d --- /dev/null +++ b/src/pages/manage/network-routes/index.mdx @@ -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). + +

+ Network Routes diagram +

+ + +Network Routes require NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later. + + + +By default, Network Routes bypass Access Control rules. Traffic flows freely to routed networks unless you [configure access control explicitly](/manage/network-routes/use-cases/by-configuration/access-control). See [Network Routes caveats](#network-routes-caveats) for details. + + +## 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. + + +Peers must still be connected to the routing peer to use the route. + + +### 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. + +

+ DNS Routes diagram +

+ +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. + + +DNS Routes require NetBird [v0.28.0](https://github.com/netbirdio/netbird/releases) or later. Wildcard domains are not supported. + + + +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. + + +## 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**. + +

+ Add route button +

+ +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` + +

+ Create network route form +

+ +Click **Add Route** to save. + +

+ Saved network route +

+ +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). + +

+ Create route with peer group +

+ +Click **Add Route** to save. + +

+ Saved route with peer group +

+ +### 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: + +

+ Add HA peer to route +

+ +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`. + +

+ Saved HA route +

+ + +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). + + +### 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`: + +

+ Group attribution for routes +

+ +### 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. + +

+ Routes without masquerading +

+ +## 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): + +

+ Route IP address configuration +

+ +After creating an Access Policy granting only `ICMP` access from `Group A` to `Group R`: + +

+ ICMP policy from group A to R +

+ +You might expect only ICMP traffic to work. However, all traffic to the routed network succeeds because Network Routes only require connectivity to the Routing Peer to activate: + +```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`: + +

+ Wildcard domain resource +

+ +An HTTP-only policy grants access from `manual:client`: + +

+ HTTP-only policy +

+ +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 + +

+ Network routers configuration +

+ +

+ Routing peer groups +

+ +The Network Route grants unrestricted access to the network range, bypassing the HTTP-only restriction on the Network Resource. + + +To prevent permission overflow, use dedicated Routing Peers for Network Routes and never use them for Networks. This separation is achievable but easy to overlook during configuration. + + + + +## Get started +

+ +

+ +- 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 diff --git a/src/pages/manage/network-routes/resolve-overlapping-routes.mdx b/src/pages/manage/network-routes/resolve-overlapping-routes.mdx deleted file mode 100644 index 86bdabe4..00000000 --- a/src/pages/manage/network-routes/resolve-overlapping-routes.mdx +++ /dev/null @@ -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. - - - The route selection feature is available in the NetBird client version `v0.27.4` and later. - - -## 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. -``` - - - When running the `netbird routes select` command, the NetBird client will automatically deselect all other routes by default. - - -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. - -

- select-network-routes -

- -### 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 -

- -

- -- 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 diff --git a/src/pages/manage/network-routes/routing-traffic-to-private-networks.mdx b/src/pages/manage/network-routes/routing-traffic-to-private-networks.mdx deleted file mode 100644 index f1e2c1e4..00000000 --- a/src/pages/manage/network-routes/routing-traffic-to-private-networks.mdx +++ /dev/null @@ -1,364 +0,0 @@ - -# Routing Traffic to Private Networks - - -

- - - - **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. - - -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. - -

- high-level-dia -

- - - 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. - - -## 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. - - - Network routes are available in NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later. - - -**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. - -

- high-level-dia -

- -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). - - - - DNS Routes are available for NetBird [v0.28.0](https://github.com/netbirdio/netbird/releases) or later. - - - - Currently, wildcard domains are not supported for DNS routes. - - - - DNS Forwarder port change: starting with NetBird v0.59.0, the local DNS forwarder used for routed DNS routes switches from port 5353 to 22054 to avoid collisions on client devices. For backward compatibility, the Management Service applies the new port only when all peers in the account run v0.59.0 or newer. If any peer is below v0.59.0, port 5353 will be used for all peers in that account. - - -### 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. - - This does not remove the need for the routing peer to be connected to these peers. - - -### 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: -

- high-level-dia -

- -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` - -

- high-level-dia -

- - -Once you fill in the route information, you can click on the `Add Route` button to save your new route. -

- high-level-dia -

-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). - -

- high-level-dia -

- -Once you fill in the route information, you can click on the `Add Route` button to save your new route. - -

- high-level-dia -

- -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: - -

- high-level-dia -

- -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. - -

- high-level-dia -

- - - 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. - - -### 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. - -

- high-level-dia -

- -### 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. - -

- high-level-dia -

- -## 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): - -

- route-ip-address -

- -After creating an **Access Policy** granting `ICMP` access from `Group A` to `Group R`: - -

- ICMP policy from group A to R -

- -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`: - -

- *.nb.test domain Resource -

- -Granting HTTP-only access to that resource from group `manual:client`: - -

- a HTTP-only policy from manual:client group -

- -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**: - -

- Network's `manual:router:srvs` router -

- -Here are this specific **Routing Peer**'s details: - -

- Routing Peer's detail page with Network Route handling -

- -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**, - - - 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. - - -## Get started -

- -

- -- 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 diff --git a/src/pages/manage/network-routes/use-cases/by-configuration/access-control.mdx b/src/pages/manage/network-routes/use-cases/by-configuration/access-control.mdx new file mode 100644 index 00000000..235b6be6 --- /dev/null +++ b/src/pages/manage/network-routes/use-cases/by-configuration/access-control.mdx @@ -0,0 +1,119 @@ +# Configuring Routes with Access Control + + + This feature requires NetBird version 0.30.0 or later. + + +By default, network routes allow unrestricted access when no access control groups are assigned. When you assign access control groups to a route, only traffic that matches the defined policies can access the routed network. + +## 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. + + + 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. + + +## 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` + +

+ Network route configuration with access control +

+ +Click **Continue** to proceed. + +

+ Network route group settings +

+ +Complete the configuration and click **Add Route** to save. + +

+ Saved network route +

+ +Because you assigned an access control group, you will be prompted to create a policy: + +

+ Policy creation prompt +

+ +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` + +

+ Create access control policy +

+ +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. + +

+ New policy in table +

+ +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
Routing Client] --- B[NetBird Peer B
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. diff --git a/src/pages/manage/network-routes/use-cases/by-configuration/advanced-configuration.mdx b/src/pages/manage/network-routes/use-cases/by-configuration/advanced-configuration.mdx new file mode 100644 index 00000000..b5d37d94 --- /dev/null +++ b/src/pages/manage/network-routes/use-cases/by-configuration/advanced-configuration.mdx @@ -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 + + +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. + + +## 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) +``` + + +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. + + +## 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 ` 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. diff --git a/src/pages/manage/network-routes/use-cases/by-configuration/overlapping-routes.mdx b/src/pages/manage/network-routes/use-cases/by-configuration/overlapping-routes.mdx new file mode 100644 index 00000000..0fdbf284 --- /dev/null +++ b/src/pages/manage/network-routes/use-cases/by-configuration/overlapping-routes.mdx @@ -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. + + + Route selection requires NetBird client version 0.27.4 or later. + + +## 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 +``` + + + Running `netbird routes select` deselects all other routes by default. + + +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. + +

+ Route selection in system tray +

+ +### 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. diff --git a/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx new file mode 100644 index 00000000..237b9681 --- /dev/null +++ b/src/pages/manage/network-routes/use-cases/by-scenario/exit-nodes.mdx @@ -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. + + + This feature requires NetBird version 0.27.0 or later. + + +## Concepts + +### Default Routes + +A default route (`0.0.0.0/0` for IPv4) directs all internet traffic through a designated routing peer. + + + IPv6 traffic is currently not supported and is blocked to prevent unintentional leakage. + + +### 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. + + + The client user's explicit selection or deselection always takes precedence on that device. + + + + Auto Apply requires NetBird client version 0.55.0 or later. + + +### 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. + +

+ Dashboard peers view +

+ +### 2. Select the Routing Peer + +Choose the peer that will serve as your exit node. + +

+ Routing peer selection +

+ +### 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. + +

+ Add exit node dialog +

+ +To make the exit node available without automatic activation, disable **Auto Apply**. Users can then enable it manually. + +

+ Auto Apply option +

+ +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. + +

+ Exit node confirmation +

+ +### 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. diff --git a/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-cloud.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-cloud.mdx new file mode 100644 index 00000000..23518181 --- /dev/null +++ b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-cloud.mdx @@ -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) +``` + + +Multi-cloud Site-to-Site requires Network Routes because the Networks feature doesn't yet support this scenario. + + +## 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` + + +You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**. + + +## 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) + +

+ Create route for AWS VPC +

+ +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) + +

+ AWS route distribution and access control groups +

+ +7. Network Identifier: `aws-vpc` +8. Enable **Masquerade** (in Additional Settings) +9. Click **Add Route** + +

+ Enable masquerade in additional settings +

+ +**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) + +

+ Create route for GCP VPC +

+ +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) + +

+ GCP route distribution and access control groups +

+ +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) +``` + +

+ AWS to GCP policy with TCP port 443 +

+ +

+ GCP to AWS policy with UDP port 53 +

+ +## 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 + + +Enable IP forwarding on routing peer instances in both clouds. + + +## 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). diff --git a/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-home.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-home.mdx new file mode 100644 index 00000000..d3729869 --- /dev/null +++ b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-home.mdx @@ -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) +``` + + +Site-to-Site requires Network Routes because the Networks feature doesn't yet support bidirectional routing between sites. + + +## 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` + + +You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**. + + +## 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** + +

+ Create route for home network +

+ +**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** + +

+ Create route for parents network +

+ +## 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) + +

+ Create policy for home to parents +

+ +3. Add second policy: + - Network Identifier: "Parents to Home" + - Source: "parents-routing-peers" + - Destination: "home-routing-peers" + - Protocol: All (or restrict as needed) + +

+ Create policy for parents to home +

+ +## 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 +``` + + +For persistent routes, configure them in your router's DHCP settings or the device's network configuration. + + +**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). diff --git a/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-office.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-office.mdx new file mode 100644 index 00000000..26ed7b8e --- /dev/null +++ b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-office.mdx @@ -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) +``` + + +Site-to-Site requires Network Routes because the Networks feature doesn't yet support bidirectional routing between sites. + + +## 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` + + +You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**. + + +## 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** + +

+ Create route for headquarters network +

+ +**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** + +

+ Create route for branch network +

+ +## 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) +``` + +

+ HQ to branch policy with TCP ports 8080 and 53 +

+ +

+ Branch to HQ policy with TCP port 443 +

+ +## 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). diff --git a/src/pages/manage/network-routes/use-cases/index.mdx b/src/pages/manage/network-routes/use-cases/index.mdx new file mode 100644 index 00000000..c8bc004f --- /dev/null +++ b/src/pages/manage/network-routes/use-cases/index.mdx @@ -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) +``` + + +For VPN-to-Site (NetBird peers accessing clientless devices), you can use either [Networks](/manage/networks/use-cases) (recommended for simplicity) or Network Routes. + + +## 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 + + +If an ACL Group is assigned but no policies grant access to it, all routed traffic will be dropped. + + +### 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 + + + + + +## 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. diff --git a/src/pages/manage/networks/accessing-entire-domains-within-networks.mdx b/src/pages/manage/networks/accessing-entire-domains-within-networks.mdx deleted file mode 100644 index 59a7b3e6..00000000 --- a/src/pages/manage/networks/accessing-entire-domains-within-networks.mdx +++ /dev/null @@ -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. - - - (1) Support for more restricted rules will be available in future releases. - - -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) - - - 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 Forwarder port change: starting with NetBird v0.59.0, the local DNS forwarder used for routed DNS routes switches from port 5353 to 22054 to avoid collisions on client devices. For backward compatibility, the Management Service applies the new port only when all peers in the account run v0.59.0 or newer. If any peer is below v0.59.0, port 5353 will be used for all peers in that account. - - -## 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. diff --git a/src/pages/manage/networks/accessing-restricted-domain-resources.mdx b/src/pages/manage/networks/accessing-restricted-domain-resources.mdx deleted file mode 100644 index 054acd9a..00000000 --- a/src/pages/manage/networks/accessing-restricted-domain-resources.mdx +++ /dev/null @@ -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. \ No newline at end of file diff --git a/src/pages/manage/networks/homelab/access-home-network.mdx b/src/pages/manage/networks/homelab/access-home-network.mdx deleted file mode 100644 index 380fed4a..00000000 --- a/src/pages/manage/networks/homelab/access-home-network.mdx +++ /dev/null @@ -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 -
- - -

+
+ +
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) - Follow us [on X](https://x.com/netbird) diff --git a/src/pages/manage/networks/routing-traffic-to-multiple-resources.mdx b/src/pages/manage/networks/routing-traffic-to-multiple-resources.mdx deleted file mode 100644 index 8647b5cb..00000000 --- a/src/pages/manage/networks/routing-traffic-to-multiple-resources.mdx +++ /dev/null @@ -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: - -

- new-net-1 -

- -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`: - -

- new-net2 -

- -### 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: - -

- new-example-routing-peer-1 -

-Click on `Continue` and then accept the defaults to add a routing peer by clicking on `Add Routing Peer`: -

- new-routing-peer-2 -

- -### 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: -

- new-example-resource-1 -

- -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: -

- new-resource-acl-1 -

- -Click on `Continue` 2 times and then click on `Add Policy` to save the policy: -

- new-resource-acl-2 -

- -### 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: -

- new-example-resource-2 -

-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: -

- new-example-resource-3 -

- -### 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: -

- new-resource-acl-3 -

- -Click on `Continue` 2 times and then click on `Add Policy` to save the policy: -

- new-resource-acl-4 -

-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: -

- view-example-network-1 -

- -To access a detailed view of the network, click on the network name: -

- view-example-network-2 -

- -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 -

- -

- -- 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 diff --git a/src/pages/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks.mdx b/src/pages/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks.mdx new file mode 100644 index 00000000..2e49f79c --- /dev/null +++ b/src/pages/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks.mdx @@ -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. + + +DNS wildcard routing shifts DNS resolution from the local client to the routing peer, enabling access control rules and optimized traffic routing. + + +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) + + +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. + + + +DNS Forwarder port change: Starting with NetBird v0.59.0, the local DNS forwarder switches from port 5353 to 22054 to avoid collisions. For backward compatibility, the Management Service applies the new port only when all peers in the account run v0.59.0 or newer. + + +## 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. diff --git a/src/pages/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources.mdx b/src/pages/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources.mdx new file mode 100644 index 00000000..f4009848 --- /dev/null +++ b/src/pages/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources.mdx @@ -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. diff --git a/src/pages/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources.mdx b/src/pages/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources.mdx new file mode 100644 index 00000000..d057fa30 --- /dev/null +++ b/src/pages/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources.mdx @@ -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: + +

+ new-net-1 +

+ +Click `Add Network` to open the setup wizard. Enter a name and description for the network, then click `Continue`: + +

+ new-net2 +

+ +### Add a routing peer + +Click `Add routing peer` and select a peer from your network: + +

+ new-example-routing-peer-1 +

+ +Click `Continue`, then accept the defaults and click `Add Routing Peer`: + +

+ new-routing-peer-2 +

+ +### 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: + +

+ new-example-resource-1 +

+ +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: + +

+ new-resource-acl-1 +

+ +Click `Continue` twice, then click `Add Policy`: + +

+ new-resource-acl-2 +

+ +### Add the DNS server resources + +Add the first DNS server as a resource. Click `Add Resource` and enter the IP address: + +

+ new-example-resource-2 +

+ +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: + +

+ new-example-resource-3 +

+ +### 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: + +

+ new-resource-acl-3 +

+ +Click `Continue` twice, then click `Add Policy`. Use a generic policy name to cover both DNS server addresses: + +

+ new-resource-acl-4 +

+ +### View the network + +After completing the wizard, the network appears in the Networks list: + +

+ view-example-network-1 +

+ +Click the network name to view details: + +

+ view-example-network-2 +

+ +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 +

+ +

+ +- 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 diff --git a/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx b/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx new file mode 100644 index 00000000..2502d681 --- /dev/null +++ b/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx @@ -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" + +

+ Add user group +

+ +## 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** + +

+ Add network +

+ +## 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** + +

+ Add resource +

+ + +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. + + +## 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** + +

+ Add policy +

+ +## 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**. + + +You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**. + + +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 + +

+ Add routing peer button +

+ +5. Select your new peer and click **Add Routing Peer** + +

+ Add routing peer +

+ +## 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 diff --git a/src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx b/src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx new file mode 100644 index 00000000..0c32037b --- /dev/null +++ b/src/pages/manage/networks/use-cases/by-scenario/cloud-to-on-premise.mdx @@ -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** + +

+ Add network +

+ +## 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** + +

+ Add resource +

+ + +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. + + +## 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** + +

+ Add policy +

+ +## 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**. + +

+ Create setup key +

+ + +You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**. + + +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 diff --git a/src/pages/manage/networks/use-cases/by-scenario/remote-worker-access.mdx b/src/pages/manage/networks/use-cases/by-scenario/remote-worker-access.mdx new file mode 100644 index 00000000..4f40976d --- /dev/null +++ b/src/pages/manage/networks/use-cases/by-scenario/remote-worker-access.mdx @@ -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` + +

+ Add remote worker to group +

+ +## 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** + +

+ Add network +

+ +## 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** + +

+ Add resource +

+ + +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. + + +## 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** + +

+ Create policy for remote worker office access +

+ +## 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**. + +

+ Create setup key +

+ + +You can also add groups to peers manually after setup. Go to **Peers**, select the peer, and add groups under **Assigned Groups**. + + +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 diff --git a/src/pages/manage/networks/use-cases/index.mdx b/src/pages/manage/networks/use-cases/index.mdx new file mode 100644 index 00000000..e2834130 --- /dev/null +++ b/src/pages/manage/networks/use-cases/index.mdx @@ -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 + + +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). + + + + +## 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. + + + +## 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. diff --git a/src/pages/manage/peers/site-to-site/db-workload-migration.mdx b/src/pages/manage/peers/site-to-site/db-workload-migration.mdx deleted file mode 100644 index 492206c1..00000000 --- a/src/pages/manage/peers/site-to-site/db-workload-migration.mdx +++ /dev/null @@ -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 `` with the key you generated: - -```bash -netbird up --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. - diff --git a/src/pages/use-cases/examples.mdx b/src/pages/use-cases/cloud/aws-ecs-terraform.mdx similarity index 100% rename from src/pages/use-cases/examples.mdx rename to src/pages/use-cases/cloud/aws-ecs-terraform.mdx diff --git a/src/pages/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm.mdx b/src/pages/use-cases/cloud/distributed-multi-cloud-ai.mdx similarity index 86% rename from src/pages/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm.mdx rename to src/pages/use-cases/cloud/distributed-multi-cloud-ai.mdx index 111dd1aa..8e078427 100644 --- a/src/pages/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm.mdx +++ b/src/pages/use-cases/cloud/distributed-multi-cloud-ai.mdx @@ -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. - 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.

@@ -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 `` 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 `` 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/) diff --git a/src/pages/use-cases/cloud/index.mdx b/src/pages/use-cases/cloud/index.mdx new file mode 100644 index 00000000..94167c7f --- /dev/null +++ b/src/pages/use-cases/cloud/index.mdx @@ -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). + + + +## 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 diff --git a/src/pages/use-cases/netbird-on-faas.mdx b/src/pages/use-cases/cloud/netbird-on-faas.mdx similarity index 96% rename from src/pages/use-cases/netbird-on-faas.mdx rename to src/pages/use-cases/cloud/netbird-on-faas.mdx index 37cffe13..fac1ca12 100644 --- a/src/pages/use-cases/netbird-on-faas.mdx +++ b/src/pages/use-cases/cloud/netbird-on-faas.mdx @@ -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). \ No newline at end of file +](https://github.com/netbirdio/azure-functions-python-db-access). diff --git a/src/pages/use-cases/routing-peers-and-kubernetes.mdx b/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx similarity index 99% rename from src/pages/use-cases/routing-peers-and-kubernetes.mdx rename to src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx index 896a1fe0..6023f629 100644 --- a/src/pages/use-cases/routing-peers-and-kubernetes.mdx +++ b/src/pages/use-cases/cloud/routing-peers-and-kubernetes.mdx @@ -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. \ No newline at end of file +hybrid, multi-cloud environments and remote access, ensuring seamless connectivity and security across your infrastructure. diff --git a/src/pages/use-cases/client-on-mikrotik-router.mdx b/src/pages/use-cases/homelab/client-on-mikrotik-router.mdx similarity index 98% rename from src/pages/use-cases/client-on-mikrotik-router.mdx rename to src/pages/use-cases/homelab/client-on-mikrotik-router.mdx index a73aafde..976a4999 100644 --- a/src/pages/use-cases/client-on-mikrotik-router.mdx +++ b/src/pages/use-cases/homelab/client-on-mikrotik-router.mdx @@ -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 diff --git a/src/pages/use-cases/homelab/index.mdx b/src/pages/use-cases/homelab/index.mdx new file mode 100644 index 00000000..7c45ae6f --- /dev/null +++ b/src/pages/use-cases/homelab/index.mdx @@ -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). + + + +## 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) | diff --git a/src/pages/use-cases/index.mdx b/src/pages/use-cases/index.mdx new file mode 100644 index 00000000..aa3d1e13 --- /dev/null +++ b/src/pages/use-cases/index.mdx @@ -0,0 +1,31 @@ +import { Tiles } from '@/components/Tiles' + +# Use Cases + +Explore practical examples and guides for deploying NetBird across different environments and scenarios. + + diff --git a/src/pages/use-cases/implement-zero-trust.mdx b/src/pages/use-cases/security/implement-zero-trust.mdx similarity index 90% rename from src/pages/use-cases/implement-zero-trust.mdx rename to src/pages/use-cases/security/implement-zero-trust.mdx index b3a47579..e3a9b72d 100644 --- a/src/pages/use-cases/implement-zero-trust.mdx +++ b/src/pages/use-cases/security/implement-zero-trust.mdx @@ -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--` for user devices - - `peer-devops-prod`, `peer-support`, `peer-contractors` -- `svc---` for services and hosts - - `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod` -- `net--` for routed Networks - - `net-aws-euc1-prod`, `net-dc-dc1-lan` +- `peer--` for user devices + - `peer-devops-prod`, `peer-support`, `peer-contractors` +- `svc---` for services and hosts + - `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod` +- `net--` 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). 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. -**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. ### 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

high-level-dia @@ -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). @@ -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. **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 **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. \ No newline at end of file +- Monitor both NetBird health and OS-level metrics. diff --git a/src/pages/use-cases/security/index.mdx b/src/pages/use-cases/security/index.mdx new file mode 100644 index 00000000..c49e1996 --- /dev/null +++ b/src/pages/use-cases/security/index.mdx @@ -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 | + + + +## 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 diff --git a/src/pages/use-cases/setup-site-to-site-access.mdx b/src/pages/use-cases/setup-site-to-site-access.mdx deleted file mode 100644 index 8507e029..00000000 --- a/src/pages/use-cases/setup-site-to-site-access.mdx +++ /dev/null @@ -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` - - - 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. - - -## 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 - -

- routes-noacl-vpn-to-site -

- -and an **Access Control Policy** that establishes connectivity between the (future) **Routing Peers**: - -

- acl-ping-to-local-only -

- - - 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). - - -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 -``` - - - This step is better handled via a DHCP server's route advertisement, but that's outside the scope of this guide. - - -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`): - -

- routes-noacl-site-to-site -

- -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**: - -

- routes-with-acl-site-to-site -

- -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. - - - 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 - - -Next, let's set up **Access Control Policies** for one-way access from `local-site` to `remote-site`: - -

- acl-unidirectional-site-to-site -

- -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**: - -

- acl-bidirectional-site-to-site-minus-routing-peer -

- - - We don't need to enable the reverse ICMP policy to the **Routing Peer**, as explained [previously](#unidirectional-routing-peer-policy). - - -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**: - -

- network-local-noacl -

- -

- network-remote-noacl -

- -and enable the two required **Access Control Policies**: - -

- acl-networks-bidirectional -

- - - 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. - - -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. - -

- acl-networks-bidirectional -

- -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**. - - - 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. - - -### 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): - -

- routes-noacl-site-to-site -

- -but you'll need to turn off **Masquerade** in each **Network Route**'s update dialog: - -

- route-without-masquerading -

- -Only one **Access Control Policy** is required, just like [above](#unidirectional-routing-peer-policy): - -

- acl-ping-to-local-only -

- -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⏎ -``` diff --git a/src/pages/use-cases/site-to-site/index.mdx b/src/pages/use-cases/site-to-site/index.mdx new file mode 100644 index 00000000..76890265 --- /dev/null +++ b/src/pages/use-cases/site-to-site/index.mdx @@ -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) + + + + + +## 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.