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

Restructuring Phase 3 (#492)

Browse Source
This commit is contained in:
Brandon Hopkins
2025-11-24 09:25:44 -08:00
committed by GitHub
parent c40c132caa
commit 0080ae97df
477 changed files with 800 additions and 564 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
src/pages/how-to/access-home-network.mdx
View File

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

335
src/pages/how-to/access-internal-resources-from-autoscaled-environments.mdx
View File

@@ -1,335 +0,0 @@
# Access Internal Resources From Autoscaled Environments
For DevOps teams managing dynamic, scalable infrastructures, maintaining secure access to internal resources as environments scale up and down is challenging. Traditional network access methods often struggle to keep pace with the rapid changes in autoscaled environments, leading to security vulnerabilities, inefficient resource utilization, and complex management overhead.
Key challenges in managing network access for autoscaled environments like Kubernetes include:
* **Dynamic Resource Management**: As pods or containers scale up and down, maintaining consistent and secure network access becomes increasingly complex.
* **Security Concerns**: Ensuring that only authorized resources have access to internal networks, especially in rapidly changing environments, is crucial but often difficult to manage.
* **Efficient Resource Utilization**: Balancing network access with resource usage, particularly in autoscaled setups, requires careful planning and execution.
This guide introduces NetBird's solution for seamlessly managing network access in autoscaled Kubernetes environments by:
* **Automating Secure Access**: Demonstrating how NetBird setup keys can automatically provide secure network access to dynamically created resources.
* **Enhancing Scalability**: Showcasing how NetBird integrates with Kubernetes' Horizontal Pod Autoscaler (HPA) to maintain network integrity during scaling events.
* **Optimizing Resource Management**: Illustrating how NetBird efficiently manages network peers as resources scale up and down, ensuring optimal resource utilization.
Let's dive into the process of using NetBird to manage network access in an autoscaled Kubernetes environment.
## Prerequisites
To replicate this use case, you'll need:
* A [NetBird account](https://app.netbird.io/)
* [NetBird](/get-started/install) installed on your local machine
* A Kubernetes cluster (local or cloud-based)
* `kubectl` installed and configured on your local machine
* [Kubernetes metrics server](https://github.com/kubernetes-sigs/metrics-server)
* The [IP address range assigned to the Pods](https://www.howtouselinux.com/post/find-the-ip-address-of-pod-in-kubernetes)
With these prerequisites in place, you'll be prepared to set up a secure network connection for autoscaled resources using NetBird by:
1. Creating a NetBird Setup Key for Kubernetes
2. Configuring Network Routes for Internal Resource Access
3. Setting Up Access Policies for Secure Communication
4. Deploying a Sample Application with NetBird Agent
5. Configuring Horizontal Pod Autoscaler (HPA)
6. Observing NetBird's Dynamic Peer Management
This process will demonstrate how NetBird simplifies secure network access in autoscaled Kubernetes environments, automatically managing connections and access controls as resources scale up and down.
## 1. Creating a NetBird Setup Key for Kubernetes
The first step in this process is [creating a NetBird setup key](/how-to/register-machines-using-setup-keys) for your Kubernetes cluster. This setup key serves as a secure authentication token, allowing your cluster's pods to join your NetBird network seamlessly.
To create an appropriate setup key for this use case:
1. Log in to your NetBird dashboard.
2. Navigate to the `Setup Keys` section.
3. Click on `Add Setup Key` to create a new key.
4. Provide a descriptive name for your key.
5. Enable the `Reusable` option to allow multiple pods to use the same key.
6. Activate the `Ephemeral Peers` toggle. This crucial setting automatically removes pods from the NetBird network if they've been offline for over 10 minutes, ensuring efficient resource management.
7. Createthe new setup key by clicking `Create Setup Key`
8. Ensure you take note of the generated setup key, you'll need it shortly.
Here's an example:
![NetBird Setup Keys](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-01.png)
This configuration allows for dynamic management of your Kubernetes pods within the NetBird network. As your cluster scales up, new pods will seamlessly join the network. When pods are terminated or remain offline, they'll be automatically removed, maintaining a clean and efficient network topology.
## 2. Configuring Network Routes for Internal Resource Access
With the setup key in place, the next crucial step is creating a network route to enable access to the Pods within your Kubernetes cluster. For this tutorial, we'll create a straightforward network route that allows access to the Kubernetes cluster from your local machine.
Follow these steps to configure the network route:
In the NetBird dashboard, navigate to the `Network Routes` section and click on `Add Route` to create a new network route.
![NetBird Add Route](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-02.png)
* In the `Network Range` field, enter the private IP range of your Kubernetes Pods. This is typically something like `10.0.0.0/16` for many Kubernetes clusters, but it may vary depending on your specific setup. If you're unsure, you can check this range in your Kubernetes configuration or consult your cluster administrator.
* Navigate to the `Peer Group` tab and select your Kubernetes cluster's group as the routing peer. This group should contain all your cluster's nodes and will automatically include all the Pods running on these nodes.
* In the `Distribution Groups` field, choose the group to which your local machine belongs.
* Review your settings to ensure everything is correct. The route you're creating will allow traffic from your local machine (in the distribution group) to reach the Kubernetes Pods (in the peer group) via the specified network range.
* Once you're satisfied with the configuration, click the `Continue` button.
![NetBird Create a New Route](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-03.png)
Provide a descriptive name for your route, such as `NetBird K8s Demo`.
![NetBird Route Name](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-04.png)
This setup creates a secure pathway for your local machine to communicate with the Pods in your Kubernetes cluster through the NetBird network. As new Pods are created or removed due to autoscaling, they'll automatically be included in or excluded from this route, maintaining seamless access without manual intervention.
![NetBird Network Route Created](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-06.png)
## 3. Setting Up Access Policies for Secure Communication
NetBird's default access control policy automatically assigns all peers to the `All` group, enabling unrestricted bidirectional access between devices and users. While this default configuration allows immediate connectivity between your Kubernetes cluster and local machine, it's crucial to implement more granular access controls for enhanced security.
To create a new access policy:
1. Navigate to the `Access Control > Policies` section in your NetBird dashboard.
2. Click on `Add Policy`.
2. Create a new policy specifically for Kubernetes access:
- Set the source as your local machine's group (e.g., `Local WS`)
- Set the destination as your Kubernetes cluster group (e.g., `Kubernetes Cluster`)
- Specify the protocols and ports required for your application if needed.
Your access policy must look similar to this:
![NetBird Access Policy](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-07.png)
Click `Continue` and name your policy:
![NetBird Access Policy Name](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-08.png)
Once you save your policy, it is a good practice to disable or modify the default `All` group policy to prevent unrestricted access.
![NetBird Access Policies](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-09.png)
This tailored access policy ensures that only authorized devices (your local machine) can communicate with the Kubernetes cluster, significantly improving your network's security posture. As your environment scales, this policy will automatically apply to new pods, maintaining consistent access control.
For more detailed information on configuring access policies, refer to the [NetBird Access Policies documentation](/manage/access-control/manage-network-access).
## 4. Deploying a Sample Application with NetBird Agent
With NetBird configured, it's time to deploy your application in Kubernetes. This process involves creating a dedicated namespace, securely storing the NetBird setup key, and deploying your application alongside the NetBird agent. Let's walk through each step:
Create a dedicated namespace to keep your NetBird-related resources organized and isolated:
```bash
kubectl create namespace netbird
```
Create a Kubernetes secret for the NetBird setup key:
```bash
kubectl create secret generic netbird-setup-key -n netbird --from-literal=setup-key=YOUR_SETUP_KEY
```
Remember to replace `YOUR_SETUP_KEY` with the actual setup key you created earlier. This method securely stores your key within Kubernetes.
Next, deploy your application. For this tutorial we'll use a [sample app](https://github.com/datawire/quote) that generates random quotes:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: quote
namespace: netbird
spec:
replicas: 1
selector:
matchLabels:
app: quote
template:
metadata:
labels:
app: quote
spec:
containers:
- name: quote
image: docker.io/datawire/quote:latest
ports:
- name: http
containerPort: 8080
resources:
requests:
cpu: 100m
memory: 50Mi
limits:
cpu: 200m
memory: 100Mi
- name: netbird-agent
image: netbirdio/netbird:latest
env:
- name: NB_SETUP_KEY
valueFrom:
secretKeyRef:
name: netbird-setup-key
key: setup-key
- name: NB_HOSTNAME
valueFrom:
fieldRef:
fieldPath: metadata.name
resources:
requests:
cpu: 50m
memory: 64Mi
limits:
cpu: 100m
memory: 128Mi
securityContext:
capabilities:
add:
- NET_ADMIN
- SYS_RESOURCE
- SYS_ADMIN
---
apiVersion: v1
kind: Service
metadata:
name: quote
namespace: netbird
spec:
ports:
- name: http
port: 80
targetPort: 8080
selector:
app: quote
```
This deployment creates a pod running both the `quote` app and the NetBird agent as a sidecar. The agent uses the setup key to automatically connect the pod to your NetBird network, enabling secure communication as defined by your routes and access policies.
Deploy the app by running the following:
```bash
kubectl apply -f quote-app.yaml
```
After a few seconds, the app will appear in NetBird's `Peers` dashboard. If you hover over the `Assigned Groups`, you'll notice the app automatically joined the group `Kubernetes Cluster` as expected.
![NetBird App Joined NetBird](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-10.png)
## 5. Configuring Horizontal Pod Autoscaler (HPA)
To enable dynamic scaling of our application, we'll configure a [Horizontal Pod Autoscaler (HPA)](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale). This YAML configuration sets up an HPA that scales based on CPU utilization:
```yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: quote-hpa
namespace: netbird
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: quote
behavior:
scaleDown:
stabilizationWindowSeconds: 60
minReplicas: 1
maxReplicas: 3
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 20
```
Key points:
* We've set `minReplicas: 1` and `maxReplicas: 3` to limit scaling range.
* `averageUtilization: 20` triggers scaling at 20% CPU usage, lower than the default for quicker demonstration.
* `stabilizationWindowSeconds: 60` reduces the cool-down period for faster downscaling.
Apply this configuration with:
```bash
kubectl apply -f quote-hpa.yaml
```
Verify the resource was created by running:
```bash
kubectl get hpa -n netbird
```
The output should be similar to:
```bash
NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE
quote-hpa Deployment/quote cpu: 1%/20% 1 3 1 21m
```
These settings accelerate scaling for tutorial purposes. In production, adjust these values based on your application's specific requirements and performance characteristics.
## 6. Observing NetBird's Dynamic Peer Management
Now that we've set up our application with NetBird integration and configured the HPA, we can observe how NetBird dynamically manages peers as the application scales. We'll use a simple load generator to trigger the autoscaling and monitor the results.
Open a new terminal window and run the following command to generate load:
```bash
kubectl run -i --tty load-generator \
--rm \
--image=busybox \
--restart=Never \
-n netbird \
-- /bin/sh -c "while sleep 0.001; do wget -q -O- http://quote; done" > /dev/null 2>&1
```
This command creates a temporary pod that continuously sends requests to our application.
Now, in another terminal window, monitor the HPA's activity:
```bash
kubectl get hpa -n netbird -w
```
The `-w` flag enables watch mode, providing real-time updates on the HPA's status. The output should be similar to this:
```bash
NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE
quote-hpa Deployment/quote cpu: 2%/20% 1 3 1 23m
quote-hpa Deployment/quote cpu: 26%/20% 1 3 1 24m
quote-hpa Deployment/quote cpu: 29%/20% 1 3 2 24m
quote-hpa Deployment/quote cpu: 41%/20% 1 3 2 24m
quote-hpa Deployment/quote cpu: 63%/20% 1 3 3 25m
quote-hpa Deployment/quote cpu: 38%/20% 1 3 3 25m
quote-hpa Deployment/quote cpu: 17%/20% 1 3 3 25m
quote-hpa Deployment/quote cpu: 1%/20% 1 3 2 30m
quote-hpa Deployment/quote cpu: 1%/20% 1 3 1 31m
quote-hpa Deployment/quote cpu: 1%/20% 1 3 1 32m
```
If you go to NetBird `Peers` dashboard, you will see new peers automatically joining the network as pods scale up.
![NetBird Two Peers](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-11.png)
As you can see, all peers join the same group, meaning all share the same access policy you defined.
![NetBird Three Peers](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-12.png)
Conversely, when scaling down, peers are removed from the group and then terminated.
![NetBird Scaling Down Peers](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-13.png)
When ready, stop the load generator by pressing `Ctrl+C` in its terminal window; eventually, you will see only one app peer in the dashboard.
![NetBird Initial State](/docs-static/img/how-to-guides/setup-keys-access-internal-resources-autoscaled-env/autoscaled-14.png)
This demonstration showcases NetBird's powerful capabilities in seamlessly managing network connections within a dynamic, autoscaling Kubernetes environment. NetBird automatically adapts to your cluster's changing topology without any manual intervention, ensuring secure and efficient connectivity as pods scale up or down. This automation saves significant time and effort in network management and enhances your environment's security posture. By integrating NetBird, you're implementing a robust, scalable networking solution that keeps pace with your application's demands while maintaining strict access controls.

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

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

158
src/pages/how-to/accessing-restricted-domain-resources.mdx
View File

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

8
src/pages/how-to/acronis-netbird-integration.mdx
View File

@@ -149,7 +149,7 @@ The advantage of deployment plans is that they enable scheduled, repeatable inst
## Installing NetBird in Windows using a PowerShell Script
In addition to packages, Acronis Cyber Protect Cloud allows you to install NetBird using PowerShell scripts. This method is handy to automate NetBird installation on Windows Servers, especially if you plan to use [setup keys](https://docs.netbird.io/how-to/register-machines-using-setup-keys).
In addition to packages, Acronis Cyber Protect Cloud allows you to install NetBird using PowerShell scripts. This method is handy to automate NetBird installation on Windows Servers, especially if you plan to use [setup keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys).
### Adding NetBird PowerShell Scripts to Acronis
@@ -567,7 +567,7 @@ From `MANAGEMENT > Scripting plans`, you can click on the three-dot menu of any
For large-scale deployments, you can automate the NetBird client installation on multiple macOS endpoints using a Bash script. This method downloads the official package directly from NetBird's GitHub releases and proceeds with the installation.
You can optionally use NetBird's [setup keys](https://docs.netbird.io/how-to/register-machines-using-setup-keys) to pre-authorize devices during provisioning. The key ensures that once a machine joins the network, it is automatically placed in the correct groups with all the right access permissions already applied.
You can optionally use NetBird's [setup keys](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys) to pre-authorize devices during provisioning. The key ensures that once a machine joins the network, it is automatically placed in the correct groups with all the right access permissions already applied.
### Adding NetBird Bash Scripts to Acronis
@@ -625,9 +625,9 @@ Tip: You can manually trigger any plan outside its schedule. Go to `MANAGEMENT >
## Confirming Endpoint Registration in NetBird
While Acronis Cyber Protect Cloud handles the automated deployment of NetBird clients to your Windows and macOS endpoints, client authentication operates independently through NetBird's identity provider integration system. NetBird [supports major Identity Providers (IdP)](https://docs.netbird.io/how-to/add-users-to-your-network#identity-provider-id-p-sync), including Microsoft Entra ID, Google Workspace, Okta, and others, allowing organizations to maintain their existing authentication infrastructure.
While Acronis Cyber Protect Cloud handles the automated deployment of NetBird clients to your Windows and macOS endpoints, client authentication operates independently through NetBird's identity provider integration system. NetBird [supports major Identity Providers (IdP)](https://docs.netbird.io/manage/team/add-users-to-your-network#identity-provider-id-p-sync), including Microsoft Entra ID, Google Workspace, Okta, and others, allowing organizations to maintain their existing authentication infrastructure.
For example, organizations using Microsoft 365 can use the [NetBird-Microsoft Entra ID integration](https://docs.netbird.io/how-to/microsoft-entra-id-sync#get-started-with-net-bird-entra-id-integration) to automatically authenticate and synchronize users and groups from Entra ID to NetBird. This integration eliminates manual user provisioning by automatically syncing organizational structure, including group memberships and user access permissions. Once synchronized, users automatically inherit the corresponding Access Control Policies created in the initial configuration section (`IT Administrators` group has access to the `Windows Workstations` group), ensuring that network access permissions align with their organizational roles.
For example, organizations using Microsoft 365 can use the [NetBird-Microsoft Entra ID integration](https://docs.netbird.io/manage/team/idp-sync/microsoft-entra-id-sync#get-started-with-net-bird-entra-id-integration) to automatically authenticate and synchronize users and groups from Entra ID to NetBird. This integration eliminates manual user provisioning by automatically syncing organizational structure, including group memberships and user access permissions. Once synchronized, users automatically inherit the corresponding Access Control Policies created in the initial configuration section (`IT Administrators` group has access to the `Windows Workstations` group), ensuring that network access permissions align with their organizational roles.
To confirm that your Acronis-deployed Windows (or macOS) endpoints successfully joined NetBird, navigate to the `Peers` menu in your NetBird dashboard. Successfully registered endpoints will appear in the peers list with their device names, connection status, and assigned IP addresses within your NetBird network.

25
src/pages/how-to/activity-event-streaming.mdx
View File

@@ -1,25 +0,0 @@
# Stream Network Activity to Third-Party SIEM Platforms
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/event-streaming-integration.png" alt="event-streaming-integration" className="imagewrapper-big"/>
</p>
Security Information and Event Management (SIEM) systems play a critical role in network security by monitoring,
detecting, and responding to security threats in real-time. By aggregating and analyzing activity across the network,
SIEMs help identify anomalous patterns and potential breaches, providing a centralized view of security events.
NetBird provides an event streaming feature that allows you to stream network [activity events](/how-to/monitor-system-and-network-activity)
to third-party SIEM systems, such as [Datadog](https://www.datadoghq.com/dg/security/siem-solution/), [Amazon S3](https://aws.amazon.com/s3/), [Amazon Data Firehose](https://aws.amazon.com/firehose/), and others through a generic HTTP integration.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
This documentation provides step-by-step guides and best practices for integrating NetBird activity event streaming with
supported third-party platforms. To get started, select one of the following integrations:
- [Datadog](/how-to/stream-activity-to-datadog)
- [Amazon S3](/how-to/stream-activity-to-amazon-s3)
- [Amazon Data Firehose](/how-to/stream-activity-to-amazon-firehose)
- [SentinelOne Data Lake](/how-to/stream-activity-to-sentinelone-data-lake)
- [Generic HTTP](/how-to/stream-activity-to-generic-http)

53
src/pages/how-to/add-machines-to-your-network.mdx
View File

@@ -1,53 +0,0 @@
# Add peers to your NetBird network
Whether you have a network for personal use or manage your company's corporate network, you'd probably want to add machines
(or peers in NetBird's terms) to your network.
NetBird peer is a machine that runs the [NetBird agent](/about-netbird/how-netbird-works#client-application)
and is connected to the network. NetBird peer can be a virtual machine running in the cloud like AWS or Google Cloud,
an Android or iOS device, a personal laptop, a single-board computer like Raspberry Pi, a docker container, or even a router.
## Related Video Content
For details on adding machines to your network, part of our "Getting started with NetBird" video covers this topic:
<iframe width="560" height="315" src="https://www.youtube.com/embed/JRCZy4rLi-c?start=34" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Use NetBird web UI to add new peers
To add a new peer to your network follow these steps:
1. Sign-in to your NetBird account at https://app.netbird.io/ and go to the Peers tab.
2. Hit `Add Peer` button
<p>
<img src="/docs-static/img/how-to-guides/add-new-peer-empty.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
3. Follow the instructions
<p>
<img src="/docs-static/img/how-to-guides/add-new-peer-popup.png" alt="high-level-dia" width="700" className="imagewrapper"/>
</p>
4. Refresh the Peers tab, and it will display new machines
<p>
<img src="/docs-static/img/how-to-guides/peer-list.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
## What's next?
Here are a few links that might be handy as you venture further into NetBird:
- [Add users to your network](/how-to/add-users-to-your-network)
- [Require a peer approval from the administrator](/how-to/approve-peers)
- [Allow only managed devices in the network](/manage/access-control/endpoint-detection-and-response)
- [Use setup keys to automate NetBird deployments](/how-to/register-machines-using-setup-keys)
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Try NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

109
src/pages/how-to/add-users-to-your-network.mdx
View File

@@ -1,109 +0,0 @@
# Add users to your network
Whether you have a network for personal use or manage your company's corporate network, you'd probably want to invite
people to your account and join your NetBird network.
There are three ways of adding users to a NetBird account - indirect, direct, and via IdP (Identity Provider) sync.
## Indirect user invites
This way of adding users is managed by the NetBird system and doesn't require administrator input.
It works only for organizations with private domains.
Whenever a new user signs up with a private domain (e.g., @netbird.io),
NetBird creates a new account and associates it with the netbird.io organization (domain) automatically.
Every consequent user signup with the same @netbird.io domain in their email address will end up under the same organization.
<Note>
This feature isn't available in the self-hosted setup. By default, all users are joining the same network instead.
</Note>
How does it work? Every time a previously unknown user registers at [app.netbird.io](https://app.netbird.io/),
the system classifies the domain part of the email.
The domain can fall into one of the following categories - `public`, `private`, or `unclassified`.
The domains of the private category are the ones that are automatically grouped under the same account.
Public domains are the ones of the public email providers like Gmail.
<Note>
It might happen (unlikely) that the domain classification system didn't classify your company's domain as private.
Our system was unsure about your domain and assigned an unclassified or public category to be on the safe side.
Just email us at [hello@netbird.io](mailto:hello@netbird.io) or ping us on [Slack](/slack-url) to fix this.
</Note>
## Direct user invites
As the name stands, this way of inviting users is straightforward and works through the web UI.
To invite a new user, proceed to `Team` then select the `Users` tab and click the <button name="button" className="button-6">Invite User</button> button.
A window will appear, allowing you to specify the name and email address of the user you want to invite. Optionally, you could select a set of groups with which you want this user to be associated.
The invited users will receive an email invitation that they have to confirm.
After logging in to the system, they will join your network automatically.
<p>
<img src="/docs-static/img/how-to-guides/user-invites.png" alt="high-level-dia" className="imagewrapper"/>
</p>
<Note>
If a user already has a NetBird account, you can't invite them.
This is a limitation that is likely to be removed in future versions.
</Note>
## Identity Provider (IdP) Sync
NetBird's IdP-Sync automates user access management by integrating with your IdP and automatically
provisioning users and groups. You can enable this feature from the `Users` tab by clicking the `Identity Provider Sync`
button.
<p>
<img src="/docs-static/img/how-to-guides/idp-sync-reference.png" alt="idp-sync-reference" className="imagewrapper"/>
</p>
See the [Provision Users and Groups From Your Identity Provider](/how-to/idp-sync) section for more details.
## Manage user roles
NetBird has five user roles - `Owner`, `Admin`, `Network Admin`, `Auditor` and `User`. The roles allow you to control the level of access to the management API of your account.
- `Owner` role - has full access to the account and can manage all aspects of the account. There can be only one account owner in NetBird. Users with the owner role can delete their organization account. See the [Delete NetBird account](/how-to/delete-account) section for more.
- `Admin` role - has full access to the account except that administrators can't delete or update the role of the Owner user and delete the organization account.
- `Network Admin` role - has access to manage network configurations, including access policies, DNS settings, networks, and network routes, but they can only view user and device information and general settings.
- `Auditor` role - can read all configurations but not modify any of them.
- `User` role - has limited access to the account, allowing users to view peers they own and others they can connect to. Users can create personal access tokens for programmatic access.
| | Owner | Admin | Network Admin | User | Auditor |
| --: | :--: | :--: | :--: | :--: | :--: |
| Peers | ✅ | ✅ | 📖 | 📖 | 📖 |
| Setup Keys | ✅ | ✅ | 📖 | ❌ | 📖 |
| Access Control | ✅ | ✅ | ✅ | ❌ | 📖 |
| Networks | ✅ | ✅ | ✅ | ❌ | 📖 |
| Network Routes | ✅ | ✅ | ✅ | ❌ | 📖 |
| DNS | ✅ | ✅ | ✅ | ❌ | 📖 |
| Team | ✅ | ✅ | 📖 | ❌ | 📖 |
| Activity | ✅ | ✅ | 📖 | ❌ | 📖 |
| Settings | ✅ | ✅ | 📖 | ❌ | 📖 |
| |
|-:|
|✅ = Full access \| 📖 = Read only \| ❌ = No access|
To manage user roles, proceed to the `Users` tab and click on the user you want to update:
<p>
<img src="/docs-static/img/how-to-guides/user-tab-list.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
After that, select the desired role from the dropdown:
<p>
<img src="/docs-static/img/how-to-guides/user-update-role.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Click the `Save` button to save the changes.
<Note>
Only users with the `Owner` role can assign another user as `Owner`; this action will transfer the `Owner` role to another user, making the current user `Admin`.
</Note>
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

50
src/pages/how-to/approve-peers.mdx
View File

@@ -1,50 +0,0 @@
import {Note} from "@/components/mdx";
# Approve peers
The peer approval feature enhances network security by requiring manual administrator approval before a device can join the NetBird network.
This feature is handy when network administrators want to ensure access is restricted only to trusted, corporate-managed devices.
When enabled, devices connect to the management service without network access to other resources.
Administrators then can assess whether the peer is eligible to join the network.
<Note>
This feature is only available in the [NetBird cloud](https://app.netbird.io/) version.
</Note>
## Related Video Content
For details on the peer approval feature, part of our "Getting started with NetBird" video covers this topic:
<iframe width="560" height="315" src="https://www.youtube.com/embed/JRCZy4rLi-c?start=335" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Enable peer approval
To enable peer approval, navigate to [Settings &raquo; Authentication](https://app.netbird.io/settings) and enable 'Peer approval'.
<p>
<img src="/docs-static/img/how-to-guides/peer-approval-settings.png" alt="peer-approval-settings" className="imagewrapper-big"/>
</p>
<Note>
When disabling the peer approval, all pending approval requests will automatically be approved.
</Note>
## Approve peer
To approve a peer, navigate to the [peers tab](https://app.netbird.io/peers) and click the `Approve` button on the right side of the peers table.
<p>
<img src="/docs-static/img/how-to-guides/peer-needs-approval.png" alt="peer-needs-approval" className="imagewrapper"/>
</p>
## Automate peer approval with EDR integrations
NetBird integrates with popular EDR solutions like [CrowdStrike](https://www.crowdstrike.com/) to automate peer approval
and allow only trusted devices to join the network.
Check the [EDR integrations](/manage/access-control/endpoint-detection-and-response) guide for more information on how to enable this feature.
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

31
src/pages/how-to/approve-users.mdx
View File

@@ -1,31 +0,0 @@
import {Note} from "@/components/mdx";
# Approve users
The user approval feature enhances security by requiring manual administrator approval before a user can join your NetBird organization via domain matching.
## Require user approval
Navigate to the Dashboard's `Settings` page and the `Authentication` tab and enable or disable `User Approval Required`.
- **Enabled**: Require manual approval for new users joining via domain matching. Users will be blocked until approved. Learn how to approve or reject users in the section [below](#approve-or-reject-user).
- **Disabled**: Manual approval for new users is not required. Users joining via domain matching will be automatically added to the organization.
<p>
<img src="/docs-static/img/approval/netbird-authentication-settings-approval.png" alt="netbird-authentication-settings-approval" className="imagewrapper-big"/>
</p>
## Approve or reject user
To approve a user, navigate to the [Users Page](https://app.netbird.io/team/users) and click the `Approve` or `Reject` button on the right side of the users table.
<p>
<img src="/docs-static/img/approval/netbird-user-approval.png" alt="netbird-user-approval" className="imagewrapper-big"/>
</p>
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

136
src/pages/how-to/audit-events-logging.mdx
View File

@@ -1,136 +0,0 @@
# Audit Events Logging
The Audit events logging functionality in NetBird allows you to observe and track changes to your network infrastructure.
This includes events such as when a new machine or user has joined your network, when access control policies have been modified,
and many other key network events.
## Related Video Content
To get started with event logging in NetBird, watch this introductory video:
<iframe width="560" height="315" src="https://www.youtube.com/embed/UlnMo1KYXPU?si=JdzEr9v2EZHlP7lc" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## Access the Audit Events Logging View
The audit events logging feature is enabled by default for every NetBird network. You can access the activity log in the web UI under the [Audit Events tab](https://app.netbird.io/events/audit). This view provides a centralized log of network events. You can use the search bar to search by activity name, and apply filters for timeframes, event types, and users.
<p>
<img src="/docs-static/img/how-to-guides/activity-monitoring.png" alt="activity-monitoring" className="imagewrapper-big"/>
</p>
The current version of NetBird tracks a wide range of network changes that occur in the Management server, such as modifications to peers, groups, system settings, setup keys, and access control policies.
<details>
<summary>Click here to view the full list of tracked events</summary>
- **Peer Management:**
- Peer added by user
- Peer added with setup key
- Peer removed by user
- Peer renamed
- Peer SSH server enabled
- Peer SSH server disabled
- Peer login expiration enabled
- Peer login expiration disabled
- **User Management:**
- User joined
- User invited
- User role updated
- User blocked
- User unblocked
- User deleted
- **Group Management:**
- Group created
- Group updated
- Group deleted
- Group added to peer
- Group removed from peer
- Group added to user
- Group removed from user
- Group added to setup key
- Group removed from setup key
- Group added to disabled management DNS setting
- Group removed from disabled management DNS setting
- **Policy Management:**
- Policy added
- Policy updated
- Policy removed
- **Rule Management:**
- Rule added
- Rule updated
- Rule removed
- **Setup Key Management:**
- Setup key created
- Setup key updated
- Setup key revoked
- Setup key overused
- **Route Management:**
- Route created
- Route removed
- Route updated
- **Account Management:**
- Account created
- Account peer login expiration duration updated
- Account peer login expiration enabled
- Account peer login expiration disabled
- Account peer approval enabled
- Account peer approval disabled
- **Nameserver Group Management:**
- Nameserver group created
- Nameserver group deleted
- Nameserver group updated
- **Token Management:**
- Personal access token created
- Personal access token deleted
- **Service User Management:**
- Service user created
- Service user deleted
- **Integration Management:**
- Integration created
- Integration updated
- Integration deleted
- **Other Events:**
- Transferred owner role
- Posture check created
- Posture check updated
- Posture check deleted
- User logged in peer
- Peer login expired
- Dashboard login
</details>
Future versions will also support connection events that occur in NetBird agents (e.g., peer A connected to peer B).
<Note>
The `unknown` name or `unknown@unknown.com` email address may be displayed in the activity event store if the encryption key has been corrupted or lost. This issue is most relevant for self-hosted setups. In this case, the events returned by the API could show `unknown@unknown.com` for the email address field and `unknown` for the name field.
If the configuration files have been generated by the `configure.sh` script, you can find the previous encryption key in the backup files in the same folder as the script. Look for the <b>DataStoreEncryptionKey</b> field in the `management.json` backup file.
</Note>
## Enable Audit Events Streaming to SIEM Systems
NetBird can stream audit events to your Security Information and Event Management (SIEM) system in real-time. With this feature enabled, you can monitor and analyze NetBird network changes within your SIEM infrastructure. Check the [integrations guide](/how-to/activity-event-streaming) for more information about the supported integrations and how to enable them.
## Get Started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

50
src/pages/how-to/auto-offboard-users.mdx
View File

@@ -1,50 +0,0 @@
# Automatically Offboard Team Members from NetBird
[NetBird's IdP-Sync integration](https://docs.netbird.io/how-to/idp-sync) simplifies offboarding team members, enhancing
security and efficiency. With this integration, you can automatically revoke access when users leave the company, when
temporary access for a freelancer ends after project completion, or when a seasonal employee's contract concludes.
Likewise, you can use this integration to restrict access to specific resources or environments when a project finishes.
For instance, you can limit network and resource access when a team member is removed from a group or when an entire group
is deleted from your Identity Provider.
## Removing Team Members
In this tutorial, we will focus on `user_01`, `user_02`, and `user_03`. From NetBird's `Users` dashboard, you can see
that `user_01` is part of the `IT Administrators` group, while `user_02` and `user_03` belong to the `Staging` group.
![NetBird Users](/docs-static/img/how-to-guides/auto-offboard-users/GT3eAeU.png)
To get started, access your Identity Provider (IdP) dashboard. For this example, we’ll use [Microsoft Entra ID (Azure AD)](https://docs.netbird.io/how-to/microsoft-entra-id-sync).
Next, locate the user you want to offboard in your IdP's user management section. Let’s say you want to revoke access to
`user_01`, in that case, you will need to select it and click the `Delete` button as shown below.
![IdP Delete User](/docs-static/img/how-to-guides/auto-offboard-users/TJWLvXL.png)
After deletion, click the `Refresh` button to confirm that the user is no longer active.
![IdP Confirm Deletion](/docs-static/img/how-to-guides/auto-offboard-users/LJ6QHRV.png)
Wait for the NetBird integration to complete its next synchronization cycle, which usually takes 300 seconds. Alternatively, go to the `Integrations` screen in the NetBird admin console and click the corresponding integration button to manually trigger the synchronization.
![NetBird Integrations Force Sync](/docs-static/img/how-to-guides/auto-offboard-users/ogiiUeT.png)
Now, go to NetBird's `Users` dashboard to verify that the user is no longer listed.
![NetBird Users Verification](/docs-static/img/how-to-guides/auto-offboard-users/MQ2yh6B.png)
## Revoking Group Access
Imagine a scenario where you have an access policy that grants all members of the `Staging` group access to resources in the `Servers` group.
![NetBird Access Control](/docs-static/img/how-to-guides/auto-offboard-users/sATMbbP.png)
Let's say the current project is finished, and you no longer want members of the `Staging` group to have access to the
`Servers` group. One way to do this is to remove the `Staging` group from your IdP.
![IdP Delete Group](/docs-static/img/how-to-guides/auto-offboard-users/TOZjFKC.png)
Once the changes synchronize in NetBird, users and their group memberships will be updated; therefore,
[network access associated with that group](https://docs.netbird.io/manage/access-control/manage-network-access) will automatically be revoked.
![NetBird No Group](/docs-static/img/how-to-guides/auto-offboard-users/NKabmN6.png)

173
src/pages/how-to/browser-client.mdx
View File

@@ -1,173 +0,0 @@
# Browser Client - Web-based Remote Access
NetBird's Browser Client enables secure remote access to SSH and RDP resources directly from your web browser, without requiring any client software installation. This feature runs a NetBird peer as WebAssembly (WASM) in your browser, establishing secure connections through your existing NetBird network.
## Overview
The Browser Client provides instant, secure remote access through your browser:
- **No installation required** - Works directly in your browser without any software downloads
- **SSH and RDP support** - Access Linux and Windows machines with complete protocol implementations
- **Secure by design** - All connections are encrypted end-to-end with WireGuard®
- **True peer-to-peer** - Runs a complete NetBird peer as WebAssembly in your browser
- **Works anywhere** - Access your resources from any device with a modern web browser
<Note>
The Browser Client is a real NetBird peer running entirely in your browser. The management server does not connect to target machines - all connections are made directly from your browser to the target peer through the NetBird network.
</Note>
## Prerequisites
Before using the Browser Client, ensure:
1. **Admin privileges** - You must be logged into the NetBird dashboard with an admin account (required for temporary ACL creation)
2. **Protocol requirements**:
- **For SSH**: The NetBird SSH server must be enabled on the target peer. Learn more about [enabling SSH access](/how-to/ssh).
- **For RDP**: The RDP server must be enabled on the target machine
3. **Modern browser** - You're using an up-to-date version of Chrome, Firefox, Edge, or Safari with WebAssembly support
## Accessing Machines via the Browser Client
### Quick Access from the Peers List
The easiest way to connect is directly from the Peers dashboard:
1. Navigate to the **Peers** section in your NetBird dashboard
2. Find the peer you want to access
3. In the **Remote Access** section, click the **SSH** or **RDP** button
<p>
<img src="/docs-static/img/how-to-guides/browser-client/peer-list-view.png" alt="peer-list-view" className="imagewrapper-big"/>
</p>
### SSH Connection
When connecting via SSH:
1. Click the **SSH** button for your target peer
2. A credentials modal will appear
<Note>
Before connecting via SSH, make sure that SSH Access is enabled both on the target peer and in the NetBird Dashboard. Learn more about [enabling SSH access](/how-to/ssh).
</Note>
<p>
<img src="/docs-static/img/how-to-guides/browser-client/ssh-credentials-modal.png" alt="ssh-credentials-modal" className="imagewrapper-big"/>
</p>
3. Adjust the SSH username in the credentials modal if required
4. Click **Connect**
5. A terminal window will open in your browser with your SSH session
<p>
<img src="/docs-static/img/how-to-guides/browser-client/ssh-terminal-connected.png" alt="ssh-terminal-connected" className="imagewrapper-big"/>
</p>
### RDP Connection
For RDP access:
1. Click the **RDP** button for your target machine
2. A new window will open with a credentials modal - enter your RDP server credentials:
<p>
<img src="/docs-static/img/how-to-guides/browser-client/rdp-credentials-modal.png" alt="rdp-credentials-modal" className="imagewrapper-big"/>
</p>
- **Username**: Your username (can include domain: `DOMAIN\username`)
- **Password**: Your password for the RDP server
3. Click **Connect**
4. In the same window, a certificate warning dialog will appear - review the certificate details
<p>
<img src="/docs-static/img/how-to-guides/browser-client/rdp-certificate-modal.png" alt="rdp-certificate-modal" className="imagewrapper-big"/>
</p>
<Note>
Certificate warnings appear for all RDP connections because the Browser Client cannot access the browser's native certificate store for validation. Accepted certificates are remembered using browser storage.
</Note>
5. Click **Accept and Continue** to proceed with the connection
6. The remote desktop will load in the window
<p>
<img src="/docs-static/img/how-to-guides/browser-client/rdp-connected-session.png" alt="rdp-connected-session" className="imagewrapper-big"/>
</p>
## Connection Management
### Active Sessions
While connected through the Browser Client:
- **Session persistence**: Sessions remain active as long as the browser tab is open
- **Multiple connections**: Open multiple tabs for concurrent sessions to different peers
- **Clipboard support**: Copy and paste text between host and RDP in both directions
### Session Security
The Browser Client maintains NetBird's security standards:
- **End-to-end encryption**: All traffic is encrypted using WireGuard®
- **Temporary access**: Uses NetBird's temporary access mechanism that:
- Creates short-lived peers with WireGuard keys generated in the browser
- Establishes temporary ACL rules (TCP/22, TCP/3389)
- Automatically removes the peer and ACLs when the session ends
- **No data persistence**: Keys and credentials exist only in browser memory
## Troubleshooting
### Common Connection Issues
**"Failed to initialize WASM"**
- Clear your browser cache and cookies
- Ensure JavaScript is enabled
- Check if your browser supports WebAssembly
- Try using a different browser
**"Connection timeout"**
- Check that the SSH/RDP services are running on the target
**"Authentication failed"**
- For RDP, try including the domain in the username (e.g., `DOMAIN\username`)
## Known Limitations
**Browser Client Constraints**
- **Relay-only connections**: No direct P2P connections (may increase latency)
- **Advanced features**: Some SSH/RDP features are not available (SFTP, sound, file shares, etc.)
- **Concurrent connections**: Browser resource limits may affect multiple simultaneous sessions
- **RDP resolution changes**: Require reconnection (not seamless)
## Technical Implementation
For technical details on the Browser Client architecture, see the [Browser Client Technical Architecture](/about-netbird/browser-client-architecture) documentation.
### SSH Requirements
For SSH access through the Browser Client:
- **NetBird SSH must be enabled** on the target peer
- The browser generates WireGuard keys and pre-registers the peer via the temporary access endpoint
- Authentication uses the pre-generated WireGuard key pair (bypassing the usual OIDC or setup key flow)
- The WASM NetBird client handles SSH connections internally
### RDP Technology Stack
The RDP implementation is 100% client-side using:
- **[IronRDP](https://github.com/Devolutions/IronRDP)**: High-performance Rust RDP client (Apache 2.0/MIT licensed)
- **RDCleanPath proxy**: IronRDP's rdp proxy reimplemented to make use of NetBird
- Both components are compiled to WebAssembly and run entirely in the browser
## Security Considerations
When using the Browser Client:
1. **Always connect from trusted devices** - The browser environment should be secure
2. **Use incognito/private mode** on shared computers to ensure no session data persists
3. **Log out properly** - Close the browser tab to ensure the session ends
4. **Keep your browser updated** to receive the latest security patches
5. **Be cautious with browser extensions** that might interfere with or monitor your sessions
The Browser Client provides a convenient, secure way to access your network resources without installing software, perfect for quick access from any device or when working from temporary workstations.

205
src/pages/how-to/client-on-mikrotik-router.mdx
View File

@@ -1,205 +0,0 @@
import {Note} from "@/components/mdx";
# NetBird client on MikroTik router
RouterOS is MikroTik's operating system that powers MikroTik's physical routers, switches and Cloud Hosted Routers (CHR).\
Container is MikroTik's implementation of Linux containers, added in RouterOS v7.4 as an extra package,
allowing users to run containerized environments within RouterOS.\
In this guide we'll deploy NetBird client in a MikroTik container.
## Use cases
Running NetBird on MikroTik router or CHR enables cost-effective remote access to RouterOS devices (and their networks)
without the need for additional hardware. In some usecases this can greatly simplify the setup and eliminate the need for additional infrastructure.
### Branch offices
Not all remote locations have a server room or a similar setup where they can deploy an additional machine to run NetBird, i.e. small shops or branch offices that barely have a network cabinet to fit a switch and a router.
Running NetBird directly on a router allows us to have remote access to perform basic network management and monitoring without having to maintain an additional machine for NetBird router, or even worse—using one of the business-critical NetBird clients as a router.
The idea is that all computers on the network would still run clients, and this container would only be used for infrastructure management, monitoring
and maybe one or two small camera streams.
Note that container routing in RouterOS is currently very CPU-bound and is likely not good enough for massive file transfers, database connectivity nor proper camera streaming.
### Field routers
For companies with field teams operating in remote areas—such as construction sites, pop-up events, or field support for vehicles and industrial equipment—MikroTik routers are a game-changer. They provide reliable connectivity without depending on on-site infrastructure, offering a distinct advantage that sets them apart.
Team members would still run NetBird on computers and phones, but a separate IT or infra team needs to be able to remotely manage MikroTik devices to help with unpredicted issues in the field. E.g., reconfigure the router to piggyback the entire network over the location's guest Wi-Fi, or quickly switch between Wi-Fi, backup cellular or satellite, depending on the type of failure.
Traditionally, we would always have cellular modems in routers for minimal management connectivity and then run CHR in a cloud VM. Those routers would all start VPN tunnels to the cloud VM so the IT team can connect to the router if needed. On top of that, we would need an additional NetBird router in the cloud to enable remote access from NetBird to that cloud router and NAT to remote devices.
Running NetBird directly on field routers removes the need for a lot of complexity because there's no longer a need for CHR to serve as a VPN concentrator or a dedicated VM to route NetBird clients to MikroTiks.
## Limitations
<Note>
Use at your own risk. All [RouterOS containers warnings](https://help.MikroTik.com/docs/display/ROS/Container#Container-Disclaimer) apply.\
This is unsupported by both MikroTik and NetBird because it uses MikroTik's beta and NetBird's legacy features.
</Note>
There are quite a few caveats to this approach because containers on RouterOS are still
a relatively new feature, provide relatively slow throughput, and are CPU-bound. They are also very restrictive compared to
standard Kubernetes or Docker platforms, so NetBird can't take advantage of kernel modules or netfilter rules.\
Also, very few current MikroTik devices are optimized for running containers, so we should be careful when deploying this in production.
- Routing through RouterOS containers is relatively slow, CPU intensive and may overload smaller devices.
- NetBird in RouterOS containers can not use an exit node (because it uses legacy routing mode).
- NetBird in RouterOS containers can't perform NAT, but it can do direct routing, and we can do NAT on RouterOS instead.
## Tested on
- Cloud Hosted Router (a.k.a CHR, x86) v7.15.3, v7.16b7
- D53G-5HacD2HnD (a.k.a. Chateau, arm) v7.15.3, v7.16b7
## Step-by-step guide
### 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)
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.
Normal container use could wear out the built-in storage's write cycles or fill up the disk space, thus bricking or even destroying the router.\
If our device has plenty of RAM, we can use Tmpfs for the container filesystem and image cache, but that complicates the setup due to race conditions after reboot.
Please check RouterOS documentation and the MikroTik forum if you want to go that route.
### Prepare RouterOS for container networking
These actions can be performed on RouterOS either via SSH or in Terminal (via Winbox or Web interface), or using Winbox gui.\
More information is available in [MikroTik's management tools documentation](https://help.mikrotik.com/docs/display/ROS/Management+tools).
Create a bridge interface for containers and VETH interface for NetBird container:
```shell
/interface/veth/add name=netbird address=172.17.0.2/24 gateway=172.17.0.1
/interface/bridge/add name=containers
/ip/address/add address=172.17.0.1/24 interface=containers
/interface/bridge/port add bridge=containers interface=netbird
```
Set up NAT for containers so they can access the internet and other networks:
```shell
/ip/firewall/nat/add chain=srcnat action=masquerade src-address=172.17.0.0/24
```
Because NetBird in RouterOS containers can't perform NAT, we'll want to add a route from MikroTik to our NetBird subnet via NetBird container.
This assumes our NetBird subnet is `100.80.0.0/16`.
```shell
/ip/route/add dst-address=100.80.0.0/16 gateway=172.17.0.2
```
We'll also want to add appropriate in, out, and forward rules, but those vary depending on the network setup, so are not covered by this guide.
We should also allow remote DNS queries from the container to the router's DNS server.
Ensure the router's firewall rules are set to block external access to DNS ports, and also allow access to DNS ports from containers.
This is beyond the scope of this guide's, though important as we'll be setting container's resolvers to router's IP addresses.
Enable container functionality logging in RouterOS and configure DockerHub registry cache on the external disk.
This assumes that our USB drive is mounted as `/usb1`:
```shell
/system/logging add topics=container
/container/config/set registry-url=https://registry-1.docker.io tmpdir=/usb1/pull
```
### Prepare the NetBird container
```shell
/container/mounts/add name=netbird_etc src=disk1/etc dst=/etc/netbird
```
Note that we placed `/etc/netbird` on router's built-in flash. This is because we don't want someone stealing the USB drive
and getting access to router's private keys. This file doesn't really change all that often so it's ok to put it there.
```shell
/container envs
add key=NB_SETUP_KEY name=netbird value=YOUR_NETBIRD_SETUP_KEY
add key=NB_NAME name=netbird value=CONTAINER_HOSTNAME
add key=NB_HOSTNAME name=netbird value=CONTAINER_HOSTNAME
add key=NB_LOG_LEVEL name=netbird value=info
add key=NB_DISABLE_CUSTOM_ROUTING name=netbird value=true
add key=NB_USE_LEGACY_ROUTING name=netbird value=true
```
We had to set `NB_DISABLE_CUSTOM_ROUTING` and `NB_USE_LEGACY_ROUTING` because RouterOS containers don't allow access to netfilter kernel module.
We also set `NB_NAME` and `NB_HOSTNAME` to match our router's identity as seen in `/system/identity/print`
because RouterOS won't allow us to set container's hostname to the same value as router's hostname.
If using a self-hosted NetBird server we'll also want to add the correct URLs to our server:
```shell
add key=NB_MANAGEMENT_URL name=netbird value=YOUR_NETBIRD_MANAGEMENT_URL
add key=NB_ADMIN_URL name=netbird value=YOUR_NETBIRD_ADMIN_URL
```
Create the container and trigger image pull from DockerHub:
```shell
/container/add remote-image=netbirdio/netbird interface=netbird root-dir=/usb1/netbird_filesystem mounts=netbird_etc envlist=netbird dns=10.71.71.1 hostname=netbird logging=yes │
```
Note that we had to set container's hostname to something other than router's identity because RouterOS doesn't allow hostname conflicts.\
We have also set container's DNS resolver to router's DNS server. Feel free to tweak this if needed.
Our container is now ready and container image pull from DockerHub should have been triggered. We can check the RouterOS logs to see if the pull was successful and we should see that RouterOS created our image cache directory in `/usb1/pull`.
### Start the container
We can verify that the container is created by running
```shell
/container print
```
We can now start it using the appropriate number from the `print` command:
```shell
/container start number=0
```
At this point we should see the container in our NetBird dashboard and we should be able to create routes through it in NetBird.
Via the NetBird dashboard, create a route through the container to the router's bridge IP address.
Address will be 172.17.0.1/32 and routing peer will be our container. Don't forget to disable NAT on this route.
## Troubleshooting
1. Increase NetBird's verbosity by setting `NB_LOG_LEVEL` env var to `trace`.\
2. Check the logs to see what's going on:
```shell
/log/print without-paging where topics~"container"
```
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
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
/container/set entrypoint="sleep 600" numbers=0
/container/shell number=0
```
When done revert the entrypoint back to NetBird:
```shell
/container/set entrypoint="" numbers=0
```
### 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
DEBG client/internal/login.go:63: connected to the Management service https://api.netbird.io:443
DEBG client/internal/login.go:93: connecting to the Management service https://api.netbird.io:443
DEBG client/internal/login.go:63: connected to the Management service https://api.netbird.io:443
INFO client/internal/connect.go:119: starting NetBird client version 0.28.6 on linux/amd64
DEBG client/internal/connect.go:180: connecting to the Management service api.netbird.io:443
DEBG client/internal/connect.go:188: connected to the Management service api.netbird.io:443
DEBG signal/client/grpc.go:81: connected to Signal Service: signal.netbird.io:443
INFO iface/tun_usp_unix.go:33: using userspace bind mode
DEBG client/internal/routemanager/sysctl/sysctl_linux.go:86: Set sysctl net.ipv4.conf.all.src_valid_mark from 0 to 1
ERROR client/internal/routemanager/systemops/systemops_linux.go:100: Error setting up sysctl: 1 errors occurred:
t* read sysctl net.ipv4.conf.eth0.rp_filter: open /proc/sys/net/ipv4/conf/eth0/rp_filter: no such file or directory
INFO client/internal/routemanager/manager.go:135: Routing setup complete
INFO iface/tun_usp_unix.go:48: create tun interface
DEBG iface/tun_link_linux.go:113: adding address 100.80.100.176/16 to interface: wt0
DEBG iface/wg_configurer_usp.go:39: adding Wireguard private key
INFO client/firewall/create_linux.go:58: no firewall manager found, trying to use userspace packet filtering firewall
DEBG iface/tun_usp_unix.go:95: device is ready to use: wt0
INFO client/internal/dns/host_unix.go:68: System DNS manager discovered: file
DEBG signal/client/grpc.go:126: signal connection state READY
WARN signal/client/grpc.go:141: disconnected from the Signal Exchange due to an error: didn't receive a registration header from the Signal server while connecting to the streams
DEBG signal/client/grpc.go:126: signal connection state IDLE
ERROR util/grpc/dialer.go:38: Failed to dial: dial: dial tcp: lookup signal.netbird.io on 172.17.0.1:53: read udp 172.17.0.2:34638->172.17.0.1:53: i/o timeout
```
Solution: double-check environment variables:
```
NB_DISABLE_CUSTOM_ROUTING=true
NB_USE_LEGACY_ROUTING=true
```
[Environment]::SetEnvironmentVariable("NB_DISABLE_CUSTOM_ROUTING", "true", "Machine")
[Environment]::SetEnvironmentVariable("NB_USE_LEGACY_ROUTING", "true", "Machine")

129
src/pages/how-to/configuring-default-routes-for-internet-traffic.mdx
View File

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

147
src/pages/how-to/configuring-routes-with-access-control.mdx
View File

@@ -1,147 +0,0 @@
# Configuring Routes with Access Control
<Note>
This feature is available from NetBird version 0.30.0 onwards.
</Note>
By default, network routes allow unrestricted access, meaning any traffic can
flow through the routes without limitations. This behavior occurs when access
control groups are not associated with a route.
However, when access control groups are set, the route inherits access restrictions based on the defined
policies. Only traffic that meets the criteria specified in these policies can
access the internal services. This ensures that your network remains secure and that
only authorized users can reach sensitive resources.
## Route Access Policies and Access Control Groups
Route access policies are unidirectional, applying only from the routing
client to the routing peer. Consequently, the access control group only takes effect
when used as a destination group in the policy.
If an empty group (containing no peers) is used for the access control group
(and subsequently in the policy), then only the routed network will be affected
by the access policy, not the routing peer itself.
<Note>
If an access control group was applied to the route but no route access policies are
enabled or none exist, all routed traffic will be dropped.
This contrasts with scenarios where no access control group is applied, in
which case all traffic is permitted.
</Note>
## Creating a Network Route with Access Control Group
Since release `0.30.0`, the management service and dashboard support access control groups for network routes.
To add a Network Route with access control groups, access the `Network Routes` tab and click the `Add Route` button to create a new route.
In the example below, we are creating a route with the following information
(see [Concepts](routing-traffic-to-private-networks#concepts) to learn more about the fields):
- Network identifier: `aws-eu-central-1-vpc`
- Description: `Production VPC in Frankfurt`
- Network range: `10.10.0.0/16`
- Routing peer: `server`
- Distribution Groups: `devs`
- Access Control Groups: `servers`
<p>
<img src="/docs-static/img/how-to-guides/network-route-acl.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Click on `Continue` to proceed.
<p>
<img src="/docs-static/img/how-to-guides/network-route-acl-group-settings.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Once you fill in the route information, you can click on the `Add Route` button to save your new route.
<p>
<img src="/docs-static/img/how-to-guides/network-route-acl-saved.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Because you used an access control group, you will be prompted to create a new policy.
<p>
<img src="/docs-static/img/how-to-guides/network-route-acl-prompt.png" alt="high-level-dia" className="imagewrapper"/>
</p>
Click on the `Create Policy` button to proceed.
## Creating an Access Control Policy
If you did not use the prompt, you can create a new policy by accessing the `Access Control` > `Policies` tab, then clicking the `Add policy` button to create a new policy.
In the popup, specify source and destination groups, and add Posture Checks if needed. Make sure to set traffic
direction only when TCP or UDP protocols are selected. Finally, provide a name and description for your policy.
In the example below, we are creating a unidirectional policy with the following information:
- Name: `Devs to Servers`
- Description: `Devs are allowed to access servers`
- Protocol: `TCP`
- Ports: `80`
- Source Groups: `devs`
- Destination Groups: `servers`
<p>
<img src="/docs-static/img/how-to-guides/network-acl-create-policy.png" alt="high-level-dia" className="imagewrapper"/>
</p>
If necessary, you can create new groups by entering new names in the input box for either the source or destination lists.
Once you have finished configuring the policy, click `Add Policy` to save it. You will then see your new policy in the table.
<p>
<img src="/docs-static/img/how-to-guides/network-acl-new-policy.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
The route has been created successfully. Now, every peer connected to your routing peer can only access port 80 services on the routed network,
as specified by the defined policy.
## Site-to-Site Traffic Configuration
For site-to-site traffic, where routes are set up in both directions with one
peer in the distribution group and the other as the routing peer (and vice
versa), there are two configuration scenarios:
### With Masquerading Enabled
To subject site-to-site traffic to route access policies, ensure masquerading
is enabled. You'll need to set up two policies, one for each direction/site.
### Without Masquerading
If masquerading is disabled, access control groups need not be applied.
This configuration allows unrestricted access in both directions.
Choose the appropriate configuration based on your security requirements and
network setup.
## Behavior Changes in Version 0.30.0
Prior to version 0.30.0, routing clients would accept any traffic initiated from
routed networks behind routing peers. From version 0.30.0 onwards, routing
clients only accept return traffic for connections initiated by routing clients.
To illustrate this change, consider the following example:
```mermaid
graph LR
A[NetBird Peer A<br>Routing Client] --- B[NetBird Peer B<br>Routing Peer]
B --- C[Routed Network]
```
Pre-0.30.0: Peer A would accept connections initiated from the Routed Network
through Peer B.
Post-0.30.0: Peer A only accepts return traffic for connections it initiates to
the Routed Network through Peer B.
To allow traffic initiated from the routed network in version 0.30.0 and later:
1. Ensure masquerade is enabled for the route.
2. Add a peer access policy to allow specific traffic from the routing peer to
the routing client. This is required whether route access policies are set up
or not. The traffic flow should be:
Routing Client (Peer A) ← Routing Peer (Peer B)
This configuration allows the routing client (Peer A) to accept incoming traffic
from the routing peer (Peer B), which may originate from the routed network.

94
src/pages/how-to/control-center.mdx
View File

@@ -1,94 +0,0 @@
import {Note} from "@/components/mdx"
export const description =
'Control Center provides a topological view of your NetBird network, visualizing access relationships between peers, groups, and networks through an interactive graph interface.'
# Visualize Remote Access with Control Center
Control Center is a topological view in the NetBird dashboard that visualizes who can access what across your environment. It maps **Peers**, **Groups**, and **Networks** to the resources they can reach and shows the access control policies that permit those connections.
<Note>
**Availability**: NetBird Cloud (all plans) and self-hosted.
</Note>
<Note>
**Permissions:** The Admin and Network Admin user roles can edit policies from Control Center. Learn more about
[user roles](/how-to/add-users-to-your-network#manage-user-roles).
</Note>
## How it helps
- **Faster audits:** Confirm a device, group, or network's effective access at a glance.
- **Quicker troubleshooting:** Follow the policy path that grants access to a resource.
- **Safer changes:** Click through to the exact policy to refine sources, destinations, or ports without hunting across pages.
## Views
### Peers view
Use this to understand what a specific machine can reach.
<p>
<img src="/docs-static/img/how-to-guides/control-center/control-center-peer-view.png" alt="Control Center Peer View"
className="imagewrapper-big"/>
</p>
- Click the peer node, then search or choose another peer from the dropdown to switch focus.
- The graph shows the peer's access control policy nodes and the reachable resources.
- Click a policy chip to open the standard policy editor. Changes you save are reflected in the graph immediately.
### Groups view
Use this to validate team-level access.
<p>
<img src="/docs-static/img/how-to-guides/control-center/control-center-groups-view.png"
alt="Control Center Groups View" className="imagewrapper-big"/>
</p>
- Click a group node, then search or choose from the dropdown to switch groups.
- The layout shows which resources that group can reach and via which policies.
- View-only for topology here; create or delete groups in the Groups section outside Control Center. Group-based access is the recommended way to manage permissions.
Common checks:
- Confirm that "DevOps" can reach RDS on TCP 5432, or that "Support" only reaches SSH on TCP 22.
### Networks view
Use this to see who can access resources in your routed [networks](/how-to/networks).
<p>
<img src="/docs-static/img/how-to-guides/control-center/control-center-network-view.png"
alt="Control Center Network View" className="imagewrapper-big"/>
</p>
- Toggle **All Networks** or select a specific network.
- The network node shows its resources. Connecting lines display the port allowed by the policy and which groups have access.
- Click any policy chip to edit it in the standard editor. NetBird Networks and routing peers enable access to private subnets and IP resources.
## Editing policies from the graph
- **Open editor:** Click an access control policy chip in any view to open the standard policy editor.
- **What you can change:** Use the editor to modify the usual policy fields as documented in [Access Control](/manage/access-control/manage-network-access), including sources, destinations, protocols, ports, and posture checks.
- **Create vs edit:** You can edit existing policies from Control Center. Creating a new policy still happens in the Access Control section.
## Quick start
1. Open **Control Center** in the NetBird dashboard.
2. Pick a tab: **Peers**, **Groups**, or **Networks**.
3. Click a node to focus, then follow the policy chips to the target resource.
4. Click a policy chip to edit it, then save. The graph updates right away.
## Use cases
- **Sanity-check a team:** In **Groups** view, select a group and verify the resources and ports granted by its policies match your intent. Adjust policies in place if needed.
- **Prepare a change:** In **Networks** view, review which groups reach a sensitive subnet before tightening ports or destinations.
- **Investigate access:** In **Peers** view, confirm why a host can reach a database by following the policy path and port labels, then narrow the rule if required.
- **MSPs:** Switch tenants in the MSP portal to repeat the same checks per customer environment.
## Related docs
- [Manage network access with Groups and Access Policies](/manage/access-control/manage-network-access)
- [Apply posture checks to policies](/manage/access-control/posture-checks)
- [Networks and routing peers](/how-to/networks)
- [MSP portal overview](/how-to/msp-portal)

375
src/pages/how-to/db-workload-migration.mdx
View File

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

2
src/pages/how-to/delete-account.mdx
View File

@@ -1,7 +1,7 @@
import {Note} from "@/components/mdx";
# Delete your NetBird account
To delete your NetBird organization account, you must be a user with the [owner role](/how-to/add-users-to-your-network#manage-user-roles). You can ask the owner to delete the organization account if you are not the account owner.
To delete your NetBird organization account, you must be a user with the [owner role](/manage/team/add-users-to-your-network#manage-user-roles). You can ask the owner to delete the organization account if you are not the account owner.
## Delete your account
<Note>
Before proceeding to delete your Netbird account, please be aware that this action is irreversible. Once your account is deleted, you will permanently lose access to all associated data, including your peers, users, groups, policies, and routes.

6
src/pages/how-to/enforce-periodic-user-authentication.mdx
View File

@@ -11,7 +11,7 @@ Every new network has this feature enabled, and the expiration period is set to
Expired peers will appear in the peers' view with the status `Login required`.
<p>
<img src="/docs-static/img/how-to-guides/peer-needs-login.png" alt="peer-needs-login.png" className="imagewrapper-big"/>
<img src="/docs-static/img/manage/team/peer-needs-login.png" alt="peer-needs-login.png" className="imagewrapper-big"/>
</p>
## Configure and disable expiration
@@ -20,7 +20,7 @@ Go to the Web UI `Settings` tab and set the desired period in the Authentication
You can also disable the expiration for the whole network in the same section.
<p>
<img src="/docs-static/img/how-to-guides/peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper-big"/>
<img src="/docs-static/img/manage/team/peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper-big"/>
</p>
@@ -36,7 +36,7 @@ In the Peers tab of the web UI click on the peer you want to disable expiration
Peers with `Expiration disabled` will be marked with a corresponding label in the Peers table.
<p>
<img src="/docs-static/img/how-to-guides/individual-peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper-big"/>
<img src="/docs-static/img/manage/team/individual-peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper-big"/>
</p>
## Get started

115
src/pages/how-to/examples.mdx
View File

@@ -1,115 +0,0 @@
export const title = 'Examples'
## NetBird Client on AWS ECS (Terraform)
<p>
<img src="/docs-static/img/examples/wiretrustee-on-aws-ecs.png" alt="high-level-dia" width="400"/>
</p>
A common way to run containers in the AWS cloud is to use Elastic Container Service (ECS).
ECS is a fully managed container orchestration service that makes it easy to deploy, manage, and scale containerized applications.
It is best practice and common to run this infrastructure behind security guardrails like strict security groups and private subnets.
Also, a routine for many System's administrators and Developers, is to connect to servers that run their company's software in order to troubleshoot, validate output and even install dependencies.
If you have your systems running in a private network, you got a few options to allow communication to hosts in that network:
* Add a [bastion host](https://en.wikipedia.org/wiki/Bastion_host) or [jump server](https://en.wikipedia.org/wiki/Jump_server).
* Connect a [site-2-site](https://en.wikipedia.org/wiki/Virtual_private_network#Types) VPN.
* [Remote access](https://en.wikipedia.org/wiki/Virtual_private_network#Types) VPN.
* Allow IP(s) address in the server's security group.
All these options are valid and proved to work over the years, but they come with some costs that in the short to mid-term you start to deal with:
* Hard implementation.
* Fragile firewall configuration.
* Yet, another server to secure and maintain.
**In this example, we will run NetBird client configured as a daemon set in ECS deployed with Terraform.**
This allows you to:
* Run NetBird as an ECS native service, you can manage and maintain it the same way you do with your other services.
* Connect to EC2 running on private subnets without the need to open firewall rules or configure bastion servers.
* Access other services connected to your NetBird network and running anywhere.
### Requirements
* Terraform > 1.0.
* A NetBird account with a Setup Key.
* Another NetBird client in your network to validate the connection (possibly your laptop or a machine you are running this example on).
* The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed.
* An [AWS account](https://aws.amazon.com/free/).
* Your AWS credentials. You can [create a new Access Key on this page](https://console.aws.amazon.com/iam/home?#/security_credentials).
### Notice
> Before getting started with this example, be aware that creating the resources from it may incur charges from AWS.
### Getting started
Clone this repository, download, and install Terraform following the guide [here](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/aws-get-started).
Login to https://app.netbird.io and [add your machine as a peer](https://app.netbird.io/add-peer), once you are done with the steps described there, copy your [Setup key](https://app.netbird.io/setup-keys).
Using a text editor, edit the [variables.tf](https://github.com/wiretrustee/wiretrustee-examples/tree/master/ecs-client-daemon/variables.tf) file, and update the `wt_setup_key` variable with your setup key. Also, make sure that `ssh_public_key_path` variable is pointing to the correct public key path. If necessary, update the remaining variables according to your requirements and their descriptions.
Before continuing, you may also update the [provider.tf](https://github.com/wiretrustee/wiretrustee-examples/tree/master/ecs-client-daemon/provider.tf) to configure proper AWS region and default tags.
#### Creating the resources with Terraform
Follow the steps below to run terraform and create your test environment:
1. From the root of the cloned repository, enter the ecs-client-daemon folder and run terraform init to download the modules and providers used in this example.
```shell
cd ecs-client-daemon
terraform init
```
2. Run terraform plan to get the estimated changes
```shell
terraform plan -out plan.tf
```
3. Run terraform apply to create your infrastructure
```shell
terraform apply plan.tf
```
#### Validating the deployment
After a few minutes, the autoscaling group will launch an EC2 instance and there you will find the NetBird's ECS Daemon service running. With that, we can go to our [NetBird dashboard](https://app.netbird.io) and pick the IP of the node that is running NetBird, then we can connect to the node via ssh. For Unix(s) systems:
```shell
ssh ec2-user@100.64.0.200
```
Once you've login, you should be able to see the containers running by using the docker command:
```shell
sudo docker ps
```
#### Deleting the infrastructure resources used in the example
Once you are done validating the example, you can remove the resources with the following steps:
1. Run terraform plan with the flag `-destroy`
```shell
terraform plan -out plan.tf -destroy
```
2. Then execute the apply command:
```shell
terraform apply plan.tf
```
## NetBird Client in Docker
One of the simplest ways of running NetBird client application is to use a pre-built [Docker image](https://hub.docker.com/r/netbirdio/netbird).
**Prerequisites:**
* **Docker installed.**
If you don't have docker installed, please refer to the installation guide on the official [Docker website](https://docs.docker.com/get-docker/).
* **NetBird account.**
Register one at [app.netbird.io](https://app.netbird.io/).
You would need to obtain a [setup key](/how-to/register-machines-using-setup-keys) to associate NetBird client with your account.
The setup key could be found in the NetBird Management dashboard under the Setup Keys tab - [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).
Set the ```NB_SETUP_KEY``` environment variable and run the command.
```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/var/lib/netbird netbirdio/netbird:latest
```
That is it! Enjoy using NetBird.
If you would like to learn how to run NetBird Client as an ECS agent on AWS, please refer to [this guide](#net-bird-client-on-aws-ecs-terraform).

250
src/pages/how-to/google-workspace-sync.mdx
View File

@@ -1,250 +0,0 @@
# Provision Users and Groups From Google Workspace
[Google Workspace](https://workspace.google.com/) provides a comprehensive suite of cloud-based productivity tools that enhance team collaboration and
communication. Notably, its [identity management](https://cloud.google.com/architecture/identity/overview-google-authentication) features streamline user authentication and access control,
ensuring efficiency and security across your organization.
NetBird's Google Workspace integration enhances user management capabilities by synchronizing users and groups from
Google Workspace to NetBird. You can utilize these synchronized groups to configure your network, establish network
access policies, and automate onboarding and offboarding processes, adding significant value to your organizational
workflow and security posture.
The integration process involves two complementary services: Google Workspace and Google Cloud Platform (GCP).
Google Workspace serves as your Identity Provider (IdP), managing user and group identities and providing Single Sign-On (SSO)
capabilities. GCP is used to create a service account, which NetBird uses to authenticate and access Google Workspace
data via the Admin SDK API. This service account uses OAuth 2.0 for secure, authorized access to Workspace information.
## Get Started with NetBird-Google Workspace Integration
Go to the `Integrations` section in the left menu to access the `Identity Provider integration`. Click the `Google Workspace` button. This will open a pop-up window featuring an intuitive wizard to guide you through the synchronization process between NetBird and Google Workspace.
![NetBird Connect NetBird with Google Workspace](/docs-static/img/how-to-guides/google-workspace-sync/q1aq98X.png)
## Prerequisites
The NetBird-Google Workspace integration process involves:
* Creating a project on the Google Cloud Platform.
* Setting up a service account within that GCP project.
* Creating a secret key for the service account.
* Creating a new role in Google Workspace for the service account.
* Granting the service account the appropriate role in Google Workspace.
You’ll need a Google Workspace user account with sufficient permissions to create and manage user and group access. User roles that have these permissions include:
* Super Admin
* Groups Admin
* User Management Admin
To [check your user permissions](https://support.google.com/a/answer/7519580?hl=en) within Google Workspace:
* Sign in to your Google Admin console
* Navigate to `Directory` > `Users`.
* Select your user account and click on `Admin roles and privileges` to view assigned roles and permissions.
Confirm that you have one of the required roles before proceeding with the integration:
![Google Workspaces User Permissions](/docs-static/img/how-to-guides/google-workspace-sync/Ky8bguM.png)
If you lack the required permissions, please contact your workspace administrator to request them.
Because Google Cloud automatically provision new organizations with [Secure by Default enforcements](https://cloud.google.com/resource-manager/docs/secure-by-default-organizations), you’ll also need a GCP user account with enough permissions to create service account keys. User roles that have these permissions include:
* Organization Administrator
* Organization Policy Administrator
To [check your organization-level permissions](https://cloud.google.com/resource-manager/docs/access-control-org) within Google Cloud:
* Sign in to [Google Console](https://console.cloud.google.com)
* In the top bar, click on the dropdown. Find and select your organization in the list.
* Once you've selected the organization, go to `IAM & Admin` > `IAM` in the left sidebar. This will show you a list of all users (principals) and service accounts with roles at the organization level.
* Look for users with roles like `Organization Administrator`, `Organization Policy Administrator`, or other high-level roles.
> NOTE: Verifying your GCP permissions is mandatory before proceeding with the integration since you might need to disable the `iam.disableServiceAccountKeyCreation` constraint temporarily during the process.
![Google Workspace IAM & Admin](/docs-static/img/how-to-guides/google-workspace-sync/9ECRJqC.png)
If you lack the required role, contact your organization's IT department or the person who set up your Google Cloud account.
## Creating the NetBird Project
Once you have the necessary permissions, you can create the NetBird project in GCP.
![NetBird Create NetBird Project](/docs-static/img/how-to-guides/google-workspace-sync/GBbcnt3.png)
Let's go through the required steps:
* Sign in to [Google Console](https://console.cloud.google.com)
* Click the project dropdown at the top of the page.
* Click `New Project` in the dropdown menu.
* Enter `NetBird` as the project name.
* Ensure the proper organization is selected in the `Organization` field.
* Click `CREATE`.
![Google Workspace New Project](/docs-static/img/how-to-guides/google-workspace-sync/sGLG0tX.png)
To let `NetBird` authenticate and access Google Workspace, you must enable the `Admin SDK API`. Here’s how to do it:
* Ensure you're in the correct project.
* Navigate to [https://console.cloud.google.com/apis/library/admin.googleapis.com](https://console.cloud.google.com/apis/library/admin.googleapis.com)
* Click the `Enable` button.
![Google Workspace Admin SDK API](/docs-static/img/how-to-guides/google-workspace-sync/ij3niha.png)
## Creating the NetBird Service Account
Once you create the project, you can set up the `NetBird` service account. On NetBird, click `Continue →`. That will show you a summary of the required steps.
![NetBird Create Service Account](/docs-static/img/how-to-guides/google-workspace-sync/tRbBQsR.png)
Here are the step-by-step instructions:
Navigate to [https://console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials), click `CREATE CREDENTIALS` at the top menu and select `Service account` from the dropdown list.
![Google Workspace Service Account](/docs-static/img/how-to-guides/google-workspace-sync/rDU0Puv.png)
Complete the form with the supplied values:
* `NerBird` for the service account name
* `netbird` for the service account ID
Click `DONE` when ready.
![Google Workspace Service Account Details](/docs-static/img/how-to-guides/google-workspace-sync/WzqMsmW.png)
## Getting Your Service Account Email
On NetBird, click `Continue →`. You’ll need to provide the email of the service account.
![NetBird Get Service Account Email](/docs-static/img/how-to-guides/google-workspace-sync/IBEGQD8.png)
You can copy the email from the `Credentials` page.
![Google Workspace Service Account Email](/docs-static/img/how-to-guides/google-workspace-sync/Z4CQd9O.png)
## Creating a New Service Account Key
Back on NetBird, click `Continue →`. You’ll see a summary of how to create a service account key.
![NetBird Create Service Account Key](/docs-static/img/how-to-guides/google-workspace-sync/MGgCzky.png)
First, click on the service account email to show its details.
![Google Workspace Service Account Details](/docs-static/img/how-to-guides/google-workspace-sync/JWdAg4R.png)
Next, click the `Keys` tab. Open the `ADD KEY` drop-down menu and select `Create new key` from the list.
![Google Workspace Create New Key](/docs-static/img/how-to-guides/google-workspace-sync/gUQ4XAd.png)
A new pop-up window will open, select `JSON` as indicated below:
![Google Workspace New Key Format](/docs-static/img/how-to-guides/google-workspace-sync/WZWFp1Z.png)
The key will automatically download to your local device. The new key will also appear as `active` in the `KEYS` tab.
![Google Workspace Copy New Key](/docs-static/img/how-to-guides/google-workspace-sync/bSakeRS.png)
During service account key creation, you may encounter the following error:
![Google Workspace Key Creation Error](/docs-static/img/how-to-guides/google-workspace-sync/mU2qAwe.png)
If that’s the case, activate Google Cloud Shell on the top menu (shell icon) and enter the following command:
```
gcloud org-policies delete iam.disableServiceAccountKeyCreation --organization=ORGANIZATION_ID
```
Remember to replace `ORGANIZATION_ID` with your organization ID.
Now, you can upload the service account key to NetBird. After a successful upload, you'll see the key listed in the NetBird interface.
![NetBird Paste New Key](/docs-static/img/how-to-guides/google-workspace-sync/g8omqCt.png)
## Creating a New Admin Role in Google Workspace
After creating the service account in GCP and uploading its secret key, return to NetBird and click 'Continue →'. The next steps will guide you through creating a role in Google Workspace for this service account
![NetBird Create Admin Role](/docs-static/img/how-to-guides/google-workspace-sync/F80lm4H.png)
Navigate to Google Workspace [Admin Console](https://admin.google.com/ac/home). Select `Account` on the left menu and then click `Admin Roles`
![Google Workspace Admin Roles](/docs-static/img/how-to-guides/google-workspace-sync/X1CYEHq.png)
Click `Create new role`
![Google Workspace Create New Role](/docs-static/img/how-to-guides/google-workspace-sync/pmeCOd4.png)
Fill in the form with the values provided in NetBird:
* Name: `User and Group Management ReadOnly`
* Description: `User and Group Management ReadOnly`
When done, click `CONTINUE`
![Google Workspace Create Role](/docs-static/img/how-to-guides/google-workspace-sync/HLddKPh.png)
## Granting Role Privileges
Return to NetBird and click `Continue →`. The next screen shows the privileges needed for the Admin API.
![NetBird Add Role Privileges](/docs-static/img/how-to-guides/google-workspace-sync/IZn8XWY.png)
Back to Google Workspace, enter `admin api` in the search bar and enable the following privileges for the Admin API:
* Users: `Read`
* Groups: `Read`
Then, click `CONTINUE`
![Google Workspace Select Privileges](/docs-static/img/how-to-guides/google-workspace-sync/nKLJX2H.png)
Review the Admin API privileges to verify they are correct and click `CREATE ROLE` when ready.
![Google Workspace Review Privileges](/docs-static/img/how-to-guides/google-workspace-sync/METhl2T.png)
## Assigning Admin API Privileges to Google Cloud Service Account
In NetBird, click `Continue →`. For convenience, you can copy the service account Email from this screen and use it to grant it the necessary permissions in Google Workspace.
![NetBird Assign Service Account](/docs-static/img/how-to-guides/google-workspace-sync/jhgTfsk.png)
Then, in Google Workspace, click on `Assign service accounts` as shown below:
![Google Workspace Assign Service Account](/docs-static/img/how-to-guides/google-workspace-sync/HHzmRAL.png)
Paste the service account Email address and click the `ADD` button.
![Google Workspace Add Service Account](/docs-static/img/how-to-guides/google-workspace-sync/ZYSw3KZ.png)
Verify the Email and click `ASSIGN ROLE` to grant the role `User and Group Management ReadOnly` to the `NetBird` service account.
![Google Workspace Assign Role](/docs-static/img/how-to-guides/google-workspace-sync/rPYNLz1.png)
## Entering Customer ID
Go back to NetBird and click `Continue →`. The next screen will prompt you to enter your Google Workspace Customer ID.
![NetBird Enter Customer ID](/docs-static/img/how-to-guides/google-workspace-sync/q6tuStz.png)
To get your customer ID, navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile?hl=en_US) and copy the corresponding ID.
![Google Workspace Customer ID](/docs-static/img/how-to-guides/google-workspace-sync/443kaDt.png)
## Synchronizing Google Workspace Groups and Users
Return to NetBird. The next two screens allow you to select which Google Workspace groups and users you want to synchronize. By default, NetBird synchronizes all groups and users. If you're okay with syncing everything, click `Continue` on both screens.
![NetBird Groups Sync](/docs-static/img/how-to-guides/google-workspace-sync/gAgKeL0.png)
You can also click on `+ Add group (or user group) filter` to change this settings as you see fit. To finish the integration process, click the `Connect` button.
![NetBird Users Sync](/docs-static/img/how-to-guides/google-workspace-sync/6Huo7vW.png)
The next screen, should be similar the following one, verifying that the integration was successful:
![NetBird Google Workspace Enabled](/docs-static/img/how-to-guides/google-workspace-sync/EkPJqpJ.png)
To verify the integration is working correctly, you can also navigate to `Team` > `Users`. Here, you should see your synchronized Google Workspace users listed.
![NetBird Users](/docs-static/img/how-to-guides/google-workspace-sync/5AcaIqW.png)
The users should be the same listed in Google Workspace Admin console:
![Google Workspace Users](/docs-static/img/how-to-guides/google-workspace-sync/BPfboem.png)

54
src/pages/how-to/idp-sync.mdx
View File

@@ -1,54 +0,0 @@
# Provision Users and Groups From Your Identity Provider
<p>
<img src="/docs-static/img/how-to-guides/supported-identity-providers.png" alt="supported-identity-providers"
className="imagewrapper-big"/>
</p>
Managing private network access in a business environment is a critical yet often cumbersome task.
As companies grow and evolve, the manual process of granting access for new employees and revoking it for
departing ones becomes increasingly time-consuming and error-prone. This challenge strains IT resources, poses significant
security risks, and impacts productivity.
NetBird's IdP-Sync automates user access management to private networks by integrating with your identity provider (IdP)
and automatically provisioning users and groups. This integration ensures that changes to groups and users are
synchronized from your identity provider to NetBird, granting appropriate network access to new users and immediately
revoking access for departing employees.
NetBird allows you to use synchronized groups to create [access control policies](/manage/access-control/manage-network-access#creating-policies),
or update network configurations like [DNS](/how-to/manage-dns-in-your-network#distribution-groups),
eliminating the need for manual grouping.
<Note>
This feature is only available in the cloud version of NetBird in the [Team plan](https://netbird.io/pricing) and above.
</Note>
This video guide walks you through an example integration with Microsoft Entra ID, covering both user onboarding and
offboarding scenarios:
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/RxYWTpf7cgY" allow="fullscreen;"></iframe>
</div>
## Supported Identity Providers
NetBird provides native support for syncing with the most popular identify providers.
For detailed setup and configuration steps, select an IdP from the section below:
* [Entra ID (Azure AD)](/how-to/microsoft-entra-id-sync)
* [Okta](/how-to/okta-sync)
* [Google Workspace](/how-to/google-workspace-sync)
* [JumpCloud](/how-to/jumpcloud-sync)
* [Keycloak](/how-to/keycloak-sync)
### Generic SCIM
NetBird provides a way to sync users and groups from any identity provider that supports the SCIM (System for Cross-domain Identity Management) protocol.
SCIM is a standardized protocol that works with most modern identity providers, although configuration varies between providers.
If your provider is not listed above, contact us at support@netbird.io for assistance with your specific IdP setup.
<p>
<img src="/docs-static/img/how-to-guides/generic-scim.png" alt="generic-scim"
className="imagewrapper-big"/>
</p>

2
src/pages/how-to/intune-netbird-integration.mdx
View File

@@ -18,7 +18,7 @@ In this hands-on tutorial, you'll learn how to deploy NetBird with Intune to gra
Before beginning this tutorial, ensure you have the following prerequisites in place:
- Complete the tutorial [Provision Users and Groups From Microsoft Entra ID](https://docs.netbird.io/how-to/microsoft-entra-id-sync) to ensure you can select Entra ID-managed users and groups within Intune.
- Complete the tutorial [Provision Users and Groups From Microsoft Entra ID](https://docs.netbird.io/manage/team/idp-sync/microsoft-entra-id-sync) to ensure you can select Entra ID-managed users and groups within Intune.
- A [NetBird account](https://app.netbird.io) with administrative permissions to create and manage access policies.
- An active [Microsoft Intune license](https://learn.microsoft.com/en-us/intune/intune-service/fundamentals/licenses) (included with Microsoft 365 E3, E5, F1, F3, Enterprise Mobility + Security E3/E5, or Business Premium plans).
- An Intune admin user with at least the [Policy and Profile Manager](https://learn.microsoft.com/en-us/intune/intune-service/fundamentals/role-based-access-control-reference#policy-and-profile-manager) built-in role (*Intune Administrator* role recommended for full control over advanced features)

115
src/pages/how-to/jumpcloud-sync.mdx
View File

@@ -1,115 +0,0 @@
# Provision Users and Groups From JumpCloud
JumpCloud is a comprehensive cloud-based directory platform that provides identity, access, and device management capabilities.
It offers features like single sign-on (SSO), multi-factor authentication (MFA), and centralized user management
to help organizations secure and manage access to their resources.
NetBird's JumpCloud integration enhances user management by allowing you to utilize JumpCloud as your identity provider.
This integration automates user authentication in your network, adds SSO and MFA support, and simplifies network access management
to your applications and resources.
## Prerequisites
Before you begin the integration process, ensure you have the necessary [admin permissions in JumpCloud](https://jumpcloud.com/support/admin-portal-roles). You need a JumpCloud user account with one of the following roles:
* Administrator (minimum required)
* Administrator with Billing
These roles have the required permissions to configure SSO applications and manage SCIM provisioning.
## Setting Up SSO with JumpCloud
Before configuring SCIM provisioning, you must first set up Single Sign-On (SSO) with JumpCloud. Please follow the detailed setup instructions in our [Single Sign-On guide for JumpCloud](/how-to/single-sign-on#jump-cloud).
Once SSO is configured, and you can successfully log in to NetBird using your JumpCloud credentials, you can proceed with the SCIM setup below.
## Enabling JumpCloud SCIM in NetBird
To enable SCIM synchronization in NetBird, navigate to `Integrations > Identity Provider Sync` in your NetBird dashboard.
![NetBird Jumpcloud Integration](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-connect.png)
Click the `Connect Jumpcloud` button to begin the configuration process.
![NetBird Jumpcloud Getting Started](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-scim-getting-started.png)
Click `Get Started` to launch the configuration wizard. You will be guided through several configuration options:
**Groups to be synchronized**
By default, all groups assigned to the NetBird application in JumpCloud will be synchronized. If you want to synchronize only assigned groups that start with a specific prefix, you can specify them in the filter. Keep in mind that the prefix matching is case-sensitive.
![NetBird Jumpcloud Group Filter](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-scim-group-filter.png)
Click `Continue` to proceed to the next step.
**Users to be synchronized**
By default, all users from the groups assigned to the NetBird application will be synchronized. If you want to further filter and synchronize only users from specific assigned groups, you can specify those group names in the filter. The group name matching is case-sensitive.
![NetBird Jumpcloud User Group Filter](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-scim-user-group-filter.png)
Click `Continue` to generate your SCIM credentials.
**SCIM Credentials**
NetBird will generate the SCIM credentials required to configure JumpCloud. Make note of both the **Base URL** and **Token Key** as you will need them in the next section to complete the JumpCloud configuration.
![NetBird Jumpcloud SCIM Credentials](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-scim-credentials.png)
Click `Finish Setup` to complete the NetBird SCIM configuration.
![NetBird Jumpcloud SCIM Enabled](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-scim-enabled.png)
You can now proceed to configure the SCIM application in JumpCloud using the credentials generated above.
## Configure SCIM Application in JumpCloud
In your [JumpCloud admin console](https://console.jumpcloud.com/), go to `SSO Applications`, select your `NetBird`
application, and then select the `Identity Management` tab.
In the **Configuration Settings** section, enter the following SCIM Service Provider details:
* **API Type**: `SCIM API` (default)
* **SCIM Version**: `SCIM 2.0` (default)
* **Base URL**: `https://api.netbird.io/api/scim/v2`
* **Token Key**: Paste the Bearer token you copied from NetBird
* **Test User Email**: Provide a new, unused email address for testing (e.g., `test@yourdomain.com`)
![JumpCloud SCIM Configuration](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-scim-config.png)
* Click `Test Connection` to verify the SCIM connection
If the connection is successful, you'll see a success message. Click `Activate` to enable SCIM provisioning.
![JumpCloud SCIM Test Success](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-scim-activated.png)
## Assigning Groups for SCIM Synchronization
To enable SCIM synchronization of groups and their memberships to NetBird, you need to assign user groups to the NetBird SCIM application.
In your [JumpCloud admin console](https://console.jumpcloud.com/):
* Navigate to your `NetBird` SSO application
* Click on the `User Groups` tab
* Select the groups whose members you want to synchronize to NetBird
* Click `Save` to apply the changes
![JumpCloud Assign Groups](/docs-static/img/how-to-guides/jumpcloud-sync/jumpcloud-assign-groups.png)
Once saved, JumpCloud will automatically synchronize the selected groups and their user memberships to NetBird.
## Verify Synchronization
After assigning groups in JumpCloud, the synchronization will begin automatically. You can verify that users and groups
have been successfully synchronized by navigating to `Team > Users` in your NetBird dashboard.
![NetBird Verify Users](/docs-static/img/how-to-guides/jumpcloud-sync/netbird-verify-users.png)
<Note>
SCIM provisioning will manage only resources that are created through Jumpcloud. Any resources created directly in NetBird will not be managed by SCIM.
</Note>
<Note>
Synced groups will only be available for membership and will not change the role of user in NetBird
</Note>

165
src/pages/how-to/keycloak-sync.mdx
View File

@@ -1,165 +0,0 @@
# Provision Users and Groups From Keycloak
Keycloak is an open-source identity and access management solution that provides features like single sign-on (SSO),
multi-factor authentication (MFA), user federation, and centralized identity management to help organizations
secure and manage access to their applications and resources.
NetBird's Keycloak integration enhances user management by allowing you to utilize Keycloak as your identity provider.
This integration automates user authentication in your network, adds SSO and MFA support, and simplifies network access management
to your applications and resources.
## Prerequisites
Before you begin the integration process, ensure you have the necessary permissions in Keycloak. You need:
* The `scim-admin` or `realm-admin` role assigned to your user to access the SCIM Administration Console
* [SCIM for Keycloak plugin installed](https://scim-for-keycloak.de/)
Once the SCIM plugin is installed, you should see the SCIM section available in your Keycloak admin console.
![Keycloak SCIM Installed](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-installed.png)
## Setting Up SSO with Keycloak
Before configuring SCIM provisioning, you must first set up Single Sign-On (SSO) with Keycloak. Please follow the detailed setup instructions in our [Single Sign-On guide for Keycloak](/how-to/single-sign-on#keycloak).
Once SSO is configured, and you can successfully log in to NetBird using your Keycloak credentials, you can proceed with the SCIM setup below.
## Enabling Keycloak SCIM in NetBird
To enable SCIM synchronization in NetBird, navigate to `Integrations > Identity Provider Sync` in your NetBird dashboard.
![NetBird Keycloak Integration](/docs-static/img/how-to-guides/keycloak-sync/keycloak-connect.png)
Click the `Connect Generic SCIM` button to begin the configuration process.
![NetBird Keycloak Getting Started](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-getting-started.png)
Click `Get Started` to launch the configuration wizard. You will be guided through several configuration options:
**Groups to be synchronized**
By default, all groups mapped in the Keycloak SCIM client will be synchronized. If you want to synchronize only groups that start with a specific prefix, you can specify them in the filter. Keep in mind that the prefix matching is case-sensitive.
![NetBird Keycloak Group Filter](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-group-filter.png)
Click `Continue` to proceed to the next step.
**Users to be synchronized**
By default, all users from the mapped groups will be synchronized. If you want to further filter and synchronize only users from specific groups, you can specify those group names in the filter. The group name matching is case-sensitive.
![NetBird Keycloak User Group Filter](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-user-group-filter.png)
Click `Continue` to generate your SCIM credentials.
**SCIM Credentials**
NetBird will generate the SCIM credentials required to configure Keycloak. Make note of both the **Base URL** and **Token Key** as you will need them in the next section to complete the Keycloak configuration.
![NetBird Keycloak SCIM Credentials](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-credentials.png)
Click `Finish Setup` to complete the NetBird SCIM configuration.
![NetBird Keycloak SCIM Enabled](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-enabled.png)
You can now proceed to configure the SCIM client in Keycloak using the credentials generated above.
## Configure SCIM Client in Keycloak
To configure SCIM in Keycloak, you need to access the SCIM Administration Console and create a service provider configuration.
Navigate to the SCIM Administration Console. On the first login screen, enter your realm name (e.g., `netbird`) and click `Start Login`.
![Keycloak SCIM Login](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-login.png)
Once logged in, navigate to the `SCIM Client` menu and click on `Remote SCIM Provider`. Then click the `+` button to add a new service provider configuration.
![Keycloak SCIM Remote Provider](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-remote-provider.png)
In the SCIM Remote Provider Configuration form, fill out the following sections:
**SCIM Provider Details:**
* **Name**: `NetBird`
* **Provider Enabled**: Enable this checkbox
* **Is User Federation Provider active**: Enable this checkbox only if you are using a federation provider like LDAP. Otherwise, leave it disabled
* **Send externalId as id in requests**: Enable this checkbox
**Connection Details:**
* **Base URL**: Paste the Base URL you copied from NetBird (e.g., `https://api.netbird.io/api/scim/v2`)
* **Hostname-Verifier Enabled**: Enable this checkbox
![Keycloak SCIM Configuration](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-config.png)
**Authentication:**
* **Authentication Type**: Select `Long Life Bearer Token Authentication`
* **Bearer Token**: Paste the Token Key you copied from NetBird
Click `Add` to save the configuration.
![Keycloak SCIM Authentication](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-authentication.png)
After adding the configuration, click `Save Configuration` and then click `Use default Configuration` to apply the settings.
The default schema for the SCIM provider will be created automatically.
![Keycloak SCIM Default Schema](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-default-schema.png)
Next, assign the SCIM provider to your realm. Click the `Realm Assignment` tab to view all available realms.
![Keycloak SCIM Realm Assignment](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-realm-assignment.png)
Find your realm (e.g., `netbird`) and click `Assign to Realm` to enable SCIM synchronization for that realm.
![Keycloak SCIM Realm Assigned](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-realm-assigned.png)
## Configure Resource Filtering
By default, the SCIM provider will synchronize all groups and users from your Keycloak realm to NetBird.
To control which specific groups and users should be synchronized, you need to configure resource filtering rules.
Under the `SCIM Client` menu section, click on `Remote SCIM Provider`, then click `Edit` in the NetBird provider row.
Select the `Resource Filtering Rules` tab.
![Keycloak SCIM Resource Filtering](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-resource-filtering.png)
**User Filtering**
To synchronize only users from specific groups, configure the user filtering rule and click `Save Configuration`:
* **Invert Filter Rule**: Leave this checkbox disabled
* **Filter Type**: Select `Group`
* **Group Name**: Enter the name of the group to sync users from
**Group Filtering**
To synchronize only groups that match specific criteria, configure the group filtering rule and click `Save Configuration`:
* **Invert Filter Rule**: Leave this checkbox disabled
* **Filter Type**: Select `Property`
* **Property Name**: Enter `Groupname`
* **Comparator**: Select `Contains`
* **Comparison Value**: Enter the text that should be contained in the group name
![Keycloak SCIM Filtering Configuration](/docs-static/img/how-to-guides/keycloak-sync/keycloak-scim-filtering-config.png)
<Note>
By default, Keycloak SCIM will not automatically push existing users and groups after the initial configuration.
To synchronize existing resources, navigate to `Synchronization` tab. Here you will find two tabs for Users and
Groups where you can manually trigger the initial sync.
</Note>
## Verify Synchronization
After configuring mappings in Keycloak, the synchronization will begin based on your schedule settings. You can verify that users and groups
have been successfully synchronized by navigating to `Team > Users` in your NetBird dashboard.
![NetBird Verify Users](/docs-static/img/how-to-guides/keycloak-sync/netbird-verify-users.png)
<Note>
SCIM provisioning will manage only resources that are created through Keycloak. Any resources created directly in
NetBird will not be managed by SCIM.
</Note>
<Note>
Synced groups will only be available for membership and will not change the role of user in NetBird
</Note>

8
src/pages/how-to/kubernetes-operator.mdx
View File

@@ -4,7 +4,7 @@ Accessing private Kubernetes clusters can be challenging, especially when connec
having multiple clusters to manage. NetBird Kubernetes operator simplifies this process by enabling secure access
to your Kubernetes clusters using custom resource configurations and annotations to expose your cluster and services in your NetBird network.
The NetBird Kubernetes operator automatically creates [Networks and Resources](/how-to/networks) in your NetBird account, allowing you to
The NetBird Kubernetes operator automatically creates [Networks and Resources](/manage/networks) in your NetBird account, allowing you to
seamlessly access your Kubernetes services and control plane from your NetBird network.
## Deployment
@@ -78,7 +78,7 @@ helm upgrade --create-namespace -f values.yaml -n netbird netbird-operator netbi
## Expose Kubernetes Control Plane to your NetBird Network
To access your Kubernetes control plane from a NetBird network, you can expose your Kubernetes control plane as a
[NetBird resource](/how-to/networks#resources) by enabling the following option in the operator values:
[NetBird resource](/manage/networks#resources) by enabling the following option in the operator values:
```yaml
ingres:
@@ -132,7 +132,7 @@ This will create a Network and a resource similar to the example below:
<Note>
Ingress DNS Resolution requires enabled `DNS Wildcard Routing` and at least one DNS Nameserver configured for clients.
Learn more about Networks settings [here](/how-to/networks#enable-dns-wildcard-routing).
Learn more about Networks settings [here](/manage/networks#enable-dns-wildcard-routing).
</Note>
Other annotations can be used to further configure the resources created by the operator:
@@ -261,7 +261,7 @@ and DNS configurations as any other peer in your NetBird network. This allows yo
through the NetBird network, enabling egress-like access to remote services from your Kubernetes services across various locations or cloud providers.
To enable sidecar functionality in your deployments, you first need to generate a setup key, either via the UI (see image below)
or by following [this guide](/how-to/register-machines-using-setup-keys) for more details.
or by following [this guide](/manage/peers/register-machines-using-setup-keys) for more details.
<p>
<img src="/docs-static/img/how-to-guides/kubernetes/side-cars-setup-key.png" alt="Setup Keys" className="imagewrapper"/>

85
src/pages/how-to/lazy-connection.mdx
View File

@@ -1,85 +0,0 @@
import {Note} from "@/components/mdx";
# Lazy Connections
NetBird now includes an experimental lazy connection feature designed to improve performance and reduce resource usage by connecting to peers only when needed. Instead of maintaining always-on connections, NetBird activates them on-demand based on activity or signaling.
This guide walks you through enabling and configuring this feature in your NetBird client.
<Note>
Minimum supported agent version: <strong>v0.45.0</strong>.
This or higher version must also be installed on the peers you are trying to access for lazy connections to function.
</Note>
<Note>
This feature also requires an upgraded NetBird Management server.
If you're self-hosting NetBird, ensure your server is updated to version <strong>v0.45.0</strong>, which adds support for lazy connections.
</Note>
<Note>
This feature is currently under active development and will continue to evolve. Future releases will enhance disconnection logic and add support for accessing resources through routing peers, which is not yet available.
</Note>
## What Are Lazy Connections?
When enabled, lazy connections allow the NetBird agent to:
- Establish peer-to-peer connections **only when needed** (e.g., when pinging a remote peer).
- Monitor peer activity and **automatically disconnect peers** that remain inactive **and unreachable** for a specified time.
- Keep critical peers (such as routers or excluded peers) **always connected** to ensure uninterrupted communication.
This feature is especially useful in **large-scale deployments** or **resource-constrained environments**, where maintaining full-mesh, permanent connections to all peers is unnecessary and inefficient.
<Note>
When using lazy connections, there may be a **slight delay** when initiating a connection to a peer that is not yet connected. This is expected behavior, as the connection is established on-demand.
</Note>
### How Automatic Disconnection Works
Once a connection between two peers is established, it will remain open **as long as the remote peer is reachable**. The connection is **not** closed just because there is no data transfer.
In other words, the inactivity timer only triggers a disconnect if the peer is both <em>inactive</em> and <em>unreachable</em> for the full duration of the threshold.
<Note>
The default inactivity threshold is <strong>60 minutes</strong>, and can be configured via the <code>NB_LAZY_CONN_INACTIVITY_THRESHOLD</code> environment variable.
</Note>
Additionally, the disconnection logic is being improved and will be enhanced in future releases to better support mobile devices—providing more intelligent reconnection behavior and improved handling of intermittent connectivity.
## Enabling Lazy Connections on agent
Lazy connections are disabled by default. You can enable Lazy Connections using the following environment variable:
```bash
export NB_ENABLE_EXPERIMENTAL_LAZY_CONN=true
```
Or pass the flag directly via the CLI when running the agent:
```bash
netbird up --enable-lazy-connection
```
<Note>
This configuration is <strong>not persistent</strong>. You must reapply the flag or environment variable after each restart unless it is built into your service definition (e.g., systemd or Docker).
</Note>
## Enabling Lazy Connections in the NetBird Dashboard
The lazy connection feature can also be configured through the NetBird Dashboard. Here’s how it works once the setting is updated:
Setting enabled:
* The client’s lazy connection manager is now active. Existing peer connections and ongoing connection attempts will remain unchanged for one hour.
After that, any connection that couldn't be established due to unavailable remote peers will transition to an idle state.
Setting disabled:
* The lazy connection manager is now disabled. The client will immediately attempt to establish connections with all remote peers.
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

167
src/pages/how-to/manage-dns-in-your-network.mdx
View File

@@ -1,167 +0,0 @@
# Manage DNS in your network
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/xxQ_QeEMC0U" allow="fullscreen;"></iframe>
</div>
<br/><br/>
With NetBird, you don't need to worry about designing your private network or configuring [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol)
as it is automatically done in a single place - the NetBird Management service.
NetBird assigns and automatically distributes IP addresses to your peers.
Once your peers have their IP addresses, they can communicate with each other, establish direct encrypted WireGuard® tunnels,
and access services running on connected peers, such as SSH.
Even though we trust our memory capacity, there is a limit to what we can remember,
especially when it comes to IP addresses like this one, 100.128.185.34.
Starting [v0.11.0](https://github.com/netbirdio/netbird/releases), NetBird automatically assigns a domain name
to each peer in a private `netbird.cloud` space that can be used to access the machines. E.g., `my-server.netbird.cloud`.
Besides accessing machines by their domain names, you can configure NetBird to use your private nameservers,
control what nameservers a specific [peer group](/manage/access-control/manage-network-access#groups) should use, and set up split DNS.
<Note>
Nameservers feature is available in NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later on both
cloud and self-hosted versions.
</Note>
## Core concepts
### Local resolver
To minimize system changes, NetBird runs a local embedded DNS resolver on each peer.
This resolver handles queries for domain names of registered peers in your network and forwards queries to upstream nameservers that you configure in the system.
<Note>
DNS Forwarder port change: starting with NetBird v0.59.0, the local DNS forwarder used for routed DNS routes switches from port <code>5353</code> to <code>22054</code> to avoid collisions on client devices. For backward compatibility, the Management Service applies the new port only when <strong>all peers in the account</strong> run v0.59.0 or newer. If any peer is below v0.59.0, port <code>5353</code> will be used for all peers in that account.
</Note>
### Nameserver
A nameserver is an upstream DNS server responsible for name resolution. If a query is not related to a peer domain name,
it will be resolved by one of the upstream servers. You can assign private and public IPs, as well as custom ports for your nameservers.
Ensure that network routes for private addresses are set up to allow peers to connect to them, when configuring private nameservers.
### Match domains
When creating nameserver groups without match domains, it implies that the nameservers will resolve all DNS queries.
For specific cases, you may want to deploy a split horizon configuration for private or specific domains.
Match domains allow you to route queries to specific nameservers, which is useful for internal DNS configurations
that only internal servers can resolve.
<Note>
Only macOS, Windows 10+, and Linux running `systemd-resolved` support nameservers with match domains.
For a better experience, we recommend setting at least one nameserver group without match domains to be applied to the `All` group.
</Note>
#### Mark match domains as search domains
Marking a match domain as a search domain configures peers to use only hostnames to perform FQDN queries, e.g., `ping host-a` instead of `ping host-a.netbird.cloud`.
<Note>
Marking a match domains as a search domain feature is available in NetBird [v0.24.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
### Distribution groups
Distribution groups define which peers will receive the nameserver configuration.
They are particularly useful when using private nameservers to link routing peers and clients of the private servers.
<Note>
When using private nameservers, you may use these groups to link routing peers and clients of the private servers.
</Note>
## Managing nameserver groups
A nameserver group defines up to 2 nameservers to resolve DNS to a set of peers in the distribution groups.
### Creating a nameserver group
Access the `DNS` tab, the `Nameservers` section and click `Add Nameserver`.
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-add-button.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
That will open a nameserver selection configuration screen where you can choose between using three predefined public
nameservers or using a custom setup.
### Selecting predefined nameservers
If you choose a predefined public nameserver option, you can select the following nameservers:
- [Google DNS servers](https://developers.google.com/speed/public-dns/docs/using)
- [Cloudflare DNS servers](https://one.one.one.one/dns/)
- [Quad9 DNS servers](https://www.quad9.net/)
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-selection-view-open.png" alt="high-level-dia" className="imagewrapper"/>
</p>
After selecting one of the three options, you need to assign a peer group for which this nameserver will be effective.
In the example below, we chose the `All` group:
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-all-group.png" alt="high-level-dia" className="imagewrapper"/>
</p>
### Creating custom nameservers
You can also configure a custom nameserver by clicking `Add custom`. Now you can enter the details of your custom nameserver.
In the example below, we are creating a nameserver with the following information:
- Name: `Office resolver`
- Description: `Berlin office resolver`
- Add at least one nameserver: `192.168.0.32` with port `53`
- Distribution group: `Remote developers`
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-custom.png" alt="high-level-dia" className="imagewrapper"/>
</p>
### Creating a nameserver for specific domains
Sometimes one may want to forward DNS queries to specific nameservers but only for particular domains that match a setting.
Taking the example of custom nameservers above, you could select a match mode for only domains listed there.
Below you can see the same nameserver setup but only for the `berlinoffice.com` domain:
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-resolver.png" alt="high-level-dia" className="imagewrapper"/>
</p>
<Note>
Only macOS, Windows 10+, and Linux running `systemd-resolved` support nameservers with only match domains. For a better experience, we recommend setting at least a nameserver group without match domains to be applied to the `All` group.
</Note>
### Distributing DNS settings with groups
You can select as many distribution groups as you want for your nameserver setup.
Keep in mind to link them to peers and, if required, to add access control rules when using private nameservers.
### Adding remote private DNS servers
To add a private DNS server that is running behind routing peers, you need to create resources to ensure communication between your nameserver clients.
In the Berlin office example from previous steps, we have a peer from the `Office network` that can route traffic to the `192.168.0.32` IP,
so we need to ensure that a similar network route exists:
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-route.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Then we need to confirm that an access rule exists to connect `Remote developers` to `Office network` group allowing port `UDP 53`:
<p>
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-rule.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
## Testing configuration
### Querying records
DNS configuration has evolved in the past few years, and each operating system might expose its nameserver configuration differently.
Unfortunately, tools like `nslookup` or `dig` didn't get updated to match these OS configurations, and in many cases,
they won't use the same servers as your browser to query domain names.
For these cases, we listed some tools to support your checks:
#### macOS
You can use `dscacheutil`:
```shell
dscacheutil -q host -a name peer-a.netbird.cloud
```
#### Windows
You can use `Resolve-DnsName` on `Powershell`:
```shell
Resolve-DnsName -Name peer-a.netbird.cloud
```
#### Linux
In most cases, you will be fine with traditional tools because most DNS managers on Linux tend to update the /etc/resolv.conf.
```shell
dig peer-a.netbird.cloud
# or
nslookup peer-a.netbird.cloud
```
If your system is running systemd-resolved, you can also use ```resolvectl```:
```shell
resolvectl query peer-a.netbird.cloud
```
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

186
src/pages/how-to/microsoft-entra-id-sync.mdx
View File

@@ -1,186 +0,0 @@
# Provision Users and Groups From Microsoft Entra ID
[Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id),
formerly known as Azure Active Directory (Azure AD), is a cloud-based identity and access management service that provides
organizations with secure authentication, single sign-on, and user management capabilities. In the context of network security,
it can be effectively used to control network access based on organizational structure, such as groups and individual user accounts.
NetBird's Microsoft Entra ID integration allows you to synchronize users and groups from Entra ID to NetBird.
You can then use these synchronized groups to configure your network, create network access policies, and automate
onboarding and offboarding processes.
## Get Started with NetBird-Entra ID Integration
To get started, navigate to [Integrations](https://app.netbird.io/integrations) in the left menu, which will take you to the
`Identity Provider` integration. Click the `Entra ID (Azure AD)` button. This action will trigger a pop-up window that will
present you with a user-friendly wizard, guiding you through the synchronization process between NetBird and Azure AD.
![NetBird Get Started IdP](/docs-static/img/how-to-guides/microsoft-entra-id-sync/FkdC8BV.png)
## Prerequisites
Before starting the integration process, verify that you have the required permissions in Microsoft Entra ID (Azure AD).
Specifically, you will need an Azure user account with at least one of these roles:
* Application Administrator
* Cloud Application Administrator
* Global Administrator
To check your permissions:
* Log in to the [Azure portal](portal.azure.com).
* Navigate to Manage Microsoft Entra ID and click `View`.
* Expand the `Manage` tab and click on `Roles and administrators` in the left menu.
* Look for your username and verify if you're assigned any of the above roles.
![EntraID Roles](/docs-static/img/how-to-guides/microsoft-entra-id-sync/lDyaAeV.png)
If you don't have the required permissions, contact your Azure AD administrator to grant you the appropriate role before proceeding with the NetBird integration.
## Create and Configure a Microsoft Entra ID Application for NetBird Integration
Now that you have the required permissions, return to the NetBird dashboard. Click on the `Get Started` button to initiate the integration process.
A new wizard screen will appear, offering step-by-step instructions for creating and configuring your Microsoft Entra ID application. To simplify the process, the wizard also provides quick-copy buttons for essential information:
* Name
* Account Type
* Redirect Type
* Redirect URI
![NetBird Create Application](/docs-static/img/how-to-guides/microsoft-entra-id-sync/oI0Pjai.png)
For convenience, click on [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) (step 1). That will open the Azure dashboard. Navigate to `App registrations` in the left menu and then click `+New registration` as indicated below:
![EntraID App Registration](/docs-static/img/how-to-guides/microsoft-entra-id-sync/Yxxktk6.png)
Fill in the required information:
![EntraID Register an App](/docs-static/img/how-to-guides/microsoft-entra-id-sync/1t8qbfK.png)
After entering all required information, click the `Register` button at the bottom of the form to finalize the application registration process.
Upon successful registration, you'll be redirected to a confirmation screen similar to the following:
![EntraID App Registered](/docs-static/img/how-to-guides/microsoft-entra-id-sync/7WYZMW6.png)
Copy and securely store the generated `Application (client) ID` and `Directory (tenant) ID` as you will need them shortly.
## Configure API Permissions for NetBird-Entra ID Integration
On the NetBird dashboard click the `Continue →` button. A new wizard screen will appear, this time, offering step-by-step instructions for setting up API permissions.
![NetBird Add API Permissions](/docs-static/img/how-to-guides/microsoft-entra-id-sync/0A98Xm9.png)
Back to Azure, in the `App registrations` screen, click on `Manage` in the left menu to expand it and then click on `API permissions`:
![EntraID API Permissions](/docs-static/img/how-to-guides/microsoft-entra-id-sync/V0aRf7f.png)
Look for the `+ Add a permission` button, located near the top of the permissions list and click on it.
![EntraID API Permissions Screen](/docs-static/img/how-to-guides/microsoft-entra-id-sync/Qy9lDMF.png)
A new pop-up window will appear, asking you to select an API. Click on `Microsoft Graph`.
![EntraID Microsoft Graph](/docs-static/img/how-to-guides/microsoft-entra-id-sync/tP7WqXO.png)
On the next screen, click on the `Application permissions` button, which will let you select the appropriate permissions for NetBird to function correctly with your Microsoft Entra ID environment.
![EntraID Request API Permissions](/docs-static/img/how-to-guides/microsoft-entra-id-sync/zSkSGAm.png)
To assign user permissions:
* Locate the search bar at the top. Type `User.Read.All` into the search bar and press `Enter`.
* In the search results, click on the `User` tab to expand it and view the available permissions.
* Click on the checkbox to select and enable the `User.Read.All` permission.
![EntraID UserReadAll](/docs-static/img/how-to-guides/microsoft-entra-id-sync/KHGbhqe.png)
The `User.Read.All` permission allows NetBird to read the full set of profile properties, group memberships, and reports of the signed-in user and other users in your organization.
Next, repeat the procedure. This time, search for `Group.Read.All` and click on the checkbox to enable it as shown below:
![EntraID GroupReadAll](/docs-static/img/how-to-guides/microsoft-entra-id-sync/XDl3b7u.png)
Once done, click the `Add permissions` button. You will see a few warnings:
![EntraID API Permissions Warnings](/docs-static/img/how-to-guides/microsoft-entra-id-sync/OGWQWVH.png)
Locate the `Grant admin consent for [Your Organization Name]` button (you’ll find it next to `+Add a permission` button). Click on it to grant the required permissions.
A confirmation dialog will appear, asking you to verify this action. Review the permissions listed in the dialog and click `Yes` to confirm. Wait for the process to complete, this may take a few seconds.
Once finished, the status of the permissions should change to `Granted for [Your Organization Name]`. Verify that all selected permissions now show a green checkmark, indicating they've been successfully granted:
![EntraID API Permissions Granted](/docs-static/img/how-to-guides/microsoft-entra-id-sync/bHb8HVZ.png)
## Create a Client Secret for Secure NetBird-Entra ID Authentication
Back to the NetBird dashboard, click the `Continue →` button. A new wizard screen will appear, showing instructions for generating a client secret in Entra ID.
![NetBird Generate Client Secret](/docs-static/img/how-to-guides/microsoft-entra-id-sync/xvLskEg.png)
On Azure, click on the `Certificates & secrets` button in the left menu to open the management page. Click on `+New client secret` as shown below. Choose an expiration time that suits your security needs and click the `Add` button.
![EntraID Add a Client Secret](/docs-static/img/how-to-guides/microsoft-entra-id-sync/WIercn5.png)
A new client secret will be generated and displayed on the screen. Copy and securely store the `Value` field immediately, as you will needed in the next step.
![EntraID Client Secret Value](/docs-static/img/how-to-guides/microsoft-entra-id-sync/LimVmGI.png)
## Enter Application ID and Directory ID in NetBird
Paste the secret `Value` from the previous step into NetBird and click the `Continue →` button. A new wizard screen will appear, asking for the `Application (client) ID` and the `Directory (tenant) ID` credentials generated previously.
Paste the values and click the `Continue →` button.
![NetBird Application ID and Directory](/docs-static/img/how-to-guides/microsoft-entra-id-sync/6yiGCtY.png)
## Choose Groups to Synchronize from Entra ID
At this stage, NetBird is set to synchronize all groups from your Microsoft Entra ID by default. You have two options:
* If you want to synchronize all groups, simply click the `Continue →` button.
* To synchronize only specific groups, click the `+ Add group filter` button, which will open a new panel where you can set criteria to include or exclude groups.
![NetBird Group Sync](/docs-static/img/how-to-guides/microsoft-entra-id-sync/xyLPzxH.png)
## Choose Users to Synchronize from Entra ID
After configuring group synchronization, you'll now set up user synchronization. Similar than before, NetBird is configured to synchronize all users from your Microsoft Entra ID by default.
* If you want to synchronize all users, you don't need to take any action, simply click the `Continue →` button.
* To synchronize only specific users, click the `+ Add user filter` button. This opens a new panel where you can set criteria to include or exclude users.
<Note>
You can modify these synchronization settings later if necessary.
</Note>
![NetBird Users Sync](/docs-static/img/how-to-guides/microsoft-entra-id-sync/bpwW1Bn.png)
After configuring user and group synchronization, the setup wizard will finalize the process and you'll automatically return to the main Identity Provider screen.
On this screen, you'll see two key indicators of successful integration:
* The Microsoft Entra ID toggle will be switched on (enabled).
* Next to the toggle, you'll see a button with a status message saying `Synced a few seconds ago`.
These indicators confirm that:
* The integration between NetBird and Microsoft Entra ID is active.
* The initial synchronization has been completed successfully.
* NetBird will now automatically sync with your Microsoft Entra ID at regular intervals.
<Note>
You can manually trigger a sync or adjust settings by clicking on the Microsoft Entra ID section in the Identity Provider screen
</Note>
![NetBird Identity Provider Synchronized](/docs-static/img/how-to-guides/microsoft-entra-id-sync/DH5hxFK.png)
## Verify the Integration
To verify the synchronization, navigate to `Teams > Users` in the left menu.
You should see all the users and groups from your Microsoft Entra ID environment listed in the NetBird dashboard.
![NetBird Checking Integration](/docs-static/img/how-to-guides/microsoft-entra-id-sync/qlNlfgV.png)
You can now proceed to configure [access control policies](/manage/access-control/manage-network-access#creating-policies) using the synchronized groups to allow or deny access to the
synchronized users.

2
src/pages/how-to/msp-portal.mdx
View File

@@ -42,7 +42,7 @@ In the 'Tenants' section of your dashboard, click on the 'Add Tenant' button to
<img src="/docs-static/img/how-to-guides/msp-portal/add-new-tenant-name-domain.png" alt="add-new-tenant-name-domain" className="imagewrapper"/>
</p>
2. Define who can access the tenant account by selecting the user groups of your account and the applicable [user role](/how-to/add-users-to-your-network#manage-user-roles) when they switch to the tenant. Only users from the selected groups will
2. Define who can access the tenant account by selecting the user groups of your account and the applicable [user role](/manage/team/add-users-to-your-network#manage-user-roles) when they switch to the tenant. Only users from the selected groups will
be able to switch to and manage the tenant account.
<p>
<img src="/docs-static/img/how-to-guides/msp-portal/add-new-tenant-permissions.png" alt="add-new-tenant-permissions" className="imagewrapper"/>

56
src/pages/how-to/netbird-on-faas.mdx
View File

@@ -1,56 +0,0 @@
# 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.
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),
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?
You can enable the netstack mode for the NetBird client using environment variables:
`NB_USE_NETSTACK_MODE`: Set to true to enable netstack mode. (Default: false)
`NB_SOCKS5_LISTENER_PORT`: Set the port where the Socks5 proxy listens. (Default: 1080)
With these variables, NetBird will launch a Socks5 proxy that you can use to connect to your internal resources.
<Note>
The DNS feature is not supported. You can reach the peers by IP address only.
</Note>
### Running locally
```bash
export NB_USE_NETSTACK_MODE=true
export NB_SOCKS5_LISTENER_PORT=30000
netbird up -F
```
### Docker
Some container environments can be restricted as well. For example, Docker containers are not allowed to create new VPN interfaces by default. For that reason, you can run a NetBird agent in a standard mode to enable the netstack mode:
```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME -d \
-e NB_SETUP_KEY=<SETUP KEY> -e NB_USE_NETSTACK_MODE=true -e NB_SOCKS5_LISTENER_PORT=1080 -v netbird-client:/var/lib/netbird netbirdio/netbird:latest
```
This is useful when you want to configure a simple routing peer without adding privileged permissions or linux capabilities.
## How to use the SOCKS5 proxy?
Once you have the agent running in netstack mode, you need to configure your application to use the SOCKS5 proxy. The following is an example of a python 3 application:
```python
import socks
import socket
import os
def Example():
socks.set_default_proxy(socks.SOCKS5, "127.0.0.1", int(os.getenv('NB_SOCKS5_LISTENER_PORT', '1080')))
socket.socket = socks.socksocket
# 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,
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,
which you can find [Azure functions python db access example
](https://github.com/netbirdio/azure-functions-python-db-access).

173
src/pages/how-to/networks.mdx
View File

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

220
src/pages/how-to/okta-sync.mdx
View File

@@ -1,220 +0,0 @@
import {
Note
} from "@/components/mdx";
# Provision Users and Groups From Okta
Okta is a cloud-based identity and access management (IAM) platform that centralizes user and customer profiles to enhance
security and streamline access. It offers features like multifactor authentication, single sign-on, and lifecycle
management to help organizations manage user identities effectively.
NetBird's Okta integration enhances user management by allowing you to utilize Okta as your identity provider.
This integration automates user authentication in your network, adds SSO and MFA support, and simplifies network access management
to your applications and resources.
The integration process consists of two stages: first, you’ll set up OpenID Connect (OIDC) to enable Single Sign-On (SSO)
from NetBird's login page using Okta credentials. Next, you’ll configure SCIM (System for Cross-domain Identity Management)
to synchronize users and groups smoothly.
## Get Started with NetBird-Okta Integration
To set up SSO, go to `Integrations` in the NetBird admin console's left menu to access the Identity Provider integration page. Click the `Connect Okta` button to get started with the Okta-NetBird integration. This will open a pop-up window with detailed instructions on synchronizing NetBird and Okta.
![NetBird Okta Integration](/docs-static/img/how-to-guides/okta-sync/nwutb3Z.png)
## Prerequisites
Before you begin the integration process, ensure you have the [necessary permissions in Okta](https://help.okta.com/en-us/content/topics/security/administrators-admin-comparison.htm). You need an Okta user account with one of the following roles:
* Super Admin
* Org Admin
* Group Admin
To check your user permissions in Okta:
* Log in to your Okta **admin** dashboard.
* Expand `People` in the left menu.
* Select your user.
* Navigate to the `Admin roles` tab.
Confirm that you have one of the required roles before proceeding with the integration.
![Okta Check User Permissions](/docs-static/img/how-to-guides/okta-sync/AGPXpZN.png)
## Installing the NetBird Integration
Once you have the necessary permissions, you can set up the NetBird application. First, on NetBird, click `Continue →` to show a summary of the necessary steps.
![NetBird Connect NetBird with Okta](/docs-static/img/how-to-guides/okta-sync/dlgCUXo.png)
Let's go through them one by one:
* In Okta’s admin dashboard, click `Applications` in the left menu.
* Select `Applications` from the submenu.
* Click the `Browse App Catalog` button.
![Okta Browse App Catalog](/docs-static/img/how-to-guides/okta-sync/fkSaYnn.png)
In the app catalog, enter "NetBird" in the search bar. Then, click the `Add Integration` button.
![Okta NetBird App](/docs-static/img/how-to-guides/okta-sync/dgxJ916.png)
Accept the default application name and click the `Done` button. On the next screen, click the `Assign` dropdown and select `Assign to People`.
![Okta Assign People To NetBird App](/docs-static/img/how-to-guides/okta-sync/WQ8O1l7.png)
You will see a list of users. Find your user account, click `Assign`, and save the changes. Verify your user is assigned to the NetBird app and click `Done`.
![Okta Verify User Added To NetBird](/docs-static/img/how-to-guides/okta-sync/bteoM6j.png)
After that, you will see your user listed in the NetBird application.
![Okta User Added To NetBird App](/docs-static/img/how-to-guides/okta-sync/IwaqFvj.png)
## Configuring SSO in Okta
The next step is to configure Okta-NetBird SSO integration.
In NetBird, click the `Continue →` button. A new wizard screen will appear, offering the instructions for retrieving Okta’s OpenID Connect credentials. You can click `Close` and navigate to Okta.
![NetBird Connect NetBird with Okta Sharing Credentials](/docs-static/img/how-to-guides/okta-sync/AYVAbEy.png)
* Click on the `Sign On` tab on Okta. Look for `OpenID Connect` under `Sign on methods` in the `Settings` section.
* Copy the `Client ID` value.
* Copy the `Client Secret` value.
Store these credentials securely, as you will need them soon.
![Okta Copy Credentials](/docs-static/img/how-to-guides/okta-sync/rl5Gelc.png)
* Click `Edit` in the `Settings` section.
* In `Credential Details`, change the `Application username format` from `Okta username` to `Email`.
* Click the `Save` button
![Okta OpenID Credential Details](/docs-static/img/how-to-guides/okta-sync/FWPf0Cu.png)
* On the top right, click on your username
* Copy your [Okta account domain](https://developer.okta.com/docs/guides/find-your-domain/main/) as shown below:
![Okta Copy Domain](/docs-static/img/how-to-guides/okta-sync/eITyobI.png)
The final step is to [send an email to the NetBird team](support@netbird.io) with the authentication information you just retrieved:
* Okta `Client ID`
* Okta `Client secret`
* Okta account domain
* Okta primary email domain (usually your username)
You will receive an email once the NetBird team enables authentication for your account.
This completes the first stage, enabling Single Sign-On (SSO) from NetBird's login page using Okta credentials. Now, you can navigate to [app.netbird.io](app.netbird.io) and log in using [Okta Verify](https://help.okta.com/eu/en-us/content/topics/end-user/ov-overview.htm).
## Enabling Okta SCIM in NetBird
In NetBird, go to `Integrations > Identity Provider` and click on the `Connect to Okta` button.
![NetBird Connect to Okta](/docs-static/img/how-to-guides/okta-sync/QbzudIU.png)
You will see a reminder of the permissions your user will require in Okta. Click the `Get Started →` button to continue.
![NetBird User Permissions](/docs-static/img/how-to-guides/okta-sync/RBsJlzu.png)
If you haven't already, you'll need to set up SSO in Okta. If you've completed the previous section, skip this step and click the `Continue →` button.
![NetBird SSO in Okta](/docs-static/img/how-to-guides/okta-sync/XYpJYW3.png)
The next screen will show you how to enable NetBird API credentials in Okta. Copy the value of the `Authorization (Bearer)` token.
![NetBird Enable Okta SCIM](/docs-static/img/how-to-guides/okta-sync/aoPqKJR.png)
Navigate to the NetBird app in your Okta admin dashboard. Click the `Provisioning` tab, then select `Configure API Integration`.
![Okta Provisioning](/docs-static/img/how-to-guides/okta-sync/m27djab.png)
Follow these steps:
* Check the box to enable API Integration.
* Enter your NetBird API Token.
* Click `Test API Credentials` to verify the SCIM connection.
![Okta Entering NetBird Bearer Token](/docs-static/img/how-to-guides/okta-sync/Wn6f9Pj.png)
If everything works as expected, you'll see the message: "NetBird was verified successfully!" as shown below. Click `Save` to continue.
![Okta Token Accepted](/docs-static/img/how-to-guides/okta-sync/7ELQBIA.png)
## Configuring SCIM Provisioning to NetBird
On NetBird, click `Continue →`. You'll see instructions for configuring SCIM provisioning to NetBird.
![NetBird Configure SCIM provisioning to NetBird](https://imgur.com/wBX2k3r.png)
Back to Okta, click `Edit` as shown below.
![Okta Edit NetBird App](/docs-static/img/how-to-guides/okta-sync/AcuWP2G.png)
Enable Okta to create, update, and deactivate NetBird users by checking the corresponding boxes:
* Create Users
* Update User Attributes
* Deactivate Users
When done, click `Save`.
![Okta Enable Create Users and More](/docs-static/img/how-to-guides/okta-sync/JD0EHVI.png)
## Assigning NetBird Application to Okta Groups
In NetBird, click `Continue →`, you'll see the steps for assigning the NetBird integration to Okta groups.
![NetBird Sync Groups to NetBird](/docs-static/img/how-to-guides/okta-sync/fLHSNsd.png)
* Navigate to the `Assignments` tab.
* Similar than before when you assigned your user to NetBird app, click the `Assign` button
* This time, select `Assign to Groups`.
* Select Okta groups that you want to assign to the NetBird app.
![Okta Assign NetBird to Groups](/docs-static/img/how-to-guides/okta-sync/yGV0u5Y.png)
Once you assign the desired groups, click `Done`. You'll see the selected groups listed in Okta.
![Okta NetBird Groups](/docs-static/img/how-to-guides/okta-sync/mxkdWc0.png)
## Push Okta Groups to NetBird
One more time, go to NetBird and click `Continue →`. You'll see the final instructions to push Okta groups to NetBird.
![NetBird Sync Groups to NetBird](/docs-static/img/how-to-guides/okta-sync/8TAvguS.png)
* In Okta, navigate to `Push Groups` tab
* Click the `Push Groups` button
* Select `Find groups by name`
* Search for specific groups to push to NetBird.
![XX](/docs-static/img/how-to-guides/okta-sync/uqUiTtg.png)
Once you finish, go back to NetBird and click `Finish Setup`. You can verify the synchronization by navigating to `Team > Users`
![XX](/docs-static/img/how-to-guides/okta-sync/GPTzvut.png)
The users listed in NetBird should match those you created in Okta.
![XX](/docs-static/img/how-to-guides/okta-sync/O1aoILr.png)
<Note>
SCIM provisioning will manage only resources that are created through Okta. Any resources created directly in NetBird will not be managed by SCIM.
</Note>
<Note>
Synced groups will only be available for membership and will not change the role of user in NetBird
</Note>

144
src/pages/how-to/peer-approval-for-remote-worker-access.mdx
View File

@@ -1,144 +0,0 @@
# Peer Approval for Remote Worker Access with NetBird
For organizations embracing remote work, ensuring secure network access for distributed teams is a paramount challenge. Traditionally, VPNs and remote desktop solutions have been the standard for granting access to company resources. However, these methods often fall short in today's dynamic work environment, especially when dealing with freelancers and temporary workers.
The conventional approach to remote worker access presents several security and operational challenges:
* **Increased Security Risks**: Granting blanket access to network resources can expose sensitive data to potential breaches, especially when dealing with external collaborators.
* **Device Management Complexity**: Ensuring that only authorized and secure devices connect to the network becomes increasingly difficult as the number of remote workers grows.
* **Lack of Granular Control**: Traditional solutions often lack the flexibility to implement fine-grained access policies based on user roles and device trust levels.
* **Scalability Issues**: As teams expand and contract, managing access for a fluctuating workforce can become a time-consuming and error-prone process.
This guide introduces NetBird's Peer Approval as a robust solution for secure remote worker access by:
* **Implementing Zero-Trust Principles**: Ensuring that every device and user is verified before granting network access, regardless of their location.
* **Simplifying Device Trust Management**: Providing a streamlined process for approving and managing trusted devices within the network.
* **Enhancing Access Control**: Offering granular control over network resources, allowing organizations to tailor access based on user roles and device status.
* **Improving Scalability**: Facilitating easy onboarding and offboarding of remote workers, including freelancers, without compromising network security.
Let's explore the step-by-step process of implementing [Peer Approval with NetBird](/how-to/approve-peers) to ensure that only trusted devices can access your network.
## Prerequisites
To replicate this use case, you'll need the following prerequisites:
* An main [NetBird account](https://app.netbird.io/) with administrative privileges.
* A secondary email address not linked to any NetBird account to simulate the freelancer's email.
* [NetBird installed](/get-started/install) on the main device.
With these prerequisites in place, you're ready to simulate granting network access to a temporary remote worker using NetBird's Peer Approval feature by:
1. Setting up NetBird's access control policies for enhanced security
2. Enabling peer approval
3. Inviting users to join your network
4. Installing NetBird on the remote worker device
5. Approving peers
6. Automating peer approval with EDR integration (optional)
## 1. Setting Up NetBird's Access Control Policies For Enhanced Security
Before onboarding remote workers, ensure your organization has appropriate [access control policies](/manage/access-control/manage-network-access) in place. Adhering to zero-trust principles, create or modify policies to grant new users access only to necessary resources.
Navigate to `Access Control > Policies` in the NetBird admin console, then click `Add Policy` or edit an existing one to define these restrictions. Here's a sample policy that grant any member of the `Freelancers` group access to the resources in the group `On-Premise-DB`.
![NetBird Freelancer Access Control Policy](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-0-01.png)
If necessary, you can also set [posture checks](/manage/access-control/posture-checks) for this policy.
![NetBird Freelancer Posture Check](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-0-02.png)
Moreover, it is a best practice to disable the `Default` policy to enforce only restrictive, custom-defined access controls.
![NetBird Access Policy View](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-0-03.png)
With appropriate access policies in place, you're ready to enable NetBird's Peer Approval feature.
## 2. Enabling Peer Approval
To enable peer approval, go to `Settings > Authentication` and activate the `Peer approval` toggle, then click `Save Changes`.
![NetBird Freelancer Device Dashboard](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-02.png)
With `Peer Approval` activated, new members will see an `Approval required` message when joining. Administrators must grant access, ensuring only vetted users enter the NetBird network, thus enhancing overall security.
## 3. Inviting Users to Join Your Network
To invite a new user to join your NetBird network, go to `Team > Users` and click the `Invite User` button.
![NetBird Invite Users](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-03.png)
A pop-up window appears for new user registration. Enter the user's name, email address, and select the `Freelancers` group from the dropdown menu. NetBird's auto-assignment feature instantly links the new user to the `Freelancers` group upon network entry, automatically applying the associated access policy you just created.
![NetBird Invite User Pop Up](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-04.png)
After clicking `Send Invitation`, you'll return to the `Users` dashboard. Here, the new user appears with a `Pending` status, awaiting their acceptance of the invitation and any required approvals.
![NetBird New User Pending](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-05.png)
## 4. Installing NetBird On The Remote Worker Device
Access the secondary email account used to mimic the freelancer. In the inbox, locate the invitation email from NetBird. This email contains a secure link to join your organization's NetBird network, initiating the freelancer's onboarding process.
![Email NetBird Invitation](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-06.png)
After clicking the invitation link, you'll be directed to NetBird's secure account creation page. Follow the on-screen instructions to create a new password.
![NetBird Login](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-07.png)
Upon logging in, you'll arrive at NetBird's Peers dashboard. Locate and click the `Add Peer` button to initiate the [Getting Started](/get-started) Wizard, which guides you through the process of adding a new device to the network.
![NetBird Freelancer Peers Dashboard](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-08.png)
The wizard will detect your operating system and provide detailed step-by-step instructions on how to [install NetBird](/get-started/install).
![NetBird Freelancer Install Client](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-09.png)
During your initial connection to NetBird, a system dialog will appear requesting authorization. This prompt asks for permission to access your profile and email information, which is necessary for NetBird to establish your account and network access.
![NetBird Authorize App](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-10.png)
After completing the installation, your device will appear in the Peers dashboard. Hover over the `+1` in the `Assigned Groups` column to confirm the device has automaticaclly assigned to the `Freelancers` group as expected.
![NetBird Freelancer Peers Listed](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-11.png)
## 5. Approving Peers
Back to your primary account, you'll notice the newly added user's status is now displayed as `Active` in the `Users` dashboard. This status update confirms that the device has successfully added to the NetBird network and is ready for secure communication.
![NetBird Peers Dashboard](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-12.png)
However, your approval is required before the user's device can fully connect to the NetBird network. To grant network access:
* Navigate to the `Peers` dashboard
* Locate the newly added device
* Click the `Approve` button next to the device
* Confirm the action when prompted
![NetBird Approve New Peer](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-13.png)
After approval, the device is granted full access to network resources allocated to the `Freelancers` group. The freelancer can now view all accessible network resources in their `Peers` dashboard:
![NetBird Freelancer Peers View](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-16.png)
Likewise, as an administrator, you can click on the user's device to see which resources and peers the freelancer has access to.
![NetBird Main Account Peers View](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-17.png)
## 6. Automating Peer Approval with EDR Integration (optional)
NetBird's EDR (Endpoint Detection and Response) integration enhances network security by restricting access to devices managed by your organization's IT department. This feature synchronizes the list of devices managed by the EDR platform via API and verifies the presence of the EDR agent on each device. If the agent is not installed, access to the network is blocked.
Key aspects of NetBird's EDR integration:
* Supports [CrowdStrike Falcon](https://www.crowdstrike.com/products)
* Allows selective application of EDR checks to specific device groups
* Automates peer approval process for trusted devices
* Available only in the cloud version of NetBird
To activate this feature, navigate to `Integrations > EDR` and activate the CrowdStrike integration toggle.
![NetBird EDR Integration](/docs-static/img/how-to-guides/peer-approval-for-remote-worker-access/peer-a-18.png)
For more information regarding NetBird's EDR integration, refer to the [documentation](/manage/access-control/endpoint-detection-and-response)

2
src/pages/how-to/plans-and-billing.mdx
View File

@@ -23,7 +23,7 @@ Details can be found on our [pricing page](https://netbird.io/pricing).
NetBird uses a pay-as-you-go model, charging only for active users or machines.
We bill you at the end of each monthly cycle based on actual usage:
* A user or machine counts as "active" only if it connects or logs in (including the admin dashboard) at least once during the billing period.
* If you integrate NetBird with your [Identity Provider (IdP)](/how-to/idp-sync),
* If you integrate NetBird with your [Identity Provider (IdP)](/manage/team/idp-sync),
we automatically sync your users and machines. Inactive synced user accounts that never connect or log in won't incur charges.
Example:

96
src/pages/how-to/register-machines-using-setup-keys.mdx
View File

@@ -1,96 +0,0 @@
# Use setup keys to run automated deployments and add machines to your network at scale
Setup key is a pre-authentication key that allows to register new machines in your network.
It simply associates a machine with an account on a first run.
## Related Video Content
For a comprehensive guide, part of our "Getting started with NetBird" video specifically covers setup keys:
<iframe width="560" height="315" src="https://www.youtube.com/embed/JRCZy4rLi-c?start=175" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
The setup key can be provided as a parameter to the ```netbird up``` command.
This makes it possible to run automated deployments with infrastructure-as-code software like Ansible, Cloudformation or Terraform.
```bash {{ title: 'Starting NetBird Client' }}
sudo netbird up --setup-key <SETUP KEY>
```
## Types of setup keys
There are 2 types of setup keys:
* **One-off key**. This type of key can be used only once to authenticate a machine.
* **Reusable key**. This type of key can be used multiple times to authenticate machines.
## Ephemeral peers
You can create a setup key with the ephemeral peers option enabled.
Peers added with this key that later become offline for over 10 minutes will be removed automatically from the NetBird system.
This is useful when you want to add containers or auto scaling instances to your network.
## Using setup keys
Setup keys are available in the NetBird Management Dashboard under the `Setup Keys` tab [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).
You can easily add new or revoke keys.
<p>
<img src="/docs-static/img/how-to-guides/setup-keys.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
<Note>
When revoking a key, all machines authenticated with this key will remain connected to the network. The same logic applies when the key expires.
</Note>
## Expiration
You can set expiration when creating a key. When expired, the setup key can't be used anymore.
## Usage limit
By default, every reusable key has unlimited usage.
We recommend limiting the number of times the key can be used, e.g., set it to 30 if you need to enroll only 30 machines.
## Allow Extra DNS labels
You can create a setup key with the `Allow Extra DNS labels` option enabled.
When enabled, peers added using this key will be able to add extra DNS labels and with that other peers in the NetBird network can reach them with these labels.
If you add multiple peers with the same labels, they became part of a DNS round-robin group for the shared label. This is useful to access services running on multiple nodes.
## Peer Auto-grouping
NetBird offers a powerful [access control feature](/manage/access-control/manage-network-access) that allows easy access management of your resources.
In a basic scenario, you would create multiple groups of peers and create access rules to define what groups can access each other.
Adding peers to groups might become time-consuming in large networks with dozens of machines.
Starting NetBird [v0.9.2](https://github.com/netbirdio/netbird/releases), when creating or updating a setup key,
it is possible to specify a list of auto-assign groups. Every peer registered with this key will be automatically added
to these groups. All the access control rules enabled for these groups will apply automatically.
To add `Auto-assign groups`, open the `Setup Keys` tab and create or update any existing setup key.
Then use this key to enroll new machine.
<p>
<img src="/docs-static/img/architecture/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" className="imagewrapper"/>
</p>
<Note>
Auto-assign groups will apply only to newly registered machines.
</Note>
## Create setup key
Go to the `Setup Keys` tab and click the `Create Setup Key` button
In the opened popup, give your new key an easily identifiable name, choose type, set usage limit, and assign auto groups.
The defaults should be suitable for most of the cases. We recommend using one-off keys for security reasons.
<p>
<img src="/docs-static/img/how-to-guides/add-setup-key.png" alt="high-level-dia" className="imagewrapper"/>
</p>
After your key has been successfully created, copy and store it in a secure location.
<p>
<img src="/docs-static/img/how-to-guides/setup-key-created.png" alt="high-level-dia" className="imagewrapper"/>
</p>

93
src/pages/how-to/resolve-overlapping-routes.mdx
View File

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

148
src/pages/how-to/routing-peers-and-kubernetes.mdx
View File

@@ -1,148 +0,0 @@
import {Note} from "@/components/mdx";
# Deploy routing peers to a Kubernetes cluster
This guide provides instructions on how to use NetBird agent within a Kubernetes cluster to establish secure, peer-to-peer
networking between your Kubernetes pods and external services or other clusters.
## Prerequisites
- Access to a Kubernetes cluster
- Kubernetes CLI (kubectl) installed and configured
- Access to the NetBird management dashboard
## Use Case Scenario
Imagine you're running a multi-cloud Kubernetes environment where your application components are distributed across
different cloud providers, including on-premise Kubernetes clusters. Your goal is to securely access your kubernetes services
from hosts running on a Hetzner without exposing them to the public internet.
## Step-by-Step guide
### Step 1: Create a setup key
Navigate to Setup Keys in the NetBird management dashboard and click on "Create setup key".
Choose a name, e.g. `Kubernetes routing peers`, mark the key as `reusable` and enable `Ephemeral peers`. This option is
ideal for stateless workloads like containers, where peers that are offline for over 10 minutes are automatically removed.
Create or add group called `kubernetes-routers` to the `Auto-assigned groups` list. This designation can be adjusted to
suit your needs.
See the screenshot below for reference:
<p>
<img src="/docs-static/img/how-to-guides/k8s-create-setup-key.png" alt="k8s-create-setup-key" width="400" className="imagewrapper"/>
</p>
With your setup key created, note it down for the next steps.
### Step 2: Add a network route
Navigate to Network Routes in the NetBird management dashboard and click on `Add Route`.
Set your kubernetes pod range as the destination network, and select the `Peer group` option, choosing the
"kubernetes-routers" group. This configuration allows for scaling pods as necessary within your Kubernetes cluster.
Set the distribution group to `hetzner-servers`. This group is used to distribute the route to all servers in the group.
See the screenshot below for reference:
<p>
<img src="/docs-static/img/how-to-guides/k8s-add-network-route.png" alt="k8s-add-network-route" width="400" className="imagewrapper"/>
</p>
Click on Name & Description to give your route a name and description. Then click on `Add Route` to save your changes.
<p>
<img src="/docs-static/img/how-to-guides/k8s-name-network-route.png" alt="k8s-name-network-route" width="400" className="imagewrapper"/>
</p>
### Step 3: Create an access control policy
Navigate to Access Control Policies in the NetBird management dashboard and click on `Add Policy`.
Set the source group to `hetzner-servers` and the destination group to `kubernetes-routers`. This configuration allows
the Hetzner servers to access the kubernetes pods.
<p>
<img src="/docs-static/img/how-to-guides/k8s-add-access-control-policy.png" alt="k8s-add-access-control-policy" width="400" className="imagewrapper"/>
</p>
Click on Name & Description to give your policy a name and description. Then click on `Add Policy` to save your changes.
<p>
<img src="/docs-static/img/how-to-guides/k8s-name-access-control-policy.png" alt="k8s-name-access-control-policy" width="400" className="imagewrapper"/>
</p>
### Step 4: Deploy the NetBird agent
You can deploy the NetBird agent using a daemon set or a deployment. Below is an example of a deployment configuration with 1 replica.
```yaml
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: netbird
namespace: default
spec:
replicas: 1
selector:
matchLabels:
app: netbird
template:
metadata:
labels:
app: netbird
spec:
containers:
- name: netbird
image: netbirdio/netbird:latest
env:
- name: NB_SETUP_KEY
value: "0000000000-0000-0000-0000-0000000000" # replace with your setup key
- name: NB_HOSTNAME
value: "netbird-k8s-router" # name that will appear in the management UI
- name: NB_LOG_LEVEL
value: "info"
securityContext:
capabilities:
add:
- NET_ADMIN
- SYS_RESOURCE
- SYS_ADMIN
```
Edit your deployment.yml file, incorporating the setup key into the relevant sections.
Apply the updated deployment file to your Kubernetes cluster using the following command:
```shell
kubectl apply -f deployment.yml
```
<Note>
In this example the setup key is passed as an environment variable. You should use a secret to pass the setup key.
</Note>
### Step 5: Make the deployment highly available
NetBird network routes support multiple routing peers running in a fail-over mode, where one routing peer will be select
as gateway for a network and when this peer becomes unavailable other routing peer will be select for the role, proving a
highly available network route.
To make the deployment highly available, you can increase the number of replicas in the deployment configuration to 3 or more.
```yaml
---
...
spec:
replicas: 3
...
```
Apply the updated deployment file to your Kubernetes cluster using the following command:
```shell
kubectl apply -f deployment.yml
```
### Step 6: Verify the deployment
After deploying the NetBird agent, you can verify that the agent is running by checking the logs of the pods.
```shell
kubectl logs -l app=netbird
```
You can also verify that the agent is connected to the NetBird management dashboard by checking the dashboard.
<p>
<img src="/docs-static/img/how-to-guides/k8s-netbird-agent-connected.png" alt="k8s-netbird-agent-connected" className="imagewrapper-big"/>
</p>
## 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.

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

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

366
src/pages/how-to/routing-traffic-to-private-networks.mdx
View File

@@ -1,366 +0,0 @@
# Routing Traffic to Private Networks
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/VQuPuBOAknQ" allow="fullscreen;"></iframe>
</div>
<br/><br/>
<Note>
**WARNING:** `Network Routes` will allow any traffic to pass through to the routed networks without regard for
the Access Control rules, unless you [configure those explicitly](./configuring-routes-with-access-control).
See [Network Routes caveats](#caveats) below for a more detailed explanation.
</Note>
NetBird provides fast and reliable end-to-end encryption between peers in your network. You can install the agent on every desktop, VM, container, or physical server to create a fast, secure peer-to-peer mesh network. This is the desired configuration, but some cases do not allow for agent installation or can slow down migration from legacy systems:
- Side-by-side migrations where part of your network is already using NetBird but needs to access services that are not.
- Systems that have limited operating system access, such as IoT devices, printers, and managed services.
- Legacy networks where an administrator is unable to install the agent on all nodes.
In these cases, you can configure network routes assigning routing peers to connect existing infrastructure. Routing peers will forward packets between your NetBird peers and your other networks; they can masquerade traffic going to your data centers or embedded devices, reducing the need for external route configuration and agent installation.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
<Note>
If you want to see the Network Routes feature in action, try our managed version at https://app.netbird.io/routes. It's free and easy to use.
</Note>
## Concepts
### Network routes
A network route describes the network you want to connect with your NetBird peers. It has an identifier, a network range or list of domains, a routing peer, and some parameters available for managing priority and masquerading.
<Note>
Network routes are available in NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
**Network identifiers and ranges** Network identifiers are names for each network you want to route traffic from your peers, and ranges are IP ranges declared in CIDR notation which refers to an external network. The combination of identifiers and these ranges makes a single network.
**Routing peer**: A routing peer is a peer that routes packets between your routed network and the other NetBird peers.
**Routing group**: A routing group is a set of routing peers. Each will route packets between your routed network and the other NetBird peers.
**High availability routes**: A highly available route is a combination of multiple routes with the same network identifier and ranges. They have different routing peers or routing peer groups offering highly available paths for communication between your peers and external networks.
Nodes connected to routing peers will choose one of them to route packets to external networks based on connection type and defined metrics.
**Masquerade**: Masquerade hides other NetBird network IPs behind the routing peer local address when accessing the target network range. This option allows access to your private networks without configuring routes on your local routers or other devices.
_If you do not enable this option, you must configure a route to your NetBird network in your external network infrastructure._
**DNS Routes**: An alternative to specifying a network range directly is to use DNS routes. Instead of adding the network directly, you can add multiple domains in a route that will be dynamically resolved on the client. The resolved IP addresses for these domains will be added as routes. For example, a network administrator can ensure that traffic to `website.com` or `api.website.com` is routed through a specific machine. So they configure DNS routes for these domains instead of specifying the IP ranges.
By default, DNS routes are resolved every 60 seconds. You can adjust this interval using the `--dns-router-interval` flag:
```bash
netbird up --dns-router-interval 30s
```
Additionally, the keep routes switch is enabled by default.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-dns-routes.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
When the keep routes switch is on, and a domain no longer resolves to an IP address, the corresponding route will still be maintained (and any new resolved IP addresses will be added).
If the switch is off, the routes will be replaced with the newly resolved IP addresses.
The purpose of the keep routes functionality is to retain previously resolved routes after IP address updates, in order to maintain stable connections. For example, long-running connections to an IP address that are still valid even if the DNS now resolves to a different IP address (e.g., DNS-based load balancing).
<Note>
DNS Routes are available for NetBird [v0.28.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
<Note>
Currently, wildcard domains are not supported for DNS routes.
</Note>
<Note>
DNS Forwarder port change: starting with NetBird v0.59.0, the local DNS forwarder used for routed DNS routes switches from port <code>5353</code> to <code>22054</code> to avoid collisions on client devices. For backward compatibility, the Management Service applies the new port only when <strong>all peers in the account</strong> run v0.59.0 or newer. If any peer is below v0.59.0, port <code>5353</code> will be used for all peers in that account.
</Note>
### Metric and priority
Metric defines prioritization when choosing the main routing peer in a high availability network. Lower metrics have higher priority.
Outside of high availability routes, the metric has no effect.
### Distribution groups
Distribution groups specify which peers will receive the network route. Peers that belong to the groups specified in this field will automatically receive the network route configuration.
<Note>
This does not remove the need for the routing peer to be connected to these peers.
</Note>
### Access Control Groups
Access Control Groups provide granular control over internal services within your network. They are used as destination
groups in access control policies, allowing you to precisely define which internal services can be accessed by
different network entities.
When you associate these groups with specific routes, the routes inherit the access control policies where
the groups are defined as destination groups. This setup enforces access restrictions based on the policies,
ensuring that only authorized traffic can reach the designated services.
Routes that do not incorporate these groups will permit unrestricted access, allowing all traffic to pass through
without any limitations.
## Managing Network Routes
A network route describes a network you want to connect with your NetBird peers. It has an identifier, a network range, a routing peer or set of peer groups, and some parameters available for managing priority and masquerading.
### Creating a Network Route
Access the `Network Routes` tab and click the `Add Route` button to create a new route.
This will open a route configuration screen where you can add the information about the network you want to route:
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-add-button.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Now you can enter the details of your route.
In the example below, we are creating a route with the following information:
- Network identifier: `aws-eu-central-1-vpc`
- Description: `Production VPC in Frankfurt`
- Network range: `172.31.0.0/16`
- Routing peer: `ec2-demo-node`
- Distribution Groups: `All`
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-create.png" alt="high-level-dia" className="imagewrapper" width="70%"/>
</p>
Once you fill in the route information, you can click on the `Add Route` button to save your new route.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-saved-new.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
The route has been created successfully. Now every peer connected to your routing peer will be able to send traffic to your external network.
### Creating a Network Route with Routing Group
You can use a peer group to automatically add any Linux peers from the groups as routing peers. To do so, follow the steps above but select the `Peer group` tab.
Ensure that the peer groups have Linux peers, as traffic routing is only supported on Linux machines.
Groups with multiple peers automatically provide [high availability routing](#high-availability-routes).
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-groups-create.png" alt="high-level-dia" className="imagewrapper" width="70%"/>
</p>
Once you fill in the route information, you can click on the `Add Route` button to save your new route.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-groups-saved-new.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
The route has been created successfully. Now every peer connected to the peer members of the groups will be able to send traffic to your external network.
### Creating highly available routes
To avoid a single point of failure when managing your network, we recommend installing NetBird on every resource. However, when running NetBird on every machine is not feasible, you still want to ensure a reliable connection to your private network. The NetBird Network Routes feature has a High Availability (HA) mode, allowing one or more NetBird peers to serve as routing peers for the same private network.
There are two options to enable HA routes:
1. Use a peer group with more than one peer in it.
2. Add more individual peers to the route.
The first option is covered [above](#creating-a-network-route-with-routing-group).
To enable the high-availability mode by adding individual peers, click on `Add Peer` in the High Availability column in the Network Routes
table and select a peer in the `Routing Peer` field. Then select the `Distribution Groups` and click on `Add Route`. This
routing configuration will be distributed to machines in the selected groups `Distribution Groups`.
In the following example, we are adding the peer `aws-nb-europe-router-az-b` to the `aws-eu-central-1-vpc` route:
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-create-ha.png" alt="high-level-dia" className="imagewrapper" width="70%"/>
</p>
This way, peers connected to `aws-nb-europe-router-az-a` and `aws-nb-europe-router-az-b` will have highly available access to the `172.31.0.0/16` network.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-saved-new-ha.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
<Note>
The number of routes that form a highly available route is unlimited.
Each connected peer will pick one routing peer to use as the router for a network.
NetBird agent bases this decision on metric prioritization (lower the metric, higher the priority) and connection attributes like direct or relayed connections.
</Note>
### Apply different routes to peers with group attribution
You can select as many distribution groups as you want for your network route.
Peers that belong to the specified group will use the route automatically to connect to the underlying network.
Remember to link groups to peers that need to access the route and, if required,
add access control rules ensuring connectivity between these peers and the routing peers.
In the following example (see column `Distribution Groups`), peers that belong to the group `berlin-office` will use
the `aws-nb-europe-router-az-a` routing peer to access the `aws-eu-central-1-vpc` network.
Peers that belong to the `london-office` group will use the `aws-nb-europe-router-az-b` routing peer.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-groups-attribution.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
### Routes without masquerading
If you want more transparency and would like to manage your external network routers, you may choose to disable masquerade for your network routes.
In this case, the routing peer will not hide any NetBird peer IP and will forward the packets to the target network transparently.
This will require a routing configuration on your external network router pointing your NetBird network back to your routing peer.
This way, devices that do not have the agent installed can communicate with your NetBird peers.
<p>
<img src="/docs-static/img/how-to-guides/netbird-network-routes-masquerading.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
## Network Routes caveats
Unless [configured explicitly](./configuring-routes-with-access-control), the **Network Routes** feature will not take into
consideration any of the Access Control rules. This might lead to surprising outcomes, which may initially appear to be security vulnerabilities.
**Important:** Understanding these caveats is essential for properly securing your network routes.
This has led us to create another, more intuitive design of **Networks** with their **Resources**, **Routers** and
mandatory **Groups** used for both access control and advertisement: your client will not "see" the resource
until it has access to its **Group**.
### Example: Network Route Configuration
Let's assume a **Network Route** is distributed through `Group R` (Routing Peer) to `Group A` (intended client):
<p>
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/route-ip-address.png" alt="route-ip-address" className="imagewrapper-big"/>
</p>
After creating an **Access Policy** granting `ICMP` access from `Group A` to `Group R`:
<p>
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/policy-icmp-group-r.png" alt="ICMP policy from group A to R" className="imagewrapper-big"/>
</p>
You will be able to access everything on the routed network without any restrictions.
This is because **Network Route** requires access to the **Routing Peer** to activate at all, which can be confusing.
```shell
root@brys-vm-nbt-ubuntu-01:~# netbird networks ls
Available Networks:
- ID: network-route-srvs-site
Network: 192.168.100.0/24
Status: Selected
root@brys-vm-nbt-ubuntu-01:~# ping -c1 192.168.100.10
PING 192.168.100.10 (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=63 time=0.521 ms
--- 192.168.100.10 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.521/0.521/0.521/0.000 ms
root@brys-vm-nbt-ubuntu-01:~# curl 192.168.100.10/health && echo
OK
```
### Setting up a Network Resource secured by HTTP policy
In the following example, we set up a **Network Resource** for a `*.nb.test` wildcard domain
using ACL group `manual:srvs`:
<p>
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/resource-domain.png" alt="*.nb.test domain Resource" className="imagewrapper-big"/>
</p>
Granting HTTP-only access to that resource from group `manual:client`:
<p>
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/policy-http.png" alt="a HTTP-only policy from manual:client group" className="imagewrapper-big"/>
</p>
Everything appears to be set up correctly. We have HTTP access and can confirm the domain was resolved:
```shell
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
Available Networks:
- ID: *.nb.test
Domains: *.nb.test
Status: Selected
Resolved IPs: -
root@brys-vm-nbt-ubuntu-02:~# curl srv.nb.test/health; echo
OK
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
Available Networks:
- ID: *.nb.test
Domains: *.nb.test
Status: Selected
Resolved IPs:
[srv.nb.test.]: 192.168.100.10
```
Before finishing, let's verify that only HTTP access is granted:
```shell
root@brys-vm-nbt-ubuntu-02:~# ping -c1 srv.nb.test
PING srv.nb.test (192.168.100.10) 56(84) bytes of data.
64 bytes from 192.168.100.10: icmp_seq=1 ttl=63 time=0.242 ms
--- srv.nb.test ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.242/0.242/0.242/0.000 ms
```
However, this reveals an unexpected behavior:
```shell
root@brys-vm-nbt-ubuntu-02:~# ssh srv.nb.test
root@srv.nb.test: Permission denied (publickey).
```
Did we inadvertently grant access to the **Network Route**?
```shell
root@brys-vm-nbt-ubuntu-02:~# netbird networks ls
Available Networks:
- ID: *.nb.test
Domains: *.nb.test
Status: Selected
Resolved IPs:
[srv.nb.test.]: 192.168.100.10
```
This does not appear to be the case.
### Why did we get ping and SSH access for the domain?
Unrestricted access to the `srv.nb.test` domain was granted, because we have used the same **Routing Peer**
for both **Network Route** and the newly created **Network**:
<p>
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/network-routers.png" alt="Network's `manual:router:srvs` router" className="imagewrapper-big"/>
</p>
Here are this specific **Routing Peer**'s details:
<p>
<img src="/docs-static/img/how-to-guides/routing-traffic-to-private-networks/routing-peer-groups.png" alt="Routing Peer's detail page with Network Route handling" className="imagewrapper-big"/>
</p>
It is a member of both routing groups:
1. `m:group-r` to advertise the **Network Route**,
2. `manual:router:srvs` to advertise the **Network** and its domain **Resource**,
<Note>
You can address the "overflowing permissions" issue by setting up a dedicated set of **Routing Peers**
to handle the **Network Routes** and never using those for anything else (especially **Networks**).
While this is achievable, it is extremely easy to miss during configuration.
</Note>
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

171
src/pages/how-to/secure-remote-webserver-access.mdx
View File

@@ -1,171 +0,0 @@
# Secure Remote Web Server Access: SSH Without Port Exposure
For DevOps teams, secure remote web server access is a critical challenge. Traditionally, remote SSH access has been the go-to solution since it uses the SSH (Secure Shell) protocol to create encrypted network connections, ensuring data confidentiality and integrity while authenticating users and devices.
The problem is that conventional remote SSH access introduces security and operational challenges:
* **Increased Attack Surface**: Exposing SSH ports to the internet creates potential entry points for attackers, increasing the risk of unauthorized access and security breaches.
* **Complex Network Configuration**: Configuring firewall rules and VPN setups for each server becomes unmanageable as the infrastructure scales.
* **Cumbersome User Access Management**: Lack of centralized management makes enforcing consistent access policies and maintaining audit trails difficult.
This guide introduces NetBird as a secure solution for remote SSH access into a server without compromising safety by:
* **Enhancing Security**: Creating a secure overlay network that implements zero-trust principles, eliminating the need for exposed inbound ports.
* **Simplifying Network Management**: Simplifying network architecture and removing the need for complex firewall rules or VPN configurations.
* **Centralizing Access Control**: Providing a unified platform for managing user access across all servers, simplifying policy enforcement and auditing.
This approach enhances security, simplifies operations, and improves scalability - key benefits for DevOps teams managing diverse environments and requiring frequent SSH into a server.
Let's dive into the step-by-step process of setting up this secure remote access solution with NetBird.
## Prerequisites
For this use case, you'll need the following prerequisites:
* A [NetBird account](https://app.netbird.io/)
* Single Sign-On (SSO) authentication set up with your preferred identity provider (optional but recommended for enhanced security).
* [NetBird installed](/get-started/install) on your local machine.
* A virtual machine running your target web server, configured to accept incoming SSH connections.
With prerequisites in place, you'll be prepared to establish an encrypted point-to-point connection between your local machine and the remote web server by:
1. Installing NetBird on the cloud VM hosting the web service
2. Configuring NetBird's access control to manage permissions
3. Establishing a secure SSH connection to access the internal web service
## 1. Installing NetBird on the Remote Server
Login to NetBird and navigate to `Peers`. Ensure you see your local peer connected.
![NetBird Local Peer](/docs-static/img/how-to-guides/peers/owyUeUn.png)
To add your remote web server to NetBird's peer network, first you need to generate a setup key:
* Navigate to `Setup Keys` in the left menu
* Click `Create Setup Key`
* Configure the key by assigning it a descriptive name (e.g., "Remote Web Server"), setting an expiration date, and defining auto-assigned groups (if required). Read the documentation for [detailed setup key configuration](/how-to/register-machines-using-setup-keys).
* Copy the generated key to a secure location as you'll need it shortly
![NetBird Creating Setup Key](/docs-static/img/how-to-guides/peers/jQ5rhEb.png)
Next, install the NetBird agent on the VM.
* SSH into the remote server
* Execute the following command:
```shell
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
The script downloads and installs the NetBird agent and starts the NetBird service. After installation, you'll see:
```shell
Netbird service has been started
Installation has been finished. To connect, you need to run NetBird by executing the following command:
netbird up
```
However, since you'll use a setup key, you'll need to run the following command instead, replacing `<YOUR_SETUP_KEY>` with the key you generated::
```shell
netbird up --setup-key <YOUR_SETUP_KEY>
```
Check NetBird status by running:
```shell
sudo netbird status
```
The expected output is similar to the following:
```shell
OS: linux/amd64
Daemon version: 0.29.0
CLI version: 0.29.0
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 0/0 Available
FQDN: webserver.netbird.cloud
NetBird IP: 100.85.105.240/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 0/0 Connected
```
Now, go back to NetBird's `Peers` dashboard and ensure your remote web server is connected.
![NetBird Peers Network](/docs-static/img/how-to-guides/peers/8I1WVEx.png)
## 2. Configuring NetBird Access Control Policies
With both peers now connected to NetBird, the next step is to configure access control rules. This step is essential to define and restrict who can access the remote server, enhancing security by limiting connections to authorized users or devices only.
* In NetBird's left menu, navigate to `Access Control > Policies`
* Click `Add Policy` to create a new one.
NetBird offers a range of options for peer access control. For comprehensive details on configuring groups and access policies, refer to the official documentation: [Managing Access with NetBird: Groups and Access Policies](/manage/access-control/manage-network-access).
For this specific use case, we've implemented a simple access policy:
* **Source Group**: `Freelancers`
* **Destination Group**: `Testing Environment`
* **Protocol**: TCP
* **Port**: 22 (SSH)
* **Action**: Allow
This policy restricts SSH access to the `Testing Environment`, permitting only authorized members from the group `Freelancers` to connect.
![NetBird Access Policy](/docs-static/img/how-to-guides/peers/AgB9Asr.png)
After establishing the policy, assign peers to their respective groups. To add the remote web server to the `Testing Environment` group:
* Navigate to `Peers` in the left menu
* Click on the name of the peer you want to edit, in this case, `webserver`
* Find the `Assigned Groups` field and select `Testing Environment` from the dropdown list.
![NetBird Web Server Peer](/docs-static/img/how-to-guides/peers/QXb6lLs.png)
While you're there, take note of the IP addresses listed on the left. Use the quick copy buttons to get `NetBird IP-Address` and `Domain Name`. Alternatively, you can hover over the peer in the peers' list and copy the IP addresses as shown below:
![NetBird IP Addresses](/docs-static/img/how-to-guides/peers/EVZssES.png)
With your remote server configured and the corresponding access policy enabled, the final step is to assign users to the appropriate group:
* Locate your user in the peers' list and click on it
* Find the `Assigned Groups` field and select `Freelancers` from the dropdown list.
![NetBird Local User Peer](/docs-static/img/how-to-guides/peers/LoNxwd4.png)
## 3. Establishing a Secure SSH Connection to Access the Internal Web Service
NetBird streamlines secure connections without traditional firewall complexities. Throughout this setup, you've implemented access controls without configuring a single firewall rule on any endpoint. This simplicity doesn't compromise security; instead, it enhances it through intuitive, group-based policies.
To verify your setup, simply ping the web server from a third-party device outside of the NetBird network using the web server's NetBird-assigned IP:
![Terminal No Access to Web Server](/docs-static/img/how-to-guides/peers/iHiFujr.png)
There is no response from the host. Now, ping the web server from your configured local machine:
![Terminal Access to Web Server](/docs-static/img/how-to-guides/peers/HKsAcFE.png)
As expected, all packets were transmitted. Now, you can securely SSH into your remote web server from your local peer, either using the NetBird-assigned domain name or IP address:
![Terminal SSH into Web Server using NetBird domain](https://imgur.com/itP1poM.png)
This straightforward test confirms your successful implementation of a secure, firewall-free connection to your remote web server via NetBird, demonstrating its power in simplifying robust network security.
![Terminal Fastfetch from Web Server](/docs-static/img/how-to-guides/peers/YoECY8k.png)
## Get Started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

214
src/pages/how-to/setup-keys-add-servers-to-network.mdx
View File

@@ -1,214 +0,0 @@
# Add Servers to the Network with Setup Keys
For DevOps teams managing complex infrastructures, adding new servers or containers to the network is a persistent challenge. Traditionally, manual configuration and individual setup processes have been the norm, often leading to time-consuming, error-prone, and potentially insecure deployments.
The problem with conventional server and container network integration methods includes:
* **Time-Intensive Setup**: Manually configuring each new server or container for network access can be tedious and time-consuming, especially in rapidly scaling environments.
* **Scalability Limitations**: As infrastructure grows, the complexity of managing network access for numerous servers and containers increases exponentially.
* **Security Risks**: Manual processes can lead to human errors, potentially exposing servers to unauthorized access or creating security loopholes in the network.
This guide introduces [NetBird's Setup Keys](/how-to/register-machines-using-setup-keys) as an elegant solution for seamlessly and securely adding servers and containers to your network by:
* **Streamlining Deployment**: Providing a simple, automated way to connect new servers and containers to your NetBird network with minimal manual intervention.
* **Facilitating Scalability**: Enabling rapid expansion of your network infrastructure without compromising on security or operational efficiency.
* **Enhancing Security**: Implementing a secure, automated process that reduces the risk of human error and unauthorized access, strengthening your overall security posture.
This approach significantly reduces deployment time, ensures consistent and secure network configurations, and supports seamless scalability.
Let's dive into the step-by-step process of using [NetBird's Setup Keys](/how-to/register-machines-using-setup-keys) to securely add a server with a Docker container to your network.
## Prerequisites
For this tutorial, you'll need the following prerequisites:
* A [NetBird account](https://app.netbird.io/)
* The [NetBird agent](https://docs.netbird.io/get-started/install) installed in your local machine
* A cloud-hosted virtual machine (VM) with SSH access
* [Docker](https://www.docker.com/) installed on the cloud VM
With these prerequisites in place, you'll be prepared to set up a secure network connection using NetBird's Setup Keys by:
1. Creating a Setup Key in your NetBird account
2. Provisioning a VM and installing NetBird using the Setup Key
3. Deploying a Docker container on the VM
4. Connecting the Docker container to the NetBird network using the Setup Key
This process will demonstrate how Setup Keys simplify and secure the addition of new servers and containers to your NetBird network.
## Creating a Setup Key in Your NetBird Account
To seamlessly integrate virtual machines or Docker containers into your NetBird network, you'll start by creating a setup key. While [NetBird's documentation offers comprehensive guidance on this process](https://docs.netbird.io/how-to/register-machines-using-setup-keys), let's quickly review the essential steps:
* Access your NetBird dashboard
* Navigate to the `Setup Keys` section
* Click the `Create Setup Key` button on the right
* Name your key (e.g., "VM-Docker-Demo")
* Set an expiration date (recommended for enhanced security)
* Configure auto-assigned groups if needed
* Click `Create Setup Key` to generate the setup key
* Copy the generated key and store it securely as you'll need it for the next steps
Here's an example:
![NetBird Generating Setup Key](/docs-static/img/how-to-guides/setup-keys-add-servers-to-network/setup-keys-add-server-01.png)
This setup key will serve as your secure passport for adding both your VM and Docker container to the NetBird network,
ensuring a consistent integration process.
<Note>
The Setup Key expiration date applies only to the key's validity period for adding new peers to the network.
Once a peer is connected using the setup key, the expiration date does not affect the peer's network access.
</Note>
## Provisioning a VM and Installing NetBird Using the Setup Key
After creating your setup key, the next step is to provision your VM and install NetBird:
* SSH into your cloud-hosted VM
* [Install NetBird](https://docs.netbird.io/get-started/install) by running:
```bash
curl -fsSL https://pkgs.netbird.io/install.sh | sh
```
Once installation completes, connect to the NetBird network using your setup key:
```bash
netbird up --setup-key <YOUR_SETUP_KEY>
```
Verify NetBird's status:
```bash
netbird status
```
You should see output confirming the connection status, assigned IP, and peer information.
```bash
OS: linux/amd64
Daemon version: 0.29.4
CLI version: 0.29.4
Management: Connected
Signal: Connected
Relays: 2/2 Available
Nameservers: 0/0 Available
FQDN: docker-vm.netbird.cloud
NetBird IP: 100.85.148.249/16
Interface type: Kernel
Quantum resistance: false
Routes: -
Peers count: 0/0 Connected
```
You can also check the NetBird service status by running:
```bash
sudo systemctl status netbird
```
This should show the service as active and running.
```bash
● netbird.service - A WireGuard-based mesh network that connects your devices into a single private network.
Loaded: loaded (/etc/systemd/system/netbird.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2024-09-24 19:22:56 UTC; 52s ago
Main PID: 3819 (netbird)
Tasks: 7 (limit: 1011)
Memory: 26.3M
CPU: 113ms
CGroup: /system.slice/netbird.service
└─3819 /usr/bin/netbird service run --config /etc/netbird/config.json --log-level info --daemon-ad
```
Next, ensure NetBird starts automatically on boot:
```bash
sudo systemctl enable netbird
```
Finally, log into your NetBird dashboard and navigate to the `Peers` section to confirm your VM is listed and connected.
![NetBird Peers View](/docs-static/img/how-to-guides/setup-keys-add-servers-to-network/setup-keys-add-server-02.png)
By using the setup key, you've securely added your VM to the NetBird network with minimal manual configuration, demonstrating the efficiency and security benefits of this approach.
## Deploying a Docker Container on the VM
To test NetBird's secure point-to-point connection, we'll deploy a simple Docker container with a Nginx-based web server serving a welcome page.
Create a directory for the Docker project:
```bash
mkdir netbird-demo && cd netbird-demo
```
Create a HTML file with the welcome message:
```bash
echo "<html><body><h1>Welcome to NetBird Demo</h1><p>If you can see this, you've successfully connected to the container via NetBird.</p></body></html>" > index.html
```
Create a `Dockerfile`:
```bash
cat << EOF > Dockerfile
FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html
EOF
```
Next, build and run the Docker container using the commands:
```bash
docker build -t netbird-demo .
docker run -d --name netbird-demo-container -p 8080:80 netbird-demo
```
Notice that the container is accessible on port `8080` of the VM. You'll use this port to test the connection.
## Connecting the Docker Container to the NetBird Network Using the Setup Key
Now that your VM is connected to the NetBird secure network, you can verify the connection using either `curl` or your web browser. Simply use the NetBird-assigned IP address or domain for the VM to access the deployed web server.
To locate the NetBird-assigned IP or domain, go to the `Peers` page in your NetBird dashboard and hover your cursor over the VM's name.
![NetBird Peers IP Address or Domain](/docs-static/img/how-to-guides/setup-keys-add-servers-to-network/setup-keys-add-server-03.png)
Verify connectivity to the VM from any NetBird-connected device using:
```bash
curl http://<NETBIRD_IP>:8080
```
The expected output should be similar to the following:
```bash
$ curl 100.85.148.249:8080
<html><body><h1>Welcome to NetBird Demo</h1><p>If you can see this, you've successfully connected to the container via NetBird.</p></body></html>
```
Alternatively, you can go to `http://VM_NETBIRD_DOMAIN:8080` using your browser:
![NetBird Welcome Page](/docs-static/img/how-to-guides/setup-keys-add-servers-to-network/setup-keys-add-server-04.png)
Keep in mind that this tutorial used the default `All` group for simplicity. However, implementing [NetBird's Access Policy](https://docs.netbird.io/manage/access-control/manage-network-access) to restrict peer-to-peer connections to specific user groups is a best practice for gaining granular control over resource access, thus improving your network's overall security posture in various scenarios.
## Optional: Automating SSH Access to Your VM
To further enhance your network security, you can enable SSH access to your VM via an embedded NetBird SSH server.
This feature allows you to securely access your VM with SSH without exposing it to the public internet and without the need
for distributing and managing SSH keys. To enable NetBird SSH access, run the following command on your VM:
```bash
netbird up --allow-server-ssh
```
You can then use the NetBird SSH client to connect to your VM:
```bash
sudo netbird ssh <NETBIRD_DOMAIN | NETBIRD_IP>
```
Summing up, NetBird's setup keys solve the challenge of securely connecting unattended resources, streamlining the integration of servers and containers without user intervention. For those looking to scale, the [NetBird API](https://docs.netbird.io/api/resources/setup-keys) offers powerful automation capabilities, allowing programmatic management of peers, setup keys, and access policies. These features combine to create a robust, secure, and easily manageable network infrastructure that adapts to your organization's needs.

249
src/pages/how-to/single-sign-on.mdx
View File

@@ -1,249 +0,0 @@
import {Note} from "@/components/mdx";
# Authenticate to NetBird with Single Sign On (SSO)
NetBird works out of the box with popular Identity Providers (IdPs) such as Google Workspace, Microsoft Entra ID, and Okta,
offering seamless Single Sign-On (SSO) for your users.
It also supports social logins including Google, GitHub, and Microsoft accounts.
For other OIDC (OpenID Connect)-compliant IdPs like Authentik, Keycloak, JumpCloud, and others, NetBird provides full support,
though some additional configuration is required to complete the integration.
<Note>
This guide covers the setup for cloud-hosted NetBird. If you are using the self-hosted version, please refer
to the [self-hosted documentation](/selfhosted/identity-providers).
</Note>
## Google, Microsoft, and GitHub
If you're using Google Workspace, Microsoft Entra ID, or a supported social login, you can simply sign in with no extra
setup—just click the appropriate button on the [login page](https://app.netbird.io/):
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/netbird-login.png" alt="netbird-login" className="imagewrapper"/>
</p>
## Okta
If you are using Okta as your Identity Provider, sign up with any email address and then follow the steps described
in [this guide](/how-to/okta-sync#get-started-with-net-bird-okta-integration)
## OIDC-compliant IdPs
For OIDC-compliant Identity Providers such as **Authentik**, **Keycloak**, and others, you’ll need to configure the IdP
to integrate with NetBird. Below are the steps to set up different OIDC-compliant IdPs with NetBird.
<Note>
Support for OIDC-compliant IdPs is available on the Team plan and higher.
The Free plan supports Google, Microsoft, and social logins.
</Note>
### Authentik
1. You need to create a new Application and Provider.
- Browse to the Applications Administration menu, click on Application, and then click on Create with Provider:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/1-create-with-provider.png" alt="create-with-provider" className="imagewrapper-big"/>
</p>
- Name the Application and select a suitable explicit user flow. In the example below, we used NetBird:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/2-new-application.png" alt="new-application" className="imagewrapper-big"/>
</p>
- Click Next and select the OAuth2/OpenID Provider Type:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/3-new-application-type.png" alt="new-application" className="imagewrapper-big"/>
</p>
- Click Next and select an explicit user authorization flow, then take note of the Client ID and Client Secret:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/4-new-application-client-id.png" alt="new-application" className="imagewrapper-big"/>
</p>
- Add the following redirect URL and select a signing key: <br/>
URL: `https://login.netbird.io/login/callback`
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/5-new-application-sign.png" alt="new-application" className="imagewrapper-big"/>
</p>
- Click on Advanced protocol settings and ensure that the email, opened, and profile scopes are selected and that Based on the User’s Hash ID is selected for Subject mode:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/6-new-application-scopes.png" alt="new-application" className="imagewrapper-big"/>
</p>
- Click Next on the following two screens and Submit to create the provider and application:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/7-new-application-submit.png" alt="new-application" className="imagewrapper-big"/>
</p>
- You should see an application listed as follow:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/8-list-applications.png" alt="list-applications" className="imagewrapper-big"/>
</p>
2. We need to copy the OpenID Configuration URL for the new provider. You can do that by navigating to Providers in the left menu and then selecting the newly created provider. There you should see a windows similar to the following:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/authentik-idp/9-list-providers.png" alt="list-providers" className="imagewrapper-big"/>
</p>
- Copy the OpenID Configuration URL.
3. Then, share the following information with the NetBird support team at support@netbird.io:
- Client ID
- Client Secret
- OpenID Configuration URL
- Email domains for your users
<Note>
We recommend using a secure channel to share the Client’s secret. You can send a separate email and use a secret sharing service like: <br/>
https://onetimesecret.com/en/ <br/>
https://password.link/en
</Note>
### Keycloak
1. You need to create a new client
- Browse to the clients Administration menu and then click in Create client:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/keycloak-idp/1-new-client.png" alt="new-client" className="imagewrapper-big"/>
</p>
2. Create a client with the type OpenID Connect and add any client ID and name for the client:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/keycloak-idp/2-new-client-type.png" alt="new-client" className="imagewrapper-big"/>
</p>
3. Click Next and enable the following options for Capability config:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/keycloak-idp/3-new-client-capability.png" alt="new-client" className="imagewrapper-big"/>
</p>
4. Click Next and fill the following fields:
Valid redirect URIs: `https://login.netbird.io/login/callback` <br/>
Web origins: `+`
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/keycloak-idp/4-new-client-callback.png" alt="new-client" className="imagewrapper-big"/>
</p>
5. Click Save.
6. Next we need to retrieve the secret for the client, you can get that in the Credentials tab for the client:
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/keycloak-idp/5-new-client-credentials.png" alt="new-client" className="imagewrapper-big"/>
</p>
7. Then, share the following information with the NetBird support team at support@netbird.io:
- Client ID
- Keycloak URL
- Realm
- Client Secret
- Email domains for your users
<Note>
We recommend using a secure channel to share the Client’s secret. You can send a separate email and use a secret sharing service like: <br/>
https://onetimesecret.com/en/ <br/>
https://password.link/en
</Note>
### JumpCloud
1. Access the JumpCloud and navigate to USER AUTHENTICATION > SSO Applications
2. Click + Add New Application, select Custom Application and click Next
3. Enable Manage Single Sign-On (SSO), select Configure SSO with OIDC and click Next
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/jumpcloud-idp/jumpcloud-sso.png" alt="jumpcloud" className="imagewrapper-big"/>
</p>
4. Add NetBird as Display Label and click Next. Optionally, you can enter a Description, adjust the User Portal Image and choose to hide or Show in User Portal.
5. Review the application setting and click Configure Application to proceed
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/jumpcloud-idp/jumpcloud-sso-config.png" alt="jumpcloud-idp" className="imagewrapper-big"/>
</p>
6. On the New Application screen, go to the SSO tab and under Endpoint Configuration set the following values:
- Redirect URIs: https://login.netbird.io/login/callback
- Login URL: https://app.netbird.io
7. Under Attribute Mapping enable Email and Profile scopes
<Note>
Sometimes, the Jumpcloud application configuration will add duplicate attributes, like email and email_verified. The duplicates should be removed.
</Note>
8. Go to the User Groups and select the list of groups to which you want to give access to the application and then click activate
9. Record the Client ID and Client Secret that JumpCloud generates for your application.
10. Share your Client ID, and Client Secret with our team. Please use a secure method for sharing this information.
<Note>
We recommend using a secure channel to share the Client’s secret. You can send a separate email and use a secret sharing service like: <br/>
- https://onetimesecret.com/en/ <br/>
- https://password.link/en <br/>
</Note>
### Auth0
1. Access the [Auth0 console](https://manage.auth0.com/) and navigate to Applications > Applications
2. Click **+ Create Application**
3. Enter **NetBird** as the name, select **Single Page Web Applications** as the application type and click **Create**
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/auth0-idp/application-create.png" alt="auth0-application-create" className="imagewrapper-big"/>
</p>
4. On the New Application screen, go to the Settings tab and under Application URIs set the following values:
- Application Login URI: https://app.netbird.io
- Allowed Callback URLs: https://login.netbird.io/login/callback
- Allowed Logout URLs: https://app.netbird.io
- Allowed Web Origins: https://app.netbird.io
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/auth0-idp/application-configure.png" alt="auth0-application-configure" className="imagewrapper-big"/>
</p>
6. Record the **Client ID** and **Client Secret** that Auth0 generates for your application.
7. Retrieve Application's **Domain** from the **Basic Information** tab
<p>
<img src="/docs-static/img/how-to-guides/single-sign-on/auth0-idp/application-domain.png" alt="auth0-application-domain" className="imagewrapper-big"/>
</p>
8. Share following with our team. Please use a secure method for sharing the sensitive parts of this information:
1. Application's **Domain**,
2. (sensitive) **Client ID** and **Client Secret**,
3. list of email domains to be registered for this SSO configuration,
<Note>
We recommend using a secure channel to share the Client’s secret. You can send a separate email and use a secret sharing service like: <br/>
- https://onetimesecret.com/en/ <br/>
- https://password.link/en <br/>
</Note>

572
src/pages/how-to/ssh.mdx
View File

@@ -1,572 +0,0 @@
import {Note} from "@/components/mdx";
# SSH Access
NetBird provides SSH access to peers through its built-in SSH server. Unlike traditional SSH setups that require exposing port 22 to the internet, NetBird SSH operates entirely over your private network. You can connect using either the `netbird ssh` command or native OpenSSH clients.
<Note>
SSH Access is disabled by default and must be enabled both on the target
peer and in the NetBird Dashboard.
</Note>
## Concepts
### SSH Server
Each NetBird peer can run an embedded SSH server by enabling `--allow-server-ssh`. From the peer's perspective the session arrives on its normal port (TCP 22); internally it's re-routed to the NetBird client on port 22022.
Management may automatically ensure the mesh access policy permits 22022 for a peer when the policy explicitly allows port 22 (or a range containing 22) and the peer advertises native SSH support (NetBird v0.60.0+). That access policy is distributed by the management plane; enforcement and forwarding are performed by the NetBird client on the peer.
### Authentication Methods
- **JWT Authentication (default)**: Maps SSH sessions to user identities via your configured Identity Provider (OIDC). Each new session will require completing the OIDC flow to mint the JWT used for SSH authentication (unless JWT caching is enabled, in which case JWT tokens are cached for a configurable duration).
- **Machine Identity (`--disable-ssh-auth`)**: When SSH auth is disabled, SSH access is governed by NetBird network ACLs (machine-level access) rather than per-user JWT identity.
### OpenSSH Integration
NetBird can provide configuration so the remote peer's OpenSSH clients behave transparently. The remote peer's NetBird client performs interception and JWT handling; NetBird may install OpenSSH configuration snippets on the client to simplify usage. The interception and forwarding logic lives in the remote peer's NetBird client, not the management server.
### Port 22 Redirection
The management server does not edit your host OS firewall or perform OS-level port redirects. The model is:
- **22** - the standard SSH port used by SSH clients and the local SSH daemon.
- **22022** - the NetBird-native endpoint used by the NetBird client on remote peers. When NetBird SSH is enabled for a peer, standard SSH traffic is redirected here.
**Behavior:**
- A modern NetBird client can intercept an `ssh user@remote` (which targets remote:22) and redirect the SSH stream to the NetBird client on port 22022.
- Management will auto-add a NetBird access-policy rule for 22022 when a policy allows 22 (or a range containing 22) and the peer supports native SSH (v0.60.0+) and SSH is enabled on the peer in the NetBird dashboard.
## Requirements
To use SSH access through NetBird, you need:
1. **NetBird v0.60.0 or later** on peers that should support native SSH (dev/development versions are treated as supporting native SSH).
2. **SSH enabled on target peer** - the peer must run with `--allow-server-ssh`.
3. **SSH enabled in Dashboard** - SSH access must be enabled for the peer and ServerSSHAllowed set in the peer meta.
4. **Access Control Policy** - an ACL rule allowing TCP port 22 for the peer (management will auto-add 22022 behind the scenes for modern peers).
5. **(Optional)** For JWT authentication: an Identity Provider configured in NetBird.
<Note>
Management distributes NetBird access-policy objects (FirewallRule) - it does
not directly open host OS ports or edit host-level firewalls. Enforcement and
forwarding are handled by the NetBird client running on each peer.
</Note>
## Enabling SSH
### Step 1: Enable SSH Server on Target Peer
On the machine you want to access via SSH, enable the NetBird SSH server.
**Using the GUI:**
1. Click on the NetBird tray icon
2. Navigate to Settings
3. Click on **Allow SSH** to enable the SSH server
<p>
<img src="/docs-static/img/ssh/ssh-client.png" alt="netbird ssh client"
className="imagewrapper"/>
</p>
**Using the CLI:**
```bash
netbird down # if NetBird is already running
netbird up --allow-server-ssh
```
For additional SSH server features, use these flags:
```bash
netbird up --allow-server-ssh \
--enable-ssh-local-port-forwarding \
--enable-ssh-remote-port-forwarding \
--enable-ssh-sftp \
--enable-ssh-root
```
**Flag Reference:**
- `--allow-server-ssh`: Enable the SSH server
- `--enable-ssh-local-port-forwarding`: Allow clients to forward local ports through the server
- `--enable-ssh-remote-port-forwarding`: Allow clients to request remote port forwarding
- `--enable-ssh-sftp`: Enable SFTP subsystem for file transfers
- `--enable-ssh-root`: Allow root user login (use with caution)
- `--disable-ssh-auth`: Disable JWT authentication (allows any peer with network access)
- `--ssh-jwt-cache-ttl <seconds>`: Enable JWT token caching with specified TTL in seconds (default: 0, disabled)
### Step 2: Create Access Control Policy
Create an ACL policy to allow SSH access:
1. Log in to your NetBird Dashboard
2. Navigate to **Access Control**
3. Create a new policy:
- **Source**: Select the peers or groups that will connect via SSH
- **Destination**: Select the peers or groups running the SSH server
- **Protocol**: TCP
- **Ports**: 22
- **Action**: Accept
4. Save the policy
### Step 3: Enable SSH in Dashboard
Enable SSH on individual peers:
1. Navigate to the target peer details page
2. Enable SSH access for the peer
3. Save the changes
<p>
<img src="/docs-static/img/ssh/ssh-dashboard.png"
alt="netbird ssh dashboard" className="imagewrapper-big"/>
</p>
## Using NetBird SSH
### NetBird CLI Client
The simplest way to connect is using the `netbird ssh` command:
```bash
netbird ssh user@100.119.230.104
```
**Execute a single command:**
```bash
netbird ssh user@100.119.230.104 "uptime"
```
**Port forwarding:**
```bash
# Local port forwarding: forward local port 8080 to remote port 80
netbird ssh -L 8080:localhost:80 user@100.119.230.104
# Remote port forwarding: forward remote port 8080 to local port 3000
netbird ssh -R 8080:localhost:3000 user@100.119.230.104
```
For detailed CLI usage, see the [CLI documentation](/get-started/cli#ssh).
### Native SSH Clients (OpenSSH)
NetBird automatically configures OpenSSH through a drop-in configuration file.
<Note>
Currently, only OpenSSH clients are supported. Other SSH clients (PuTTY,
etc.) are not compatible.
</Note>
**Prerequisites:**
NetBird creates `/etc/ssh/ssh_config.d/99-netbird.conf` (or equivalent on your OS) which automatically:
1. Detects if the target is a NetBird SSH server
2. Handles JWT authentication transparently
3. Handles server host key verification
**Using OpenSSH:**
```bash
# Connect using standard SSH
ssh user@100.119.230.104
# Port forwarding
ssh -L 8080:localhost:80 user@100.119.230.104
# SFTP
sftp user@100.119.230.104
# SCP
scp file.txt user@100.119.230.104:/path/to/destination
```
**How it works:**
When you run `ssh user@<netbird-peer>`:
1. OpenSSH reads the NetBird configuration from `99-netbird.conf`
2. NetBird detects if the target is a NetBird SSH server
3. If detected, NetBird handles JWT authentication automatically (OIDC flow if needed)
4. The SSH connection is established with your user identity
### Browser Client
For SSH access directly from your web browser without installing any software, refer to the [Browser Client documentation](/how-to/browser-client#ssh-connection).
## Authentication
### JWT Authentication (Default)
By default, NetBird SSH uses JWT-based authentication with the configured Identity Provider. This provides user identity verification instead of machine identity.
<Note>
Currently, SSH access is controlled by ACL policies and the
`--enable-ssh-root` flag. Users connect as either root (if enabled) or
admin-equivalent users on Windows. In the future, NetBird will support more
granular user mapping, allowing OIDC user X to connect to specific local
users (PAM/local) on the target system.
</Note>
<Note type="warning">
**Time synchronization required**: The SSH server's system clock must be
synchronized with the IdP for JWT validation. Clock skew can cause
authentication failures.
</Note>
**How it works:**
1. When you connect via SSH, the NetBird client requests a JWT token
2. If no cached token exists or the token is expired:
- NetBird initiates an OIDC flow
- A URL is displayed that you must open in your browser to authenticate with the IdP
- After successful login, NetBird receives and caches the JWT token
3. The client sends the JWT to the SSH server
4. The server validates the JWT using the JWKS endpoint configured in the management server
5. If valid, the SSH session is established with the user identity from the JWT
**Benefits:**
- **User identity**: SSH sessions are associated with actual users, not machines
- **Centralized auth**: Leverage the configured IdP (Okta, Google, Microsoft, etc.)
- **Audit trail**: Know exactly which user accessed which machine
- **Token expiration**: Automatic re-authentication when tokens expire
**Token caching:**
By default, JWT tokens are **not cached**, meaning you'll need to authenticate for each new SSH connection. To enable token caching and reduce authentication prompts on the **SSH client machine**, use the `--ssh-jwt-cache-ttl` flag:
```bash
# On the SSH client: enable caching with 1-hour TTL
netbird up --ssh-jwt-cache-ttl 3600
# On the SSH client: disable caching (default)
netbird up --ssh-jwt-cache-ttl 0
```
**When caching is disabled (default):**
- You'll authenticate via OIDC for each new SSH connection
- More secure but less convenient
- Recommended for high-security environments
**When caching is enabled:**
- JWT tokens are cached on the client for the specified TTL in seconds
- Reduces repeated authentication prompts
- Cached tokens expire after the configured TTL or when the NetBird daemon is restarted
### Machine Identity (--disable-ssh-auth)
If you prefer to allow SSH access from any peer with network access (similar to pre-0.60 behavior), you can disable JWT authentication:
```bash
netbird up --allow-server-ssh --disable-ssh-auth
```
**Important considerations:**
- **Less secure**: Any peer with network access (ACL policy) can connect
- **Machine identity**: Connections are identified by peer/machine, not by user
- **No audit trail**: You cannot track which user accessed the system
- **Use cases**: Automated scripts, service accounts, environments without IdP
<Note type="warning">
When JWT authentication is disabled, SSH access is controlled solely by
network-level ACL policies. Ensure your policies are appropriately
restrictive.
</Note>
## Advanced Features
### Port Forwarding
NetBird SSH supports both local and remote port forwarding, allowing you to create secure tunnels through the SSH connection.
**Local Port Forwarding:**
Forward a local port on your machine to a remote address through the SSH server:
```bash
# Forward local port 8080 to remote localhost:80
netbird ssh -L 8080:localhost:80 user@100.119.230.104
# Forward local port 5432 to a database accessible from the remote peer
netbird ssh -L 5432:database.internal:5432 user@100.119.230.104
```
Use case: Access a web service or database running on the remote peer or in its network.
**Remote Port Forwarding:**
Forward a port on the remote SSH server to your local machine:
```bash
# Forward remote port 8080 to local port 3000
netbird ssh -R 8080:localhost:3000 user@100.119.230.104
```
Use case: Allow the remote peer to access a service running on your local machine.
<Note>
Port forwarding must be enabled on the SSH server using
`--enable-ssh-local-port-forwarding` and
`--enable-ssh-remote-port-forwarding` flags.
</Note>
### SFTP and SCP
Transfer files securely using native SFTP or SCP clients:
**SFTP:**
```bash
sftp user@100.119.230.104
```
**SCP:**
```bash
# Upload file
scp file.txt user@100.119.230.104:/path/to/destination
# Download file
scp user@100.119.230.104:/path/to/file.txt .
# Copy directory
scp -r directory/ user@100.119.230.104:/path/to/destination
```
<Note>
SFTP must be enabled on the SSH server using the `--enable-ssh-sftp` flag.
SFTP and SCP require native OpenSSH clients.
</Note>
### Non-interactive Command Execution
Execute commands on remote peers without an interactive shell:
```bash
netbird ssh user@100.119.230.104 "uptime"
```
## Platform Support & Limitations
### Supported Platforms
NetBird SSH is supported on the following platforms:
- **Linux**: Full support (all features)
- **macOS**: Full support (all features)
- **Windows**: Full support with platform-specific considerations (see below)
- **FreeBSD**: Full support (all features)
- **Android**: Server-only support (SSH client not available)
### Platform-Specific Considerations
#### Windows
- **Port forwarding not supported**: SSH servers on Windows cannot accept port forwarding requests
- **Other features supported**: SFTP, non-interactive commands fully functional
#### Linux/Unix
- **User Switching**: Available when running as root
- The SSH server can switch to any user when running with root privileges
- Non-root NetBird (e.g., rootless containers) will run sessions under the given account
- **All features supported**: Full feature parity across these platforms
#### Android
- **Server-only**: SSH client functionality not available
- **Server features**: Can run NetBird SSH server (configured via GUI)
## Known Limitations
### Port Forwarding
Port forwarding has the following limitations:
- **Not supported with native SSH clients**: Port forwarding (both local `-L` and remote `-R`) is **only available** when using the `netbird ssh` command directly
- Native OpenSSH clients **cannot** use port forwarding
- This is a current implementation limitation
- Use `netbird ssh -L` or `netbird ssh -R` instead of `ssh -L` or `ssh -R`
- **Not supported on Windows servers**: SSH servers running on Windows cannot accept port forwarding requests
- **No user switching with port forwarding**: Port forwarding only works when connecting as the user running the NetBird process
### User Mapping
- **Current behavior**: SSH sessions connect as either:
- The `root` user on Linux/Unix (if `--enable-ssh-root` is enabled)
- Administrator-equivalent users on Windows
- The SSH server's service account (if user switching is unavailable)
- **Future enhancement**: Planned support for granular user mapping (OIDC user → specific local user)
- **PAM integration**: Linux/Unix PAM integration is planned for more flexible authentication
### Feature Availability
Some features require specific flags to be enabled on the SSH server:
- **SFTP**: Requires `--enable-ssh-sftp`
- **Local port forwarding**: Requires `--enable-ssh-local-port-forwarding`
- **Remote port forwarding**: Requires `--enable-ssh-remote-port-forwarding`
- **Root login**: Requires `--enable-ssh-root` (use with caution)
## Security Considerations
### Access Control
SSH access is controlled by multiple layers:
1. **Network ACL policies**: Control which peers can access SSH over the mesh. Management will auto-add the mesh-native endpoint (22022) for a peer when the policy explicitly allows port 22 (or a range containing 22) and the peer advertises native SSH support (NetBird v0.60.0+).
2. **SSH enabled in dashboard**: Per-peer SSH access toggle
3. **JWT authentication** (if enabled): User identity verification via IdP
## Troubleshooting
### Connection Issues
**"SSH server not detected"** or **"Permission denied (publickey)"** or **"No more authentication methods available"**
- Ensure the target peer is running with `--allow-server-ssh`
- Verify SSH is enabled in the dashboard for the target peer
- Check that the target peer is online and connected
**"Authentication failed"** (JWT authentication)
- Complete the OIDC flow when prompted
- Verify the IdP is properly configured
- Check if your JWT token is expired (NetBird will request a new one)
- Ensure the SSH server's system clock is synchronized (time skew causes JWT validation failures)
- For `--disable-ssh-auth`: Ensure ACL policy allows access
**"Connection timeout"**
- Verify ACL policy allows TCP port 22
- Check if peers are connected to each other: `netbird status -d`
- Test basic connectivity: `ping <peer-ip>`
### Port Forwarding Issues
**"Port forwarding not available"**
- Ensure the SSH server was started with appropriate flags:
- `--enable-ssh-local-port-forwarding` for local forwarding
- `--enable-ssh-remote-port-forwarding` for remote forwarding
**"Cannot bind to port"**
- For local forwarding: Ensure the local port is not already in use
- For remote forwarding: Ensure the remote port is available
### SFTP Issues
**"SFTP subsystem not available"**
- Ensure the SSH server was started with `--enable-ssh-sftp`
**"Permission denied"**
- Check file system permissions on the target peer
- Verify you're connecting with the correct user
## CLI Reference
For complete CLI command reference, including all SSH-related commands and flags, see the [CLI documentation](/get-started/cli#ssh).
## Migrating from v0.59.x and Earlier
<Note>
This section is only relevant if you're upgrading from NetBird v0.59.x or
earlier. New installations can skip this section.
</Note>
### What Changed in v0.60.0
Version 0.60.0 is a complete rewrite with breaking changes:
**New capabilities:**
- OpenSSH client support via automatic proxy configuration
- Windows client and server support
- SFTP subsystem for file transfers
- Local and remote port forwarding (`netbird ssh` only)
- Non-interactive command execution
- Configurable JWT token caching
**Breaking changes:**
- Server port changed from 44338 to 22 (22022 internally)
- Authentication changed from machine public keys to JWT tokens (user identity)
- Port 22 automatically redirects to 22022 for NetBird traffic
- Old implicit firewall rule removed - explicit ACL policy required for port 22
- Client no longer requires `sudo` for authentication
- **Not backward compatible**: v0.60.0+ clients cannot connect to older servers and vice versa
### Upgrade Steps
<Note type="warning">
**Self-hosted deployments:** Update order is important:
1. Management server
2. Dashboard (optional - only if you use browser-based SSH)
3. **SSH servers first** (peers running `--allow-server-ssh`)
4. SSH clients last (peers using `netbird ssh`)
New clients cannot connect to old servers, so update servers before clients.
</Note>
#### For Self-Hosted Deployments
1. **Update management server** to v0.60.0 or later
- Verify server is running correctly
- Confirm JWKS endpoint is accessible
2. **Update dashboard** (optional)
- Only needed if you use the browser-based SSH client
- Maintains browser SSH access during peer migration
3. **Create ACL policy** for port 22:
```
Source: [SSH Client Group/Peers]
Destination: [SSH Server Group/Peers]
Protocol: TCP
Port: 22
Action: Accept
```
4. **Update SSH servers FIRST** (peers running `--allow-server-ssh`)
- Start with non-critical peers for testing
- Old clients can still connect to updated servers
5. **Update SSH clients LAST** (peers using `netbird ssh`)
- Updated clients cannot connect to old servers
- This is why servers must be updated first
#### Optional Configuration
Disable JWT authentication on SSH servers (allows network-level access without user auth):
```bash
netbird up --allow-server-ssh --disable-ssh-auth
```
Enable JWT token caching on SSH clients (reduces auth prompts):
```bash
netbird up --ssh-jwt-cache-ttl 3600 # 1 hour
```
<Note>
The browser-based SSH client in the dashboard remains compatible with both
old and new peer versions.
</Note>
## Get started
<p float="center">
<Button name="button" className="button-5"
onClick={() => window.open("https://netbird.io/pricing")}>Use
NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub

69
src/pages/how-to/stream-activity-to-amazon-firehose.mdx
View File

@@ -1,69 +0,0 @@
# Stream Network Activity to Amazon Data Firehose
[Amazon Data Firehose](https://docs.aws.amazon.com/firehose/) is a fully managed service for delivering real-time streaming data to destinations such as Amazon Simple Storage Service (Amazon S3), Amazon Redshift,
an other AWS services. You can use Amazon Data Firehose as a bridge between NetBird and other third-party providers that support Data Firehose
to ingest, transform and analyze your network activity events.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start creating and configuring an Amazon Data Firehose event streaming integration, ensure that you have the following:
- An AWS account with the permissions to create and manage Data Firehose delivery streams.
- Permissions to create and manage IAM users, roles and policies.
If you don't have the required permissions, ask your AWS administrator to grant them to you.
## Create a Data Firehose Stream
- Navigate to the [Data Firehose Dashboard](https://console.aws.amazon.com/firehose/home)
- Click `Create Firehose stream`
- As source select `Direct PUT` and the desired destination
- Give it a descriptive name like `netbird-activity-events` and configure the stream to your needs
## Create an IAM User
- Navigate to the [IAM Dashboard](https://console.aws.amazon.com/iam/home)
- Create an IAM User (for details see the [Amazon Docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html))
- Create a custom policy with the following permissions (replace the resource with the ARN of your delivery stream):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"firehose:PutRecord",
"firehose:PutRecordBatch"
],
"Resource": "arn:aws:firehose:region:accountID:deliverystream/netbird-event-streaming"
}
]
}
```
- Attach the policy to the IAM user
- Select the user and navigate to the `Security credentials` tab
- Click `Create access key`
- Select `Third-party service` and click `Next`
- Give it a description
- Store `Access key` and `Secret access key` in a secure place. You will need these when configuring an integration in NetBird.
## Create an Integration in NetBird
- Navigate to the [Integrations &raquo; Event Streaming](https://preview.netbird.io/integrations) tab in the NetBird dashboard
<p>
<img src="/docs-static/img/how-to-guides/event-streaming-integration.png" alt="event-streaming-integration" className="imagewrapper-big"/>
</p>
- Enable and configure the `Amazon Data Firehose` integration
- First select the region your Firehose stream is created in
<p>
<img src="/docs-static/img/how-to-guides/firehose-region-select.png" alt="firehose-region-select" className="imagewrapper" />
</p>
- Then enter the Firehose stream name you created in [Step 1](#step-1-create-a-data-firehose-stream) and click `Next`
<p>
<img src="/docs-static/img/how-to-guides/firehose-stream-name.png" alt="firehose-stream-name" className="imagewrapper" />
</p>
- Enter the `Access key` and `Secret access key` you created in [Step 2](#step-2-create-an-iam-user-2) and click `Connect`
<p>
<img src="/docs-static/img/how-to-guides/firehose-iam-credentials.png" alt="firehose-iam-credentials" className="imagewrapper" />
</p>

119
src/pages/how-to/stream-activity-to-amazon-s3.mdx
View File

@@ -1,119 +0,0 @@
# Stream Network Activity to Amazon S3
[Amazon Simple Storage Service (Amazon S3)](https://aws.amazon.com/s3/) is a scalable, high-speed, web-based cloud storage service.
You can use Amazon S3 to store and analyze large amounts of data, including network activity events from NetBird.
NetBird integrates with Amazon S3 and sends activity events to an S3 bucket in real-time once they occur. For every event,
NetBird creates a new object in the S3 bucket, which you can then analyze, filter, and query using Amazon tools.
Storing one event per object is not the most efficient way to save data in S3, therefore NetBird provides an
[alternative integration](/how-to/stream-activity-to-amazon-firehose) that uses Amazon Data Firehose for a more efficient
data ingestion.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start creating and configuring an Amazon S3 event streaming integration, ensure that you have the following:
- An AWS account with the permissions to create and manage S3 buckets.
- Permissions to create and manage IAM users, roles and policies.
If you don't have the required permissions, ask your AWS administrator to grant them to you.
## Create an S3 Bucket
- Navigate to the [S3 dashboard](https://console.aws.amazon.com/s3/home)
- Select the correct region in the top menu
- Click `Create bucket`
- Give it a descriptive name like `netbird-activity-events`
- (Optional) Change bucket configurations to your needs
- Click `Create bucket`
## Create an IAM User
- Navigate to the [IAM Dashboard](https://console.aws.amazon.com/iam/home)
- Create an IAM User (for details see the [Amazon Docs](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html))
- Create a custom policy with the following permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::netbird-activity-events/*"
}
]
}
```
- Attach the policy to the IAM user
- Select the user and navigate to the `Security credentials` tab
- Click `Create access key`
- Select `Third-party service` and click `Next`
- Give it a description
- Store `Access key` and `Secret access key` in a secure place. You will need these when configuring an integration in NetBird.
## Create an Integration in NetBird
- Navigate to the [Integrations &raquo; Event Streaming](https://preview.netbird.io/integrations) tab in the NetBird dashboard
<p>
<img src="/docs-static/img/how-to-guides/event-streaming-integration.png" alt="event-streaming-integration" className="imagewrapper-big"/>
</p>
- Enable and configure the `Amazon S3` integration
- First select the region your S3 bucket is created in
<p>
<img src="/docs-static/img/how-to-guides/s3-region-select.png" alt="s3-region-select" className="imagewrapper" />
</p>
- Then enter the S3 bucket name you created in [Step 1](#step-1-create-an-s3-bucket) and click `Next`
<p>
<img src="/docs-static/img/how-to-guides/s3-bucket-name.png" alt="s3-bucket-name" className="imagewrapper"/>
</p>
- Enter the `Access key` and `Secret access key` you created in [Step 2](#step-2-create-an-iam-user) and click `Connect`
<p>
<img src="/docs-static/img/how-to-guides/s3-iam-credentials.png" alt="s3-iam-credentials" className="imagewrapper" />
</p>
## Verify the Integration
After configuring the integration in NetBird, you can verify that the integration is working correctly by checking
the S3 bucket for newly created objects. If the integration is successful, you should see two `.json` files in your bucket
containing the following events:
- `integration test`
- `integration created`
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/verify-amazon-s3-integration.png" alt="verify-amazon-s3-integration" className="imagewrapper-big" />
</p>
```json
{
"timestamp": "2024-04-11T19:01:05.381074+02:00",
"message": "integration test",
"id": 0,
"initiator_id": "netbird",
"target_id": "netbird",
"meta": null,
"reference": ""
}
```
```json
{
"timestamp": "2024-04-11T19:01:08.769292+02:00",
"message": "integration created",
"id": 0,
"initiator_id": "netbird",
"target_id": "netbird",
"meta": null,
"reference": ""
}
```
The integration test event is sent to validate whether the provided credentials are correct and NetBird can stream events.
The integration created event is sent when the integration is successfully created.
The integration is now set up and ready to stream network activity events to Amazon S3.

59
src/pages/how-to/stream-activity-to-datadog.mdx
View File

@@ -1,59 +0,0 @@
# Stream Network Activity to Datadog Cloud SIEM
Datadog is a monitoring and analytics platform for cloud-scale applications. Datadog Cloud SIEM provides real-time threat
detection and security monitoring for cloud environments. By using the NetBird-Datadog integration, you can stream [network activity](/how-to/monitor-system-and-network-activity) to Datadog Cloud SIEM for real-time monitoring
and threat detection across your private network.
NetBird integrates with Datadog using the [Datadog Log Collection HTTP API](https://docs.datadoghq.com/api/latest/logs/#send-logs)
and sends activity events to Datadog in real-time once they occur. The events appear in the [Datadog Log Explorer](https://docs.datadoghq.com/logs/explorer/), where you can
search, filter, and analyze them right away.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start creating and configuring a Datadog event streaming integration, ensure that you have the following:
- A Datadog account with permissions to create and manage API keys. If you don't have the required permissions,
ask your Datadog administrator to grant them to you.
## Create a Datdog API Key
- Navigate to the [API Keys](https://app.datadoghq.eu/organization-settings/api-keys) page
- Click `+ New Key` at the top
- Give it a descriptive name like `NetBird Event Streaming`
- Click `Create Key`
- Copy the key. You will need this key when configuring an integration in NetBird.
## Create an Integration in NetBird
- Navigate to the [Integrations &raquo; Event Streaming](https://preview.netbird.io/integrations) tab in the NetBird Dashboard
<p>
<img src="/docs-static/img/how-to-guides/event-streaming-integration.png" alt="event-streaming-integration" className="imagewrapper-big"/>
</p>
- Enable and configure the Datadog integration
- First select the region of your Datadog account (for more details see [Datadog Documentation](https://docs.datadoghq.com/getting_started/site/))
<p>
<img src="/docs-static/img/how-to-guides/datadog-region-select.png" alt="datadog-region-select" className="imagewrapper" />
</p>
- Then enter the API key you created in [Step 1](#step-1-create-a-datdog-api-key) and click `Connect`
<p>
<img src="/docs-static/img/how-to-guides/datadog-api-key.png" alt="datadog-api-key" className="imagewrapper" />
</p>
## Verify the Integration
After configuring the Datadog integration in NetBird, you can verify that the integration is working correctly by checking
the Datadog Log Explorer for incoming events. If the integration is successful, you should see two events from the netbird service
in the Log Explorer:
- `integration test`
- `integration created`
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/verify-datadog-integration.png" alt="verify-datadog-integration" className="imagewrapper"/>
</p>
The `integration test` event is sent to validate whether the provided credentials are correct and NetBird can stream events.
The `integration created` event is sent when the integration is successfully created.
The integration is now set up and ready to stream network activity events to Datadog.

102
src/pages/how-to/stream-activity-to-generic-http.mdx
View File

@@ -1,102 +0,0 @@
# Stream Network Activity to a Generic HTTP Endpoint
The Generic HTTP integration allows you to stream your NetBird network activity events to any custom HTTP/S endpoint. This provides a flexible way to connect NetBird with a wide range of third-party systems, including custom SIEMs, log management tools like Grafana Loki, or any service that can receive POST requests.
For every event, NetBird will send a POST request to your configured endpoint. You have full control over the request's body format and headers, allowing for seamless integration with various APIs.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start, ensure you have an HTTP/S endpoint that is publicly accessible and ready to receive POST requests from NetBird. You will also need any necessary authentication details, such as an API key or credentials for Basic Authentication.
## Create an Integration in NetBird
1. Navigate to the **Integrations** tab in the NetBird dashboard and select **Event Streaming**.
2. Find the **Generic HTTP** option and click **Connect**.
3. A configuration panel will open with several tabs: **General**, **Headers**, **Body Template**, and **Danger Zone**.
### General Configuration
This tab is for the essential endpoint details.
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/generic-http/general-config.png" alt="Generic HTTP General Configuration" className="imagewrapper-big"/>
</p>
- **Endpoint URL**: Enter the full HTTPS or HTTP URL where NetBird should send the events. This field is mandatory.
- **Authentication**: Select the authentication method required by your endpoint.
- **No Authentication**: Sends requests without an `Authorization` header.
- **Bearer Token**: Adds an `Authorization: Bearer <your-token>` header to each request. You will need to provide your API key or token.
- **Basic Auth**: Adds an `Authorization: Basic <credentials>` header. You must provide the credentials in the format `username:password`.
- **Custom Authentication**: Allows you to specify a custom HTTP header for authentication. You will need to provide both the header name (e.g., `X-API-Key`) and its value.
<Note>
After saving the integration, the configured authentication details will be converted into an HTTP header and will appear in the **Headers** tab.
</Note>
### HTTP Headers (Optional)
You can add custom HTTP headers to every outgoing request in the **Headers** tab. This is useful for passing static tokens, setting a custom `Content-Type`, or other API requirements. By default, the `Content-Type` is `application/json`.
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/generic-http/headers-config.png" alt="Generic HTTP Headers Configuration" className="imagewrapper-big"/>
</p>
### Custom Body Template (Optional)
The **Body Template** tab gives you powerful control over the structure of the JSON payload sent to your endpoint.
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/generic-http/body-template-config.png" alt="Generic HTTP Body Template Configuration" className="imagewrapper-big"/>
</p>
If this option is disabled, NetBird sends a default JSON object for each event. When enabled, you can define your own payload structure using Go's `text/template` templating engine.
This is especially useful for integrating with services that expect a specific format, like Grafana Loki.
#### Available Template Variables
You can use the following variables from the `StreamEvent` object in your template:
| Variable | Type | Description | Example Usage |
|---------------|----------------------|--------------------------------------------------------------------------------------|-----------------------------------|
| `.ID` | `any` | The unique ID of the event. | `{"event_id": "{{.ID}}"}` |
| `.Timestamp` | `time.Time` | The timestamp of when the event occurred. Can be formatted. | `{{.Timestamp.UnixNano}}` / `{{.Timestamp.Format "2006-01-02T15:04:05.999Z07:00"}}` |
| `.Message` | `string` | A human-readable message describing the event. | `{"text": "{{.Message}}"}` |
| `.InitiatorID`| `string` | The ID of the object that initiated the event (e.g., a user or peer ID). | `{"user": "{{.InitiatorID}}"}` |
| `.TargetID` | `string` | The ID of the object that was affected by the event (e.g., a peer or group ID). | `{"resource": "{{.TargetID}}"}` |
| `.Meta` | `map[string]any` | A map containing additional metadata about the event. | `{"source": "{{.Meta.source}}"}` |
| `.Reference` | `string` | A URL to the event in the NetBird activity log for easy cross-referencing. | `{"ref": "{{.Reference}}"}` |
### Danger Zone
This tab allows you to delete the integration. This action is irreversible and will immediately stop events from being sent to your endpoint.
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/generic-http/danger-zone.png" alt="Generic HTTP Danger Zone" className="imagewrapper-big"/>
</p>
After configuring all settings, click **Save Changes**.
## Verify the Integration
Once you save the integration, NetBird sends a test event to your endpoint to confirm that the connection and authentication are successful.
Check the logs of your receiving service for a new POST request. You should find a JSON payload similar to this (if custom template wasn't set up):
```json
{
"ID": "test-event-1685635200",
"Timestamp": "2025-06-01T16:00:00Z",
"Message": "integration test event for generic http endpoint",
"InitiatorID": "netbird-test-system",
"TargetID": "target-id",
"Meta": {
"purpose": "configuration-test",
"source": "netbird-test"
},
"Reference": "netbird:test:generichttp"
}

77
src/pages/how-to/stream-activity-to-sentinelone-data-lake.mdx
View File

@@ -1,77 +0,0 @@
# Stream Network Activity to SentinelOne Singularity Data Lake
[SentinelOne Singularity Data Lake](https://www.sentinelone.com/platform/data-lake/) provides a centralized repository for storing and analyzing security data across your organization. By streaming NetBird network activity events to SentinelOne Data Lake, you can correlate network connectivity events with endpoint security data for comprehensive threat detection and investigation.
This integration leverages NetBird's Generic HTTP streaming capability with SentinelOne Singularity Data Lake-specific configurations to ensure seamless data ingestion into your Data Lake environment.
<Note>
This feature is only available in the cloud version of NetBird.
</Note>
## Prerequisites
Before you start creating and configuring a SentinelOne Singularity Data Lake event streaming integration, ensure that you have the following:
- A SentinelOne account with Singularity Data Lake access and appropriate permissions
- Administrative access to create API keys in your SentinelOne console
## Create a SentinelOne API Token
- Log in to your SentinelOne Management Console and navigate to **Visibility** from the left menu
- Click on your user email dropdown in the top right toolbar and select **API Keys**
- Under the **Log Access Keys** section, click **Add Key** dropdown menu and select **Add Write Key**
- A new API key will be created with access to write logs to Data Lake
- Click **Copy to Clipboard** and store this token securely. You will need this token when configuring the integration in NetBird.
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/sentinelone-data-lake/api-key-generation.png" alt="API Key Generation" className="imagewrapper-big"/>
</p>
## Get the HEC Ingestion URL
Navigate to `https://<your-tenant>.sentinelone.net/docs/en/http-event-collector--hec-.html#http-event-collector--hec-` (replace `<your-tenant>` with your actual SentinelOne tenant)
to find and copy the HTTP Event Collector base URL from the documentation page. The URL format will be `https://ingest.<region>.sentinelone.net` where `<region>` is your deployment region.
## Create an Integration in NetBird
- Navigate to the **Integrations** tab in the NetBird dashboard and select **Event Streaming**
- Find the **Generic HTTP** option and click **Connect Generic HTTP**
- Configure the endpoint URL by entering the full HEC endpoint URL: `https://ingest.<region>.sentinelone.net/services/collector/event`
- Select **Bearer Token** for authentication and provide the API token you created earlier
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/sentinelone-data-lake/general-settings.png" alt="General Settings Configuration" className="imagewrapper-big"/>
</p>
- Enable the custom body template and use the following template optimized for SentinelOne Singularity Data Lake:
```json
{
"id": "{{.ID}}",
"time": "{{.Timestamp.UnixNano}}",
"event": "{{.Message}}",
"initiator_id": "{{.InitiatorID}}",
"target_id": "{{.TargetID}}",
"host": "netbird",
"source": "netbird",
"sourcetype": "json",
"fields": "{{.Meta}}"
}
```
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/sentinelone-data-lake/custom-template.png" alt="Custom Template Configuration" className="imagewrapper-big"/>
</p>
## Verify the Integration
After configuring the SentinelOne Singularity Data Lake integration in NetBird, you can verify that the integration is working correctly by checking the SentinelOne Singularity Data Lake for incoming events. If the integration is successful, you should see test events from NetBird in your Data Lake.
- Navigate to **Data Lake** > **Search** > **New Search** in your SentinelOne console
- Select to search **All Data** and filter for recent events with source **netbird**
- Verify the test events appear with the expected structure
<p>
<img src="/docs-static/img/how-to-guides/activity-event-streaming/sentinelone-data-lake/verify-integration.png" alt="Verify Integration" className="imagewrapper-big"/>
</p>
The integration is now set up and ready to stream network activity events to SentinelOne Singularity Data Lake.

361
src/pages/how-to/traffic-events-logging.mdx
View File

@@ -1,361 +0,0 @@
# Traffic Events Logging
<Note>
This feature is available only in the NetBird cloud under the [Business plan](https://www.netbird.io/pricing?utm_source=docs&utm_content=traffic-events).
This is feature is in Beta and may change over time — including how data is collected and reported.
To use this feature, make sure you're running NetBird client version 0.39 or higher.
</Note>
The traffic events logging functionality enables comprehensive monitoring and analysis of connections across your infrastructure.
It captures network activity, including peer-to-peer, site-to-site, peer-to-resource, and other network traffic events.
It provides detailed visibility into connections and network traffic flow, helping to answer key questions such as who initiated
the connection, what resource was accessed, when it happened, where it originated, and why it was allowed. By enhancing
network monitoring capabilities, it strengthens security measures and delivers actionable operational insights, empowering
you to better manage and secure your environment.
## How Traffic Events Logging Works
NetBird offers flexibility as a peer-to-peer (p2p) overlay network and a remote network access solution. You can use NetBird to connect
machines directly (p2p) when running the NetBird client on each machine. You can also use NetBird to organize remote employee access
to internal networks like VPCs, office networks, and internal services without running the NetBird client on the remote resources using the [NetBird Networks](/how-to/networks) feature.
The way you use NetBird influences the way traffic events are captured and logged. Below are the two main scenarios for traffic events logging
that describe how NetBird logs traffic events for different types of connections.
### Peer-to-Peer Connections
When two peers are connected directly (p2p), NetBird captures and logs the traffic events for that connection on both peers.
For example, if a user accessed an internal CRM server from their laptop via a browser and port 443, NetBird would log the traffic events for that
connection on both the user's machine and the CRM server. If the connection was blocked, such as when there is a
[policy](/manage/access-control/manage-network-access#managing-policies) that restricts access to the CRM server,
NetBird would log the blocked event on the peer that refused the connection.
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/p2p-traffic-events.png" alt="traffic-events-p2p-diagram" className="imagewrapper-big"/>
</p>
#### Successful P2P Connection Events
NetBird helps you better understand connection flows by correlating related events and presenting them in a clear, organized manner.
For example, in a successful peer-to-peer connection scenario, a user initiates a connection from the peer `Alice` to the peer `server`.
This is illustrated in the screenshot below.
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/p2p-successful-connection.png" alt="traffic-events-p2p-successful-connection" className="imagewrapper-big"/>
</p>
You'll see two grouped sets of events, one from each peer (source and destination). The source peer `Alice` initiates the
connection and then terminates it after a few seconds.
On the other side, the destination peer `server` receives the connection request and also terminates it shortly afterward,
following the disconnection from `Alice`. Since `server` allows the connection, the log includes the policy `IT Admins to Servers`
that authorized the connection over the `ICMP` protocol.
<Note>
Use the `P2P` filter in the table to view only peer-to-peer connection events.
</Note>
#### Blocked P2P Connections Events
If a connection is refused, NetBird logs the blocked event on the peer that denies the connection, in this case, `server`.
The initiating peer `Alice` will still report the connection attempt but won't be aware that it was blocked.
In this scenario, the `IT Admins to Servers` policy is configured to allow only ping requests (`ICMP`),
meaning all `HTTP` requests are intentionally not allowed. The screenshot below illustrates this behavior.
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/p2p-blocked-connection.png" alt="traffic-events-p2p-blocked-connection" className="imagewrapper-big"/>
</p>
### Peer-to-Network Resource Connections
When a peer connects to a [network resource](/how-to/networks#resources), NetBird captures and logs the traffic
events for that connection on the peer that initiated the connection, and on the [routing peer](/how-to/networks#routing-peers) that connects the peer to
the internal network resource.
A slightly modified example of the CRM server connection scenario would be if instead of running the NetBird client on the CRM server,
you used the [NetBird Networks feature](/how-to/networks) and created a network resource for the CRM server. In this case, if a user accessed an internal CRM from their laptop via a browser
and port 443, NetBird would log the traffic events for that connection on the user's machine and the routing peer that
routed the connection to the CRM server. If the connection was blocked, NetBird would log the blocked event on the routing peer.
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/routed-traffic-events.png" alt="traffic-events-routed-diagram" className="imagewrapper-big"/>
</p>
#### Successful Peer-to-Network Resource Events
The screenshot below illustrates a successful connection from `Alice` to the network resource `CRM` running in the AWS VPC.
The traffic is routed through a routing peer, which logs the connection event and reports it to the NetBird servers.
The access is permitted by the policy `IT Admins to AWS Servers`, which allows connections over the `TCP` protocol on port `443`.
Note the `ROUTER` column in the table, which identifies the routing peer responsible for routing to the internal network resource.
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/network-resource-successful-connection.png" alt="network-resource-succesful-connection" className="imagewrapper-big"/>
</p>
<Note>
Use the `Routed` filter in the table to view only peer-to-network resource connection events.
</Note>
#### Blocked Peer-to-Network Resource Events
In the event of a blocked connection, the initiating peer logs the connection attempt, while the routing peer records the blocked event.
The screenshot below demonstrates this behavior: the routing peer blocks a connection to the network resource `CRM` because
the policy `IT Admins to AWS Servers` does not permit connections over the `HTTP` protocol on port `6432`.
You can see multiple blocked events reported by the routing peer, which indicates that the initiating peer `Alice` attempted to connect multiple times
in one TCP session, but the routing peer blocked all attempts.
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/network-resource-blocked-connection.png" alt="network-resource-succesful-connection" className="imagewrapper-big"/>
</p>
<Note>
For all the examples above, we used the `nc` command to initiate the connection to the CRM server from the peer `Alice`.
E.g., `nc -v crm.netbird.cloud 443`.
</Note>
## Enabling Traffic Events Logging
Traffic events logging feature is disabled by default. To enable it on the NetBird dashboard, navigate to `Settings > Networks`.
Under the Experimental section, you'll find the `Enable Traffic Events` option. Toggle the switch to enable traffic event logging.
By default, traffic reporting in userspace is always enabled, providing basic logging of network interactions.
However, packet size reporting at the kernel level is disabled by default to minimize CPU usage.
<Note>
You can optionally enable `Traffic Reporting (Kernel)` to capture additional details, such as network packet sizes,
at the kernel level. Be aware that enabling this option may lead to higher CPU usage on the NetBird client.
</Note>
<p>
<img src="/docs-static/img/how-to-guides/traffic-events-logging-settings.png" alt="traffic-events-logging-settings" className="imagewrapper-big"/>
</p>
### Limiting Traffic Events to Specific Groups
You can scope traffic events logging to only the peers that belong to specific groups.
- When you select one or more groups, only peers that are members of the selected groups will report traffic events.
- If no group is selected, logging applies to all peers in the account (default behavior).
To configure this setting, navigate to `Settings > Networks` in the Experimental section, open the Group Selector under `Enable Traffic Events`
choose the groups you want to include, and click `Save Groups`.
<p>
<img src="/docs-static/img/how-to-guides/traffic-events-groups-logging-settings.png" alt="traffic-events-groups-logging-settings" className="imagewrapper-big"/>
</p>
## Log Retention
While in experimental mode, logs are retained for **seven days**.
Additionally, please note that the current API returns a maximum of **50,000 events**.
We are actively working on expanding this limit in the coming days to support larger datasets and increased usage.
## Report rate
The events might take up to **ten minutes** to become available via API and Dashboard. For some TCP connections, the full event cycle might take longer, depending on OS settings and connection termination.
## Enable Traffic Events Streaming to SIEM Systems
NetBird allows you to stream traffic events directly to your Security Information and Event Management (SIEM) system in real time.
By enabling this feature, you can seamlessly monitor and analyze NetBird network flow events within your existing SIEM infrastructure,
enhancing your ability to detect and respond to security events.
For detailed instructions on supported integrations and how to set them up, refer to the [integrations guide](/how-to/activity-event-streaming).
## Traffic Events Data
When enabled, a NetBird peer will record metadata for each network flow that it participates in. The data collected by peers includes:
* **Timestamp**: When the flow started and ended.
* **Flow ID**: A unique identifier for the traffic event flow.
* **Type**: The type of traffic event, such as Start, End, or Blocked.
* **Source and Destination IP Addresses**: The IP of the peer (source) and the IP of the remote endpoint (destination). For peer-to-peer traffic,
these will be the NetBird network IPs (e.g. 100.x.x.x addresses of each peer). For traffic to an external resource (like a private server or subnet), the destination might be an IP in that remote network.
* **Source and Destination Ports**: The network ports used by the connection (for TCP/UDP flows).
* **ICMP Code and Type**: For ICMP traffic, the ICMP code and type.
* **Protocol**: The protocol of the traffic, such as TCP, UDP, or ICMP.
* **Direction**: Whether the flow was inbound or outbound. This takes into consideration the perspective of the **peer reporting the traffic** and the NetBird interface.
* **Volume of Data**: The amount of data transferred, measured in number of packets and bytes sent/received for the duration of the flow.
* **Resource ID**: Network route or Networks resource ID that the flow is associated with. This is useful for identifying the routing configuration that allowed the flow. DNS route information is **available only** on the routing client.
* **Rule ID**: The ID of the policy that allowed the flow. This is useful for identifying the access control policy that allowed the flow. This information is **available only** on the receiving side of the traffic.
In addition to the data collected by the peers, the NetBird API provides additional context about the peers and resources involved in the traffic event. These details include:
* **Peer Name**: The name of the peer.
* **Peer ID**: The unique identifier of the peer.
* **Resource name**: The name of the resource or network route.
* **Policy Name**: The name of the policy that allowed the flow.
* **User ID, name, and email**: The name and email of the user associated with the source peer.
* **Reporter ID**: The unique identifier of the peer that reported the traffic event.
* **Received timestamp**: The timestamp when the event was received by the NetBird servers.
<details>
<summary>API sample response</summary>
```json
{
"destination": {
"address": "142.250.185.206:443",
"dns_label": "*.google.com",
"geo_location": {
"city_name": "",
"country_code": ""
},
"id": "cvco2st9q2cs73btphmg",
"name": "Any google.com domain",
"os": "",
"type": "DOMAIN_RESOURCE"
},
"direction": "EGRESS",
"flow_id": "9682d060-3b28-4fa3-8b47-98595a51bbda",
"icmp_code": 0,
"icmp_type": 0,
"id": "c94e398c-dbfb-4344-8c47-a731b984d86e",
"policy_id": "ndkslcanlksncl",
"policy_name": "Allow google access",
"protocol": 6,
"receive_timestamp": "2025-03-22T20:26:19.491144Z",
"reporter_id": "ldkfnwklenfklernl",
"rx_bytes": 0,
"rx_packets": 0,
"source": {
"address": "100.89.67.186:50229",
"dns_label": "macbook-pro-10-2",
"geo_location": {
"city_name": "Frankfurt",
"country_code": "DE"
},
"id": "ldkfnwklenfklernl",
"name": "MacBook-Pro-10.local",
"os": "Darwin",
"type": "PEER"
},
"timestamp": "2025-03-22T20:26:16.937522Z",
"tx_bytes": 64,
"tx_packets": 1,
"type": "TYPE_START",
"user_email": "john@example.com",
"user_id": "google-oauth2|xyz0123",
"user_name": "John Doe"
}
```
</details>
## Viewing Traffic Events on the Dashboard
There are two places where you can see the traffic events on the NetBird dashboard:
1. **Traffic events**: Under Activity, you will find the Traffic events menu. This view shows the traffic events in a table format for all peers in your network.
2. **Peer details**: When you click on a peer, you will see the traffic events for that peer in the Peer details view.
### Filters
You can use various filters to search and filter received events. The filters include:
- **Peer name**: Name of the peer that is the source or destination of the traffic event
- **Resource name**: Name of the resource or network route
- **IP address**: Source or destination IP addresses
- **Ports**: Source or destination ports
- **User**: User from the peer that initiated the connection
- **Timestamp**: Time range of the event
- **Protocol**: ICMP, TCP, UDP
- **Type of event**:
- **P2P connection started (inbound/outbound)**: Events with started status and initiated by peers to other peers
- **P2P connection stopped (inbound/outbound)**: Events with stopped status and initiated by peers to other peers
- **P2P connection blocked (inbound/outbound)**: Events with blocked status and initiated by peers to other peers
- **Routed connection started (inbound/outbound)**: Events with started status and with a remote resource destination
- **Routed connection stopped (inbound/outbound)**: Events with stopped status and with a remote resource destination
- **Routed connection blocked (inbound/outbound)**: Events with blocked status and with a remote resource destination
## Correlating events
Events can be correlated by observing the traffic from both peers involved in a traffic session. Let's say you have two peers, Peer A and Peer B, and Peer A initiates a connection to Peer B. In the traffic events,
you will see up to 4 events from these peers. If the connection was successful, you will see a started and a stopped event from Peer A and Peer B. But, if one peer blocks the connection, then you will see a started and stopped events from the initiator and
a blocked event from the responder.
<Note>
The blocked event will be available only if the destination uses the NetBird client in userspace mode.
This is the case for Windows and MacOs nodes. For Linux, you can enable userspace mode with the environment variable `NB_WG_KERNEL_DISABLED=true` and `NB_FORCE_USERSPACE_ROUTER=true`
</Note>
### Viewing TCP and UDP connections
You can use source ports to correlate TCP and UDP. Below we will analyze a few examples for a connection between a user computer and a Web and FTP servers.
The peer Maycons-MacBook-Pro.local initiates a connection to the Web server. The source port is `51997` and the destination port is TCP/80. The connection is successful, and the event is marked as started and stopped. See screenshot below:
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/p2p-tcp-allow.png" alt="P2P TCP Allowed" className="imagewrapper-big"/>
</p>
Besides the ports and protocol information, we can review the event description in the screenshot above to understand what happened. For all four events we have the following:
- **Peer `Maycons-MacBook-Pro-2.local` requested P2P connection to Peer `webserver`**: This is the event from the perspective of the peer that initiated the connection. The sources and destination provide the IPs and ports used in the connection.
- **Peer `webserver` received P2P connection from Peer `Maycons-MacBook-Pro-2.local`**: This is the event from the perspective of the peer that received the connection.
- **Peer `Maycons-MacBook-Pro-2.local` stopped P2P connection to Peer `webserver`**: This is the event from the perspective of the peer that initiated the connection when the connection ended on its side.
- **Peer `webserver` stopped P2P connection from Peer `Maycons-MacBook-Pro-2.local`**: This is the event from the perspective of the peer that received the connection when the connection has ended on its side.
In case of the peer receiving the connection, the stopped status might arrive several minutes later, due to TCP sessions.
The UDP connection is very similar:
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/p2p-udp-allow.png" alt="P2P UDP Allowed" className="imagewrapper-big"/>
</p>
<Note>
The UDP connection is stateless, so the stopped event will be generated right after a certain period of inactivity.
</Note>
When a connection is blocked, you may see similar entries to the following events but with a few differences:
**TCP**:
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/p2p-tcp-blocked.png" alt="P2P TCP Blocked" className="imagewrapper-big"/>
</p>
**UDP**:
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/p2p-udp-blocked.png" alt="P2P UDP Blocked" className="imagewrapper-big"/>
</p>
Key differences:
- There are no events that have started or stopped on the refusing side. The connection is blocked right after the request.
- Depending on the application making a request in the initiator, you may see multiple blocked events from the receiving side of the connection due to retries:
<Note>
The blocked event will be available only if the destination is using the NetBird client in userspace mode.
This is the case for Windows and MacOs nodes. For Linux, you can enable userspace mode with the environment variable `NB_WG_KERNEL_DISABLED=true` and `NB_FORCE_USERSPACE_ROUTER=true`
</Note>
### Viewing ICMP connections
ICMP events are similar to TCP and UDP events. The main difference is that ICMP doesn't have ports:
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/p2p-icmp-allowed.png" alt="P2P ICMP Allowed" className="imagewrapper-big"/>
</p>
<Note>
The ICMP connection is stateless, so the stopped event will be generated right after a certain period of inactivity.
</Note>
### Routed events
Routed events follow the same pattern as P2P events. The main difference is that the destination or source can be a resource or network route. Below, we have a few examples of a connection from a peer to a resource:
**ICMP**:
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/routed-icmp-allowed.png" alt="Routed ICMP Allowed" className="imagewrapper-big"/>
</p>
**TCP**:
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/routed-tcp-allowed.png" alt="Routed TCP Allowed" className="imagewrapper-big"/>
</p>
Key differences:
- The source or destination is a resource or network route.
- On the receiver side, we will have an indication of which routing peer reported the event.
- The source or destination identifier will be unknown on the routing peer side if the route or resource is of a DNS type.
For site-2-site connections, the events will be similar to the above examples, but you will see a routing peer for each event:
<p>
<img src="/docs-static/img/how-to-guides/traffic-events/s2s-tcp-allowed.png" alt="S2S TCP Allowed" className="imagewrapper-big"/>
</p>
## Limitations
There are a few differences between the different WireGuard modes NetBird supports and the data captured by the NetBird client.
| Feature | Kernel Mode | Userspace Mode | Netstack Mode |
|:---------:|:-------------:|:----------------:|:---------------:|
| Blocked traffic event | No | Yes | Yes |
| Site-2-Site events | No | Yes | Yes |
| Rule IDs | No | Yes | Yes |
| Allowed rule ID for routed events | Yes | No | No |
| Byte counters for routed events | Yes | No | No |
We are actively working to improve the data captured by the NetBird client in Kernel and userspace modes to align with customers' expectations.
## Conclusion
Traffic events logging provides a powerful tool for monitoring and analyzing network traffic across your infrastructure.
Enabling this feature can provide valuable insights into network activity, enhance security measures, and improve operational efficiency.
The ability to correlate events, view detailed traffic data, and stream events to SIEM systems empowers you to make informed decisions
and take proactive steps to protect your network environment.

4
src/pages/how-to/troubleshooting-client.mdx
View File

@@ -817,7 +817,7 @@ misconfiguration and resulting lack of connectivity establishment.
This section will provide general directions for verifying connectivity on every step involved in handling
the Domain Resources, to better understand where issue might lie.
For in-depth overview of the mechanism please read [Domain Resources](/how-to/networks#domain-resources) section.
For in-depth overview of the mechanism please read [Domain Resources](/manage/networks#domain-resources) section.
Analyzing those issues will take a "backwards" approach (based on the most common issues), where we will first confirm
that Routing Peer itself is working as expected and will check the client's operating system configuration as one of the
@@ -905,7 +905,7 @@ Address: 100.83.136.209#22054
### Trigger the Domain Resource
I have yet to see a local DNS forwarder fail, but using it is a good way of forcing the NetBird client to set up
routing for the domain (see the [Domain Resources](/how-to/networks#domain-resources) for explanation).
routing for the domain (see the [Domain Resources](/manage/networks#domain-resources) for explanation).
<Note>
On MacOS & Windows the IP address would always be `100.83.255.254` instead of `100.83.73.97`.