diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..f49f0281 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,79 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is the documentation website for [NetBird](https://netbird.io), an open-source WireGuard-based Zero Trust Networking platform. The site is built with Next.js 14 and MDX support. + +## Common Commands + +```bash +# Install dependencies +npm install + +# Start development server +npm run dev + +# Build for production +npm run build + +# Run linting +npm run lint + +# Regenerate API documentation from OpenAPI spec +npm run gen + +# Regenerate LLM-friendly markdown docs (runs automatically with dev/build) +npm run gen:llm +``` + +## Architecture + +### Content Structure +- Documentation pages are MDX files in `src/pages/` organized by topic: + - `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 (mapped to `/api` route via rewrite) + - `use-cases/` - Tutorials and examples + - `client/` - Client configuration + - `help/` - Troubleshooting + +### Navigation +- `src/components/NavigationDocs.jsx` - Contains `docsNavigation` array that defines the sidebar structure. Update this when adding new pages. + +### MDX Components +Custom components available in MDX files (import from `@/components/mdx` or their respective files): + +- `` - Orange info box for important notes +- `` - Red warning box +- `` - Green success message +- `` - Grid of clickable cards for related links +- `` - Embedded YouTube videos +- ` -

- -- 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 index 4671b0ed..0255a544 100644 --- a/src/pages/manage/network-routes/index.mdx +++ b/src/pages/manage/network-routes/index.mdx @@ -1,90 +1,311 @@ -import { Note } from '@/components/mdx' +import { Note, Warning, Button } from '@/components/mdx' import { Tiles } from '@/components/Tiles' # Network Routes -Network Routes allow you to 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 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 diagram

-## When to Use Network Routes - -Network Routes support all remote access scenarios: - -| Scenario | Description | -|----------|-------------| -| **VPN-to-Site** | NetBird peers access devices on remote networks | -| **Site-to-VPN** | Clientless devices initiate connections to NetBird peers | -| **Site-to-Site** | Two networks communicate through NetBird, with neither endpoint running NetBird | - -For VPN-to-Site only, you can also use [Networks](/manage/networks), which offers a simpler setup experience. Network Routes is required for Site-to-VPN and Site-to-Site scenarios. +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/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 device running NetBird that forwards traffic between the NetBird network and a private network. The routing peer must have network access to the resources you want to reach. + +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 (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. + +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 -Specify which peers receive the network route configuration. Peers in the distribution groups will automatically have the route available. + +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 -Provide granular access control for routes. When assigned, only peers with policies granting access to the ACL Group can use the route. + +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 -Deploy multiple routing peers for the same route to provide failover. NetBird clients will automatically select the best available peer based on metrics and connection quality. -## Networks vs Network Routes +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. -| Capability | Networks | Network Routes | -|-----------|----------|----------------| -| VPN-to-Site | Yes | Yes | -| Site-to-VPN | No | Yes | -| Site-to-Site | No | Yes | -| Setup complexity | Simpler | More configuration | -| Access control | Per-resource policies | Per-route with ACL Groups | -| Masquerade control | Always on | Configurable | +Connected peers select a routing peer based on connection type and metric priority. -**Use Networks when:** -- You only need VPN-to-Site access -- You prefer a guided setup experience +### DNS Routes -**Use Network Routes when:** -- You need Site-to-VPN or Site-to-Site connectivity -- You need to disable masquerade for source IP preservation -- You need ACL Groups for route-level access control +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/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. + 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..e5daf49b --- /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/advanced-configuration.mdx b/src/pages/manage/network-routes/use-cases/by-configuration/advanced-configuration.mdx similarity index 78% rename from src/pages/manage/network-routes/use-cases/advanced-configuration.mdx rename to src/pages/manage/network-routes/use-cases/by-configuration/advanced-configuration.mdx index bbd24685..b5d37d94 100644 --- a/src/pages/manage/network-routes/use-cases/advanced-configuration.mdx +++ b/src/pages/manage/network-routes/use-cases/by-configuration/advanced-configuration.mdx @@ -2,7 +2,7 @@ import { Note, Warning } from '@/components/mdx' # Advanced Configuration -This guide covers technical details for site-to-site connectivity, including masquerade options, access control configuration, and troubleshooting. +This guide covers technical details for site-to-site connectivity, including masquerade options, access control, and troubleshooting. ## Understanding Masquerade @@ -10,10 +10,10 @@ Masquerade determines how source IP addresses are handled when traffic passes th ### With Masquerade (Default) -When enabled, the routing peer performs NAT on forwarded traffic: +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 -- Simpler setup—no additional routing configuration needed on remote networks +- 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 @@ -27,11 +27,11 @@ Device A (192.168.1.50) → Routing Peer → [Source becomes 100.64.0.10] → Re **Disadvantages:** - Original source IP is hidden - Access control is limited to the routing peer level -- Audit logs show routing peer IP, not original device +- Audit logs show the routing peer IP, not the original device ### Without Masquerade -When disabled, original source IPs are preserved: +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 @@ -51,7 +51,7 @@ Device A (192.168.1.50) → Routing Peer → [Source stays 192.168.1.50] → Rem - More complex setup -Without masquerade, traffic from unknown source IPs will be rejected by NetBird's policy engine. You cannot use ACL Groups or Network Resources without masquerade enabled. +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 @@ -71,21 +71,21 @@ ACL Groups provide route-level access control when using Network Routes with mas 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 policies granting access to the ACL Group can use the route +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 route for `192.168.100.0/24` +2. Add a route for `192.168.100.0/24` 3. Select your routing peer 4. Enable Masquerade -5. Add ACL Group: "remote-resources" +5. Add ACL Group: `remote-resources` **Step 2: Create Access Policies** -For the route to be active, you need at least one policy granting access to the routing peer: +For the route to be active, create a policy granting access to the routing peer: ``` Source: any-group → Destination: routing-peer-group (any protocol) @@ -98,24 +98,24 @@ Source: authorized-users → Destination: remote-resources (TCP, specific ports) ``` -The routing peer must be accessible via some policy for the route to activate. The route itself is controlled by policies targeting the ACL Group. +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 Details +## Site-to-Site Configuration ### Bidirectional Route Setup Site-to-site requires routes in both directions: -**Site A → Site B:** +**Site A to Site B:** - Network Route: Site B's subnet - Routing Peer: Site A's routing peer -- Masquerade: Enable for simplicity +- Masquerade: Enabled (recommended) -**Site B → Site A:** +**Site B to Site A:** - Network Route: Site A's subnet - Routing Peer: Site B's routing peer -- Masquerade: Enable for simplicity +- Masquerade: Enabled (recommended) ### Access Policies for Site-to-Site @@ -173,24 +173,24 @@ sudo route add -net 192.168.200.0/24 192.168.100.10 **Router-level (recommended):** -Configure your router to advertise routes via DHCP or add static routes that apply to all devices on the network. +Configure your router to advertise routes via DHCP or add static routes for all devices on the network. -## Networks vs Network Routes Detailed Comparison +## 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 UI workflow | More manual configuration | +| Setup complexity | Simpler | More manual configuration | | Routing peer redundancy | Built-in | Manual configuration | -| Policy requirement | Only resource policies | Routing peer + ACL Group policies | +| Policy requirement | Resource policies only | Routing peer + ACL Group policies | ## Troubleshooting ### Route Not Active -**Symptoms:** Peers don't see the route; `netbird routes list` shows nothing +**Symptoms:** Peers do not see the route; `netbird routes list` shows nothing **Causes:** 1. No access policy grants access to the routing peer @@ -200,25 +200,25 @@ Configure your router to advertise routes via DHCP or add static routes that app **Solution:** - Ensure at least one policy connects to the routing peer's group - Verify routing peer status in the dashboard -- Check ACL Group policies exist +- Check that ACL Group policies exist ### Traffic Times Out -**Symptoms:** Ping or connections hang, no response +**Symptoms:** Ping or connections hang with no response **Causes:** -1. Routing peer can't reach the destination network -2. Masquerade disabled and no return route exists -3. Firewall blocking traffic +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 OS firewall on routing peer: `iptables -L -n` or equivalent +- Check the OS firewall on the routing peer: `iptables -L -n` or equivalent ### Connection Works One Way -**Symptoms:** Can reach remote site but responses don't return +**Symptoms:** Can reach the remote site but responses do not return **Causes:** 1. Missing reverse route (site-to-site) @@ -287,7 +287,7 @@ traceroute 192.168.200.50 For high availability or load distribution: - Deploy multiple routing peers for the same route -- NetBird will distribute traffic across available peers +- NetBird distributes traffic across available peers - Monitor peer health and remove failed peers promptly ### Monitoring 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..7bf3ebc6 --- /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..e582566d --- /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/site-to-site-cloud.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-cloud.mdx similarity index 55% rename from src/pages/manage/network-routes/use-cases/site-to-site-cloud.mdx rename to src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-cloud.mdx index 08d29361..c3672b82 100644 --- a/src/pages/manage/network-routes/use-cases/site-to-site-cloud.mdx +++ b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-cloud.mdx @@ -19,7 +19,7 @@ Multi-cloud Site-to-Site requires Network Routes because the Networks feature do ## Prerequisites -- A [NetBird account](https://app.netbird.io/) +- 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 @@ -30,7 +30,25 @@ Connect workloads across AWS and GCP: - **AWS VPC**: `10.0.0.0/16` - **GCP VPC**: `10.1.0.0/16` -## Step 1: Deploy Routing Peers in Each Cloud +## 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:** @@ -52,42 +70,81 @@ curl -fsSL https://pkgs.netbird.io/install.sh | sh netbird up --setup-key YOUR_GCP_SETUP_KEY ``` -Create groups for the routing peers: -- "aws-routing-peers" -- "gcp-routing-peers" - -## Step 2: Create Network Routes +## Step 3: Create Network Routes **For AWS VPC:** 1. Go to **Network Routes** -2. Add route: - - Network identifier: `aws-vpc` - - Network range: `10.0.0.0/16` - - Routing peer: Your AWS instance - - Enable **Masquerade** - - Distribution Groups: "gcp-routing-peers" +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. Add route: - - Network identifier: `gcp-vpc` - - Network range: `10.1.0.0/16` - - Routing peer: Your GCP instance - - Enable **Masquerade** - - Distribution Groups: "aws-routing-peers" +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) -## Step 3: Create Access Policies +

+ Create route for GCP VPC +

-Create policies allowing the routing peers to communicate: +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 bidirectional policies between the routing peer groups: +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) ``` -## Step 4: Configure VPC Routing +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:** @@ -105,7 +162,7 @@ Add a custom route: Enable IP forwarding on routing peer instances in both clouds. -## Step 5: Test Connectivity +## Step 6: Test Connectivity From an AWS instance: diff --git a/src/pages/manage/network-routes/use-cases/site-to-site-home.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-home.mdx similarity index 55% rename from src/pages/manage/network-routes/use-cases/site-to-site-home.mdx rename to src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-home.mdx index 7058d895..2477b199 100644 --- a/src/pages/manage/network-routes/use-cases/site-to-site-home.mdx +++ b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-home.mdx @@ -22,16 +22,34 @@ Site-to-Site requires Network Routes because the Networks feature doesn't yet su ## Prerequisites -- A [NetBird account](https://app.netbird.io/) +- 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/resolve-overlapping-routes)) +- 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: Set Up Routing Peers at Both Locations +## 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:** @@ -47,49 +65,63 @@ curl -fsSL https://pkgs.netbird.io/install.sh | sh sudo netbird up --setup-key YOUR_PARENTS_SETUP_KEY ``` -Create groups for each routing peer in the NetBird dashboard: -- "home-routing-peers" containing "home-rpi" -- "parents-routing-peers" containing "parents-rpi" - -## Step 2: Create Network Routes +## Step 3: Create Network Routes 1. Go to **Network Routes** in the dashboard 2. Click **Add Route** **For your home network:** -- Network identifier: `home-lan` - Network range: `192.168.1.0/24` -- Routing Peer: Select "home-rpi" -- Enable **Masquerade** (recommended for simplicity) -- Distribution Groups: Add groups that need access (e.g., "parents-routing-peers") -- Click **Save** +- 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 identifier: `parents-lan` - Network range: `192.168.2.0/24` -- Routing Peer: Select "parents-rpi" -- Enable **Masquerade** (recommended) -- Distribution Groups: Add groups that need access (e.g., "home-routing-peers") -- Click **Save** +- 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** -## Step 3: Create Access Policies +

+ Create route for parents network +

-Create policies that allow the routing peers to communicate: +## 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 a policy: - - Name: "Home to Parents" +2. Add first policy: + - Network Identifier: "Home to Parents" - Source: "home-routing-peers" - Destination: "parents-routing-peers" - Protocol: All (or restrict as needed) -3. Add another policy for the reverse direction: - - Name: "Parents to Home" +

+ 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 + - Protocol: All (or restrict as needed) -## Step 4: Configure Clientless Devices +

+ 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. @@ -122,7 +154,7 @@ Destination: 192.168.2.0/24 Gateway: 192.168.1.100 (your routing peer's IP) ``` -## Step 5: Test Cross-Network Access +## Step 6: Test Cross-Network Access From a device at your home: @@ -152,7 +184,7 @@ ping 192.168.1.50 # Your NAS **Traffic works one way but not the other:** 1. Check that both network routes exist -2. Verify access policies are bidirectional +2. Verify access policies exist for both directions 3. Ensure static routes are configured at both ends ## Advanced Configuration diff --git a/src/pages/manage/network-routes/use-cases/site-to-site-office.mdx b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-office.mdx similarity index 61% rename from src/pages/manage/network-routes/use-cases/site-to-site-office.mdx rename to src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-office.mdx index e1f6b4eb..13505959 100644 --- a/src/pages/manage/network-routes/use-cases/site-to-site-office.mdx +++ b/src/pages/manage/network-routes/use-cases/by-scenario/site-to-site-office.mdx @@ -22,7 +22,7 @@ Site-to-Site requires Network Routes because the Networks feature doesn't yet su ## Prerequisites -- A [NetBird account](https://app.netbird.io/) +- 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 @@ -31,7 +31,25 @@ Site-to-Site requires Network Routes because the Networks feature doesn't yet su - **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: Deploy Routing Peers +## 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: @@ -49,48 +67,62 @@ curl -fsSL https://pkgs.netbird.io/install.sh | sh sudo netbird up --setup-key YOUR_BRANCH_SETUP_KEY ``` -Create dedicated groups for each routing peer: -- "hq-routing-peers" containing "hq-router" -- "branch-routing-peers" containing "branch-router" - -## Step 2: Create Network Routes +## Step 3: Create Network Routes **For headquarters:** 1. Go to **Network Routes** 2. Click **Add Route** -3. Network identifier: `hq-network` -4. Network range: `10.0.0.0/24` -5. Routing Peer: Select "hq-router" -6. Enable **Masquerade** (recommended) -7. Distribution Groups: "branch-routing-peers" -8. Optionally add ACL Groups for access control -9. Click **Save** +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. Add route: `10.1.0.0/24` -2. Routing peer: "branch-router" -3. Enable Masquerade +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. Optionally add ACL Groups -6. Click **Save** +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** -## Step 3: Create Access Policies +

+ Create route for branch network +

-Create policies allowing the routing peers to communicate: +## 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): +For route-level access control (if ACL Groups configured), you can restrict by protocol and port: ``` -Source: hq-resources → Destination: branch-resources (specific protocols) -Source: branch-resources → Destination: hq-resources (specific protocols) +Source: hq-routing-peers → Destination: branch-routing-peers (specific protocols) +Source: branch-routing-peers → Destination: hq-routing-peers (specific protocols) ``` -## Step 4: Configure Network Equipment +

+ 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)** @@ -128,7 +160,7 @@ route -p add 10.1.0.0 mask 255.255.255.0 10.0.0.50 route -p add 10.0.0.0 mask 255.255.255.0 10.1.0.50 ``` -## Step 5: Test Connectivity +## Step 6: Test Connectivity From a device at headquarters: @@ -160,7 +192,7 @@ 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 bidirectional access policies allowing traffic in both directions +3. Create two access policies allowing traffic in both directions ## Best Practices for Business Deployments diff --git a/src/pages/manage/network-routes/use-cases/index.mdx b/src/pages/manage/network-routes/use-cases/index.mdx index 0cd69296..926b6448 100644 --- a/src/pages/manage/network-routes/use-cases/index.mdx +++ b/src/pages/manage/network-routes/use-cases/index.mdx @@ -1,54 +1,80 @@ import { Tiles } from '@/components/Tiles' -import { Note } from '@/components/mdx' +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. -## Understanding the Scenarios +## What Are Site-to-Site and Site-to-VPN? -### Site-to-Site +Network Routes enables two connectivity patterns that go beyond standard VPN-to-Site access: -Two networks communicate with each other, with neither end-device running NetBird directly. Each network has a routing peer that handles traffic. +**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) ``` -**Example scenarios:** -- Connect branch offices to headquarters -- Link home networks of family members -- Bridge on-premise data centers with cloud VPCs - -### Site-to-VPN - -A device without NetBird initiates connections to NetBird peers. This is the reverse of VPN-to-Site. +**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) ``` -**Example scenarios:** -- Monitoring systems pushing data to remote analysts -- On-premise servers initiating backups to cloud peers -- Legacy systems that must initiate outbound connections - 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 +- **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 + + -## Key Configuration Steps +## Configuration Pattern All Site-to-Site and Site-to-VPN scenarios follow this pattern: @@ -82,4 +129,8 @@ All Site-to-Site and Site-to-VPN scenarios follow this pattern: 3. **Create access policies** allowing routing peers to communicate 4. **Configure clientless devices** to route traffic through the local routing peer -For detailed configuration guidance, see [Advanced Configuration](/manage/network-routes/use-cases/advanced-configuration). +For step-by-step instructions, choose your scenario above. For technical details and troubleshooting, see [Advanced Configuration](/manage/network-routes/use-cases/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/index.mdx b/src/pages/manage/networks/index.mdx index 3de7f663..ea5d9d68 100644 --- a/src/pages/manage/networks/index.mdx +++ b/src/pages/manage/networks/index.mdx @@ -1,177 +1,151 @@ # Networks -NetBird provides a fast and secure peer-to-peer mesh network with end-to-end encryption, enabling devices and machines -running the NetBird agent to connect directly. This setup allows for precise network segmentation, -isolation of individual machines, and secure remote access without the need to open ports or expose resources to the -internet. However, there are situations where installing the agent on every machine is not feasible or hasn't been -completed, requiring access to entire LANs, office networks, or cloud VPCs instead. +NetBird creates a secure peer-to-peer mesh network where devices running the NetBird agent connect directly with end-to-end encryption. This enables precise network segmentation and secure remote access without exposing resources to the internet. -Starting from version `0.35.0`, NetBird introduces Networks, a new concept that allows you to map your internal networks -such as LANs, VPCs, or office networks, and manage access to internal resources without installing NetBird agent. +However, installing the agent on every machine is not always feasible. Networks solve this by letting you route traffic to entire LANs, office networks, or cloud VPCs without requiring the NetBird agent on each device.

high-level-dia

- - Networks and [Network Routes](/manage/network-routes) are complementary features for routing traffic to private networks. - **Networks** is recommended for VPN-to-Site scenarios due to its simpler setup and per-resource access control. - **Network Routes** is required for Site-to-VPN and Site-to-Site scenarios, and offers additional features like configurable masquerade and ACL Groups. - Both features are fully supported—choose based on your use case. - +## Networks vs. Network Routes + +Networks is the newer, simpler replacement for Network Routes. We encourage you to use Networks where possible; however, Networks do not yet support all remote access scenarios. Network Routes will continue to be actively maintained, so use whichever fits your use case. + +For a detailed comparison, see our [site-to-site documentation](/use-cases/site-to-site). ## Concepts + ### Networks -Networks are configuration containers that map your on-premise or cloud networks in a logical set of configurations, -making it easier to visualise and manage access to your internal resources. You can create multiple networks to represent your -different environments, such as office networks, cloud VPCs, or on-premise LANs. + +A Network is a configuration container that maps your on-premise or cloud infrastructure into a logical set of resources and routing peers. You can create multiple networks to represent different environments such as office networks, cloud VPCs, or data center LANs.

high-level-dia

-### Routing peers -To access your internal resources, you need to route traffic from your NetBird peers to your internal networks. -Routing peers are machines that connect your NetBird peers and your internal networks. -You can add as many routing peers as you need using single peers or groups to ensure high availability and load balancing. -You can define masquerading and priority for each routing peer. +### Routing Peers + +Routing peers are machines that bridge your NetBird peers to your internal networks. They forward traffic from NetBird clients to resources that do not have the NetBird agent installed. + +You can add multiple routing peers using individual peers or groups to ensure high availability and load balancing. Each routing peer can be configured with masquerading and priority settings.

high-level-dia

- ### Resources -Resources are individual machines, services, or subnets within your internal network. You can define resources as single -IP addresses, IP ranges, domain names, or wildcard domains (e.g., *.company.internal) when enabling [DNS wildcard routing](#enable-dns-wildcard-routing). + +Resources are the machines, services, or subnets you want to access within your internal network. You can define resources as: + +- Single IP addresses +- IP ranges +- Domain names (e.g., `example.com`) +- Wildcard domains (e.g., `*.company.internal`) when [DNS wildcard routing](#enable-dns-wildcard-routing) is enabled

resources

- - Support to exit nodes and site-2-site VPNs may become available in future releases. In the meantime you can use [Network routes](/manage/network-routes/routing-traffic-to-private-networks) add your exit-node routes and site-2-site routes. - ### Domain Resources -In addition to routing IP addresses, NetBird also supports routing domain names. In the Dashboard you can just pass -a domain name (eg: `example.com`) or a wildcard domain (eg: `*.example.com`) in place where you would normally -put an IP address range. Then NetBird clients will start responding to and routing the given domain. +In addition to IP-based resources, NetBird supports routing domain names. In the Dashboard, you can enter a domain name (e.g., `example.com`) or wildcard domain (e.g., `*.example.com`) instead of an IP range. NetBird clients will then resolve and route traffic to that domain. -Please consult the -[Debugging access to Domain Resources](/help/troubleshooting-client#debugging-access-to-domain-resources) -documentation to troubleshoot common issues with this type of resources yourself. +For troubleshooting, see [Debugging access to Domain Resources](/help/troubleshooting-client#debugging-access-to-domain-resources). - Due to a mix of a bug and initial design choice clients running `0.59.0` & `0.59.1` might not be able to resolve - domain Resources served by Routing Peers running versions `0.59.0` to `0.59.9` in case when all the Peers in the - NetBird organization are running versions `0.59.0` or newer. + Clients running versions `0.59.0` and `0.59.1` may fail to resolve domain resources served by routing peers running versions `0.59.0` to `0.59.9` when all peers in the organization are on version `0.59.0` or newer. - Installing client in versions `<= 0.58.2` or `>= 0.59.2` or upgrading a Routing Peer to version `0.59.10+` will - resolve this issue. + To fix this, either use client versions `<= 0.58.2` or `>= 0.59.2`, or upgrade the routing peer to version `0.59.10` or later. -On a technical level the feature works as follows: +#### How Domain Resolution Works -1. Initially (when NetBird connects) the operating system is instructed to use NetBird to resolve the requested - domain(s). No routing rules are configured yet. -2. An Application (could be a web browser) requests a domain `example.com` from the Operating System - 1. the Operating System requests a name from NetBird's Local DNS Forwarder, by default running on port `53` of: - - for MacOS & Windows: the highest available IP address in your NetBird range, usually `100.xxx.255.254:53` - - for other systems: local NetBird client's IP address, eg: `100.xxx.123.45` - 2. the Local DNS Forwarder forwards the query to Remote DNS Resolver running on Routing Peer's address - and the following port: - - `22054` for version `0.59.0` and newer - - `5353` for versions below `0.58.x` and older - 3. the Routing Peer resolves the domain name using its local configuration (often independent of NetBird) and returns - the result. - 4. the Local DNS Forwarder sets up routing rules for IP addresses returned from the query, - before returning them to the Application - - see [Trigger the Domain Resource](/help/troubleshooting-client#trigger-the-domain-resource) - to observe this behaviour "in action". -3. the Application receives the result "as usual", except for a slight delay before all of the above takes place the - first time a domain name is requested, -4. all subsequent requests to `example.com` will be served instantly from the Local DNS Forwarder's cache +1. When NetBird connects, it configures the operating system to use NetBird for resolving the specified domains. No routing rules are set up yet. +2. When an application requests a domain (e.g., `example.com`): + - The OS sends the DNS query to NetBird's Local DNS Forwarder, which runs on: + - **macOS and Windows**: The highest available IP in your NetBird range (typically `100.xxx.255.254:53`) + - **Other systems**: Your local NetBird client IP (e.g., `100.xxx.123.45:53`) + - The Local DNS Forwarder sends the query to the Remote DNS Resolver on the routing peer using: + - Port `22054` for NetBird client versions `0.59.0` and newer + - Port `5353` for NetBird client versions `0.58.x` and older + - The routing peer resolves the domain using its local DNS configuration and returns the result. + - The Local DNS Forwarder creates routing rules for the returned IP addresses before sending them to the applicatioxn. See [Trigger the Domain Resource](/help/troubleshooting-client#trigger-the-domain-resource) to observe this behavior. +3. The application receives the response normally, with a slight delay on the first request. +4. Subsequent requests are served instantly from the Local DNS Forwarder's cache. - NetBird tries its best to automatically open up DNS forwarder ports on Routing Peer's firewalls, but might fail on - some system configurations and you might need to open up above 2 ports manually. + NetBird attempts to automatically open DNS forwarder ports on routing peer firewalls, but this may fail on some systems. If you experience issues, manually open the required ports. - You can verify that firewall allows the DNS request in using following command issued from the clients device - `nslookup -port=22054 `, eg: `nslookup -port=22054 example.com 100.123.45.67`. + To verify firewall access, run this command from the client device: + `nslookup -port=22054 ` (e.g., `nslookup -port=22054 example.com 100.123.45.67`). - This is by far the most common cause of issues with domain Resources. + Firewall blocking DNS requests is the most common cause of domain resource issues. -## Manage access to resources +## Manage Access to Resources -To manage access to resources, you should assign them to groups and create [access control policies](/manage/access-control/manage-network-access#creating-policies) to grant access from the specific peer groups. A peer will "see" the resource only after a policy allows access from one of peer's (source) groups to one of the resource's (destination) groups. +To control access to resources, assign them to groups and create [access control policies](/manage/access-control/manage-network-access#creating-policies). A peer can only see a resource when a policy grants access from one of the peer's groups (source) to one of the resource's groups (destination). -See the image below with an example resource `CRM`: +Example resource `CRM` assigned to a group:

resource-group

-Access control policies are rules that define which peers can access the resources in your network. You can create policies based on the source and destination groups, and the type of traffic allowed (e.g., TCP, UDP, ICMP). -The groups assigned to resources should always be placed in the destination input field of the policy. -The peers belonging to the source groups will receive the resources linked to the policy and the firewall rules will be applied according to what is defined. +Access control policies define which peers can access which resources based on source groups, destination groups, and allowed traffic types (TCP, UDP, ICMP). When creating a policy: + +- Place the resource's group in the **destination** field +- Place the peer's group in the **source** field +- Peers in the source groups will receive the resource routes and corresponding firewall rules - Unlike peers, resources are not members of the built-in `All` group by default. If you want to utilize `All` group rules with resources, you must explicitly add them to this group. + Unlike peers, resources are not automatically members of the built-in `All` group. To use `All` group rules with resources, you must explicitly add them to this group. -See the example below with a policy that allows the group `Berlin Office` to access the internal CRM system: +Example policy allowing the `Berlin Office` group to access the internal CRM system:

resource-acl

- Policies for domains or wildcard domains applied to peers with IP ranges might influence access control for those peers, as their destination ranges include any IPs. Therefore, we recommend creating networks with routing peers dedicated to domain and wildcard domains to prevent unwanted access. In upcoming releases, we will provide a fix for this behavior. + Policies for domain or wildcard domain resources may unintentionally affect peers with IP range resources, since IP ranges can match any address. We recommend using dedicated networks and routing peers for domain-based resources to prevent unwanted access. A fix for this behavior is planned for an upcoming release. -## Enable DNS wildcard routing -When you configure wildcard domains as resources, you need to enable DNS wildcard routing. Which has an additional effect in comparison to the previous DNS routes behavior from Network routes; it switches the DNS resolution to the routing peer instead of the local client system. -This is also useful for regular DNS routes when you want to resolve the domain names using the routing peer's IP infrastructure, which will allow for more restricted access control rules in newer versions of the clients (**1**) and for the traffic to go to a near routing peer service. - - (1) Support for more restricted rules will be available in future releases. - -You can enable DNS resolution on the routing peer by accessing your account `Settings` > `Networks` > Enable DNS wildcard routing. See example below: +## Enable DNS Wildcard Routing + +To use wildcard domains as resources, you must enable DNS wildcard routing. This setting changes how domains are resolved: instead of the client resolving domains locally, the routing peer performs DNS resolution. + +This is also useful for regular domain resources when you want to: + +- Resolve domain names using the routing peer's DNS infrastructure +- Route traffic through a geographically nearby routing peer +- Enable more restrictive access control rules (support coming in future releases) + +To enable DNS wildcard routing, go to **Settings** > **Networks** > **Enable DNS wildcard routing**: +

settings-acl

- The `Enable DNS wildcard routing` is supported by routing peers and routing clients running version 0.35.0 or later. - Once the feature is enabled, you may need to restart your routing peers and clients to apply the changes. + DNS wildcard routing requires routing peers and clients running version 0.35.0 or later. After enabling this feature, restart your routing peers and clients to apply the changes. - 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. + Starting with NetBird v0.59.0, the local DNS forwarder port changed from `5353` to `22054` to avoid port collisions. For backward compatibility, the new port is only used when **all peers in the account** run v0.59.0 or newer. If any peer is on an older version, port `5353` is used for all peers. -## Differences between Networks and Network Routes +## Use Cases -| | Networks | Network routes | -|---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| **Requires extra policy connecting routing peers to distribution peers?** | No, the connection is implied when a policy is added to control access to resources | Yes, the routing peers need to have a policy that connects them to peers in the distribution groups | -| **Needs distribution groups?** | No, the source groups in the policies define the distribution groups | Yes, they need to be explicitly defined per network route configured | -| **Requires adding full sets of configurations per routed resource?** | No, the routing peers in a Network are used to route all resources in that network | Yes, every network route needs to have a routing peer, distribution group, access control group, and the network range or DNS route | -| **Allows edit routed resources?** | Yes, you can edit ranges or domains | No, you can't edit IP ranges or DNS routes once created | -| **Allows edit names?** | Yes, names are editable | No, names are defined once while creating the route | -| **Support to wildcard domains?** | Yes, wildcard domains are supported | No, network routes are limited to individual domains | -| **Support for exit-nodes?** | No, even though that exit-nodes can be linked to on-premises or cloud networks, they invalidate other resources | Yes, but the same note is valid when using an exit-node to route other traffic to the same resources | -| **Support for site-2-site IP ranges routing?** | No, but support is planned | Yes, when you create a network route without access control groups | +- [Routing traffic to multiple IP resources](/manage/networks/use-cases/by-resource-type/routing-traffic-to-multiple-resources) +- [Accessing restricted website domain resources](/manage/networks/use-cases/by-resource-type/accessing-restricted-domain-resources) +- [Accessing entire domains within networks](/manage/networks/use-cases/by-resource-type/accessing-entire-domains-within-networks) +## Get Started -## Use cases -- [Routing traffic to multiple IP resources](/manage/networks/routing-traffic-to-multiple-resources) -- [Accessing restricted website domain resources](/manage/networks/accessing-restricted-domain-resources) -- [Accessing entire domains within networks](/manage/networks/accessing-entire-domains-within-networks) - -## Get started

- +

- Make sure to [star us on GitHub](https://github.com/netbirdio/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..b6e01608 --- /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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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..9a42588b --- /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/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/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/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/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/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/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/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/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/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/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/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/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/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..65bfd8e9 --- /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/access-home-devices.mdx b/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx similarity index 64% rename from src/pages/manage/networks/use-cases/access-home-devices.mdx rename to src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx index e49ff657..dcf099b5 100644 --- a/src/pages/manage/networks/use-cases/access-home-devices.mdx +++ b/src/pages/manage/networks/use-cases/by-scenario/access-home-devices.mdx @@ -15,7 +15,7 @@ Your Laptop ──────► NetBird Tunnel ──────► Routing P ## Prerequisites -- A [NetBird account](https://app.netbird.io/) +- 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.) @@ -28,7 +28,16 @@ If you haven't already, install NetBird on your laptop and connect: 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: Find Your Home Subnet +## 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. @@ -44,44 +53,61 @@ netstat -rn | grep default Look for your local subnet, typically something like `192.168.1.0/24` or `192.168.0.0/24`. -## Step 3: Create a Network for Your Home LAN +## 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** -## Step 4: Add Your Home Subnet as a Resource +

+ 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 +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 5: Create an Access Policy +## Step 6: Create an Access Policy 1. After adding your resource, click **Create Policy** -2. Set **Source** to a group containing your devices (e.g., "All Users" or create "Home Users") -3. Set **Destination** to "home-lan" +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** -## Step 6: Set Up the Routing Peer +

+ 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/QNAP NAS (via Docker) -- Old laptop running Linux +- 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) +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 @@ -90,9 +116,18 @@ 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** -## Step 7: Test the Connection +

+ Add routing peer +

+ +## Step 8: Test the Connection From your laptop (connected to a different network like mobile data or coffee shop WiFi): @@ -127,5 +162,5 @@ You can now access your home devices from anywhere. ## Next Steps -- **Need Site-to-Site?** If you want to connect two home networks together, see [Site-to-Site: Home Networks](/manage/network-routes/use-cases/site-to-site-home) -- **Advanced configuration:** See [Advanced Configuration](/manage/network-routes/use-cases/advanced-configuration) for masquerade options and access control details +- **Need Site-to-Site?** If you want to connect two home networks together, see [Site-to-Site: 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..1438c6b3 --- /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..eecf00ab --- /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/cloud-to-on-premise.mdx b/src/pages/manage/networks/use-cases/cloud-to-on-premise.mdx deleted file mode 100644 index 052a9026..00000000 --- a/src/pages/manage/networks/use-cases/cloud-to-on-premise.mdx +++ /dev/null @@ -1,162 +0,0 @@ -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 account](https://app.netbird.io/) -- Access to deploy VMs or containers in your cloud environment -- Network configuration permissions in your cloud VPC - -## Step 1: Deploy a Routing Peer On-Premise - -Install NetBird on a server in your data center that can reach the database: - -```bash -curl -fsSL https://pkgs.netbird.io/install.sh | sh -``` - -Create a setup key in the dashboard and connect: - -```bash -sudo netbird up --setup-key YOUR_SETUP_KEY -``` - -## Step 2: Create a Network for On-Premise Resources - -1. Go to **Networks** in the dashboard -2. Click **Add Network** and name it "On-Premise Data Center" -3. Click **Add Resource** -4. Add your database subnet or specific IP (e.g., `10.100.0.0/24` or `10.100.0.50/32`) -5. Assign to a group like "on-prem-databases" - -## Step 3: Add the Routing Peer - -1. In your network, click **Add Routing Peer** -2. Select your on-premise server -3. Click **Add Routing Peer** - -## Step 4: Deploy NetBird on Cloud Workloads - -**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 5: Create Access Policies - -1. Go to **Access Control > Policies** -2. Create a policy: - - Source: Group containing your cloud workloads - - Destination: "on-prem-databases" - - Protocol: TCP - - Ports: 5432 (PostgreSQL), 3306 (MySQL), etc. - -## Step 6: 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 (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 - -**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/site-to-site-cloud) -- **Advanced configuration:** See [Advanced Configuration](/manage/network-routes/use-cases/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 index e7d5c3aa..41c27054 100644 --- a/src/pages/manage/networks/use-cases/index.mdx +++ b/src/pages/manage/networks/use-cases/index.mdx @@ -23,15 +23,8 @@ Your Laptop ──────► NetBird Tunnel ──────► Routing P 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). -## Why Use Networks? - -Networks is the recommended approach for VPN-to-Site because it offers: -- **Simpler setup** - Streamlined UI workflow -- **Per-resource access control** - Define policies for specific resources -- **Built-in routing peer redundancy** - Easy high-availability configuration - +## 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: diff --git a/src/pages/manage/networks/use-cases/remote-worker-access.mdx b/src/pages/manage/networks/use-cases/remote-worker-access.mdx deleted file mode 100644 index f5c29b2f..00000000 --- a/src/pages/manage/networks/use-cases/remote-worker-access.mdx +++ /dev/null @@ -1,113 +0,0 @@ -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 account](https://app.netbird.io/) -- Admin access to office network infrastructure -- A server or VM at the office to serve as the routing peer - -## Step 1: Deploy a Routing Peer at the Office - -Choose an always-on server at your office. This can be: -- A dedicated Linux VM -- A Windows Server -- A Docker container on an existing server - -**Install NetBird:** - -```bash -# Linux -curl -fsSL https://pkgs.netbird.io/install.sh | sh - -# Windows (PowerShell as Administrator) -Invoke-WebRequest -Uri "https://pkgs.netbird.io/install.ps1" -OutFile "install.ps1"; .\install.ps1 -``` - -**Connect using a setup key:** - -1. In the NetBird dashboard, go to **Setup Keys** -2. Create a reusable key for server deployments -3. Run: `netbird up --setup-key YOUR_SETUP_KEY` - -## Step 2: Create a Network for Office Resources - -1. Go to **Networks** in the dashboard -2. Click **Add Network** and name it "Office LAN" -3. Click **Add Resource** and enter your office subnet (e.g., `10.0.0.0/24`) -4. Assign it to a group like "office-resources" - -## Step 3: Add the Routing Peer - -1. In the Office LAN network, click **Add Routing Peer** -2. Select your office server -3. Click **Add Routing Peer** - -## Step 4: Create Access Policies - -1. Go to **Access Control > Policies** -2. Create a policy: - - Name: "Remote Worker Office Access" - - Source: "Remote Workers" group (or appropriate user group) - - Destination: "office-resources" - - Protocol: Choose based on needs (TCP for most apps, All for full access) - -## Step 5: Onboard Remote Workers - -Distribute NetBird to remote workers: - -1. Create setup keys for employee devices -2. Have employees install NetBird and connect -3. Add employees to the "Remote Workers" group - -Employees can now access office resources from any location. - -## 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, 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/advanced-configuration) for masquerade options and detailed access control diff --git a/src/pages/use-cases/homelab/index.mdx b/src/pages/use-cases/homelab/index.mdx index c631e22b..b5c92611 100644 --- a/src/pages/use-cases/homelab/index.mdx +++ b/src/pages/use-cases/homelab/index.mdx @@ -48,5 +48,5 @@ For most homelabbers, we recommend: | Scenario | Recommended Feature | |----------|---------------------| | Access home devices from laptop/phone | [Networks](/manage/networks) | -| Connect two home networks | [Network Routes](/manage/network-routes/routing-traffic-to-private-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/security/implement-zero-trust.mdx b/src/pages/use-cases/security/implement-zero-trust.mdx index 2284a573..98c16350 100644 --- a/src/pages/use-cases/security/implement-zero-trust.mdx +++ b/src/pages/use-cases/security/implement-zero-trust.mdx @@ -500,7 +500,7 @@ Broken DNS is the most common cause of "NetBird is broken" complaints. For every Use routing peers and Networks when you need to reach private subnets (LAN, VPC, on-premises) rather than only NetBird overlay peers. -**Network Routes vs Networks:** Legacy [Network Routes](/manage/network-routes/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/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. ### 5.1 Requirements for a routing peer @@ -508,7 +508,7 @@ Use routing peers and Networks when you need to reach private subnets (LAN, VPC, 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 +- Is selected as a routing peer in a [Network](/manage/networks) or [Network Route](/manage/network-routes) configuration

high-level-dia diff --git a/src/pages/use-cases/site-to-site/index.mdx b/src/pages/use-cases/site-to-site/index.mdx index 90abd50a..97d85972 100644 --- a/src/pages/use-cases/site-to-site/index.mdx +++ b/src/pages/use-cases/site-to-site/index.mdx @@ -1,4 +1,3 @@ -import { Note } from '@/components/mdx' import { Tiles } from '@/components/Tiles' # Site-to-Site Connectivity @@ -57,9 +56,21 @@ Home NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer **Implementation:** Requires [Network Routes](/manage/network-routes) (Networks does not currently support this) - -The Networks feature currently supports VPN-to-Site only. For Site-to-VPN and Site-to-Site scenarios, use Network Routes. Networks support for these scenarios may be added in future releases. - +### 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/exit-nodes) ## Which Scenario Do I Need? @@ -71,6 +82,7 @@ The Networks feature currently supports VPN-to-Site only. For Site-to-VPN and Si | Connect two home networks together | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/site-to-site-home) only | | Link branch offices | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/site-to-site-office) only | | Bridge cloud VPC with on-premise network | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/site-to-site-cloud) only | +| Route all internet traffic through a specific peer | Exit Node | [Network Routes](/manage/network-routes/use-cases/exit-nodes) only | ## How It Works @@ -134,44 +146,37 @@ All scenarios use a routing peer—a device running NetBird that forwards traffi |------|-------------| | 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) | -| Network Routes | Feature for routing traffic to private networks (supports all scenarios) | -| Networks | Newer feature for defining network resources (VPN-to-Site only, simpler setup) | -| Masquerade | NAT that hides source IPs behind the routing peer's IP (simplifies setup) | +| Masquerade | NAT that hides source IPs behind the routing peer's IP (simplifies routing configuration on clientless devices) | ## Networks vs Network Routes -NetBird has two features for routing traffic to private networks: **Networks** and **Network Routes**. Both are fully supported and coexist in the product. +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. -### Why Two Features? +**Use Networks** for VPN-to-Site scenarios where you want a guided setup experience and per-resource access policies. -Networks is the newer, redesigned approach to private network access. It offers a simpler setup experience with a streamlined UI workflow. However, it doesn't yet support all the scenarios that Network Routes handles. +**Use Network Routes** when you need Site-to-VPN or Site-to-Site connectivity, or require advanced options like disabling masquerade. -Network Routes is the original routing feature. It requires more manual configuration but supports the full range of remote access scenarios, including Site-to-VPN and Site-to-Site. +### Scenario Support -### Which Should I Use? - -| Capability | Networks | Network Routes | -|-----------|----------|----------------| +| Scenario | Networks | Network Routes | +|----------|----------|----------------| | VPN-to-Site | Yes | Yes | | Site-to-VPN | No | Yes | | Site-to-Site | No | Yes | -| Setup complexity | Simpler | More configuration | -| Access control | Per-resource policies | Per-route with ACL Groups | + +### 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 | -| Routing peer redundancy | Built-in UI | Manual setup | - -**Use Networks when:** -- You only need VPN-to-Site access (peers accessing clientless devices) -- You prefer a guided setup experience -- You want per-resource access policies - -**Use Network Routes when:** -- You need Site-to-VPN or Site-to-Site connectivity -- You need to disable masquerade for source IP preservation -- You need ACL Groups for route-level access control +| Exit node support | No | Yes | ### Future Direction -The goal is to eventually migrate all routing functionality into Networks, providing a unified experience. However, this is a gradual process. **Network Routes will not be deprecated without advance notice**, and any migration path will be clearly documented. - -For now, use whichever feature fits your needs. If Networks supports your use case, it's the recommended choice for new setups. If you need capabilities only available in Network Routes, use that—it's stable and fully supported. +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.