mirror of
https://github.com/netbirdio/docs.git
synced 2026-05-04 00:06:36 +00:00
Streamlined site-to-site docs in new dedicated section. Removed old u… (#585)
* Streamlined site-to-site docs in new dedicated section. Removed old use-case guide and added redirects
* restructure use-cases, move network use cases to network sections
* Reorganize network routes and networks documentation structure
- Restructure use cases into by-scenario and by-configuration folders
- Reorganize images to match new doc structure (concepts, by-scenario, by-resource-type)
- Add screenshots for site-to-site guides (home, office, cloud)
- Add policy screenshots for networks use cases
- Update site-to-site docs to use two separate policies instead of bidirectional
- Fix Access Control Groups to use correct destination groups
- Move "Self-Hosted vs Cloud" page to about section
- Update navigation and add redirects for moved pages
- Add CLAUDE.md for Claude Code guidance
* cleaned up network docs/image folder structure
* Align site-to-site use case links and redirects
Co-authored-by: Cursor <cursoragent@cursor.com>
* Update CLAUDE.md with accurate project details
Fix Next.js version (14 → 16), add React 19/Tailwind/Pages Router
details, document MDX page conventions, image paths, and note
absence of test suite.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix broken images and hydration error on networks page
- Restore 6 network index images accidentally deleted in 4116092
- Fix keycloak image filename typo (keycloack -> keycloak)
- Fix hydration mismatch by replacing invalid <p><div> nesting with <div>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix 4 broken internal links found in PR review
- Fix missing by-scenario/ segment in site-to-site-home and
site-to-site-office Tile hrefs (network-routes use-cases index)
- Fix lazy-connections typo to lazy-connection (implement-zero-trust)
- Update stale redirect link to direct path for access-control
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
shuuri-labs
@@ -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
70
src/pages/use-cases/cloud/index.mdx
Normal file
@@ -0,0 +1,70 @@
|
||||
import { Tiles } from '@/components/Tiles'
|
||||
|
||||
# Cloud Use Cases
|
||||
|
||||
Deploy NetBird across cloud environments to securely connect workloads, enable hybrid cloud connectivity, and simplify multi-cloud networking.
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
- **Hybrid Cloud**: Connect cloud workloads to on-premise databases and services
|
||||
- **Multi-Cloud**: Bridge AWS, GCP, and Azure environments without exposing traffic to the internet
|
||||
- **Kubernetes**: Enable secure communication between clusters and external resources
|
||||
- **Serverless**: Run NetBird on FaaS platforms for ephemeral, secure connectivity
|
||||
- **Container Orchestration**: Deploy NetBird as a daemon set on ECS, EKS, or other container platforms
|
||||
|
||||
## Getting Started
|
||||
|
||||
For connecting cloud VPCs to on-premise networks, see the [Site-to-Site Connectivity Guide](/use-cases/site-to-site).
|
||||
|
||||
<Tiles
|
||||
title="Guides"
|
||||
items={[
|
||||
{
|
||||
href: '/use-cases/cloud/aws-ecs-terraform',
|
||||
name: 'NetBird on AWS ECS',
|
||||
description: 'Deploy NetBird as an ECS daemon set using Terraform',
|
||||
},
|
||||
{
|
||||
href: '/use-cases/cloud/netbird-on-faas',
|
||||
name: 'NetBird on Serverless (FaaS)',
|
||||
description: 'Run NetBird on serverless platforms for ephemeral connectivity',
|
||||
},
|
||||
{
|
||||
href: '/use-cases/cloud/routing-peers-and-kubernetes',
|
||||
name: 'Routing Peers and Kubernetes',
|
||||
description: 'Use routing peers to connect Kubernetes workloads to external networks',
|
||||
},
|
||||
{
|
||||
href: '/use-cases/cloud/distributed-multi-cloud-ai',
|
||||
name: 'Distributed Multi-Cloud AI',
|
||||
description: 'Build distributed AI infrastructure across multiple clouds with ArgoCD and MicroK8s',
|
||||
},
|
||||
{
|
||||
href: '/manage/networks/use-cases/by-scenario/cloud-to-on-premise',
|
||||
name: 'Cloud to On-Premise Access',
|
||||
description: 'Connect cloud workloads to on-premise databases and services',
|
||||
},
|
||||
{
|
||||
href: '/manage/network-routes/use-cases/by-scenario/site-to-site-cloud',
|
||||
name: 'Multi-Cloud Site-to-Site',
|
||||
description: 'Bridge cloud VPCs across providers using Site-to-Site routing',
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
## Cloud Provider Considerations
|
||||
|
||||
### AWS
|
||||
- Use VPC endpoints where possible for AWS services
|
||||
- Security groups must allow traffic from NetBird routing peers
|
||||
- Consider Auto Scaling groups with static ENIs for high availability
|
||||
|
||||
### GCP
|
||||
- Enable IP forwarding on routing peer instances
|
||||
- Firewall rules must allow traffic from routing peer internal IPs
|
||||
- Use instance groups for redundancy
|
||||
|
||||
### Azure
|
||||
- Enable IP forwarding on routing peer NICs
|
||||
- Network security groups must allow routing peer traffic
|
||||
- Consider Virtual Machine Scale Sets for HA
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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
52
src/pages/use-cases/homelab/index.mdx
Normal file
@@ -0,0 +1,52 @@
|
||||
import { Tiles } from '@/components/Tiles'
|
||||
|
||||
# Homelab Use Cases
|
||||
|
||||
NetBird helps homelabbers securely access their home infrastructure from anywhere and connect multiple home networks together.
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
- **Remote NAS Access**: Access your Synology, QNAP, or TrueNAS from anywhere
|
||||
- **Home Automation**: Reach Home Assistant, smart home devices, and IoT systems remotely
|
||||
- **Media Servers**: Stream from Plex, Jellyfin, or Emby while traveling
|
||||
- **Family Network Sharing**: Connect your home network with family members' networks
|
||||
- **Self-hosted Services**: Access Pi-hole, Nextcloud, and other self-hosted applications
|
||||
|
||||
## Getting Started
|
||||
|
||||
For connecting entire home networks (accessing devices that don't have NetBird installed), see the [Site-to-Site Connectivity Guide](/use-cases/site-to-site).
|
||||
|
||||
<Tiles
|
||||
title="Guides"
|
||||
items={[
|
||||
{
|
||||
href: '/use-cases/homelab/client-on-mikrotik-router',
|
||||
name: 'NetBird on MikroTik Router',
|
||||
description: 'Run NetBird directly on your MikroTik router for whole-network connectivity',
|
||||
},
|
||||
{
|
||||
href: '/manage/networks/use-cases/by-scenario/access-home-devices',
|
||||
name: 'Access Home Devices',
|
||||
description: 'Set up VPN-to-Site access to reach home network devices from anywhere',
|
||||
},
|
||||
{
|
||||
href: '/manage/network-routes/use-cases/site-to-site-home',
|
||||
name: 'Connect Home Networks',
|
||||
description: 'Link multiple home networks together using Site-to-Site routing',
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
## Recommended Setup
|
||||
|
||||
For most homelabbers, we recommend:
|
||||
|
||||
1. **Install NetBird on your devices** - Laptop, phone, and any servers you access directly
|
||||
2. **Set up a routing peer** - Use a Raspberry Pi, NAS with Docker, or dedicated device
|
||||
3. **Configure network access** - Use Networks (simpler) or Network Routes (more flexible)
|
||||
|
||||
| Scenario | Recommended Feature |
|
||||
|----------|---------------------|
|
||||
| Access home devices from laptop/phone | [Networks](/manage/networks) |
|
||||
| Connect two home networks | [Network Routes](/manage/network-routes) |
|
||||
| Run NetBird on router | [MikroTik Guide](/use-cases/homelab/client-on-mikrotik-router) |
|
||||
31
src/pages/use-cases/index.mdx
Normal file
31
src/pages/use-cases/index.mdx
Normal 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',
|
||||
},
|
||||
]}
|
||||
/>
|
||||
@@ -87,19 +87,19 @@ This section defines how terms are used in this guide and in NetBird.
|
||||
- **Overlay network and overlay IP**
|
||||
|
||||
The overlay network is a virtual network that NetBird creates on top of your existing infrastructure (a "network on top of a network"). For each NetBird tenant, the overlay is a random /16 CIDR block within the `100.64.0.0/10` range (a private IP range reserved for carrier-grade NAT). Each peer receives an overlay IP address from this /16 range for communication with other peers. Internal networks never see WireGuard encryption keys or tunnels directly. They only see overlay IPs or the routing peer's IP address, depending on whether masquerading is enabled (see Section 6.2).
|
||||
|
||||
|
||||
- **Network (NetBird object)**
|
||||
|
||||
A NetBird configuration object that maps your internal networks (such as VPCs, LANs, or office networks) and organizes routing peers and resources. [Networks](/manage/networks) group routing peers that provide access to the same internal subnets. Resources within Networks (IP addresses, ranges, or DNS names) serve as destinations in access policies. Networks replaced the older "Network Routes" concept starting with NetBird v0.35.0. Resources within a Network must be assigned to groups, and access is controlled through policies. Resources only become visible to peers after a policy explicitly grants access.
|
||||
|
||||
|
||||
- **Posture check**
|
||||
|
||||
A rule that evaluates device state, such as OS version, client version, geographic location, local network range, or running processes. Policies can require one or more posture checks to pass before allowing traffic.
|
||||
|
||||
|
||||
- **SIEM (Security Information and Event Management)**
|
||||
|
||||
A security platform that collects, analyzes, and stores security events from various sources. Examples include Datadog, AWS Firehose, and S3-based pipelines. SIEMs ingest NetBird events (traffic flows, policy changes, authentication events) for visibility, alerting, and compliance reporting.
|
||||
|
||||
|
||||
|
||||
### 1.2 Resources and scopes
|
||||
|
||||
@@ -110,7 +110,7 @@ This section defines how terms are used in this guide and in NetBird.
|
||||
- **Scope**
|
||||
|
||||
A bounded set of users, groups, peers, and resources that belong together operationally. Examples include `prod-orders-app`, `prod-admin-portal`, or `dev-tooling`.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -122,7 +122,7 @@ In this guide, "resources" refers to what you are protecting: applications, serv
|
||||
|
||||
### Phase 1: Select initial protected resources
|
||||
|
||||
Start with one or two concrete resources, not “our whole network”. For example:
|
||||
Start with one or two concrete resources, not "our whole network". For example:
|
||||
|
||||
- Customer-facing admin portal
|
||||
- Remote access to internal developer tools
|
||||
@@ -138,7 +138,7 @@ You are not configuring anything yet. You are deciding what to bring under Zero
|
||||
|
||||
**Outcome of Phase 1**
|
||||
|
||||
- One to two clearly named resource scopes (for example, `prod-order-api`, `prod-admin-portal`)
|
||||
- One to two clearly named resource scopes (for example, `prod-order-api`, `prod-admin-portal`)
|
||||
- A simple inventory of who needs access (users, service accounts) and what they access (hosts, services, subnets) per scope
|
||||
- A named owner for each resource who can confirm whether the rollout broke anything
|
||||
|
||||
@@ -177,7 +177,7 @@ Now decide how access should look under a Zero Trust posture.
|
||||
|
||||
For each flow identified in Phase 2:
|
||||
|
||||
- Is this flow required, or is it legacy or “nice to have”?
|
||||
- Is this flow required, or is it legacy or "nice to have"?
|
||||
- Which side should initiate the connection?
|
||||
- Which protocol and port are actually required?
|
||||
- Should the flow be allowed, restricted to a smaller group, or blocked?
|
||||
@@ -212,7 +212,7 @@ Where to do this: [Integrations → Identity Provider Sync](/manage/team/idp-syn
|
||||
|
||||
Map:
|
||||
|
||||
- Your IdP groups (for example `DevOps`, `Support`, `Finance`) to NetBird groups where it makes sense
|
||||
- Your IdP groups (for example `DevOps`, `Support`, `Finance`) to NetBird groups where it makes sense
|
||||
- A small pilot set of users (for example DevOps and the owners of your Phase 1 resources)
|
||||
|
||||
Do not expose production Networks yet. At this stage, you only need authenticated identities and a few test peers.
|
||||
@@ -240,20 +240,20 @@ Where to manage groups: [Access Control → Groups](/manage/access-control).
|
||||
|
||||
Recommended naming:
|
||||
|
||||
- `peer-<team>-<env>` for user devices
|
||||
- `peer-devops-prod`, `peer-support`, `peer-contractors`
|
||||
- `svc-<app>-<tier>-<env>` for services and hosts
|
||||
- `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod`
|
||||
- `net-<location>-<purpose>` for routed Networks
|
||||
- `net-aws-euc1-prod`, `net-dc-dc1-lan`
|
||||
- `peer-<team>-<env>` for user devices
|
||||
- `peer-devops-prod`, `peer-support`, `peer-contractors`
|
||||
- `svc-<app>-<tier>-<env>` for services and hosts
|
||||
- `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod`
|
||||
- `net-<location>-<purpose>` for routed Networks
|
||||
- `net-aws-euc1-prod`, `net-dc-dc1-lan`
|
||||
|
||||
Use suffixes for environment:
|
||||
|
||||
- `dev`, `stage`, `prod`
|
||||
- `dev`, `stage`, `prod`
|
||||
|
||||
The exact scheme is up to you. The important point is to pick a convention and stick with it. Without one, the group and policy list will become unmanageable.
|
||||
|
||||
See [Appendix A](#appendix-a-naming-and-object-cheat-sheet) for a quick naming cheat sheet.
|
||||
See [Appendix A](#appendix-a-naming-and-object-cheat-sheet) for a quick naming cheat sheet.
|
||||
|
||||
### 3.3 Setup keys for automation and service accounts
|
||||
|
||||
@@ -263,13 +263,13 @@ See [Appendix A](#appendix-a-naming-and-object-cheat-sheet) for a quick naming
|
||||
- Servers without human login (CI runners, Kubernetes nodes, headless Linux boxes)
|
||||
- Automated deployment through MDM, RMM, or configuration management tools
|
||||
|
||||
Where to manage them: Setup Keys.
|
||||
Where to manage them: Setup Keys.
|
||||
|
||||
Guidelines:
|
||||
|
||||
- Create scoped keys per environment:
|
||||
- `setup-prod-servers` that auto-assigns `svc-*-prod` groups
|
||||
- `setup-stage-servers` that auto-assigns `svc-*-stage` groups
|
||||
- `setup-prod-servers` that auto-assigns `svc-*-prod` groups
|
||||
- `setup-stage-servers` that auto-assigns `svc-*-stage` groups
|
||||
- Prefer one-off keys for bulk enrollment and delete them after use.
|
||||
- Restrict who can view or create setup keys.
|
||||
|
||||
@@ -326,7 +326,7 @@ NetBird posture checks evaluate device state before allowing traffic. They can v
|
||||
- Network CIDR the peer is connected from
|
||||
- Presence of specific processes
|
||||
|
||||
Where to configure them: [Access Control → Posture Checks](/manage/access-control/posture-checks).
|
||||
Where to configure them: [Access Control → Posture Checks](/manage/access-control/posture-checks).
|
||||
|
||||
<Warning>
|
||||
Posture checks are not a security boundary against compromised endpoints. They validate configuration and policy compliance, not trustworthiness. An attacker with admin rights on a device can bypass or spoof them. Design your policies assuming posture checks can be evaded.
|
||||
@@ -335,7 +335,7 @@ Posture checks are not a security boundary against compromised endpoints. They v
|
||||
Recommended posture checks per policy:
|
||||
|
||||
- **Client version**
|
||||
- Enforce minimum NetBird version (for example `>= 0.45.0`) for critical access.
|
||||
- Enforce minimum NetBird version (for example `>= 0.45.0`) for critical access.
|
||||
- **OS and version**
|
||||
- Block unsupported or unpatched OS versions on production access.
|
||||
- **Geolocation or peer network range**
|
||||
@@ -404,7 +404,7 @@ Resource groups:
|
||||
- `svc-orders-app-prod`
|
||||
- `svc-orders-db-prod`
|
||||
- `svc-monitoring`
|
||||
- `svc-dns-prod` (or a Network resource containing the DNS IPs)
|
||||
- `svc-dns-prod` (or a Network resource containing the DNS IPs)
|
||||
|
||||
Diagram:
|
||||
|
||||
@@ -436,20 +436,20 @@ All Peers ──UDP,TCP/53──► Internal DNS (svc-dns-prod)
|
||||
**Policies**
|
||||
|
||||
1. **Users to web**
|
||||
- Source: `peer-devops-prod`, `peer-support`
|
||||
- Destination: `svc-orders-web-prod`
|
||||
- Source: `peer-devops-prod`, `peer-support`
|
||||
- Destination: `svc-orders-web-prod`
|
||||
- Protocol: TCP, Port: 443
|
||||
2. **Web to app**
|
||||
- Source: `svc-orders-web-prod`
|
||||
- Destination: `svc-orders-app-prod`
|
||||
- Source: `svc-orders-web-prod`
|
||||
- Destination: `svc-orders-app-prod`
|
||||
- Protocol: TCP, Port: 8443
|
||||
3. **App to DB**
|
||||
- Source: `svc-orders-app-prod`
|
||||
- Destination: `svc-orders-db-prod`
|
||||
- Source: `svc-orders-app-prod`
|
||||
- Destination: `svc-orders-db-prod`
|
||||
- Protocol: TCP, Port: 5432
|
||||
4. **Monitoring**
|
||||
- Source: `svc-monitoring`
|
||||
- Destination: `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod`
|
||||
- Source: `svc-monitoring`
|
||||
- Destination: `svc-orders-web-prod`, `svc-orders-app-prod`, `svc-orders-db-prod`
|
||||
- Protocol: TCP, Ports: 9100 and 9200
|
||||
5. **DNS (critical, often forgotten)**
|
||||
- Source: all peer groups that use this environment (`peer-devops-prod`, `peer-support`, `svc-*`)
|
||||
@@ -478,7 +478,7 @@ The example above uses group names for readability. The actual API requires grou
|
||||
|
||||
**Deliberately not allowed**
|
||||
|
||||
- Any `peer-*` group to the database directly.
|
||||
- Any `peer-*` group to the database directly.
|
||||
- Database initiating connections to app or web tiers.
|
||||
- Support laptops directly to the DB or app backend.
|
||||
|
||||
@@ -500,15 +500,15 @@ Broken DNS is the most common cause of "NetBird is broken" complaints. For every
|
||||
Use routing peers and Networks when you need to reach private subnets (LAN, VPC, on-premises) rather than only NetBird overlay peers.
|
||||
|
||||
<Warning>
|
||||
**Network Routes vs Networks:** Legacy [Network Routes](/manage/network-routes/routing-traffic-to-private-networks) bypass Access Control policies by default unless [Access Control Groups are explicitly configured](/manage/network-routes/configuring-routes-with-access-control). The newer [Networks](/manage/networks) feature (v0.35.0+) handles this automatically—resources only become visible to peers after a policy explicitly grants access. For Zero Trust implementations, we recommend using Networks instead of legacy Network Routes.
|
||||
**Network Routes vs Networks:** Legacy [Network Routes](/manage/network-routes) bypass Access Control policies by default unless [Access Control Groups are explicitly configured](/manage/network-routes/use-cases/by-configuration/access-control). The newer [Networks](/manage/networks) feature (v0.35.0+) handles this automatically—resources only become visible to peers after a policy explicitly grants access. For Zero Trust implementations, we recommend using Networks instead of legacy Network Routes.
|
||||
</Warning>
|
||||
|
||||
### 5.1 Requirements for a routing peer
|
||||
|
||||
A routing peer is a NetBird peer that:
|
||||
|
||||
- Has network access to one or more internal subnets (for example `10.10.0.0/16`)
|
||||
- Is selected as a routing peer in a [Network](/manage/networks) or [Network Route](/manage/network-routes/routing-traffic-to-private-networks) configuration
|
||||
- Has network access to one or more internal subnets (for example `10.10.0.0/16`)
|
||||
- Is selected as a routing peer in a [Network](/manage/networks) or [Network Route](/manage/network-routes) configuration
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/networks/netbird-network-routes.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
@@ -539,7 +539,7 @@ General rules:
|
||||
- Create a Network that includes:
|
||||
- IP ranges (for example `10.10.0.0/16` - the `/16` means the first 16 bits are the network portion, allowing 65,536 IP addresses)
|
||||
- DNS resources (for example `db.internal.example.com` for a specific hostname, or `*.corp.internal` for all subdomains) where appropriate
|
||||
- Add a DNS server in NetBird with the right match domain (for example `corp.internal`) under [DNS → Nameservers](/manage/dns/nameserver-groups).
|
||||
- Add a DNS server in NetBird with the right match domain (for example `corp.internal`) under [DNS → Nameservers](/manage/dns/nameserver-groups).
|
||||
- Add explicit policies allowing peers to reach the DNS servers themselves (UDP and TCP 53 to the resolver IPs).
|
||||
|
||||
<Note>
|
||||
@@ -573,11 +573,11 @@ Practical recommendations:
|
||||
- Backup or cross-region routing peer: metric 200
|
||||
- For critical Networks, run at least two routing peers in separate failure domains (different zones, racks, or hosts).
|
||||
- Monitor routing peers with your existing monitoring plus NetBird events. If one fails, verify that clients start using the other peers.
|
||||
- Verify HA behavior by simulating a failure and checking route selection with `netbird status -d` and test traffic.
|
||||
- Verify HA behavior by simulating a failure and checking route selection with `netbird status -d` and test traffic.
|
||||
|
||||
The same pattern applies to exit nodes that provide default routes for internet-bound traffic.
|
||||
|
||||
See [Appendix B](#appendix-b-quick-reference-and-commands) for a quick HA checklist.
|
||||
See [Appendix B](#appendix-b-quick-reference-and-commands) for a quick HA checklist.
|
||||
|
||||
### 6.2 Masquerading versus return routes
|
||||
|
||||
@@ -588,29 +588,29 @@ Masquerading (also called NAT masquerading or source NAT) controls how routed tr
|
||||
- Internal firewall log:
|
||||
- `10.10.0.5 → 10.10.1.10:5432`
|
||||
|
||||
This usually works out of the box because internal firewalls already trust the routing peer’s subnet. NetBird enables masquerading by default.
|
||||
This usually works out of the box because internal firewalls already trust the routing peer's subnet. NetBird enables masquerading by default.
|
||||
|
||||
**With masquerading disabled**, internal systems see the original NetBird overlay IP:
|
||||
|
||||
- Internal firewall log:
|
||||
- `100.64.1.45 → 10.10.1.10:5432`
|
||||
- where `100.64.1.45` is a NetBird overlay address (always within `100.64.0.0/10`)
|
||||
- where `100.64.1.45` is a NetBird overlay address (always within `100.64.0.0/10`)
|
||||
|
||||
To make non-masqueraded traffic work you must:
|
||||
|
||||
1. Add a route for the overlay range in your internal router or firewall, pointing to the routing peer’s internal IP.
|
||||
1. Add a route for the overlay range in your internal router or firewall, pointing to the routing peer's internal IP.
|
||||
2. Allow that traffic in internal firewall rules.
|
||||
|
||||
Examples for non-masquerade mode:
|
||||
|
||||
- **Linux router:**
|
||||
|
||||
|
||||
```bash
|
||||
# Add a route: send all traffic destined for 100.64.0.0/10
|
||||
# Add a route: send all traffic destined for 100.64.0.0/10
|
||||
# through the gateway at 10.10.0.5 (the routing peer's internal IP)
|
||||
ip route add 100.64.0.0/10 via 10.10.0.5
|
||||
```
|
||||
|
||||
|
||||
- **AWS VPC route table:**
|
||||
- Destination: `100.64.0.0/10` (the NetBird overlay range)
|
||||
- Target: ENI (Elastic Network Interface) of the routing peer instance (the network interface attached to your EC2 instance running the routing peer)
|
||||
@@ -635,13 +635,13 @@ If you need real client IP visibility for logging while passing traffic through
|
||||
|
||||
At larger scale, you will care about:
|
||||
|
||||
- Overlapping routes to different environments (for example, multiple `172.17.0.0/16` networks)
|
||||
- Overlapping routes to different environments (for example, multiple `172.17.0.0/16` networks)
|
||||
- Connection overhead for many peers
|
||||
|
||||
NetBird has route selection tools and an experimental lazy connections feature for large networks. In practice:
|
||||
|
||||
- Use network/route selection to avoid accidental routing into the wrong VPC or site when CIDRs overlap. You can do this in the systray application or via the command line.
|
||||
- [Lazy connections](/manage/peers/lazy-connections) reduce CPU and battery usage on devices by establishing tunnels only when traffic is sent, rather than maintaining keep-alive with every peer in the mesh. Note that lazy connections is an experimental feature that requires NetBird client version 0.50.1 or later and does NOT support accessing resources through routing peers (Networks). Review the current scaling guidance and lazy connections documentation before rolling out to thousands of peers.
|
||||
- [Lazy connections](/manage/peers/lazy-connection) reduce CPU and battery usage on devices by establishing tunnels only when traffic is sent, rather than maintaining keep-alive with every peer in the mesh. Note that lazy connections is an experimental feature that requires NetBird client version 0.50.1 or later and does NOT support accessing resources through routing peers (Networks). Review the current scaling guidance and lazy connections documentation before rolling out to thousands of peers.
|
||||
|
||||
<Note>
|
||||
**Verification checklist:**
|
||||
@@ -737,7 +737,7 @@ For each pattern:
|
||||
1. Apply it to dev first:
|
||||
- Use the same group and policy structure (`peer-devops-dev → svc-orders-web-dev`, etc.).
|
||||
2. Mirror to staging, refine there, then apply to prod.
|
||||
3. Keep group and policy names aligned across environments, only changing the `dev`, `stage`, `prod` suffix.
|
||||
3. Keep group and policy names aligned across environments, only changing the `dev`, `stage`, `prod` suffix.
|
||||
|
||||
This keeps cognitive load low and reduces surprises in production.
|
||||
|
||||
@@ -747,9 +747,9 @@ When you move from broad access to strict Zero Trust, have an explicit rollback
|
||||
|
||||
- Maintain one "break glass" access method (for example, a physical console or a separate VPN/bastion) that does *not* rely on NetBird during the initial setup phase.
|
||||
- Keep a known good emergency broad policy, for example:
|
||||
|
||||
|
||||
`peer-devops-prod → net-aws-euc1-prod [ALL]` but keep it disabled.
|
||||
|
||||
|
||||
- If production breaks and you cannot immediately identify the cause:
|
||||
1. Temporarily enable the emergency policy.
|
||||
2. Confirm that service has recovered.
|
||||
@@ -768,18 +768,18 @@ To keep the system healthy over time:
|
||||
|
||||
- Enforce group and policy naming consistently.
|
||||
- Example policy name pattern:
|
||||
|
||||
|
||||
`peer-devops-prod → svc-orders-db-prod [TCP/5432]`
|
||||
|
||||
|
||||
- Use policy descriptions to record the business justification and owner:
|
||||
- “Orders app backend to DB, owned by App Team X”
|
||||
- "Orders app backend to DB, owned by App Team X"
|
||||
- Periodically review:
|
||||
- Unused groups
|
||||
- Redundant policies
|
||||
- Peers that have not connected recently
|
||||
- Keep an eye on:
|
||||
- NetBird client versions (enforce minimum via posture checks)
|
||||
- Routing peers’ capacity and health
|
||||
- Routing peers' capacity and health
|
||||
|
||||
<Note>
|
||||
**Verification checklist:**
|
||||
@@ -794,7 +794,7 @@ To keep the system healthy over time:
|
||||
|
||||
This section provides practical checks and commands you can run on peers.
|
||||
|
||||
### 9.1 “Policy exists but connection is still blocked”
|
||||
### 9.1 "Policy exists but connection is still blocked"
|
||||
|
||||
Most often:
|
||||
|
||||
@@ -806,9 +806,9 @@ Most often:
|
||||
|
||||
What to do:
|
||||
|
||||
- Check the policy and its posture checks in **Access Control → Policies**.
|
||||
- Confirm the peer’s group membership in the dashboard under **Peers**.
|
||||
- Look at Traffic Events for explicit “blocked due to posture” or “no matching policy” entries.
|
||||
- Check the policy and its posture checks in **Access Control → Policies**.
|
||||
- Confirm the peer's group membership in the dashboard under **Peers**.
|
||||
- Look at Traffic Events for explicit "blocked due to posture" or "no matching policy" entries.
|
||||
|
||||
Useful commands on the peer:
|
||||
|
||||
@@ -817,7 +817,7 @@ Useful commands on the peer:
|
||||
netbird status -d
|
||||
```
|
||||
|
||||
### 9.2 “Connection works sometimes”
|
||||
### 9.2 "Connection works sometimes"
|
||||
|
||||
Common causes:
|
||||
|
||||
@@ -830,7 +830,7 @@ Common causes:
|
||||
|
||||
What to do:
|
||||
|
||||
- Check routing peers’ health and logs.
|
||||
- Check routing peers' health and logs.
|
||||
- Use network listing and selection on the client to see which routes are active:
|
||||
|
||||
```bash
|
||||
@@ -852,9 +852,9 @@ What to do:
|
||||
netbird routes deselect "route_id"
|
||||
netbird routes select "route_id"
|
||||
```
|
||||
|
||||
|
||||
### 9.3 “After deleting the Default policy, nothing works”
|
||||
|
||||
### 9.3 "After deleting the Default policy, nothing works"
|
||||
|
||||
Cause:
|
||||
|
||||
@@ -863,7 +863,7 @@ Cause:
|
||||
Fix:
|
||||
|
||||
- Create a broad but scoped policy:
|
||||
- For example `peer-devops-prod → svc-orders-*` with required ports.
|
||||
- For example `peer-devops-prod → svc-orders-*` with required ports.
|
||||
- Test that critical access works.
|
||||
- Only then delete the Default policy and tighten further.
|
||||
|
||||
@@ -888,16 +888,16 @@ Fix:
|
||||
- Ports: UDP and TCP 53
|
||||
- Verify DNS routing configuration in Networks and match domains.
|
||||
- From a client, run DNS lookup commands and compare behavior with your expectations:
|
||||
|
||||
|
||||
```bash
|
||||
# nslookup: Basic DNS lookup tool (works on Windows, Linux, macOS)
|
||||
nslookup db.internal.example.com
|
||||
|
||||
|
||||
# dig: More detailed DNS query tool (Linux/macOS, or install on Windows)
|
||||
# The @10.10.0.10 specifies which DNS server to query
|
||||
dig @10.10.0.10 db.internal.example.com
|
||||
```
|
||||
|
||||
|
||||
- **Linux:** `resolvectl status` (systemd-resolved command to see if the NetBird interface has the right DNS domains configured)
|
||||
- **Windows:** `Get-DnsClientNrptPolicy` (PowerShell command to see if Name Resolution Policy Table rules are active; these tell Windows which DNS server to use for specific domains)
|
||||
|
||||
@@ -1003,4 +1003,4 @@ netbird routes ls
|
||||
- At least two routing peers per critical NetBird Network.
|
||||
- Different failure domains (AZs, racks, hosts).
|
||||
- Primary metric 100, backup metric 200.
|
||||
- Monitor both NetBird health and OS-level metrics.
|
||||
- Monitor both NetBird health and OS-level metrics.
|
||||
53
src/pages/use-cases/security/index.mdx
Normal file
53
src/pages/use-cases/security/index.mdx
Normal 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
|
||||
@@ -1,529 +0,0 @@
|
||||
import {Note} from "@/components/mdx";
|
||||
|
||||
# Setting up Site-to-Site/VPN access over NetBird
|
||||
|
||||
This page explains the characteristics of **Site-to-Site**, **Site-to-VPN**, and **VPN-to-Site** setups and how to configure them with NetBird. We'll start by defining key terminology and reviewing the available setup options before walking through concrete implementation examples.
|
||||
|
||||
## Overview
|
||||
|
||||
A **Site** in the context of this guide refers to any single network or subnet that is typically not exposed to the Internet nor directly accessible from other Sites.
|
||||
|
||||
Examples include:
|
||||
- Home or office networks
|
||||
- Internal networks at cloud providers or datacenters
|
||||
- Restricted VLANs
|
||||
- Internal container or VM networking ranges
|
||||
- Other VPN networking ranges
|
||||
- Another NetBird organization's resource ranges
|
||||
|
||||
A **device** in this guide refers to any physical computing device (PC, laptop, phone, datacenter server, etc.) or virtual computing device (VM, container, load balancer, etc.). A **device** can be either **clientless** or a **Peer**.
|
||||
|
||||
**Clientless devices** are **devices** that don't run a NetBird client themselves (they are not **Peers**).
|
||||
|
||||
A **Peer** is a **device** running the NetBird client directly on it:
|
||||
|
||||
- A laptop running the NetBird client directly on the system is a **Peer**
|
||||
- A laptop running the NetBird client in a container using default (internal) networking mode is not a **Peer** - the container itself is the **Peer** in this case
|
||||
- A laptop running the NetBird client in a container using host-networking mode could be considered a **Peer**
|
||||
|
||||
Other **bold** terms refer to NetBird-specific features or configuration options:
|
||||
**Network Route**, **Network**, **Resource**, **Access Control Policy**, **ACL Group**.
|
||||
|
||||
Non-bold terms refer to context-specific concepts:
|
||||
- route: a generic term for an operating system network route
|
||||
- resource: a generic term for software or a machine listening on a specific IP address and port
|
||||
|
||||
|
||||
### Site-to-Site
|
||||
|
||||
A **Site-to-Site** setup enables **clientless** devices from two or more **Sites** to reach each other. Each **Site** requires at least one **Peer** to route traffic over the VPN, but other on-site devices don't need to run (or even be aware of) the VPN software.
|
||||
|
||||
The **clientless** devices must be configured to route the remote **Site**'s IP address range through the local **Peer**. You can configure this manually using commands and persist it with your operating system's native tools, or automate it using DHCP route advertisements or device management software.
|
||||
|
||||
The remote **Peer** must also know how to route responses back to the local **Site**. Typically, you'll need to set up a pair of routes to enable site-to-site access:
|
||||
|
||||
1. A route from the local **Peer** to the remote **Site** for outbound traffic
|
||||
2. A reverse route from the remote **Site** to the local **Peer** for return traffic
|
||||
|
||||
### Site-to-VPN
|
||||
|
||||
A **Site-to-VPN** setup enables a **clientless** device to reach **Peers** in the VPN network.
|
||||
|
||||
You can think of this as the 'local half' of a **Site-to-Site** setup. The **clientless** devices need to be configured to reach the VPN network, but typically no additional setup is required to route responses back from the VPN.
|
||||
|
||||
### VPN-to-Site
|
||||
|
||||
A **VPN-to-Site** setup enables a **Peer** to reach **clientless** devices on a network external to the VPN itself. This is the default mode of operation for most VPNs, but we're including it here for completeness. In NetBird, this scenario is achieved using **Networks** or the older **Network Routes** feature.
|
||||
|
||||
## NetBird implementations overview
|
||||
|
||||
While NetBird doesn't yet have explicit support for Site-to-VPN or Site-to-Site scenarios, you can achieve them using one of the following approaches, depending on your requirements:
|
||||
|
||||
1. Using a **Network Route** for each **Site** with Masquerade (with or without **ACL Groups**)
|
||||
2. Using a **Network Route** for each **Site** without Masquerade (without **ACL Groups**)
|
||||
3. Using a **Network** **Resource** with Masquerade
|
||||
|
||||
All of these options require the following:
|
||||
|
||||
- You must manually configure **clientless** devices to route traffic appropriately
|
||||
- The easiest method is using device management software or DHCP route advertisements from your local router
|
||||
- You can only have one routing **Peer** per **Site**
|
||||
- Routing traffic correctly and reliably through multiple routing devices is extremely complex (if not impossible), so multi-peer routing is out of scope for this guide
|
||||
|
||||
You'll need to consider one of two primary tradeoffs:
|
||||
|
||||
1. **Forfeit source IP information to preserve basic access control** - Use Masquerade to maintain a basic form of access control
|
||||
- Masqueraded traffic can only be controlled by **Access Control Policies** attached to the **Routing Peer**, with no way to restrict access for specific **clientless** devices
|
||||
- You can still create coarse-grained access controls by setting up multiple **Network** **Routing Peers** for different purposes
|
||||
2. **Forfeit access control to preserve source IP information** - Skip Masquerade to keep the original source IP addresses (this allows any traffic through)
|
||||
- This approach may be required for specific networking setups
|
||||
|
||||
## Prerequisites and initial assumptions
|
||||
|
||||
For this guide, we'll use four `libvirt` Ubuntu virtual machines, split into two separate **Sites** (networks) as follows:
|
||||
```shell
|
||||
root@vms ~# virsh net-dhcp-leases local-site
|
||||
... IP address Hostname ...
|
||||
... ---------------------------------...
|
||||
... 192.168.122.144/24 local-nb-01 ...
|
||||
... 192.168.122.65/24 local-01 ...
|
||||
|
||||
root@vms ~# virsh net-dhcp-leases remote-site
|
||||
... IP address Hostname ...
|
||||
...------------------------------------...
|
||||
... 192.168.100.189/24 remote-nb-01 ...
|
||||
... 192.168.100.215/24 remote-01 ...
|
||||
```
|
||||
|
||||
All VMs can be reached from the host `vms`:
|
||||
```shell
|
||||
kdn@pc ~> ssh vms.lan ping -c1 192.168.100.189
|
||||
PING 192.168.100.189 (192.168.100.189) 56(84) bytes of data.
|
||||
64 bytes from 192.168.100.189: icmp_seq=1 ttl=64 time=0.154 ms
|
||||
|
||||
--- 192.168.100.189 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.154/0.154/0.154/0.000 ms
|
||||
kdn@pc ~> ssh vms.lan ping -c1 192.168.122.144
|
||||
PING 192.168.122.144 (192.168.122.144) 56(84) bytes of data.
|
||||
64 bytes from 192.168.122.144: icmp_seq=1 ttl=64 time=0.162 ms
|
||||
|
||||
--- 192.168.122.144 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.162/0.162/0.162/0.000 ms
|
||||
```
|
||||
|
||||
Both **Sites** can reach the Internet, and devices within each site can communicate with each other, but they cannot directly reach devices on the other **Site**:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh 192.168.100.189 -J vms.lan ping -c1 192.168.122.144
|
||||
PING 192.168.122.144 (192.168.122.144) 56(84) bytes of data.
|
||||
From 192.168.122.1 icmp_seq=1 Destination Port Unreachable
|
||||
|
||||
--- 192.168.122.144 ping statistics ---
|
||||
1 packets transmitted, 0 received, +1 errors, 100% packet loss, time 0ms
|
||||
|
||||
kdn@pc ~ [1]>
|
||||
```
|
||||
|
||||
The `local-site` network VMs are also directly attached to my LAN. The `remote-site` VMs are only attached to their network, so we'll reference them by IP address and use `vms` as an SSH jump host.
|
||||
|
||||
The devices `local-01` and `remote-01` are **clientless** for the purposes of this guide. Additionally, `remote-01` runs CoreDNS, which responds with `OK` to `http://192.168.100.10/health`.
|
||||
|
||||
The **Peers** are configured as follows:
|
||||
|
||||
| dns_label | netbird_ip | groups |
|
||||
|----------------|------------------|---------------------|
|
||||
| `local-nb-01` | `100.83.73.97` | `s2s: local peers` |
|
||||
| `remote-nb-01` | `100.83.136.209` | `s2s: remote peers` |
|
||||
|
||||
We'll grant access between:
|
||||
- `local-01` running on the `local-site` through **Routing Peer** `local-nb-01` using **Group** `s2s: local peers`
|
||||
- `remote-01` running on the `remote-site` through **Routing Peer** `remote-nb-01` using **Group** `s2s: remote peers`
|
||||
|
||||
<Note>
|
||||
This guide assumes the use of a Linux terminal, but the commands used are relatively simple and ubiquitous
|
||||
and should easily translate to other operating systems.
|
||||
</Note>
|
||||
|
||||
## Site-to-Site with Masquerade
|
||||
|
||||
The **Masquerade** option means that packets forwarded by a **Routing Peer** will:
|
||||
- Have their source IP address replaced with the **Routing Peer**'s NetBird IP address when leaving the **Site**
|
||||
- Be translated back from the **Routing Peer**'s IP address to the local **Site**'s IP address when returning
|
||||
|
||||
This is currently the easiest way to configure routing because it uses existing **Peer** forwarding and policy enforcement facilities.
|
||||
|
||||
The main downsides of this approach are:
|
||||
|
||||
- Loss of source IP addressing information, which may be required for auditing purposes
|
||||
- Very coarse-grained access control limited to the **Routing Peer**'s permissions
|
||||
|
||||
### Site-to-Site using Network Routes with Masquerade and without Access Control
|
||||
|
||||
In this section, we'll set up Site-to-Site **Network Routes** with Masquerade but without access control. We'll start by configuring the required **Network Routes** and **Access Control Policies**, then manually configure a **clientless** device to route traffic through the local **Routing Peer**. Finally, we'll verify that everything works as expected.
|
||||
|
||||
#### Setting up a simple VPN-to-Site access
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/routes-noacl-vpn-to-site.png" alt="routes-noacl-vpn-to-site"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
and an **Access Control Policy** that establishes connectivity between the (future) **Routing Peers**:
|
||||
|
||||
<p id="unidirectional-routing-peer-policy">
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-ping-to-local-only.png" alt="acl-ping-to-local-only"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
It doesn't matter that this is a unidirectional ICMP rule in the wrong direction - **Network Routes** are activated as soon as any **Access Control Policy** establishes connectivity to the **Routing Peer**, as explained in [Network Routes caveats](/manage/network-routes/routing-traffic-to-private-networks#network-routes-caveats).
|
||||
</Note>
|
||||
|
||||
We can verify that the local **Peer** can reach the `remote-site` using both `ping` and `curl`:
|
||||
```shell
|
||||
kdn@pc ~> ssh local-nb-01.lan "netbird networks ls"
|
||||
Available Networks:
|
||||
|
||||
- ID: network-route-srvs-site
|
||||
Network: 192.168.122.0/24
|
||||
Status: Selected
|
||||
|
||||
kdn@pc ~> ssh local-nb-01.lan "ping -c1 192.168.100.10"
|
||||
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
|
||||
64 bytes from 192.168.100.10: icmp_seq=1 ttl=63 time=0.475 ms
|
||||
|
||||
--- 192.168.100.10 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.475/0.475/0.475/0.000 ms
|
||||
|
||||
kdn@pc ~> ssh local-nb-01.lan "curl 192.168.100.10/health; echo"
|
||||
OK
|
||||
```
|
||||
|
||||
#### Setting up the clientless device
|
||||
|
||||
Now we'll manually configure the **clientless** `local-01` device to route traffic to the `remote-site` through `local-nb-01`'s local IP address `192.168.122.144`:
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
|
||||
kdn@pc ~ [1]> ssh local-01.lan "sudo ip route add 192.168.100.0/24 via 192.168.122.144"
|
||||
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
|
||||
192.168.100.0/24 via 192.168.122.144 dev enp7s0
|
||||
```
|
||||
|
||||
<Note>
|
||||
This step is better handled via a DHCP server's route advertisement, but that's outside the scope of this guide.
|
||||
</Note>
|
||||
|
||||
This won't work yet from a **clientless** device because we're missing the other half of the connection needed to route responses back:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
|
||||
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
|
||||
|
||||
--- 192.168.100.10 ping statistics ---
|
||||
1 packets transmitted, 0 received, 100% packet loss, time 0ms
|
||||
|
||||
kdn@pc ~ [1]>
|
||||
```
|
||||
|
||||
#### Closing the loop with a reverse Network Route
|
||||
|
||||
Now we can complete the setup by enabling the reverse **Network Route** (from `remote-site` to `local-site`):
|
||||
|
||||
<p id="routes-noacl-site-to-site">
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/routes-noacl-site-to-site.png" alt="routes-noacl-site-to-site"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
Let's verify it's working for both ICMP and HTTP:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
|
||||
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
|
||||
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.867 ms
|
||||
|
||||
--- 192.168.100.10 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.867/0.867/0.867/0.000 ms
|
||||
kdn@pc ~> ssh local-01.lan "curl 192.168.100.10/health; echo"
|
||||
OK
|
||||
```
|
||||
|
||||
#### Confirming remote Site access to the local Site
|
||||
|
||||
Let's fetch the `local-01` IP address, perform the reverse setup on `remote-01`, and test access back from the `remote-site`:
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "ip a | grep 192.168.122"
|
||||
inet 192.168.122.65/24 metric 100 brd 192.168.122.255 scope global dynamic enp7s0
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
|
||||
kdn@pc ~ [1]> ssh 192.168.100.215 -J vms.lan "sudo ip route add 192.168.122.0/24 via 192.168.100.189"
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
|
||||
192.168.122.0/24 via 192.168.100.189 dev enp7s0
|
||||
kdn@pc ~> ssh 192.168.100.189 -J vms.lan "ping -c1 192.168.122.65"
|
||||
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
|
||||
64 bytes from 192.168.122.65: icmp_seq=1 ttl=63 time=0.523 ms
|
||||
|
||||
--- 192.168.122.65 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.523/0.523/0.523/0.000 ms
|
||||
kdn@pc ~>
|
||||
```
|
||||
|
||||
### Site-to-Site using Network Routes with Masquerade and Access Control
|
||||
|
||||
We'll start by picking up where we left off in the previous example: [Site-to-Site using Network Routes with Masquerade and without Access Control](#site-to-site-using-network-routes-with-masquerade-and-without-access-control). Now we can restrict access to the remote **Site**'s resources to ICMP only and verify the restrictions are enforced. We'll set up and verify unidirectional access first, then enable bidirectional access.
|
||||
|
||||
First, let's add dedicated `* resources` Access Control Groups to the **Network Routes**:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/routes-with-acl-site-to-site.png" alt="routes-with-acl-site-to-site"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
Note that we're using a different Group to grant access to the **Network Route** than the one used for **Routing Peers**. Using the **Routing Peer**'s Group in **ACL Groups** would also work and be slightly simpler to manage.
|
||||
|
||||
<Note>
|
||||
Granting access only to the **Network Route**'s **ACL Groups** still requires at least one **Access Control Policy** that grants any kind of access directly to the **Routing Peer**. This makes the **Network Route** visible to the **Peer** using the route.
|
||||
|
||||
This is in stark contrast to Network Resources, where:
|
||||
- **Resource** **Groups** control both access and discovery in a single step
|
||||
- **Routing Peer** permissions aren't required unless you want to access its LAN IPs
|
||||
</Note>
|
||||
|
||||
Next, let's set up **Access Control Policies** for one-way access from `local-site` to `remote-site`:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-unidirectional-site-to-site.png" alt="acl-unidirectional-site-to-site"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
Now we can verify that `ping` (ICMP) is allowed while `curl` (HTTP) is blocked in the local-to-remote direction:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
|
||||
192.168.100.0/24 via 192.168.122.144 dev enp7s0
|
||||
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
|
||||
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
|
||||
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.738 ms
|
||||
|
||||
--- 192.168.100.10 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.738/0.738/0.738/0.000 ms
|
||||
kdn@pc ~> ssh local-01.lan "curl -sv -m 2 192.168.100.10/health; echo"
|
||||
* Trying 192.168.100.10:80...
|
||||
|
||||
* Connection timed out after 2002 milliseconds
|
||||
* closing connection #0
|
||||
```
|
||||
|
||||
Let's also verify that reverse access (from `remote-site` to `local-site`) isn't possible yet:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
|
||||
192.168.122.0/24 via 192.168.100.189 dev enp7s0
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ping -c1 192.168.122.65"
|
||||
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
|
||||
|
||||
--- 192.168.122.65 ping statistics ---
|
||||
1 packets transmitted, 0 received, 100% packet loss, time 0ms
|
||||
|
||||
kdn@pc ~ [1]>
|
||||
```
|
||||
|
||||
Finally, let's enable the `s2s: ping to local resources` **Access Control Policy**:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-bidirectional-site-to-site-minus-routing-peer.png" alt="acl-bidirectional-site-to-site-minus-routing-peer"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
We don't need to enable the reverse ICMP policy to the **Routing Peer**, as explained [previously](#unidirectional-routing-peer-policy).
|
||||
</Note>
|
||||
|
||||
Now let's verify that remote-to-local access is working:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
|
||||
192.168.122.0/24 via 192.168.100.189 dev enp7s0
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ping -c1 192.168.122.65"
|
||||
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
|
||||
64 bytes from 192.168.122.65: icmp_seq=1 ttl=62 time=0.755 ms
|
||||
|
||||
--- 192.168.122.65 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.755/0.755/0.755/0.000 ms
|
||||
kdn@pc ~>
|
||||
```
|
||||
|
||||
### Site-to-Site using Network Resources with Masquerade
|
||||
|
||||
In this section, we'll replicate the previous [Site-to-Site using Network Routes with Masquerade and Access Control](#site-to-site-using-network-routes-with-masquerade-and-access-control) configuration using **Network Resources** and verify that it works. We'll start by setting up a **Network** for each **Site**, enable the minimum set of **Access Control Policies** required (which already exist), and finally verify that access control is working as expected.
|
||||
|
||||
Let's start by creating two new **Networks**, one for each **Site**:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/network-local-noacl.png" alt="network-local-noacl"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/network-remote-noacl.png" alt="network-remote-noacl"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
and enable the two required **Access Control Policies**:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-networks-bidirectional.png" alt="acl-networks-bidirectional"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Unlike **Network Routes**, you don't need policies granting access to the **Routing Peers**.
|
||||
|
||||
However, a reverse **Access Control Policy** is mandatory for **Resources** - the reverse route won't be advertised on the local client and response packets will be lost, otherwise.
|
||||
</Note>
|
||||
|
||||
Let's verify it's working:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
|
||||
192.168.100.0/24 via 192.168.122.144 dev enp7s0
|
||||
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
|
||||
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
|
||||
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.783 ms
|
||||
|
||||
--- 192.168.100.10 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.783/0.783/0.783/0.000 ms
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
|
||||
192.168.122.0/24 via 192.168.100.189 dev enp7s0
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ping -c1 192.168.122.65"
|
||||
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
|
||||
64 bytes from 192.168.122.65: icmp_seq=1 ttl=62 time=0.925 ms
|
||||
|
||||
--- 192.168.122.65 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.925/0.925/0.925/0.000 ms
|
||||
```
|
||||
|
||||
Let's also verify that no additional traffic is allowed:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "curl -m 2 192.168.100.10/health; echo"
|
||||
curl: (28) Connection timed out after 2002 milliseconds
|
||||
```
|
||||
|
||||
### Asymmetric Network Resource policies
|
||||
|
||||
The reverse **Access Control Policy** doesn't need to match the protocol and access level of the forward policy. Established connections will be routed back correctly as long as the reverse (operating system) route is registered on the remote end.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-networks-bidirectional-assymetric.png" alt="acl-networks-bidirectional"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
Now we can verify that `local-site` can reach `remote-site` only over ICMP:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
|
||||
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
|
||||
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.836 ms
|
||||
|
||||
--- 192.168.100.10 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.836/0.836/0.836/0.000 ms
|
||||
kdn@pc ~ [1]> ssh local-01.lan "nc -v -w 2 192.168.100.10 22"
|
||||
nc: connect to 192.168.100.10 port 22 (tcp) failed: Connection timed out
|
||||
kdn@pc ~ [1]>
|
||||
```
|
||||
|
||||
while `remote-site` can only reach `local-site` over SSH:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ip route | grep 192.168.122"
|
||||
192.168.122.0/24 via 192.168.100.189 dev enp7s0
|
||||
kdn@pc ~> ssh 192.168.100.215 -J vms.lan "ping -c1 192.168.122.65"
|
||||
PING 192.168.122.65 (192.168.122.65) 56(84) bytes of data.
|
||||
|
||||
--- 192.168.122.65 ping statistics ---
|
||||
1 packets transmitted, 0 received, 100% packet loss, time 0ms
|
||||
|
||||
kdn@pc ~ [1]> ssh 192.168.100.215 -J vms.lan "nc -w 2 192.168.122.65 22"
|
||||
SSH-2.0-OpenSSH_9.7p1 Ubuntu-7ubuntu4.3
|
||||
kdn@pc ~>
|
||||
```
|
||||
|
||||
## Site-to-Site without Masquerade
|
||||
|
||||
This approach preserves source IP addressing information, but the traffic will be immediately rejected by the remote **Routing Peer** if you try to enable any **Access Control Policies** (such as **Network Resources** or **ACL Groups** on **Network Routes**).
|
||||
|
||||
This happens because all access control in NetBird is currently based on **Peer** IP addresses. Packets arriving from different address spaces (without Masquerade) are unknown to the NetBird policy engine and are therefore immediately rejected by the receiving **Peer**/**Routing Peer**.
|
||||
|
||||
<Note>
|
||||
We plan to address these limitations in the future by implementing dedicated facilities for setting up and applying granular policies to Site-to-Site and Site-to-VPN scenarios.
|
||||
|
||||
In the meantime, you can manually restrict forwarded traffic using your operating system's firewall - for example, by implementing `FORWARD` policies on Linux.
|
||||
</Note>
|
||||
|
||||
### Site-to-Site using Network Routes without Masquerade
|
||||
|
||||
Simply disable Masquerade on each **Network Route** from [the first example](#site-to-site-using-network-routes-with-masquerade-and-without-access-control).
|
||||
|
||||
To summarize, you'll need:
|
||||
- A pair of local and remote **Network Routes**
|
||||
- An **Access Control Policy** to establish connectivity between **Routing Peers**
|
||||
- Manual route configuration on **clientless** devices pointing to the respective **Routing Peers**
|
||||
|
||||
The **Network Routes** list will look just like [above](#routes-noacl-site-to-site):
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/routes-noacl-site-to-site.png" alt="routes-noacl-site-to-site"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
but you'll need to turn off **Masquerade** in each **Network Route**'s update dialog:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/route-without-masquerading.png" alt="route-without-masquerading"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
Only one **Access Control Policy** is required, just like [above](#unidirectional-routing-peer-policy):
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/use-cases/setup-site-to-site-access/acl-ping-to-local-only.png" alt="acl-ping-to-local-only"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
With these two pieces of configuration in place, we can verify that `ping` works:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh local-01.lan "ip route | grep 192.168.100"
|
||||
192.168.100.0/24 via 192.168.122.144 dev enp7s0
|
||||
kdn@pc ~> ssh local-01.lan "ping -c1 192.168.100.10"
|
||||
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
|
||||
64 bytes from 192.168.100.10: icmp_seq=1 ttl=62 time=0.897 ms
|
||||
|
||||
--- 192.168.100.10 ping statistics ---
|
||||
1 packets transmitted, 1 received, 0% packet loss, time 0ms
|
||||
rtt min/avg/max/mdev = 0.897/0.897/0.897/0.000 ms
|
||||
```
|
||||
|
||||
and that packets arrive unmodified on the remote end:
|
||||
|
||||
```shell
|
||||
kdn@pc ~> ssh 192.168.100.10 -J vms.lan "sudo tcpdump -nvv -i any --immediate-mode -l icmp"
|
||||
tcpdump: WARNING: any: That device doesn't support promiscuous mode
|
||||
(Promiscuous mode not supported on the "any" device)
|
||||
tcpdump: data link type LINUX_SLL2
|
||||
tcpdump: listening on any, link-type LINUX_SLL2 (Linux cooked v2), snapshot length 262144 bytes
|
||||
17:32:17.845428 enp7s0 In IP (tos 0x0, ttl 62, id 56506, offset 0, flags [DF], proto ICMP (1), length 84)
|
||||
192.168.122.65 > 192.168.100.10: ICMP echo request, id 4480, seq 1, length 64
|
||||
17:32:17.845468 enp7s0 Out IP (tos 0x0, ttl 64, id 51781, offset 0, flags [none], proto ICMP (1), length 84)
|
||||
192.168.100.10 > 192.168.122.65: ICMP echo reply, id 4480, seq 1, length 64
|
||||
^C⏎
|
||||
```
|
||||
182
src/pages/use-cases/site-to-site/index.mdx
Normal file
182
src/pages/use-cases/site-to-site/index.mdx
Normal file
@@ -0,0 +1,182 @@
|
||||
import { Tiles } from '@/components/Tiles'
|
||||
|
||||
# Site-to-Site Connectivity
|
||||
|
||||
Site-to-site connectivity allows you to connect entire networks together, enabling devices to communicate across locations without installing the NetBird client on every device.
|
||||
|
||||
## Understanding Remote Access Scenarios
|
||||
|
||||
NetBird supports three distinct remote access scenarios. Understanding which one you need is the first step to a successful setup.
|
||||
|
||||
### VPN-to-Site
|
||||
|
||||
A NetBird peer (device running the NetBird client) accesses devices on a remote network that don't have NetBird installed.
|
||||
|
||||
```
|
||||
Your Laptop ──────► NetBird Tunnel ──────► Routing Peer ──────► Office Printer
|
||||
(peer) (peer) (clientless)
|
||||
```
|
||||
|
||||
**Common use cases:**
|
||||
- Access your home NAS from anywhere
|
||||
- Reach office servers while traveling
|
||||
- Connect to IoT devices on a remote network
|
||||
|
||||
**Implementation:** Use [Networks](/manage/networks) (recommended) or [Network Routes](/manage/network-routes)
|
||||
|
||||
### Site-to-VPN
|
||||
|
||||
A device without NetBird initiates connections to NetBird peers. This is the reverse of VPN-to-Site—the clientless device starts the connection.
|
||||
|
||||
```
|
||||
Office Server ──────► Routing Peer ──────► NetBird Tunnel ──────► Your Laptop
|
||||
(clientless) (peer) (peer)
|
||||
```
|
||||
|
||||
**Common use cases:**
|
||||
- Office monitoring systems pushing data to remote analysts
|
||||
- On-premise servers initiating backups to cloud peers
|
||||
- Legacy systems that must initiate outbound connections
|
||||
|
||||
**Implementation:** Requires [Network Routes](/manage/network-routes) (Networks does not currently support this)
|
||||
|
||||
### Site-to-Site
|
||||
|
||||
Devices on separate networks communicate with each other, with neither running NetBird directly. Each network has a routing peer that handles traffic.
|
||||
|
||||
```
|
||||
Home NAS ──► Routing Peer ──► NetBird Tunnel ──► Routing Peer ──► Office Server
|
||||
(clientless) (peer) (peer) (clientless)
|
||||
```
|
||||
|
||||
**Common use cases:**
|
||||
- Connect branch office networks to headquarters
|
||||
- Link home networks of family members
|
||||
- Bridge on-premise data centers with cloud VPCs
|
||||
|
||||
**Implementation:** Requires [Network Routes](/manage/network-routes) (Networks does not currently support this)
|
||||
|
||||
### Exit Nodes
|
||||
|
||||
Exit nodes route all internet-bound traffic (`0.0.0.0/0`) through a designated peer, changing your apparent public IP address. Unlike the scenarios above, exit nodes handle internet egress rather than private network access.
|
||||
|
||||
```
|
||||
Your Laptop ──────► NetBird Tunnel ──────► Exit Node ──────► Internet
|
||||
(peer) (peer)
|
||||
```
|
||||
|
||||
**Common use cases:**
|
||||
- Access region-restricted content while traveling
|
||||
- Route traffic through a trusted network for compliance
|
||||
- Mask your location for privacy
|
||||
|
||||
**Implementation:** Requires [Network Routes](/manage/network-routes/use-cases/by-scenario/exit-nodes)
|
||||
|
||||
## Which Scenario Do I Need?
|
||||
|
||||
| I want to... | Scenario | Feature to Use |
|
||||
|-------------|----------|----------------|
|
||||
| Access home devices from my laptop | VPN-to-Site | [Networks](/manage/networks/use-cases/by-scenario/access-home-devices) or [Network Routes](/manage/network-routes) |
|
||||
| Access office resources while traveling | VPN-to-Site | [Networks](/manage/networks/use-cases/by-scenario/remote-worker-access) or [Network Routes](/manage/network-routes) |
|
||||
| Let an office server connect to my laptop | Site-to-VPN | [Network Routes](/manage/network-routes/use-cases/by-scenario/site-to-site-office) only |
|
||||
| Connect two home networks together | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/by-scenario/site-to-site-home) only |
|
||||
| Link branch offices | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/by-scenario/site-to-site-office) only |
|
||||
| Bridge cloud VPC with on-premise network | Site-to-Site | [Network Routes](/manage/network-routes/use-cases/by-scenario/site-to-site-cloud) only |
|
||||
| Route all internet traffic through a specific peer | Exit Node | [Network Routes](/manage/network-routes/use-cases/by-scenario/exit-nodes) only |
|
||||
|
||||
## How It Works
|
||||
|
||||
All scenarios use a routing peer—a device running NetBird that forwards traffic for its local network:
|
||||
|
||||
1. **Deploy a routing peer** at each site (any device running NetBird with access to the local network)
|
||||
2. **Configure routing** to advertise each site's subnet through NetBird
|
||||
3. **Set access policies** to control which peers can reach which networks
|
||||
4. **Configure clientless devices** to route traffic through the routing peer (for Site-to-VPN and Site-to-Site)
|
||||
|
||||
<Tiles
|
||||
title="VPN-to-Site Guides (Networks)"
|
||||
items={[
|
||||
{
|
||||
href: '/manage/networks/use-cases/by-scenario/access-home-devices',
|
||||
name: 'Access Home Devices',
|
||||
description: 'Access your NAS, home automation, and media servers from anywhere',
|
||||
},
|
||||
{
|
||||
href: '/manage/networks/use-cases/by-scenario/remote-worker-access',
|
||||
name: 'Remote Worker Access',
|
||||
description: 'Enable employees to access office resources while working remotely',
|
||||
},
|
||||
{
|
||||
href: '/manage/networks/use-cases/by-scenario/cloud-to-on-premise',
|
||||
name: 'Cloud to On-Premise',
|
||||
description: 'Connect cloud workloads to on-premise databases and services',
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
<Tiles
|
||||
title="Site-to-Site Guides (Network Routes)"
|
||||
items={[
|
||||
{
|
||||
href: '/manage/network-routes/use-cases/site-to-site-home',
|
||||
name: 'Connect Home Networks',
|
||||
description: 'Link multiple home networks so devices can communicate across locations',
|
||||
},
|
||||
{
|
||||
href: '/manage/network-routes/use-cases/site-to-site-office',
|
||||
name: 'Connect Office Networks',
|
||||
description: 'Connect branch offices to headquarters and enable cross-site communication',
|
||||
},
|
||||
{
|
||||
href: '/manage/network-routes/use-cases/by-scenario/site-to-site-cloud',
|
||||
name: 'Connect Cloud Environments',
|
||||
description: 'Bridge cloud VPCs across providers or connect cloud to on-premise',
|
||||
},
|
||||
{
|
||||
href: '/manage/network-routes/use-cases/by-configuration/advanced-configuration',
|
||||
name: 'Advanced Configuration',
|
||||
description: 'Masquerade options, ACL Groups, and troubleshooting',
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
## Key Concepts
|
||||
|
||||
| Term | Description |
|
||||
|------|-------------|
|
||||
| Routing peer | A device running NetBird that forwards traffic for its local network |
|
||||
| Clientless device | A device that doesn't run NetBird (printers, IoT, legacy systems) |
|
||||
| Masquerade | NAT that hides source IPs behind the routing peer's IP (simplifies routing configuration on clientless devices) |
|
||||
|
||||
## Networks vs Network Routes
|
||||
|
||||
NetBird offers two features for routing traffic to private networks: [Networks](/manage/networks) (newer, simpler) and [Network Routes](/manage/network-routes) (original, more flexible). Both are fully supported and will continue to be maintained.
|
||||
|
||||
**Use Networks** for VPN-to-Site scenarios where you want a guided setup experience and per-resource access policies.
|
||||
|
||||
**Use Network Routes** when you need Site-to-VPN or Site-to-Site connectivity, or require advanced options like disabling masquerade.
|
||||
|
||||
### Scenario Support
|
||||
|
||||
| Scenario | Networks | Network Routes |
|
||||
|----------|----------|----------------|
|
||||
| VPN-to-Site | Yes | Yes |
|
||||
| Site-to-VPN | No | Yes |
|
||||
| Site-to-Site | No | Yes |
|
||||
|
||||
### Detailed Comparison
|
||||
|
||||
| Capability | Networks | Network Routes |
|
||||
|-----------|----------|----------------|
|
||||
| Setup complexity | Simpler, guided UI | More manual configuration |
|
||||
| Distribution groups | Automatic (from policy sources) | Explicit configuration required |
|
||||
| Extra routing peer policy | No (implied by resource policies) | Yes (must connect routing peers to distribution groups) |
|
||||
| Per-route configuration | No (routing peers serve all resources) | Yes (each route needs peer, groups, range) |
|
||||
| Edit resources after creation | Yes | No |
|
||||
| Wildcard domains | Yes | No |
|
||||
| Masquerade control | Always on | Configurable |
|
||||
| Exit node support | No | Yes |
|
||||
|
||||
### Future Direction
|
||||
|
||||
The goal is to migrate all routing functionality into Networks for a unified experience. **Network Routes will not be deprecated without advance notice**, and any migration path will be documented. For now, use whichever feature fits your scenario.
|
||||
Reference in New Issue
Block a user