mirror of
https://github.com/netbirdio/docs.git
synced 2026-05-22 17:07:57 -07:00
add first version of tailwind docs
This commit is contained in:
Pascal Fischer
@@ -22,3 +22,4 @@ yarn-error.log*
|
||||
.idea
|
||||
|
||||
package-lock.json
|
||||
/.next/
|
||||
|
||||
@@ -1,3 +0,0 @@
|
||||
module.exports = {
|
||||
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
|
||||
};
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
id: firewall-ports
|
||||
title: What firewall ports should I open to use NetBird?
|
||||
sidebar_position: 1
|
||||
---
|
||||
### Incoming ports
|
||||
NetBird's agent doesn't require any incoming port to be open; It negotiates the connection with the support of the signal and relay services.
|
||||
### Outgoing ports
|
||||
NetBird usually won't need open ports, but sometimes you or your IT team needs to secure and verify
|
||||
all outgoing traffic, and that may affect how NetBird clients connect to the [control layer](/overview/architecture)
|
||||
and negotiate the peer-to-peer connections.
|
||||
|
||||
Below is the list of NetBird hosted endpoints and ports they listen to:
|
||||
* Management service:
|
||||
* **Endpoint**: api.wiretrustee.com
|
||||
* **Port**: TCP/443
|
||||
* Signal service:
|
||||
* **Endpoint**: signal2.wiretrustee.com
|
||||
* **Port**: TCP/443
|
||||
* Relay (TURN) service:
|
||||
* **Endpoint**: turn.netbird.io
|
||||
* **Port range**: UDP/5555-65535
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
id: metrics-collection
|
||||
title: Why and what are the anonymous usage metrics?
|
||||
sidebar_position: 2
|
||||
---
|
||||
### Why we added metrics collection?
|
||||
As an open-source project and business, making decisions based on data is essential. We will know our adoption rate, feature usage, and client type with anonymous metrics.
|
||||
|
||||
:::info
|
||||
The collection is strict to our management system.
|
||||
:::
|
||||
|
||||
If the metric collection infringes any internal regulation or policy, it can be disabled by setting the flag `--disable-anonymous-metrics=true` to the management service startup command.
|
||||
|
||||
### What are the metrics being collected?
|
||||
We are collecting the following metrics:
|
||||
* Number of accounts
|
||||
* Number of users
|
||||
* Number of peers
|
||||
* Number of active peers in the last 24 hours
|
||||
* Number of peers per operating system
|
||||
* Number of setup keys usage
|
||||
* Number of peers activated by users
|
||||
* Number of rules
|
||||
* Number of groups
|
||||
* Number of routes
|
||||
* Number of nameservers
|
||||
* Service uptime
|
||||
* Service version
|
||||
* Metrics generation time
|
||||
|
||||
|
||||
### Metrics UUID
|
||||
We are using an installation ID for each management service which is generated once and stored in your management store database. It doesn't have any trace of any other private information, and it helps distinguish each deployment.
|
||||
|
||||
### Metrics pusher IP
|
||||
We are not storing the pusher IP address; it gets discarded once the request is complete.
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"label": "Examples",
|
||||
"position": 5
|
||||
}
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# NetBird Client on AWS ECS (Terraform)
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/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
|
||||
```
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# 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](/overview/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 -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/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](/examples/aws-ecs-client-daemon).
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"label": "Getting Started",
|
||||
"position": 4
|
||||
}
|
||||
@@ -1,280 +0,0 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
title: Installation
|
||||
tags:
|
||||
- client
|
||||
- how-to
|
||||
- install
|
||||
---
|
||||
|
||||
### Linux
|
||||
|
||||
**APT/Debian**
|
||||
1. Add the repository:
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install ca-certificates curl gnupg -y
|
||||
curl -sSL https://pkgs.wiretrustee.com/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/wiretrustee-archive-keyring.gpg
|
||||
echo 'deb [signed-by=/usr/share/keyrings/wiretrustee-archive-keyring.gpg] https://pkgs.wiretrustee.com/debian stable main' | sudo tee /etc/apt/sources.list.d/wiretrustee.list
|
||||
```
|
||||
2. Update APT's cache
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
```
|
||||
3. Install the package
|
||||
|
||||
```bash
|
||||
# for CLI only
|
||||
sudo apt-get install netbird
|
||||
# for GUI package
|
||||
sudo apt-get install netbird-ui
|
||||
```
|
||||
|
||||
**RPM/Red hat**
|
||||
|
||||
1. Add the repository:
|
||||
```bash
|
||||
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
|
||||
[Wiretrustee]
|
||||
name=Wiretrustee
|
||||
baseurl=https://pkgs.wiretrustee.com/yum/
|
||||
enabled=1
|
||||
gpgcheck=0
|
||||
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
|
||||
repo_gpgcheck=1
|
||||
EOF
|
||||
```
|
||||
2. Install the package
|
||||
```bash
|
||||
# for CLI only
|
||||
sudo yum install netbird
|
||||
# for GUI package
|
||||
sudo yum install netbird-ui
|
||||
```
|
||||
|
||||
**Fedora**
|
||||
|
||||
1. Create the repository file:
|
||||
```bash
|
||||
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
|
||||
[Wiretrustee]
|
||||
name=Wiretrustee
|
||||
baseurl=https://pkgs.wiretrustee.com/yum/
|
||||
enabled=1
|
||||
gpgcheck=0
|
||||
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
|
||||
repo_gpgcheck=1
|
||||
EOF
|
||||
```
|
||||
2. Import the file
|
||||
```bash
|
||||
sudo dnf config-manager --add-repo /etc/yum.repos.d/wiretrustee.repo
|
||||
```
|
||||
3. Install the package
|
||||
```bash
|
||||
# for CLI only
|
||||
sudo dnf install netbird
|
||||
# for GUI package
|
||||
sudo dnf install netbird-ui
|
||||
```
|
||||
|
||||
|
||||
**NixOS 22.11+/unstable**
|
||||
|
||||
1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
{
|
||||
services.netbird.enable = true; # for netbird service & CLI
|
||||
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
|
||||
}
|
||||
```
|
||||
2. Build and apply new configuration
|
||||
|
||||
```bash
|
||||
sudo nixos-rebuild switch
|
||||
```
|
||||
|
||||
### macOS
|
||||
**Homebrew install**
|
||||
1. Download and install homebrew at https://brew.sh/
|
||||
2. If wiretrustee was previously installed with homebrew, you will need to run:
|
||||
```bash
|
||||
# Stop and uninstall daemon service:
|
||||
sudo wiretrustee service stop
|
||||
sudo wiretrustee service uninstall
|
||||
# unlik the app
|
||||
brew unlink wiretrustee
|
||||
```
|
||||
> netbird will copy any existing configuration from the Wiretrustee's default configuration paths to the new NetBird's default location
|
||||
|
||||
3. Install the client
|
||||
```bash
|
||||
# for CLI only
|
||||
brew install netbirdio/tap/netbird
|
||||
# for GUI package
|
||||
brew install --cask netbirdio/tap/netbird-ui
|
||||
```
|
||||
4. If you installed CLI only, you need to install and start the client daemon service:
|
||||
```bash
|
||||
sudo netbird service install
|
||||
sudo netbird service start
|
||||
```
|
||||
|
||||
### Windows
|
||||
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
|
||||
2. Download the latest Windows release installer ```netbird_installer_<VERSION>_windows_amd64.exe``` (**Switch VERSION to the latest**):
|
||||
3. Proceed with the installation steps
|
||||
4. This will install the UI client in the C:\\Program Files\\NetBird and add the daemon service
|
||||
5. After installing, you can follow the steps from [Running NetBird with SSO Login](#Running-NetBird-with-SSO-Login) steps.
|
||||
> To uninstall the client and service, you can use Add/Remove programs
|
||||
|
||||
⚠️ In case of any issues with the connection on Windows check the firewall settings. With default Windows 11 firewall setup there could be connectivity issue related to egress traffic.
|
||||
|
||||
Recommended way is to add NetBird in firewall settings:
|
||||
|
||||
1. Go to "Control panel".
|
||||
2. Select "Windows Defender Firewall".
|
||||
3. Select "Advanced settings".
|
||||
4. Select "Outbound Rules" -> "New rule".
|
||||
5. In the new rule select "Program" and click "Next".
|
||||
6. Point to the NetBird installation exe file (usually in `C:\Program Files\NetBird\netbird.exe`) and click "Next".
|
||||
7. Select "Allow the connection" and click "Next".
|
||||
8. Select the network in which rule should be applied (Domain, Private, Public) according to your needs and click "Next".
|
||||
9. Provide rule name (e.g. "Netbird Egress Traffic") and click "Finish".
|
||||
10. Disconnect and connect to NetBird.
|
||||
|
||||
|
||||
### Binary Install
|
||||
**Installation from binary (CLI only)**
|
||||
|
||||
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
|
||||
2. Download the latest release:
|
||||
```bash
|
||||
curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
You need to replace some variables from the URL above:
|
||||
|
||||
- Replace **VERSION** with the latest released verion.
|
||||
- Replace **OS** with "linux", "darwin" for MacOS or "windows"
|
||||
- Replace **Arch** with your target system CPU archtecture
|
||||
|
||||
:::
|
||||
|
||||
3. Decompress
|
||||
```bash
|
||||
tar xcf ./netbird_<VERSION>.tar.gz
|
||||
sudo mv netbird /usr/bin/netbird
|
||||
sudo chown root:root /usr/bin/netbird
|
||||
sudo chmod +x /usr/bin/netbird
|
||||
```
|
||||
After that you may need to add /usr/bin in your PATH environment variable:
|
||||
````bash
|
||||
export PATH=$PATH:/usr/bin
|
||||
````
|
||||
4. Install and run the service
|
||||
```bash
|
||||
sudo netbird service install
|
||||
sudo netbird service start
|
||||
```
|
||||
|
||||
### Running NetBird with SSO Login
|
||||
#### Desktop UI Application
|
||||
If you installed the Desktop UI client, you can launch it and click on Connect.
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/docs/img/getting-started/netbird-sso-login-ui.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
#### CLI
|
||||
Alternatively, you could use command line. Simply run
|
||||
```bash
|
||||
netbird up
|
||||
```
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/docs/img/getting-started/netbird-sso-login-cmd.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
Check connection status:
|
||||
```bash
|
||||
netbird status
|
||||
```
|
||||
|
||||
### Running NetBird with a Setup Key
|
||||
In case you are activating a server peer, you can use a [setup key](/overview/setup-keys) as described in the steps below.
|
||||
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
|
||||
|
||||
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/overview/setup-keys)).
|
||||
|
||||
For all systems:
|
||||
```bash
|
||||
netbird up --setup-key <SETUP KEY>
|
||||
```
|
||||
|
||||
For **Docker**, you can run with the following command:
|
||||
```bash
|
||||
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:<TAG>
|
||||
```
|
||||
> TAG > 0.6.0 version
|
||||
|
||||
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
|
||||
```bash
|
||||
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
|
||||
```
|
||||
|
||||
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
|
||||
|
||||
2. Check connection status:
|
||||
```bash
|
||||
netbird status
|
||||
```
|
||||
|
||||
3. Check your IP:
|
||||
|
||||
On **macOS** :
|
||||
````bash
|
||||
sudo ifconfig utun100
|
||||
````
|
||||
On **Linux**:
|
||||
```bash
|
||||
ip addr show wt0
|
||||
```
|
||||
On **Windows**:
|
||||
```bash
|
||||
netsh interface ip show config name="wt0"
|
||||
```
|
||||
|
||||
### Running NetBird in Docker
|
||||
|
||||
Set the ```NB_SETUP_KEY``` environment variable and run the command.
|
||||
:::tip Environment variables
|
||||
You can pass other settings as environment variables. See [Environment variables](reference/netbird-commands.md#environment-variables) for details.
|
||||
:::
|
||||
```bash
|
||||
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
|
||||
```
|
||||
|
||||
See [Docker example](examples/netbird-docker.md) for details.
|
||||
|
||||
### Troubleshooting
|
||||
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
|
||||
which is ```https://api.wiretrustee.com:33073```.
|
||||
|
||||
2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting)
|
||||
to override it you can do the following:
|
||||
|
||||
```bash
|
||||
netbird down
|
||||
netbird up --management-url https://<CORRECT HOST:PORT>/
|
||||
```
|
||||
|
||||
To override it see the solution #1 above.
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
title: Quickstart Guide
|
||||
---
|
||||
|
||||
Step-by-step video guide on YouTube:
|
||||
|
||||
<div class="videowrapper">
|
||||
<iframe src="https://www.youtube.com/embed/HYlhvr_eu2U" allow="fullscreen;"></iframe>
|
||||
</div>
|
||||
<br/>
|
||||
This guide describes how to quickly get started with NetBird and create a secure private network with 2 connected machines.
|
||||
|
||||
One machine is a Linux laptop, and the other one a EC2 node running on AWS.
|
||||
Both machines are running Linux but NetBird also works on Windows and MacOS.
|
||||
|
||||
1. Sign-up at [https://app.netbird.io/](https://app.netbird.io/)
|
||||
|
||||
You can use your Google, GitHub or Microsoft account.
|
||||
|
||||
|
||||
|
||||
2. After a successful login you will be redirected to the ```Peers``` screen which is empty because you don't have any peers yet.
|
||||
|
||||
Click ```Add peer``` to add a new machine.
|
||||
|
||||
|
||||
|
||||
3. Choose your machine operating system (in our case it is ```Linux```) and proceed with the installation steps.
|
||||
|
||||
|
||||
|
||||
4. If you installed NetBird Desktop UI you can use it to connect to the network instead of running `netbird up` command. Look for `NetBird` in your application list, run it, and click `Connect`.
|
||||
>
|
||||
|
||||
|
||||
|
||||
5. At this point a browser window pops up starting a device registration process. Click confirm and follow the steps if required.
|
||||
|
||||
|
||||
|
||||
6. On the EC2 node repeat the installation steps and run `netbird up` command.
|
||||
|
||||
```bash
|
||||
sudo netbird up
|
||||
```
|
||||
7. Copy the verification URL from the terminal output and paste it in your browser. Repeat step #5
|
||||
|
||||
|
||||
|
||||
8. Return to ```Peers``` and you should notice 2 new machines with status ```online```
|
||||
|
||||
|
||||
|
||||
9. To test the connection you could try pinging devices:
|
||||
|
||||
On your laptop:
|
||||
```bash
|
||||
ping 100.64.0.2
|
||||
```
|
||||
|
||||
On the EC2 node:
|
||||
```bash
|
||||
ping 100.64.0.1
|
||||
```
|
||||
10. Done! You now have a secure peer-to-peer private network configured.
|
||||
|
||||
<br/>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on Twitter](https://twitter.com/netbird)
|
||||
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
|
||||
- NetBird release page on GitHub: [releases](https://github.com/netbirdio/netbird/releases/latest)
|
||||
|
||||
|
||||
@@ -1,179 +0,0 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Self-hosting Guide
|
||||
|
||||
NetBird is open-source and can be self-hosted on your servers.
|
||||
|
||||
It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal),
|
||||
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and an identity provider (available options will be listed later in this guide).
|
||||
|
||||
If you would like to learn more about the architecture please refer to the [Architecture section](/overview/architecture).
|
||||
|
||||
:::tip netbird as a service
|
||||
It might be a good idea to try NetBird before self-hosting.
|
||||
We run NetBird in the cloud, and it will take less than 5 minutes to get started with our managed version. [Check it out!](https://netbird.io/pricing)
|
||||
:::
|
||||
|
||||
### Requirements
|
||||
|
||||
- Virtual machine offered by any cloud provider (e.g., AWS, DigitalOcean, Hetzner, Google Cloud, Azure ...).
|
||||
- Any Linux OS.
|
||||
- Docker Compose installed (see [Install Docker Compose](https://docs.docker.com/compose/install/)).
|
||||
- Domain name pointing to the public IP address of your server.
|
||||
- Open TCP ports ```80, 443, 33073, 10000``` (Dashboard HTTP & HTTPS, Management gRCP & HTTP APIs, Signal gRPC API respectively) on your server.
|
||||
- Coturn is used for relay using the STUN/TURN protocols. It requires a listening port, `UDP 3478`, and range of ports, `UDP 49152-65535`, for dynamic relay connections. These are set as defaults in setup file, but can be configured to your requirements.
|
||||
- Maybe a cup of coffee or tea :)
|
||||
|
||||
For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.
|
||||
|
||||
### Step 1: Get the latest stable NetBird code
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
REPO="https://github.com/netbirdio/netbird/"
|
||||
# this command will fetch the latest release e.g. v0.8.7
|
||||
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
|
||||
echo $LATEST_TAG
|
||||
|
||||
# this comman will clone the latest tag
|
||||
git clone --depth 1 --branch $LATEST_TAG $REPO
|
||||
```
|
||||
|
||||
Then switch to the infra folder that contains docker-compose file:
|
||||
|
||||
```bash
|
||||
cd netbird/infrastructure_files/
|
||||
```
|
||||
### Step 2: Prepare configuration files
|
||||
|
||||
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
|
||||
|
||||
The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env.example) file contains multiple properties that have to be filled. You need to copy the example file to `setup.env` before updating it.
|
||||
|
||||
```bash
|
||||
## example file, you can copy this file to setup.env and update its values
|
||||
##
|
||||
# Dashboard domain. e.g. app.mydomain.com
|
||||
NETBIRD_DOMAIN=""
|
||||
# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration
|
||||
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT=""
|
||||
NETBIRD_AUTH_AUDIENCE=""
|
||||
# e.g. netbird-client
|
||||
NETBIRD_AUTH_CLIENT_ID=""
|
||||
# indicates whether to use Auth0 or not: true or false
|
||||
NETBIRD_USE_AUTH0="false"
|
||||
NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="none"
|
||||
# enables Interactive SSO Login feature (Oauth 2.0 Device Authorization Flow)
|
||||
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
|
||||
# e.g. hello@mydomain.com
|
||||
NETBIRD_LETSENCRYPT_EMAIL=""
|
||||
```
|
||||
|
||||
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
|
||||
- Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
|
||||
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
|
||||
|
||||
:::tip
|
||||
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
|
||||
:::
|
||||
|
||||
:::info
|
||||
If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](#advanced-running-netbird-behind-an-existing-reverse-proxy).
|
||||
:::
|
||||
|
||||
### Step 3: Configure Identity Provider
|
||||
|
||||
NetBird supports generic OpenID (OIDC) protocol allowing for the integration with any IDP that follows the specification.
|
||||
Pick the one that suits your needs, follow the steps, and continue with this guide:
|
||||
|
||||
- Continue with [Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0) (managed service).
|
||||
- Continue with [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
|
||||
|
||||
### Step 4: Disable single account mode (optional)
|
||||
|
||||
NetBird Management service runs in a single account mode by default since version v0.10.1.
|
||||
Management service was creating a separate account for each registered user before v0.10.1.
|
||||
Single account mode ensures that all the users signing up for your self-hosted installation will join the same account/network.
|
||||
In most cases, this is the desired behavior.
|
||||
|
||||
If you want to disable the single-account mode, set `--disable-single-account-mode` flag in the
|
||||
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
|
||||
`command` section of the `management` service.
|
||||
|
||||
### Step 5: Run configuration script
|
||||
Make sure all the required properties set in the ```setup.env``` file and run:
|
||||
|
||||
```bash
|
||||
./configure.sh
|
||||
```
|
||||
|
||||
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
|
||||
|
||||
### Step 6: Run docker compose:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
### Step 7: Check docker logs (Optional)
|
||||
|
||||
```bash
|
||||
docker-compose logs signal
|
||||
docker-compose logs management
|
||||
docker-compose logs coturn
|
||||
docker-compose logs dashboard
|
||||
```
|
||||
|
||||
### Advanced: Running netbird behind an existing reverse-proxy
|
||||
|
||||
If you want to run netbird behind your own reverse-proxy, some additional configuration-steps have to be taken to [Step 2](#step-2--prepare-configuration-files).
|
||||
|
||||
:::info
|
||||
Not all reverse-proxies are supported as netbird uses *gRPC* for various components.
|
||||
:::
|
||||
|
||||
#### Configuration for netbird
|
||||
|
||||
In `setup.env`:
|
||||
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
|
||||
- Set ```NETBIRD_DISABLE_LETSENCRYPT=true```
|
||||
- Add ```NETBIRD_MGMT_API_PORT``` to your reverse-proxy TLS-port (default: 443)
|
||||
- Add ```NETBIRD_SIGNAL_PORT``` to your reverse-proxy TLS-port
|
||||
|
||||
Optional:
|
||||
- Add ```TURN_MIN_PORT``` and ```TURN_MAX_PORT``` to configure the port-range used by the Turn-server
|
||||
|
||||
:::tip info
|
||||
The `coturn`-service still needs to be directly accessible under your set-domain as it uses UDP for communication.
|
||||
:::
|
||||
|
||||
Now you can continue with [Step 3](#step-3-configure-identity-provider).
|
||||
|
||||
#### Configuration for your reverse-proxy
|
||||
|
||||
Depending on your port-mappings and choice of reverse-proxy, how you configure the forwards differs greatly.
|
||||
|
||||
The following endpoints have to be setup:
|
||||
|
||||
Endpoint | Protocol | Target service and internal-port
|
||||
------------------------------- | --------- | --------------------------------
|
||||
/ | HTTP | dashboard:80
|
||||
/signalexchange.SignalExchange/ | gRPC | signal:80
|
||||
/api | HTTP | management:443
|
||||
/management.ManagementService/ | gRPC | management:443
|
||||
|
||||
Make sure your reverse-Proxy is setup to use the HTTP2-Protocol when forwarding.
|
||||
|
||||
:::tip
|
||||
You can find helpful templates with the reverse-proxy-name as suffix (e.g. `docker-compose.yml.tmpl.traefik`)
|
||||
Simply replace the file `docker-compose.yml.tmpl` with the chosen version.
|
||||
:::
|
||||
|
||||
### Get in touch
|
||||
|
||||
Feel free to ping us on [Slack](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) if you have any questions
|
||||
|
||||
- NetBird managed version: [https://app.netbird.io](https://app.netbird.io)
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird) :pray:
|
||||
- Follow us [on Twitter](https://twitter.com/netbird)
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"label": "How-to Guides",
|
||||
"position": 3
|
||||
}
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
# Monitor system and network activity
|
||||
|
||||
The activity monitoring feature lets you quickly see what's happening with your network.
|
||||
Whether a new machine or user joined your network or the access control policy has been modified, the activity log allows you to track the changes to your network.
|
||||
|
||||
Activity monitoring is enabled by default for every network, and you can access it in the web UI under the [Activity tab](https://app.netbird.io/activity).
|
||||
You can also use the search bar to filter events by activity type.
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/activity-monitoring.png" alt="activity-monitoring" width="800" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
:::info
|
||||
The current version of NetBird tracks network changes that occur in the Management server. E.g., changes related to the list of peers, groups, system settings, setup keys, access control, etc.
|
||||
The future versions will support connection events that occur in NetBird agents (e.g., peer A connected to peer B).
|
||||
:::
|
||||
|
||||
## 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 Twitter](https://twitter.com/netbird)
|
||||
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
# 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 two ways of adding users to a NetBird account - indirect and direct.
|
||||
|
||||
### 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.
|
||||
|
||||
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.
|
||||
|
||||
:::info
|
||||
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](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) to fix this.
|
||||
:::
|
||||
|
||||
### 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 the `Users` tab and click the <button name="button" className="button-6">Invite User</button> button.
|
||||
A user window will pop up where you can specify the name and email address of the invited user. 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 align="center">
|
||||
<img src="/docs/img/how-to-guides/user-invites.gif" alt="high-level-dia" width="800" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
:::info
|
||||
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.
|
||||
:::
|
||||
|
||||
### 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 Twitter](https://twitter.com/netbird)
|
||||
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,155 +0,0 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
# Manage DNS in your network
|
||||
|
||||
<div class="videowrapper">
|
||||
<iframe src="https://www.youtube.com/embed/xxQ_QeEMC0U" allow="fullscreen;"></iframe>
|
||||
</div>
|
||||
<br/><br/>
|
||||
|
||||
You don't need to design a network or configure [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 peers have IPs, they can communicate with one another and establish direct encrypted WireGuard® tunnels.
|
||||
You can use these IPs to access the services running on the connected peers (e.g., 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](https://netbird.io/docs/overview/acls#groups) should use, and set up split DNS.
|
||||
|
||||
:::info
|
||||
Nameservers is available for NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later.
|
||||
:::
|
||||
|
||||
## Concepts
|
||||
### Local resolver
|
||||
To minimize the number of changes in your system, NetBird will spin up a local DNS resolver.
|
||||
|
||||
This local resolver will be responsible for queries to the domain names of peers registered in your network and forwarding queries to upstream nameservers you configure in the system.
|
||||
|
||||
It listens on the peer's IP, and usually, it will use the default port 53, but if it is in use, it will use the 5053 port.
|
||||
:::info
|
||||
Custom port support is not builtin into most operating systems. At the time of release, the supported systems are:
|
||||
- MacOS
|
||||
- Linux with systemd-resolved
|
||||
:::
|
||||
### Nameserver
|
||||
Nameserver is an upstream DNS server for name resolution, if a query comes and is not a peer domain name, it will be resolved by one of the upstream servers. You can assign private and public IPs and custom ports. Remember that you might need a network route for private addresses to allow peers to connect to it.
|
||||
### Match domains
|
||||
Match domains allow you to route queries of names, matching them to specific nameservers. This is useful when you have an internal DNS configuration that only internal servers can resolve.
|
||||
### All domains option
|
||||
The all domains option defines a default nameserver configuration to resolve all domains that don't have a match domain setting. Because not all operating systems support match domain configuration, we recommend configuring at least one nameserver set with this option enabled per distribution group. You may also consider using the group All for distribution, so you don't have to define multiple sets of nameservers to resolve all domains.
|
||||
:::info
|
||||
A nameserver set may only be configured with either All domains or match domains, you can have both settings in a single configuration as they overlap.
|
||||
:::
|
||||
### Distribution groups
|
||||
Distribution defines that peers that belong to groups set in this field will receive the nameserver configuration.
|
||||
:::info
|
||||
When using private nameservers, you may use these groups to link routing peers and clients of the private servers.
|
||||
:::
|
||||
|
||||
## Managing nameserver groups
|
||||
A nameserver group defines up to 2 nameservers to resolve DNS to a set of peers in distribution groups.
|
||||
|
||||
### Creating a nameserver group
|
||||
Access the `DNS` tab and click the `Add Nameserver` button to create a new nameserver.
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-nameserver-add-button.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</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 align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-nameserver-selection-view-open.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</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 align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-nameserver-all-group.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
#### Creating custom nameservers
|
||||
You can also configure a custom nameserver by clicking the `Add custom` button. Now you can enter the details of your 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`
|
||||
- Match mode: `All domains`
|
||||
- Distribution group: `Remote developers`
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-nameserver-custom.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
### Creating a nameserver for specific domains
|
||||
Sometimes we 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 align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-nameserver-remote-resolver.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
:::info
|
||||
Currently, only MacOS, Windows 10+, and Linux running systemd-resolved support nameservers without an all domains resolver. For a better experience, we recommend setting at least one all domain resolver to be applied to all groups.
|
||||
:::
|
||||
|
||||
### Distributing the 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 can communicate. 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 align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-nameserver-remote-route.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
Then we need to confirm that an access rule exists to connect `Remote developers` to `Office network` group:
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-nameserver-remote-rule.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
## Testing configuration
|
||||
### Querying records
|
||||
DNS configuration has evolved in the last 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 Twitter](https://twitter.com/netbird)
|
||||
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,132 +0,0 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
# Routing traffic to private networks
|
||||
|
||||
<div class="videowrapper">
|
||||
<iframe src="https://www.youtube.com/embed/VQuPuBOAknQ" allow="fullscreen;"></iframe>
|
||||
</div>
|
||||
<br/><br/>
|
||||
|
||||
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 and have a fast, secure peer-to-peer mesh network. That 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. e.g., 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 align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-network-routes.png" alt="high-level-dia" />
|
||||
</p>
|
||||
|
||||
:::tip try it
|
||||
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 simple! :)
|
||||
:::
|
||||
|
||||
## Concepts
|
||||
### Network routes
|
||||
A network route describes the network you want to connect with your NetBird peers. It has an identifier, a network range, a routing peer, and some parameters available for managing priority and masquerading.
|
||||
:::info
|
||||
Network routes is available for NetBird [v0.9.0](https://github.com/netbirdio/netbird/releases) or later.
|
||||
:::
|
||||
### Network identifiers and ranges
|
||||
Network identifiers are names for each network you want to route traffic from your peers, and ranges are IP ranges declared in CIDR notation which refers to an external network. The combination of identifiers and these ranges makes a single network.
|
||||
### Routing peer
|
||||
A routing peer is a node that will route packets between your routed network and the other NetBird peers.
|
||||
:::info
|
||||
Only Linux OS nodes can be assigned as routing 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 offering high-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 don't enable this option, you must configure a route to your NetBird network in your external network infrastructure.
|
||||
### Metric and priority
|
||||
Metric defines prioritization when choosing the main routing peer in a high availability network. Lower metrics have higher priority.
|
||||
|
||||
### Distribution groups
|
||||
Distribution groups define that peers that belong to groups set in this field will receive the network route.
|
||||
:::info
|
||||
It doesn't remove the need for the routing peer to be connected to these peers
|
||||
:::
|
||||
|
||||
## 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, 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.
|
||||
That will open a route configuration screen where you can add the information about the network you want to route:
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-network-routes-add-button.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</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: `aws-nb-europe-router-az-a`
|
||||
- Distribution Groups: `All`
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-network-routes-create.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
Once you fill in the route information, you can click on the `Save` button to save your new route.
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-network-routes-saved-new.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
Done! Now every peer connected to your routing peer 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, you still want to ensure a reliable connection to your private network when running NetBird on every machine is not feasible.
|
||||
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.
|
||||
|
||||
To enable high-available mode, you can click on `Configure` and select a new peer in the `Add additional routing peer` field, then select the distribution groups and click on `Save`.
|
||||
|
||||
In the following screenshot, we are adding the peer `aws-nb-europe-router-az-b` to the `aws-eu-central-1-vpc` route:
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-network-routes-create-ha.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
This way, nodes connected to both peer `aws-nb-europe-router-az-a` and peer `aws-nb-europe-router-az-b` would have a highly available connection with the network `172.31.0.0/16`.
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-network-routes-saved-new-ha.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
:::info
|
||||
Currently, there is no limitation in the number of routes that form a highly available route. Each connected peer will pick one routing peer to use as the router for a network; this decision is based on metric prioritization and connection attributes like direct or relayed connections.
|
||||
:::
|
||||
|
||||
### Filtering routes distribution with groups
|
||||
You can select as many distribution groups as you want for your network route. You can update them at the routing peer or high-availability group level. Keep in mind to link them to peers and, if required, to add access control rules ensuring connectivity between these peers and the routing peers of your route
|
||||
### 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 won't hide any NetBird peer IP and will forward the packets to the target network transparently.
|
||||
|
||||
That will require a routing configuration on your external network router pointing your NetBird network back to your routing peer.
|
||||
This way, devices that don't have the agent installed can communicate with your NetBird peers.
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/netbird-network-routes-masquerading.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</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 Twitter](https://twitter.com/netbird)
|
||||
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,52 +0,0 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
# Configure periodic user authentication
|
||||
|
||||
To ensure a high level of security, NetBird offers a peer login expiration feature that requires users to periodically reauthenticate their devices.
|
||||
Every new network has this feature enabled, and the expiration period is set to 24 hours by default. You can disable this feature and configure the expiration period in the account settings in the web UI https://app.netbird.io/settings.
|
||||
|
||||
:::tip
|
||||
This feature is only applied to peers added with the [interactive SSO login feature](/getting-started/installation#running-netbird-with-sso-login). Peers, added with a setup key, won't be affected.
|
||||
:::
|
||||
|
||||
Expired peers will appear in the peers' view with the status `needs login`.
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/peer-needs-login.png" alt="peer-needs-login.png" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
### Configure and disable expiration
|
||||
The expiration period can be set to anything between one hour and 180 days.
|
||||
Go to the Web UI Settings tab and set the desired period in the Authentication section.
|
||||
You can also disable the expiration for the whole network in the same section.
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/peer-login-expiration.png" alt="peer-login-expiration" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
|
||||
:::danger
|
||||
Enabling peer expiration or changing the expiration period will cause some peers added with the SSO login to disconnect,
|
||||
and re-authentication will be required.
|
||||
:::
|
||||
|
||||
### Disable expiration individually per peer
|
||||
Sometimes, you might want to disable peer expiration for some peers.
|
||||
With NetBird you can disable login expiration per peer without disabling expiration globally.
|
||||
In the Peers tab of the web UI click on the peer you want to disable expiration for and use the Login Expiration switch.
|
||||
Peers with `expiration disabled` will be marked with a corresponding label in the peers' table.
|
||||
|
||||
<p align="center">
|
||||
<img src="/docs/img/how-to-guides/individual-peer-login-expiration.png" alt="peer-login-expiration" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</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 Twitter](https://twitter.com/netbird)
|
||||
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"label": "Integrations",
|
||||
"position": 4
|
||||
}
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"label": "Identity Providers",
|
||||
"position": 4
|
||||
}
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"label": "Self-Hosted NetBird",
|
||||
"position": 4
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user