sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-08-26 01:31:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Ashley Mensah
2026-02-03 14:28:03 +01:00
parent 96c06a0b1c
commit 0962784937
27 changed files with 1717 additions and 882 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
next.config.mjs
View File

@@ -252,27 +252,27 @@ const nextConfig = {
// documentation redirects for use-cases
{
source: '/how-to/examples',
destination: '/use-cases/examples',
destination: '/use-cases/cloud/aws-ecs-terraform',
permanent: true,
},
{
source: '/how-to/netbird-on-faas',
destination: '/use-cases/netbird-on-faas',
destination: '/use-cases/cloud/netbird-on-faas',
permanent: true,
},
{
source: '/how-to/routing-peers-and-kubernetes',
destination: '/use-cases/routing-peers-and-kubernetes',
destination: '/use-cases/cloud/routing-peers-and-kubernetes',
permanent: true,
},
{
source: '/how-to/client-on-mikrotik-router',
destination: '/use-cases/client-on-mikrotik-router',
destination: '/use-cases/homelab/client-on-mikrotik-router',
permanent: true,
},
{
source: '/how-to/distributed-multi-cloud-ai-argocd-microk8s-vllm',
destination: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm',
destination: '/use-cases/cloud/distributed-multi-cloud-ai',
permanent: true,
},
// documentation redirects for networks
@@ -513,17 +513,74 @@ const nextConfig = {
// Site-to-site documentation restructure redirects
{
source: '/use-cases/setup-site-to-site-access',
destination: '/manage/site-to-site',
destination: '/use-cases/site-to-site',
permanent: true,
},
{
source: '/manage/peers/site-to-site/db-workload-migration',
destination: '/manage/site-to-site/connect-cloud-environments',
destination: '/manage/network-routes/use-cases/site-to-site-cloud',
permanent: true,
},
{
source: '/manage/networks/homelab/access-home-network',
destination: '/manage/site-to-site/connect-home-networks',
destination: '/manage/networks/use-cases/access-home-devices',
permanent: true,
},
// Site-to-Site section redirects (overview and comprehensive guides)
{
source: '/manage/site-to-site',
destination: '/use-cases/site-to-site',
permanent: true,
},
{
source: '/manage/site-to-site/connect-home-networks',
destination: '/use-cases/site-to-site',
permanent: true,
},
{
source: '/manage/site-to-site/connect-office-networks',
destination: '/use-cases/site-to-site',
permanent: true,
},
{
source: '/manage/site-to-site/connect-cloud-environments',
destination: '/use-cases/site-to-site',
permanent: true,
},
{
source: '/manage/site-to-site/advanced-configuration',
destination: '/manage/network-routes/use-cases/advanced-configuration',
permanent: true,
},
// Use-cases flat pages -> categorized
{
source: '/use-cases/examples',
destination: '/use-cases/cloud/aws-ecs-terraform',
permanent: true,
},
{
source: '/use-cases/netbird-on-faas',
destination: '/use-cases/cloud/netbird-on-faas',
permanent: true,
},
{
source: '/use-cases/routing-peers-and-kubernetes',
destination: '/use-cases/cloud/routing-peers-and-kubernetes',
permanent: true,
},
{
source: '/use-cases/implement-zero-trust',
destination: '/use-cases/security/implement-zero-trust',
permanent: true,
},
{
source: '/use-cases/client-on-mikrotik-router',
destination: '/use-cases/homelab/client-on-mikrotik-router',
permanent: true,
},
{
source: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm',
destination: '/use-cases/cloud/distributed-multi-cloud-ai',
permanent: true,
},
]

68
src/components/NavigationDocs.jsx
View File

@@ -130,27 +130,38 @@ export const docsNavigation = [
{ title: 'Route Traffic to Multiple IP resources', href: '/manage/networks/routing-traffic-to-multiple-resources' },
{ title: 'Access Restricted Website Domain Resources', href: '/manage/networks/accessing-restricted-domain-resources' },
{ title: 'Access Entire Domains Within Networks', href: '/manage/networks/accessing-entire-domains-within-networks' },
]
},
{
title: 'Site-to-Site',
isOpen: false,
links: [
{ title: 'Overview', href: '/manage/site-to-site' },
{ title: 'Connect Home Networks', href: '/manage/site-to-site/connect-home-networks' },
{ title: 'Connect Office Networks', href: '/manage/site-to-site/connect-office-networks' },
{ title: 'Connect Cloud Environments', href: '/manage/site-to-site/connect-cloud-environments' },
{ title: 'Advanced Configuration', href: '/manage/site-to-site/advanced-configuration' },
{
title: 'Use Cases',
isOpen: false,
links: [
{ title: 'Overview', href: '/manage/networks/use-cases' },
{ title: 'Access Home Devices', href: '/manage/networks/use-cases/access-home-devices' },
{ title: 'Remote Worker Access', href: '/manage/networks/use-cases/remote-worker-access' },
{ title: 'Cloud to On-Premise', href: '/manage/networks/use-cases/cloud-to-on-premise' },
]
}
]
},
{
title: 'Network Routes',
isOpen: false,
links: [
{ title: 'Concept', href: '/manage/network-routes' },
{ title: 'Route Traffic to Private Networks', href: '/manage/network-routes/routing-traffic-to-private-networks' },
{ title: 'Configure Default Routes for Internet Traffic', href: '/manage/network-routes/configuring-default-routes-for-internet-traffic' },
{ title: 'Configure Routes with Access control', href: '/manage/network-routes/configuring-routes-with-access-control' },
{ title: 'Resolve Overlapping Routes', href: '/manage/network-routes/resolve-overlapping-routes' },
{
title: 'Use Cases',
isOpen: false,
links: [
{ title: 'Overview', href: '/manage/network-routes/use-cases' },
{ title: 'Site-to-Site: Home', href: '/manage/network-routes/use-cases/site-to-site-home' },
{ title: 'Site-to-Site: Office', href: '/manage/network-routes/use-cases/site-to-site-office' },
{ title: 'Site-to-Site: Cloud', href: '/manage/network-routes/use-cases/site-to-site-cloud' },
{ title: 'Advanced Configuration', href: '/manage/network-routes/use-cases/advanced-configuration' },
]
}
]
},
{
@@ -347,12 +358,35 @@ export const docsNavigation = [
{
title: 'USE CASES',
links: [
{ title: 'Serverless and NetBird', href: '/use-cases/netbird-on-faas' },
{ title: 'Routing peers and Kubernetes', href: '/use-cases/routing-peers-and-kubernetes' },
{ title: 'Implement Zero Trust with NetBird', href: '/use-cases/implement-zero-trust' },
{ title: 'NetBird Client on AWS ECS', href: '/use-cases/examples' },
{ title: 'NetBird on Mikrotik Router', href: '/use-cases/client-on-mikrotik-router' },
{ title: 'Distributed AI on Kubernetes', href: '/use-cases/distributed-multi-cloud-ai-argocd-microk8s-vllm' },
{ title: 'Overview', href: '/use-cases' },
{
title: 'Homelab',
isOpen: false,
links: [
{ title: 'Overview', href: '/use-cases/homelab' },
{ title: 'NetBird on MikroTik Router', href: '/use-cases/homelab/client-on-mikrotik-router' },
]
},
{
title: 'Cloud',
isOpen: false,
links: [
{ title: 'Overview', href: '/use-cases/cloud' },
{ title: 'NetBird on AWS ECS', href: '/use-cases/cloud/aws-ecs-terraform' },
{ title: 'NetBird on Serverless (FaaS)', href: '/use-cases/cloud/netbird-on-faas' },
{ title: 'Routing Peers and Kubernetes', href: '/use-cases/cloud/routing-peers-and-kubernetes' },
{ title: 'Distributed Multi-Cloud AI', href: '/use-cases/cloud/distributed-multi-cloud-ai' },
]
},
{
title: 'Security',
isOpen: false,
links: [
{ title: 'Overview', href: '/use-cases/security' },
{ title: 'Implement Zero Trust', href: '/use-cases/security/implement-zero-trust' },
]
},
{ title: 'Site-to-Site Guide', href: '/use-cases/site-to-site' },
{ title: 'Self-hosted vs. Cloud-hosted NetBird', href: '/selfhosted/self-hosted-vs-cloud-netbird' },
],
},

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

@@ -0,0 +1,123 @@
import { Note } 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).
<p>
<img src="/docs-static/img/manage/network-routes/routing-traffic-to-private-networks/netbird-network-routes.png" alt="Network Routes diagram" className="imagewrapper-big"/>
</p>
## 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 |
<Note>
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.
</Note>
## Key Concepts
### 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.
### 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.
### Distribution Groups
Specify which peers receive the network route configuration. Peers in the distribution groups will automatically have the route available.
### ACL Groups
Provide granular access control for routes. When assigned, only peers with policies granting access to the ACL Group can use the route.
### 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
| 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 |
**Use Networks when:**
- You only need VPN-to-Site access
- You prefer a guided setup experience
**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
<Tiles
title="Guides"
items={[
{
href: '/manage/network-routes/routing-traffic-to-private-networks',
name: 'Route Traffic to Private Networks',
description: 'Complete guide to creating and managing network routes',
},
{
href: '/manage/network-routes/configuring-routes-with-access-control',
name: 'Configure Routes with Access Control',
description: 'Use ACL Groups to control who can access routed networks',
},
{
href: '/manage/network-routes/configuring-default-routes-for-internet-traffic',
name: 'Configure Exit Nodes',
description: 'Route all internet traffic through a specific peer',
},
{
href: '/manage/network-routes/resolve-overlapping-routes',
name: 'Resolve Overlapping Routes',
description: 'Handle scenarios where multiple routes have the same CIDR',
},
]}
/>
<Tiles
title="Use Cases"
items={[
{
href: '/manage/network-routes/use-cases',
name: 'Use Cases Overview',
description: 'Site-to-Site and Site-to-VPN scenarios',
},
{
href: '/manage/network-routes/use-cases/site-to-site-home',
name: 'Site-to-Site: Home',
description: 'Connect multiple home networks together',
},
{
href: '/manage/network-routes/use-cases/site-to-site-office',
name: 'Site-to-Site: Office',
description: 'Connect branch offices to headquarters',
},
{
href: '/manage/network-routes/use-cases/site-to-site-cloud',
name: 'Site-to-Site: Cloud',
description: 'Bridge cloud VPCs across providers',
},
]}
/>
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

0
src/pages/manage/site-to-site/advanced-configuration.mdx → src/pages/manage/network-routes/use-cases/advanced-configuration.mdx
View File

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

@@ -0,0 +1,85 @@
import { Tiles } from '@/components/Tiles'
import { Note } 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
### Site-to-Site
Two networks communicate with each other, with neither end-device running NetBird directly. Each network has a routing peer that handles traffic.
```
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.
```
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
<Note>
For VPN-to-Site (NetBird peers accessing clientless devices), you can use either [Networks](/manage/networks/use-cases) (recommended for simplicity) or Network Routes.
</Note>
## Why Use Network Routes?
Network Routes is required when you need:
- **Site-to-Site connectivity** - Connect two networks together
- **Site-to-VPN connectivity** - Clientless devices initiating connections
- **Masquerade control** - Preserve source IPs for auditing
- **ACL Groups** - Route-level access control
<Tiles
title="Choose Your Scenario"
items={[
{
href: '/manage/network-routes/use-cases/site-to-site-home',
name: 'Site-to-Site: Home Networks',
description: 'Connect multiple home networks so devices can communicate across locations',
},
{
href: '/manage/network-routes/use-cases/site-to-site-office',
name: 'Site-to-Site: Office Networks',
description: 'Connect branch offices to headquarters and enable cross-site communication',
},
{
href: '/manage/network-routes/use-cases/site-to-site-cloud',
name: 'Site-to-Site: Cloud Environments',
description: 'Bridge cloud VPCs across providers or connect cloud to on-premise',
},
{
href: '/manage/network-routes/use-cases/advanced-configuration',
name: 'Advanced Configuration',
description: 'Masquerade options, ACL Groups, troubleshooting, and detailed configuration',
},
]}
/>
## Key Configuration Steps
All Site-to-Site and Site-to-VPN scenarios follow this pattern:
1. **Deploy routing peers** at each site
2. **Create network routes** for each site's subnet
3. **Create access policies** allowing routing peers to communicate
4. **Configure clientless devices** to route traffic through the local routing peer
For detailed configuration guidance, see [Advanced Configuration](/manage/network-routes/use-cases/advanced-configuration).

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

@@ -0,0 +1,187 @@
import { Note } from '@/components/mdx'
# Site-to-Site: Cloud Environments
This guide shows how to connect cloud VPCs across providers or bridge cloud and on-premise networks using Network Routes.
## What You'll Achieve
After following this guide, workloads across different cloud providers (AWS, GCP, Azure) or between cloud and on-premise can communicate without exposing traffic to the public internet.
```
AWS VPC ────► Routing Peer ────► NetBird ────► Routing Peer ────► GCP VPC
(10.0.0.0/16) (peer) (peer) (10.1.0.0/16)
```
<Note>
Multi-cloud Site-to-Site requires Network Routes because the Networks feature doesn't yet support this scenario.
</Note>
## Prerequisites
- A [NetBird account](https://app.netbird.io/)
- Access to deploy VMs in your cloud environments
- Network configuration permissions in your cloud VPCs
## Example: Multi-Cloud Connectivity
Connect workloads across AWS and GCP:
- **AWS VPC**: `10.0.0.0/16`
- **GCP VPC**: `10.1.0.0/16`
## Step 1: Deploy Routing Peers in Each Cloud
**AWS:**
Launch an EC2 instance in your VPC with NetBird installed. Use the following user data:
```bash
#!/bin/bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --setup-key YOUR_AWS_SETUP_KEY
```
**GCP:**
Launch a Compute Engine instance in your VPC:
```bash
#!/bin/bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --setup-key YOUR_GCP_SETUP_KEY
```
Create groups for the routing peers:
- "aws-routing-peers"
- "gcp-routing-peers"
## Step 2: 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"
**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"
## Step 3: Create Access Policies
Create policies allowing the routing peers to communicate:
1. Go to **Access Control > Policies**
2. Create bidirectional 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
**AWS VPC:**
Add a route in your route table:
- Destination: `10.1.0.0/16` (GCP CIDR)
- Target: Your NetBird routing peer instance (ENI)
**GCP VPC:**
Add a custom route:
- Destination: `10.0.0.0/16` (AWS CIDR)
- Next hop: Your NetBird routing peer instance
<Note>
Enable IP forwarding on routing peer instances in both clouds.
</Note>
## Step 5: Test Connectivity
From an AWS instance:
```bash
ping 10.1.0.100 # GCP instance
```
From a GCP instance:
```bash
ping 10.0.0.100 # AWS instance
```
## Cloud-Specific Considerations
### AWS
- Security groups must allow traffic from the NetBird routing peer
- Enable source/destination check disabled on the routing peer instance
- Consider using an Auto Scaling group for the routing peer with a static ENI
### GCP
- Firewall rules must allow traffic from the routing peer's internal IP
- Enable IP forwarding on the routing peer instance
- Use managed instance groups for high availability
### Azure
- Network security groups must allow traffic from the routing peer
- Enable IP forwarding on the routing peer NIC
- Consider using a Virtual Machine Scale Set for HA
## Secure Workload Migration
Use Site-to-Site connectivity for migrating workloads between environments:
### Example: Migrating from On-Premise to Cloud
1. **Before migration**: Application and database both on-premise
2. **During migration**: Application in cloud, database still on-premise (use VPN-to-Site via [Networks](/manage/networks/use-cases/cloud-to-on-premise))
3. **Cutover**: Switch traffic to the cloud application
4. **After migration**: Once database is also migrated, update connection strings and remove NetBird if no longer needed
## Best Practices
### Security
- Use dedicated setup keys per environment (dev, staging, production)
- Restrict access policies to specific ports and protocols
- Enable [activity logging](/manage/activity) for compliance
### High Availability
- Deploy multiple routing peers and configure failover
- Monitor routing peer health with your existing tools
- Use cloud-native load balancing where appropriate
### Performance
- Place routing peers close to the resources they serve
- Use direct peering where possible (NetBird will automatically optimize paths)
- Monitor latency and throughput between environments
## Troubleshooting
**Multi-cloud connectivity issues:**
1. Confirm both routing peers are connected to NetBird
2. Check VPC routing tables have correct entries
3. Verify security groups/firewall rules allow traffic
**High latency:**
1. Check routing peer placement and network connectivity
2. Verify traffic is using direct peer-to-peer connections (not relays)
3. Review cloud network configuration for bottlenecks
## Advanced Configuration
For masquerade options, ACL Groups, and detailed troubleshooting, see [Advanced Configuration](/manage/network-routes/use-cases/advanced-configuration).

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

@@ -0,0 +1,160 @@
import { Note } from '@/components/mdx'
# Site-to-Site: Home Networks
This guide shows how to connect two home networks together so devices can communicate across locations—without installing NetBird on every device.
## What You'll Achieve
After following this guide, devices on one home network can communicate with devices on another home network. For example:
- Your home NAS can back up to your parents' NAS
- Family members can access shared media servers
- IoT devices can communicate across homes
```
Home A: NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer ──► Parents' NAS
(no NetBird) (peer) (peer) (no NetBird)
```
<Note>
Site-to-Site requires Network Routes because the Networks feature doesn't yet support bidirectional routing between sites.
</Note>
## Prerequisites
- A [NetBird account](https://app.netbird.io/)
- 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))
## 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
**At your home:**
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_HOME_SETUP_KEY
```
**At parents' home:**
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key YOUR_PARENTS_SETUP_KEY
```
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
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**
**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**
## Step 3: Create Access Policies
Create policies that allow the routing peers to communicate:
1. Go to **Access Control > Policies**
2. Add a policy:
- Name: "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"
- Source: "parents-routing-peers"
- Destination: "home-routing-peers"
- Protocol: All
## Step 4: Configure Clientless Devices
For devices without NetBird to reach the other network, add a static route pointing to the local routing peer.
**On a Linux device at your home:**
```bash
# Route to parents' network through your routing peer
sudo ip route add 192.168.2.0/24 via 192.168.1.100
```
Where `192.168.1.100` is your routing peer's local IP.
**On a Windows device:**
```powershell
route add 192.168.2.0 mask 255.255.255.0 192.168.1.100
```
<Note>
For persistent routes, configure them in your router's DHCP settings or the device's network configuration.
</Note>
**Router-level configuration (recommended):**
Configure your router to advertise routes via DHCP or add a static route that applies to all devices:
```
# On your home router
Destination: 192.168.2.0/24
Gateway: 192.168.1.100 (your routing peer's IP)
```
## Step 5: Test Cross-Network Access
From a device at your home:
```bash
ping 192.168.2.1 # Parents' router
ping 192.168.2.50 # Parents' NAS
```
From a device at parents' home:
```bash
ping 192.168.1.1 # Your router
ping 192.168.1.50 # Your NAS
```
## Troubleshooting
**Site-to-site not working:**
1. Verify both routing peers are online and connected: check `netbird status` on each
2. Check that static routes are configured on clientless devices
3. Ensure access policies allow traffic in both directions
**Can't reach specific devices:**
1. Verify the device has a route to the remote network
2. Check firewall rules on the target device
3. Ensure the routing peer can reach the target on its local network
**Traffic works one way but not the other:**
1. Check that both network routes exist
2. Verify access policies are bidirectional
3. Ensure static routes are configured at both ends
## Advanced Configuration
For masquerade options, ACL Groups for access control, and detailed troubleshooting, see [Advanced Configuration](/manage/network-routes/use-cases/advanced-configuration).

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

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

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

@@ -14,9 +14,10 @@ such as LANs, VPCs, or office networks, and manage access to internal resources
</p>
<Note>
Networks replace the old [Network Routes](/manage/network-routes/routing-traffic-to-private-networks) concept, which is now deprecated.
Existing Network routes will continue to work as before, but we recommend migrating to Networks for better access
management to your resources.
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.
</Note>
## Concepts

114
src/pages/manage/site-to-site/connect-home-networks.mdx → src/pages/manage/networks/use-cases/access-home-devices.mdx
View File

@@ -1,14 +1,17 @@
import { Note, Warning } from '@/components/mdx'
import { Note } from '@/components/mdx'
# Connect Home Networks
# Access Home Devices (VPN-to-Site)
This guide helps homelabbers set up remote access to home network devices and optionally connect multiple home networks together.
This guide shows how to access your home network devices from anywhere using the Networks feature.
## What You'll Achieve
After following this guide, you'll be able to:
- Access your NAS, media server, or home automation from anywhere (VPN-to-Site)
- Optionally connect two home networks together so devices can communicate (Site-to-Site)
After following this guide, you'll be able to access your home NAS, media server, home automation, or any device on your home network from your laptop or phone—anywhere in the world.
```
Your Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Home NAS
(peer) (at home) (no NetBird)
```
## Prerequisites
@@ -16,11 +19,7 @@ After following this guide, you'll be able to:
- 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.)
## Part 1: Access Home Devices from Anywhere (VPN-to-Site)
This is the most common homelab scenario: you're traveling and want to access devices on your home network.
### Step 1: Connect Your Laptop to NetBird
## Step 1: Connect Your Laptop to NetBird
If you haven't already, install NetBird on your laptop and connect:
@@ -29,7 +28,7 @@ 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: Find Your Home Subnet
Before configuring NetBird, identify your home network's subnet.
@@ -45,13 +44,13 @@ 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 3: 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
## Step 4: Add Your Home Subnet as a Resource
1. In your new network, click **Add Resource**
2. Enter a name like "Home Subnet"
@@ -63,7 +62,7 @@ Look for your local subnet, typically something like `192.168.1.0/24` or `192.16
For more granular access, add specific device IPs instead of the entire subnet. For example, add `192.168.1.50/32` to only allow access to your NAS.
</Note>
### Step 5: Create an Access Policy
## Step 5: 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")
@@ -71,7 +70,7 @@ For more granular access, add specific device IPs instead of the entire subnet.
4. Set **Protocol** to All
5. Name it "Home LAN Access" and click **Add Policy**
### Step 6: Set Up the Routing Peer
## Step 6: Set Up the Routing Peer
The routing peer forwards traffic from NetBird to your local network. Use any always-on device:
- Raspberry Pi
@@ -93,7 +92,7 @@ sudo netbird up --setup-key YOUR_SETUP_KEY
4. In the Networks view, click **Add Routing Peer** on your Home LAN network
5. Select your new peer and click **Add Routing Peer**
### Step 7: Test the Connection
## Step 7: Test the Connection
From your laptop (connected to a different network like mobile data or coffee shop WiFi):
@@ -104,79 +103,6 @@ ping 192.168.1.50 # Your NAS or other device
You can now access your home devices from anywhere.
---
## Part 2: Connect Two Home Networks (Site-to-Site)
Want to connect your home network with a family member's? This requires Network Routes instead of Networks.
<Note>
Site-to-site requires Network Routes because the Networks feature doesn't yet support bidirectional routing between sites.
</Note>
### 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
Install NetBird on a device at each home following the same process as Part 1, Step 6.
### Step 2: Create Network Routes
1. Go to **Network Routes** in the dashboard
2. Click **Add Route**
**For your home network:**
- Network: `192.168.1.0/24`
- Routing Peer: Select "home-rpi"
- Enable **Masquerade** (recommended)
- Click **Save**
**For parents' home network:**
- Network: `192.168.2.0/24`
- Routing Peer: Select "parents-rpi"
- Enable **Masquerade** (recommended)
- Click **Save**
### Step 3: Create Access Policies
Create policies that allow the routing peers to communicate:
1. Go to **Access Control > Policies**
2. Add a policy:
- Source: Group containing "home-rpi"
- Destination: Group containing "parents-rpi"
- Protocol: All (or restrict as needed)
### Step 4: Configure Clientless Devices
For devices without NetBird to reach the other network, add a static route pointing to the local routing peer.
**Example on a Linux device at your home:**
```bash
# Route to parents' network through your routing peer
sudo ip route add 192.168.2.0/24 via 192.168.1.100
```
Where `192.168.1.100` is your routing peer's local IP.
<Note>
For persistent routes, configure them in your router's DHCP settings or the device's network configuration.
</Note>
### Step 5: Test Cross-Network Access
From a device at your home:
```bash
ping 192.168.2.1 # Parents' router
```
---
## Common Home Devices to Access
| Device | Typical Access Method |
@@ -199,9 +125,7 @@ ping 192.168.2.1 # Parents' router
1. Ensure the routing peer has a stable internet connection
2. Check if your ISP blocks VPN traffic (try a different port or protocol)
**Site-to-site not working:**
1. Verify both routing peers are online and connected
2. Check that static routes are configured on clientless devices
3. Ensure access policies allow traffic in both directions
## Next Steps
For advanced configuration options including masquerade settings and access control, see [Advanced Configuration](/manage/site-to-site/advanced-configuration).
- **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

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

@@ -0,0 +1,162 @@
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

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

@@ -0,0 +1,61 @@
import { Tiles } from '@/components/Tiles'
import { Note } from '@/components/mdx'
# Networks Use Cases
These guides show how to use the [Networks](/manage/networks) feature for VPN-to-Site access—where NetBird peers access devices on remote networks that don't have NetBird installed.
## What is VPN-to-Site?
VPN-to-Site allows a device running NetBird (like your laptop) to access devices on a remote network (like your home or office) without installing NetBird on every device.
```
Your Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Target Device
(peer) (peer) (no NetBird)
```
**Example scenarios:**
- Access your home NAS from a coffee shop
- Reach office servers while traveling
- Connect to IoT devices on a remote network
<Note>
Networks supports VPN-to-Site only. For Site-to-VPN (clientless devices initiating connections) or Site-to-Site (connecting two networks), use [Network Routes](/manage/network-routes/use-cases).
</Note>
## 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
<Tiles
title="Choose Your Scenario"
items={[
{
href: '/manage/networks/use-cases/access-home-devices',
name: 'Access Home Devices',
description: 'Access your NAS, home automation, and media servers from anywhere',
},
{
href: '/manage/networks/use-cases/remote-worker-access',
name: 'Remote Worker Access',
description: 'Enable employees to access office resources while working remotely',
},
{
href: '/manage/networks/use-cases/cloud-to-on-premise',
name: 'Cloud to On-Premise',
description: 'Connect cloud workloads to on-premise databases and services',
},
]}
/>
## Need More Than VPN-to-Site?
If your scenario requires:
- Clientless devices initiating connections (Site-to-VPN)
- Two networks communicating with each other (Site-to-Site)
- Disabling masquerade for source IP preservation
See [Network Routes Use Cases](/manage/network-routes/use-cases) instead.

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

@@ -0,0 +1,113 @@
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

287
src/pages/manage/site-to-site/connect-cloud-environments.mdx
View File

@@ -1,287 +0,0 @@
import { Note, Warning } from '@/components/mdx'
# Connect Cloud Environments
This guide helps DevOps engineers set up secure connectivity between cloud environments, on-premise infrastructure, and hybrid deployments.
## What You'll Achieve
After following this guide, you'll be able to:
- Connect cloud workloads to on-premise databases (VPN-to-Site)
- Bridge multiple cloud providers (Site-to-Site)
- Enable secure workload migration between environments
## 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
## Scenario 1: Cloud Workload Accessing On-Premise Database
A common hybrid cloud pattern: your application runs in the cloud but needs to access an on-premise database.
### Architecture Overview
```
Cloud VM ────► NetBird Tunnel ────► Routing Peer ────► Database Server
(peer) (peer) (on-premise)
```
### 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.
---
## Scenario 2: Multi-Cloud Connectivity (Site-to-Site)
Connect workloads across different cloud providers (AWS, GCP, Azure) without exposing them to the public internet.
<Note>
Multi-cloud site-to-site requires Network Routes because the Networks feature doesn't yet support this scenario.
</Note>
### Architecture Overview
```
AWS VPC ────► Routing Peer ────► NetBird ────► Routing Peer ────► GCP VPC
(10.0.0.0/16) (peer) (peer) (10.1.0.0/16)
```
### Step 1: Deploy Routing Peers in Each Cloud
**AWS:**
Launch an EC2 instance in your VPC with NetBird installed. Use the following user data:
```bash
#!/bin/bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --setup-key YOUR_AWS_SETUP_KEY
```
**GCP:**
Launch a Compute Engine instance in your VPC:
```bash
#!/bin/bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --setup-key YOUR_GCP_SETUP_KEY
```
### Step 2: Create Network Routes
**For AWS VPC:**
1. Go to **Network Routes**
2. Add route: `10.0.0.0/16`
3. Routing peer: Your AWS instance
4. Enable Masquerade
**For GCP VPC:**
1. Add route: `10.1.0.0/16`
2. Routing peer: Your GCP instance
3. Enable Masquerade
### Step 3: Create Access Policies
Create policies allowing the routing peers to communicate:
1. Go to **Access Control > Policies**
2. Create bidirectional policies between the routing peer groups
### Step 4: Configure VPC Routing
**AWS VPC:**
Add a route in your route table:
- Destination: `10.1.0.0/16` (GCP CIDR)
- Target: Your NetBird routing peer instance
**GCP VPC:**
Add a custom route:
- Destination: `10.0.0.0/16` (AWS CIDR)
- Next hop: Your NetBird routing peer instance
### Step 5: Test Connectivity
From an AWS instance:
```bash
ping 10.1.0.100 # GCP instance
```
---
## Scenario 3: Secure Workload Migration
Migrate workloads between environments while maintaining connectivity to dependencies.
### Example: Migrating from On-Premise to Cloud
1. **Before migration**: Application and database both on-premise
2. **During migration**: Application in cloud, database still on-premise
3. **After migration**: Both in cloud (NetBird connection can be removed or repurposed)
### Step 1: Establish Connectivity First
Before migrating the application, set up VPN-to-Site connectivity (Scenario 1) so the cloud application can reach the on-premise database.
### Step 2: Deploy the Cloud Application
Deploy your application in the cloud with NetBird configured. Test that it can reach the on-premise database.
### Step 3: Cutover
Switch traffic to the cloud application. The database connection works identically—just over NetBird instead of the local network.
### Step 4: Complete Migration
Once the database is also migrated to the cloud:
1. Update the application's database connection to the new cloud IP
2. Remove the on-premise network from NetBird
3. Optionally remove NetBird from the application if no longer needed
---
## 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
**Multi-cloud connectivity issues:**
1. Confirm both routing peers are connected to NetBird
2. Check VPC routing tables have correct entries
3. Verify security groups/firewall rules allow traffic
**High latency:**
1. Check routing peer placement and network connectivity
2. Verify traffic is using direct peer-to-peer connections (not relays)
3. Review cloud network configuration for bottlenecks
For advanced configuration including masquerade options and detailed access control, see [Advanced Configuration](/manage/site-to-site/advanced-configuration).

238
src/pages/manage/site-to-site/connect-office-networks.mdx
View File

@@ -1,238 +0,0 @@
import { Note, Warning } from '@/components/mdx'
# Connect Office Networks
This guide helps IT administrators set up secure remote access to office resources and connect multiple office locations.
## What You'll Achieve
After following this guide, you'll be able to:
- Enable remote workers to access office resources (VPN-to-Site)
- Allow office systems to reach remote workers (Site-to-VPN)
- Connect branch offices to headquarters (Site-to-Site)
## Prerequisites
- A [NetBird account](https://app.netbird.io/)
- Admin access to office network infrastructure
- A server or VM at each office location to serve as the routing peer
## Scenario 1: Remote Worker Access (VPN-to-Site)
The most common business scenario: employees need to access office resources while working remotely.
### 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.
---
## Scenario 2: Office Systems Reaching Remote Workers (Site-to-VPN)
Some scenarios require office systems to initiate connections to remote workers (monitoring, management tools, etc.).
<Note>
Site-to-VPN requires Network Routes because the Networks feature doesn't support clientless devices initiating connections.
</Note>
### Step 1: Set Up the Routing Peer
Follow Scenario 1, Step 1 to deploy a routing peer at the office.
### Step 2: Create a Network Route for the Office Network
1. Go to **Network Routes**
2. Click **Add Route**
3. Enter the office subnet (e.g., `10.0.0.0/24`)
4. Select your routing peer
5. Enable **Masquerade**
6. Click **Save**
### Step 3: Configure the Office System
On the office system that needs to reach remote workers, add a route to the NetBird network:
```bash
# Route to NetBird network through the routing peer
sudo ip route add 100.64.0.0/10 via 10.0.0.50
```
Where `10.0.0.50` is the routing peer's office IP.
### Step 4: Create Bidirectional Access Policies
Create policies allowing traffic in both directions:
1. Office to remote workers (for initiated connections)
2. Remote workers to office (for responses)
---
## Scenario 3: Branch Office Connectivity (Site-to-Site)
Connect multiple office locations so all devices can communicate.
### Example Setup
- **Headquarters**: `10.0.0.0/24` with routing peer "hq-router"
- **Branch Office**: `10.1.0.0/24` with routing peer "branch-router"
### Step 1: Deploy Routing Peers
Install NetBird on a server at each location. Create dedicated groups for each:
- "hq-routing-peers" for headquarters
- "branch-routing-peers" for branch office
### Step 2: Create Network Routes
**For headquarters:**
1. Go to **Network Routes**
2. Add route: `10.0.0.0/24`
3. Routing peer: "hq-router"
4. Enable Masquerade
5. Optionally add ACL Groups for access control
**For branch office:**
1. Add route: `10.1.0.0/24`
2. Routing peer: "branch-router"
3. Enable Masquerade
4. Optionally add ACL Groups
### Step 3: Create Access Policies
Create policies allowing the routing peers to communicate:
```
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, also create policies for the ACL Groups if configured.
### Step 4: Configure Network Equipment
**Option A: Router-level routes (recommended)**
Configure your routers to advertise routes to the remote network via DHCP or add static routes:
```
# On HQ router, route to branch through routing peer
10.1.0.0/24 via 10.0.0.50 (hq-router's IP)
# On Branch router, route to HQ through routing peer
10.0.0.0/24 via 10.1.0.50 (branch-router's IP)
```
**Option B: Per-device routes**
Add routes on individual devices that need cross-site access:
```bash
# On HQ device
sudo ip route add 10.1.0.0/24 via 10.0.0.50
# On Branch device
sudo ip route add 10.0.0.0/24 via 10.1.0.50
```
### Step 5: Test Connectivity
From a device at headquarters:
```bash
ping 10.1.0.1 # Branch router
ping 10.1.0.100 # Branch server
```
---
## 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
**Branch office connectivity issues:**
1. Confirm both routing peers show as connected in the dashboard
2. Verify static routes are configured correctly
3. Check firewall rules aren't blocking traffic
**Slow performance:**
1. Check routing peer placement—it should have good network connectivity
2. Consider enabling [lazy connections](/manage/peers/lazy-connection) for large deployments
3. Review network route priorities if multiple routes exist
For advanced configuration including masquerade options and detailed access control, see [Advanced Configuration](/manage/site-to-site/advanced-configuration).

130
src/pages/manage/site-to-site/index.mdx
View File

@@ -1,130 +0,0 @@
import { Note } from '@/components/mdx'
import { Tiles } from '@/components/Tiles'
# Site-to-Site Connectivity
Site-to-site connectivity allows you to connect entire networks together, enabling devices to communicate across locations without installing the NetBird client on every device.
## Understanding Remote Access Scenarios
NetBird supports three distinct remote access scenarios. Understanding which one you need is the first step to a successful setup.
### VPN-to-Site
A NetBird peer (device running the NetBird client) accesses devices on a remote network that don't have NetBird installed.
```
Your Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Office Printer
(peer) (peer) (clientless)
```
**Common use cases:**
- Access your home NAS from anywhere
- Reach office servers while traveling
- Connect to IoT devices on a remote network
**Implementation:** Use [Networks](/manage/networks) (recommended) or [Network Routes](/manage/network-routes/routing-traffic-to-private-networks)
### Site-to-VPN
A device without NetBird initiates connections to NetBird peers. This is the reverse of VPN-to-Site—the clientless device starts the connection.
```
Office Server ──────► Routing Peer ──────► NetBird Tunnel ──────► Your Laptop
(clientless) (peer) (peer)
```
**Common use cases:**
- Office monitoring systems pushing data to remote analysts
- On-premise servers initiating backups to cloud peers
- Legacy systems that must initiate outbound connections
**Implementation:** Requires [Network Routes](/manage/network-routes/routing-traffic-to-private-networks) (Networks does not currently support this)
### Site-to-Site
Devices on separate networks communicate with each other, with neither running NetBird directly. Each network has a routing peer that handles traffic.
```
Home NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer ──► Office Server
(clientless) (peer) (peer) (clientless)
```
**Common use cases:**
- Connect branch office networks to headquarters
- Link home networks of family members
- Bridge on-premise data centers with cloud VPCs
**Implementation:** Requires [Network Routes](/manage/network-routes/routing-traffic-to-private-networks) (Networks does not currently support this)
<Note>
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.
</Note>
## Which Scenario Do I Need?
| I want to... | Scenario | Feature to Use |
|-------------|----------|----------------|
| Access home devices from my laptop | VPN-to-Site | Networks or Network Routes |
| Access office resources while traveling | VPN-to-Site | Networks or Network Routes |
| Let an office server connect to my laptop | Site-to-VPN | Network Routes only |
| Connect two home networks together | Site-to-Site | Network Routes only |
| Link branch offices | Site-to-Site | Network Routes only |
| Bridge cloud VPC with on-premise network | Site-to-Site | Network Routes only |
## How It Works
All scenarios use a routing peer—a device running NetBird that forwards traffic for its local network:
1. **Deploy a routing peer** at each site (any device running NetBird with access to the local network)
2. **Configure routing** to advertise each site's subnet through NetBird
3. **Set access policies** to control which peers can reach which networks
4. **Configure clientless devices** to route traffic through the routing peer (for Site-to-VPN and Site-to-Site)
<Tiles
title="Choose Your Guide"
items={[
{
href: '/manage/site-to-site/connect-home-networks',
name: 'Connect Home Networks',
description: 'For homelabbers: access your NAS, home automation, media servers, and connect family homes',
},
{
href: '/manage/site-to-site/connect-office-networks',
name: 'Connect Office Networks',
description: 'For IT admins: enable remote worker access, connect branch offices, and link multiple sites',
},
{
href: '/manage/site-to-site/connect-cloud-environments',
name: 'Connect Cloud Environments',
description: 'For DevOps: bridge cloud and on-premise, enable hybrid deployments, migrate workloads',
},
{
href: '/manage/site-to-site/advanced-configuration',
name: 'Advanced Configuration',
description: 'Deep dive into masquerade options, access control, and troubleshooting',
},
]}
/>
## Key Concepts
| Term | Description |
|------|-------------|
| Routing peer | A device running NetBird that forwards traffic for its local network |
| Clientless device | A device that doesn't run NetBird (printers, IoT, legacy systems) |
| Network Routes | Legacy feature for routing traffic to private networks (supports all scenarios) |
| Networks | Newer feature for defining network resources (VPN-to-Site only) |
| Masquerade | NAT that hides source IPs behind the routing peer's IP (simplifies setup) |
## Quick Reference: Networks vs Network Routes
| Capability | Networks | Network Routes |
|-----------|----------|----------------|
| VPN-to-Site | Yes | Yes |
| Site-to-VPN | No | Yes |
| Site-to-Site | No | Yes |
| Setup complexity | Simpler | More configuration required |
| Access control | Per-resource policies | Per-route with ACL Groups |
For detailed technical configuration including masquerade options, access control setup, and troubleshooting, see [Advanced Configuration](/manage/site-to-site/advanced-configuration).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,177 @@
import { Note } from '@/components/mdx'
import { Tiles } from '@/components/Tiles'
# Site-to-Site Connectivity
Site-to-site connectivity allows you to connect entire networks together, enabling devices to communicate across locations without installing the NetBird client on every device.
## Understanding Remote Access Scenarios
NetBird supports three distinct remote access scenarios. Understanding which one you need is the first step to a successful setup.
### VPN-to-Site
A NetBird peer (device running the NetBird client) accesses devices on a remote network that don't have NetBird installed.
```
Your Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Office Printer
(peer) (peer) (clientless)
```
**Common use cases:**
- Access your home NAS from anywhere
- Reach office servers while traveling
- Connect to IoT devices on a remote network
**Implementation:** Use [Networks](/manage/networks) (recommended) or [Network Routes](/manage/network-routes)
### Site-to-VPN
A device without NetBird initiates connections to NetBird peers. This is the reverse of VPN-to-Site—the clientless device starts the connection.
```
Office Server ──────► Routing Peer ──────► NetBird Tunnel ──────► Your Laptop
(clientless) (peer) (peer)
```
**Common use cases:**
- Office monitoring systems pushing data to remote analysts
- On-premise servers initiating backups to cloud peers
- Legacy systems that must initiate outbound connections
**Implementation:** Requires [Network Routes](/manage/network-routes) (Networks does not currently support this)
### Site-to-Site
Devices on separate networks communicate with each other, with neither running NetBird directly. Each network has a routing peer that handles traffic.
```
Home NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer ──► Office Server
(clientless) (peer) (peer) (clientless)
```
**Common use cases:**
- Connect branch office networks to headquarters
- Link home networks of family members
- Bridge on-premise data centers with cloud VPCs
**Implementation:** Requires [Network Routes](/manage/network-routes) (Networks does not currently support this)
<Note>
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.
</Note>
## Which Scenario Do I Need?
| I want to... | Scenario | Feature to Use |
|-------------|----------|----------------|
| Access home devices from my laptop | VPN-to-Site | [Networks](/manage/networks/use-cases/access-home-devices) or [Network Routes](/manage/network-routes) |
| Access office resources while traveling | VPN-to-Site | [Networks](/manage/networks/use-cases/remote-worker-access) or [Network Routes](/manage/network-routes) |
| Let an office server connect to my laptop | Site-to-VPN | [Network Routes](/manage/network-routes/use-cases/site-to-site-office) only |
| 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 |
## How It Works
All scenarios use a routing peer—a device running NetBird that forwards traffic for its local network:
1. **Deploy a routing peer** at each site (any device running NetBird with access to the local network)
2. **Configure routing** to advertise each site's subnet through NetBird
3. **Set access policies** to control which peers can reach which networks
4. **Configure clientless devices** to route traffic through the routing peer (for Site-to-VPN and Site-to-Site)
<Tiles
title="VPN-to-Site Guides (Networks)"
items={[
{
href: '/manage/networks/use-cases/access-home-devices',
name: 'Access Home Devices',
description: 'Access your NAS, home automation, and media servers from anywhere',
},
{
href: '/manage/networks/use-cases/remote-worker-access',
name: 'Remote Worker Access',
description: 'Enable employees to access office resources while working remotely',
},
{
href: '/manage/networks/use-cases/cloud-to-on-premise',
name: 'Cloud to On-Premise',
description: 'Connect cloud workloads to on-premise databases and services',
},
]}
/>
<Tiles
title="Site-to-Site Guides (Network Routes)"
items={[
{
href: '/manage/network-routes/use-cases/site-to-site-home',
name: 'Connect Home Networks',
description: 'Link multiple home networks so devices can communicate across locations',
},
{
href: '/manage/network-routes/use-cases/site-to-site-office',
name: 'Connect Office Networks',
description: 'Connect branch offices to headquarters and enable cross-site communication',
},
{
href: '/manage/network-routes/use-cases/site-to-site-cloud',
name: 'Connect Cloud Environments',
description: 'Bridge cloud VPCs across providers or connect cloud to on-premise',
},
{
href: '/manage/network-routes/use-cases/advanced-configuration',
name: 'Advanced Configuration',
description: 'Masquerade options, ACL Groups, and troubleshooting',
},
]}
/>
## Key Concepts
| Term | Description |
|------|-------------|
| Routing peer | A device running NetBird that forwards traffic for its local network |
| Clientless device | A device that doesn't run NetBird (printers, IoT, legacy systems) |
| 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) |
## 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.
### Why Two Features?
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.
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.
### Which Should I Use?
| 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 |
| 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
### 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.