mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-16 07:26:35 +00:00
restructure how-to
This commit is contained in:
Pascal Fischer
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB |
@@ -187,27 +187,34 @@ export const docsNavigation = [
|
||||
{
|
||||
title: 'About NetBird',
|
||||
links: [
|
||||
{ title: 'Why Wireguard with NetBird?', href: '/docs/why-wireguard-with-netbird' },
|
||||
{ title: 'How Netbird Works', href: '/docs/how-netbird-works' },
|
||||
{ title: 'NetBird vs. Traditional VPN', href: '/docs/netbird-vs-traditional-vpn' },
|
||||
{ title: 'Other', href: '/docs/other' },
|
||||
{ title: 'FAQ', href: '/docs/faq' },
|
||||
{ title: 'Why Wireguard with NetBird?', href: '/docs/about-netbird/why-wireguard-with-netbird' },
|
||||
{ title: 'How Netbird Works', href: '/docs/about-netbird/how-netbird-works' },
|
||||
{ title: 'NetBird vs. Traditional VPN', href: '/docs/about-netbird/netbird-vs-traditional-vpn' },
|
||||
{ title: 'Other', href: '/docs/about-netbird/other' },
|
||||
{ title: 'FAQ', href: '/docs/about-netbird/faq' },
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'How-to Guides',
|
||||
title: 'How-to',
|
||||
links: [
|
||||
{ title: 'Getting Started', href: '/docs/getting-started' },
|
||||
{ title: 'Managing your Network', href: '/docs/managing-your-network' },
|
||||
{ title: 'Examples', href: '/docs/examples' },
|
||||
{ title: 'CLI', href: '/docs/cli' },
|
||||
{ title: 'Getting Started', href: '/docs/how-to/getting-started' },
|
||||
{ title: 'Peers', href: '/docs/how-to/peers' },
|
||||
{ title: 'Setup Keys', href: '/docs/how-to/setup-keys' },
|
||||
{ title: 'Access Control', href: '/docs/how-to/access-control' },
|
||||
{ title: 'Network Routes', href: '/docs/how-to/network-routes' },
|
||||
{ title: 'DNS', href: '/docs/how-to/dns' },
|
||||
{ title: 'Users', href: '/docs/how-to/users' },
|
||||
{ title: 'Activity', href: '/docs/how-to/activity' },
|
||||
{ title: 'Settings', href: '/docs/how-to/settings' },
|
||||
{ title: 'Examples', href: '/docs/how-to/examples' },
|
||||
{ title: 'CLI', href: '/docs/how-to/cli' },
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'Self-Hosted',
|
||||
links: [
|
||||
{ title: 'Installation Guide', href: '/docs/selfhosted-guide' },
|
||||
{ title: 'Identity Providers', href: '/docs/identity-providers' },
|
||||
{ title: 'Installation Guide', href: '/docs/selfhosted/selfhosted-guide' },
|
||||
{ title: 'Identity Providers', href: '/docs/selfhosted/identity-providers' },
|
||||
],
|
||||
},
|
||||
|
||||
|
||||
142
src/pages/docs/about-netbird/how-netbird-works.mdx
Normal file
142
src/pages/docs/about-netbird/how-netbird-works.mdx
Normal file
@@ -0,0 +1,142 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern"; import {Note} from "@/components/mdx";
|
||||
|
||||
<HeroPattern />
|
||||
|
||||
export const title = 'How NetBird Works'
|
||||
|
||||
## Architecture
|
||||
|
||||
### Overview
|
||||
NetBird is an open source platform consisting of a collection of components, responsible for handling peer-to-peer connections, tunneling, authentication, and network management (IPs, keys, ACLs, etc).
|
||||
|
||||
It uses open-source technologies like [WireGuard®](https://www.wireguard.com/), [Pion ICE (WebRTC)](https://github.com/pion/ice), [Coturn](https://github.com/coturn/coturn),
|
||||
and [software](https://github.com/netbirdio/netbird) developed by NetBird authors to make secure private networks deployment and management simple.
|
||||
|
||||
NetBird relies on four components - **Client** application (or agent), **Management**, **Signal** and **Relay** services.
|
||||
|
||||
The combination of these elements ensures that direct point-to-point connections are established and only authenticated users (or machines) have access to the resources for which they are authorized.
|
||||
|
||||
A **Peer** is a machine or any device that is connected to the network.
|
||||
It can be a Linux server running in the cloud or on-premises, a personal laptop, or even a Raspberry PI.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/high-level-dia.png" alt="high-level-dia" width="781" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
With NetBird clients installed and authorized on the Management service, machines form a mesh network connecting to each other directly via an encrypted point-to-point Wireguard tunnel.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/mesh.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>
|
||||
|
||||
While it is possible to create a full mesh network, it might be not a desirable outcome. In this case, [ACLs](/overview/acls) can be utilized to limit the access to certain machines.
|
||||
|
||||
Let's now take a closer look at each of NetBird's components.
|
||||
|
||||
### Management Service
|
||||
|
||||
The Management service is the central coordination component for NetBird with a UI dashboard.
|
||||
It keeps the network state, public Wireguard keys of the peers, authenticates and distributes network changes to peers.
|
||||
|
||||
The Management Service's responsibilities include:
|
||||
|
||||
* **Registering and authenticating new peers.** Every new machine has to register itself in the network in order to connect to other machines.
|
||||
After installation, NetBird client requires login that can be done through Identity Provider (IDP) or with a [setup key](/overview/setup-keys).
|
||||
* **Keeping the network map.** The Management service stores information about all the registered peers including Wireguard public key that was sent during the registration process.
|
||||
* **Managing private IP addresses.** Each peer receives a unique private IP with which it can be identified in the network.
|
||||
We use [Carrier Grade NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) address space with an allocated address block <em>100.64.0.0/10</em>.
|
||||
* **Synchronizing network changes to peers.** The Management Service keeps a control channel open to each peer sending network updates.
|
||||
Whenever a new peer joins the network, all other peers that are authorized to connect to it receive an update.
|
||||
After that, they are able to establish a connection to the new peer.
|
||||
* **Creating and managing ACLs.** ACL is a list of peers that a given peer has access to. <em>Coming Soon</em>.
|
||||
* **Managing private DNS.** [DNS](/overview/dns) allows referring to each of the peers with a fully qualified domain name (FQDN). <em>Coming Soon</em>.
|
||||
* **Monitoring network activity.** <em>Coming Soon</em>.
|
||||
* **Wireguard key rotation.** <em>Coming Soon</em>.
|
||||
|
||||
The Management service runs in the cloud NetBird-managed. It can also be self-hosted.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/management.png" alt="management-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
### Client Application
|
||||
|
||||
The NetBird Client application (or agent) is a software that is installed on your machines.
|
||||
It is an entry point to you private network that makes it possible for machines to communicate with each other.
|
||||
Once installed and registered, a machine becomes a peer in the network.
|
||||
|
||||
The Client's roles are the following:
|
||||
|
||||
* **Generating private and public Wireguard keys.** These keys are used for packet encryption between peers and for [Wireguard Cryptokey Routing](https://www.wireguard.com/#cryptokey-routing).
|
||||
To accept the incoming connections, peers have to know each other, therefore, the generated public keys have to be pre-shared on the machines. The client application sends its public key to the Management service which then distributes it to the authorized peers.
|
||||
* **Handling peer registration and authentication.** Each peer has to be authenticated and registered in the system. The client application requests a user to log in with an Identity Provider (IDP) or a [setup key](/overview/setup-keys) so that the peer can be associated with the organization's account.
|
||||
* **Receiving network updates from the Management service.**
|
||||
Each peer receives initial configuration and a list of peers with corresponding public keys and IP addresses so that it can establish a peer-to-peer connection.
|
||||
* **Establishing peer-to-peer Wireguard connection.** To establish a connection with a remote peer, the Client first discovers the most suitable connection candidate, or simply address (IP:port) that other peer can use to connect to it.
|
||||
Then sends it to the remote peer via Signal. This message is encrypted with the peer's private key and a public key of the remote peer.
|
||||
The remote peer does the same and once the peers can reach each other, they establish an encrypted Wireguard tunnel.
|
||||
|
||||
<Note>
|
||||
The **private key**, generated by the Client, **never leaves the machine**, ensuring that only the machine that owns the key can decrypt traffic addressed to it.
|
||||
</Note>
|
||||
|
||||
### Signal Service
|
||||
|
||||
The Signal Service or simply Signal is a lightweight piece of software that helps peers to negotiate direct connections.
|
||||
It does not store any data and no traffic passes through it.
|
||||
|
||||
The only Signal's responsibility is:
|
||||
* **Serve as a notification mechanism for peers.** Before a connection can be established, peers need to find each other and exchange the most suitable connection candidates.
|
||||
This is done through Signal. After a connection has been established, Signal steps out.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/signal.png" alt="signal-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Messages that are sent over Signal are **peer-to-peer encrypted**, so Signal can't see the contents.
|
||||
</Note>
|
||||
|
||||
NetBird Signal is very similar to the signaling servers used in [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling#the_signaling_server).
|
||||
It runs in the cloud NetBird-managed and can be self-hosted.
|
||||
|
||||
### Relay Service
|
||||
|
||||
The Relay service is a [TURN server](https://webrtc.org/getting-started/turn-server) in WebRTC terminology.
|
||||
In fact, we use an open-source implementation called [Coturn](https://github.com/coturn/coturn).
|
||||
The purpose of this service is to be a "plan B" and relay traffic between peers in case a peer-to-peer connection isn't possible.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/relay.png" alt="relay-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Similar to Signal, traffic that flows through the Relay can't be decrypted due to the **Wireguard peer-to-peer encryption**.
|
||||
</Note>
|
||||
|
||||
It runs in the cloud or can be self-hosted.
|
||||
|
||||
[//]: # (### STUN (NAT Traversal))
|
||||
|
||||
|
||||
## General Flow Overview
|
||||
|
||||
Below is a high level, step-by-step overview of the flow of communications within NetBird.
|
||||
|
||||
1. Administrator creates an account at [app.netbird.io](https://app.netbird.io/).
|
||||
2. The system automatically generates a new network with an allocated address block <em>100.64.0.0/10</em>.
|
||||
3. The system automatically generates 2 [setup keys](/overview/setup-keys) that can be used for authenticating new machines.
|
||||
4. Administrator (or a user) installs NetBird client and runs ```netbird up``` command providing one of the setup keys.
|
||||
5. NetBird client generates Wireguard private and public keys along with the initial configuration.
|
||||
6. NetBird client sends a registration request to the NetBird Management service calling Login gRPC endpoint, providing setup key, Wireguard public key and additional information about the machine.
|
||||
7. NetBird Management service checks the provided setup key, registers the machine and returns initial configuration to the NetBird client.
|
||||
8. NetBird client receives initial configuration and starts the engine configuring Wireguard, connecting to the Signal Service channel, and the Management Service network updates channel.
|
||||
9. NetBird client receives network map update from the Management Service that includes a list of peers/machines to connect to, and a private IP address.
|
||||
10. For each peer NetBird client initiates a connection process by sending a connection offer message through the Signal service indicating its intent to connect, and a Wireguard public key.
|
||||
11. If the client wasn't the initiator of the connection and receives an offer message, it checks whether the initiator is in the allowed peers list and sends an acknowledgement message through Signal.
|
||||
12. Once the acknowledgement message has been received, NetBird Client (on both ends) starts a connection negotiation process using [Interactive Connectivity Establishment protocol (ICE)](https://datatracker.ietf.org/doc/html/rfc8445).
|
||||
13. Once the direct connection between peers has been established successfully, NetBird Client starts proxying data to Wireguard.
|
||||
14. In case a direct Wireguard connection is possible (e.g., peers are in the same network or one of the peers has a public IP), NetBird Client establishes a direct Wireguard connection avoiding proxy.
|
||||
15. NetBird Client keeps a connection to the Management service receiving network updates such as new peers joining the network or peers deleted from the network.
|
||||
16. When a new peer joins the network, the NetBird client receives an update and triggers connection (see #10).
|
||||
17. When network administrator removes a peer, the NetBird client receives an update and removes the connection.
|
||||
@@ -1,399 +0,0 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern"; import {Note} from "@/components/mdx";
|
||||
|
||||
<HeroPattern />
|
||||
|
||||
export const title = 'How NetBird Works'
|
||||
|
||||
## Architecture
|
||||
|
||||
### Overview
|
||||
NetBird is an open source platform consisting of a collection of components, responsible for handling peer-to-peer connections, tunneling, authentication, and network management (IPs, keys, ACLs, etc).
|
||||
|
||||
It uses open-source technologies like [WireGuard®](https://www.wireguard.com/), [Pion ICE (WebRTC)](https://github.com/pion/ice), [Coturn](https://github.com/coturn/coturn),
|
||||
and [software](https://github.com/netbirdio/netbird) developed by NetBird authors to make secure private networks deployment and management simple.
|
||||
|
||||
NetBird relies on four components - **Client** application (or agent), **Management**, **Signal** and **Relay** services.
|
||||
|
||||
The combination of these elements ensures that direct point-to-point connections are established and only authenticated users (or machines) have access to the resources for which they are authorized.
|
||||
|
||||
A **Peer** is a machine or any device that is connected to the network.
|
||||
It can be a Linux server running in the cloud or on-premises, a personal laptop, or even a Raspberry PI.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/high-level-dia.png" alt="high-level-dia" width="781" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
With NetBird clients installed and authorized on the Management service, machines form a mesh network connecting to each other directly via an encrypted point-to-point Wireguard tunnel.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/mesh.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>
|
||||
|
||||
While it is possible to create a full mesh network, it might be not a desirable outcome. In this case, [ACLs](/overview/acls) can be utilized to limit the access to certain machines.
|
||||
|
||||
Let's now take a closer look at each of NetBird's components.
|
||||
|
||||
### Management Service
|
||||
|
||||
The Management service is the central coordination component for NetBird with a UI dashboard.
|
||||
It keeps the network state, public Wireguard keys of the peers, authenticates and distributes network changes to peers.
|
||||
|
||||
The Management Service's responsibilities include:
|
||||
|
||||
* **Registering and authenticating new peers.** Every new machine has to register itself in the network in order to connect to other machines.
|
||||
After installation, NetBird client requires login that can be done through Identity Provider (IDP) or with a [setup key](/overview/setup-keys).
|
||||
* **Keeping the network map.** The Management service stores information about all the registered peers including Wireguard public key that was sent during the registration process.
|
||||
* **Managing private IP addresses.** Each peer receives a unique private IP with which it can be identified in the network.
|
||||
We use [Carrier Grade NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) address space with an allocated address block <em>100.64.0.0/10</em>.
|
||||
* **Synchronizing network changes to peers.** The Management Service keeps a control channel open to each peer sending network updates.
|
||||
Whenever a new peer joins the network, all other peers that are authorized to connect to it receive an update.
|
||||
After that, they are able to establish a connection to the new peer.
|
||||
* **Creating and managing ACLs.** ACL is a list of peers that a given peer has access to. <em>Coming Soon</em>.
|
||||
* **Managing private DNS.** [DNS](/overview/dns) allows referring to each of the peers with a fully qualified domain name (FQDN). <em>Coming Soon</em>.
|
||||
* **Monitoring network activity.** <em>Coming Soon</em>.
|
||||
* **Wireguard key rotation.** <em>Coming Soon</em>.
|
||||
|
||||
The Management service runs in the cloud NetBird-managed. It can also be self-hosted.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/management.png" alt="management-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
### Client Application
|
||||
|
||||
The NetBird Client application (or agent) is a software that is installed on your machines.
|
||||
It is an entry point to you private network that makes it possible for machines to communicate with each other.
|
||||
Once installed and registered, a machine becomes a peer in the network.
|
||||
|
||||
The Client's roles are the following:
|
||||
|
||||
* **Generating private and public Wireguard keys.** These keys are used for packet encryption between peers and for [Wireguard Cryptokey Routing](https://www.wireguard.com/#cryptokey-routing).
|
||||
To accept the incoming connections, peers have to know each other, therefore, the generated public keys have to be pre-shared on the machines. The client application sends its public key to the Management service which then distributes it to the authorized peers.
|
||||
* **Handling peer registration and authentication.** Each peer has to be authenticated and registered in the system. The client application requests a user to log in with an Identity Provider (IDP) or a [setup key](/overview/setup-keys) so that the peer can be associated with the organization's account.
|
||||
* **Receiving network updates from the Management service.**
|
||||
Each peer receives initial configuration and a list of peers with corresponding public keys and IP addresses so that it can establish a peer-to-peer connection.
|
||||
* **Establishing peer-to-peer Wireguard connection.** To establish a connection with a remote peer, the Client first discovers the most suitable connection candidate, or simply address (IP:port) that other peer can use to connect to it.
|
||||
Then sends it to the remote peer via Signal. This message is encrypted with the peer's private key and a public key of the remote peer.
|
||||
The remote peer does the same and once the peers can reach each other, they establish an encrypted Wireguard tunnel.
|
||||
|
||||
<Note>
|
||||
The **private key**, generated by the Client, **never leaves the machine**, ensuring that only the machine that owns the key can decrypt traffic addressed to it.
|
||||
</Note>
|
||||
|
||||
### Signal Service
|
||||
|
||||
The Signal Service or simply Signal is a lightweight piece of software that helps peers to negotiate direct connections.
|
||||
It does not store any data and no traffic passes through it.
|
||||
|
||||
The only Signal's responsibility is:
|
||||
* **Serve as a notification mechanism for peers.** Before a connection can be established, peers need to find each other and exchange the most suitable connection candidates.
|
||||
This is done through Signal. After a connection has been established, Signal steps out.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/signal.png" alt="signal-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Messages that are sent over Signal are **peer-to-peer encrypted**, so Signal can't see the contents.
|
||||
</Note>
|
||||
|
||||
NetBird Signal is very similar to the signaling servers used in [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling#the_signaling_server).
|
||||
It runs in the cloud NetBird-managed and can be self-hosted.
|
||||
|
||||
### Relay Service
|
||||
|
||||
The Relay service is a [TURN server](https://webrtc.org/getting-started/turn-server) in WebRTC terminology.
|
||||
In fact, we use an open-source implementation called [Coturn](https://github.com/coturn/coturn).
|
||||
The purpose of this service is to be a "plan B" and relay traffic between peers in case a peer-to-peer connection isn't possible.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/relay.png" alt="relay-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Similar to Signal, traffic that flows through the Relay can't be decrypted due to the **Wireguard peer-to-peer encryption**.
|
||||
</Note>
|
||||
|
||||
It runs in the cloud or can be self-hosted.
|
||||
|
||||
[//]: # (### STUN (NAT Traversal))
|
||||
|
||||
|
||||
## General Flow Overview
|
||||
|
||||
Below is a high level, step-by-step overview of the flow of communications within NetBird.
|
||||
|
||||
1. Administrator creates an account at [app.netbird.io](https://app.netbird.io/).
|
||||
2. The system automatically generates a new network with an allocated address block <em>100.64.0.0/10</em>.
|
||||
3. The system automatically generates 2 [setup keys](/overview/setup-keys) that can be used for authenticating new machines.
|
||||
4. Administrator (or a user) installs NetBird client and runs ```netbird up``` command providing one of the setup keys.
|
||||
5. NetBird client generates Wireguard private and public keys along with the initial configuration.
|
||||
6. NetBird client sends a registration request to the NetBird Management service calling Login gRPC endpoint, providing setup key, Wireguard public key and additional information about the machine.
|
||||
7. NetBird Management service checks the provided setup key, registers the machine and returns initial configuration to the NetBird client.
|
||||
8. NetBird client receives initial configuration and starts the engine configuring Wireguard, connecting to the Signal Service channel, and the Management Service network updates channel.
|
||||
9. NetBird client receives network map update from the Management Service that includes a list of peers/machines to connect to, and a private IP address.
|
||||
10. For each peer NetBird client initiates a connection process by sending a connection offer message through the Signal service indicating its intent to connect, and a Wireguard public key.
|
||||
11. If the client wasn't the initiator of the connection and receives an offer message, it checks whether the initiator is in the allowed peers list and sends an acknowledgement message through Signal.
|
||||
12. Once the acknowledgement message has been received, NetBird Client (on both ends) starts a connection negotiation process using [Interactive Connectivity Establishment protocol (ICE)](https://datatracker.ietf.org/doc/html/rfc8445).
|
||||
13. Once the direct connection between peers has been established successfully, NetBird Client starts proxying data to Wireguard.
|
||||
14. In case a direct Wireguard connection is possible (e.g., peers are in the same network or one of the peers has a public IP), NetBird Client establishes a direct Wireguard connection avoiding proxy.
|
||||
15. NetBird Client keeps a connection to the Management service receiving network updates such as new peers joining the network or peers deleted from the network.
|
||||
16. When a new peer joins the network, the NetBird client receives an update and triggers connection (see #10).
|
||||
17. When network administrator removes a peer, the NetBird client receives an update and removes the connection.
|
||||
|
||||
|
||||
## Setup Keys
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### 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).
|
||||
|
||||
By default, we generate 2 setup keys right after account creation. You can easily add new or revoke keys.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/setup-keys.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>
|
||||
|
||||
<Note>
|
||||
When revoking a key, all machines authenticated with this key will remain connected in the network. The same logic applies when the key expires.
|
||||
</Note>
|
||||
### Expiration
|
||||
|
||||
Setup keys are set to expire after 30 days. When expired, the setup key can't be used anymore.
|
||||
|
||||
### Peer Auto-grouping
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/peer-auto-tagging-setupkey.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>
|
||||
|
||||
NetBird offers a powerful [Access Control feature](/overview/acls) 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 align="center">
|
||||
<img src="/img/architecture/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" width="500" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Auto-assign groups will apply only to newly registered machines.
|
||||
</Note>
|
||||
|
||||
|
||||
## Access Control
|
||||
NetBird allows administrators to restrict access to resources (peers) by creating access rules and
|
||||
defining what peer groups are permitted to establish connections with one another.
|
||||
|
||||
<div class="videowrapper">
|
||||
|
||||
<iframe src="https://www.youtube.com/embed/WvbkACjdsHA" allow="fullscreen;" width="800" height="500" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}></iframe>
|
||||
|
||||
</div>
|
||||
|
||||
### Introduction
|
||||
A NetBird account comes with a `Default` rule that allows all peers of the account to connect to each other forming a full mesh network.
|
||||
In most cases, this is the desired state for a small network or network that has low-security requirements.
|
||||
When you need to restrict access to certain resources that belong to specific users or services within your organization, you can create rules that dictate who can access what.
|
||||
|
||||
Access control rules make use of groups to control connections between peers; these groups can be added as `Source` or `Destination` of a rule and will be evaluated when the Management service distributes the list of peers across your network.
|
||||
|
||||
### Concepts
|
||||
#### Groups
|
||||
A NetBird group works and follows a similar concept to tags in other platforms; they are easily created and can be associated with peers and used in rules to control traffic within your network.
|
||||
|
||||
Some characteristics of groups:
|
||||
- They are unique.
|
||||
- One group can have multiple peers.
|
||||
- Peers can belong to multiple groups.
|
||||
- Rules can have multiple groups in their `Source` and `Destination` lists.
|
||||
- They are created in the `Access Control` or `Peers` tabs.
|
||||
- They can only be deleted via API.
|
||||
- There is a default group called `All`.
|
||||
|
||||
<Note>
|
||||
You can assign groups automatically with the [peer auto-grouping feature](/overview/setup-keys#peer-auto-grouping).
|
||||
</Note>
|
||||
|
||||
#### The All Group
|
||||
The `All` group is a default group to which every peer in your network is automatically added to. This group cannot be modified or deleted.
|
||||
#### Rules
|
||||
Rules are lists of `Source` and `Destination` groups of peers that can communicate with each other.
|
||||
Rules are processed when the Management service distributes a network map to all peers of your account. Because you can only create ALLOW rules, there is no processing
|
||||
order or priority, so the decision to distribute peer information is based on its association with a group belonging to an existing rule.
|
||||
|
||||
Currently, the communication between lists of groups in source and destination lists of a rule is bidirectional,
|
||||
meaning that destinations can also initiate connections to a group of peers listed in the source field of the rule.
|
||||
|
||||
The behavior of a network without any rules is to deny traffic. No peers will be able to communicate with each other.
|
||||
|
||||
<Note>
|
||||
If you need to allow peers from the same group to communicate with each other, just add the same group to the `Source` and `Destination` lists.
|
||||
</Note>
|
||||
|
||||
#### The Default Rule
|
||||
The `Default` rule is created when you first create your account. This rule is very permissive because it allows communication between all peers in your network.
|
||||
It uses the [`All`](#the-all-group) group as a source and destination. If you want to have better
|
||||
control over your network, it is recommended that you delete this rule and create more restricted rules with custom groups.
|
||||
|
||||
<Note>
|
||||
If you need to restrict communication within your network, you can create new rules and use different groups, and then remove the default rule to achieve the desired behavior.
|
||||
</Note>
|
||||
|
||||
#### Multiple Mesh Networks
|
||||
As mentioned above, rules are bidirectional, which is basically the control of how your network will behave as a mesh network.
|
||||
|
||||
There is a `Default` rule, which configures a Default mesh connection between all peers of your network. With rules, you can define smaller mesh networks by grouping peers and adding these groups to `Source` and `Destination` lists.
|
||||
### Managing Rules
|
||||
|
||||
#### Creating Rules
|
||||
After accessing the `Access Control` tab, you can click on the `Add Rule` button to create a new rule. This will open a screen
|
||||
where you need to name the rule, set its status, and add groups to the source and destination lists.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/create-rule.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>
|
||||
|
||||
If required, you can create new groups by simply entering new names in the input box for either source or destination lists.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/create-group-in-rule.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 are done configuring the rule, click the `Create` button to save it. You will then see your new rule in the table.
|
||||
<p align="center">
|
||||
<img src="/img/overview/new-rule-list.png" alt="high-level-dia" width="600" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Because of its permissiveness, new rules will take effect once you remove the `Default` rule.
|
||||
</Note>
|
||||
|
||||
#### Adding peers to groups
|
||||
If you create a new group when defining a rule, you will need to associate peers with this group.
|
||||
You can do it by accessing the `Peers` tab and clicking the `Groups` column of any peer you want to associate with the new group.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/associate-peer-groups.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>
|
||||
|
||||
<Note>
|
||||
You can assign groups automatically with the [peer auto-grouping feature](/overview/setup-keys#peer-auto-grouping).
|
||||
</Note>
|
||||
|
||||
#### Updating Rules
|
||||
To update a rule, you can click on the rule's `Name` or on either `Sources` and `Destinations` columns. You could also click the menu
|
||||
button of a rule and select `View`. This will open the same screen where you can update rule groups, description, or status.
|
||||
#### Disabling Rules
|
||||
To disable a rule, you should follow the steps of [updating rules](#updating-rules) changing its status, and then click on Save.
|
||||
#### Deleting Rules
|
||||
To delete a rule, you should click on the rule's menu and choose `Delete`. A confirmation window will pop up.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/delete-rule-menu.png" alt="high-level-dia" width="600" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/delete-rule-popup.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>
|
||||
|
||||
## Service Users
|
||||
|
||||
Service users are a type of account that allow applications or services to access resources and perform actions within your organization.
|
||||
|
||||
### What are Service Users used for?
|
||||
|
||||
Service users are typically used to authenticate requests to a web service on behalf of an application or a service. They are an alternative to using a personal account, and can provide additional security by allowing you to limit the scope of access granted to the service user.
|
||||
|
||||
Service users can be used in a variety of scenarios, including:
|
||||
|
||||
- **Automated scripts**: If you need to run automated scripts that access resources within your organization, you can use service users instead of storing your login credentials in plain text.
|
||||
- **Third-party integrations**: If you want to integrate your resources with a third-party service, you can use a service user to provide access to your data without giving the third-party service access to your personal account.
|
||||
- **Access control**: If you need to grant access to a specific set of resources to a particular application or service, you can create a service user with the necessary permissions.
|
||||
|
||||
### Creating a Service User
|
||||
|
||||
To create a service user, you'll need to log in to your organization's account and navigate to the "Service Users" section of your account settings.
|
||||
<p align="center">
|
||||
<img src="/img/overview/service-user-overview.png" alt="service-user-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
From there, you can create a new service user and specify the permissions that the user should have.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/service-user-creation.png" alt="service-user-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
It's important to keep your service users secure, as they can provide access to sensitive data and actions within your organization. You should treat your service users like you would treat your own personal account and limit the scope of access granted to the service user.
|
||||
</Note>
|
||||
|
||||
|
||||
## Personal Access Tokens
|
||||
|
||||
Personal access tokens are a type of authentication credential that allow you to access your account and perform actions on behalf of yourself or your organization.
|
||||
|
||||
### What are Personal Access Tokens used for?
|
||||
|
||||
Personal access tokens are typically used to authenticate API requests to a web service. They are an alternative to using your username and password, and can provide additional security by allowing you to limit the scope of access granted to the token.
|
||||
|
||||
Personal access tokens can be used in a variety of scenarios, including:
|
||||
|
||||
- **Automated scripts**: If you need to run automated scripts that access your account, you can use personal access tokens instead of storing your login credentials in plain text.
|
||||
- **Third-party integrations**: If you want to integrate your account with a third-party service, you can use a personal access token to provide access to your data without giving the third-party service your login credentials.
|
||||
- **Command-line tools**: If you use command-line tools to interact with your account, you can use personal access tokens to authenticate those requests.
|
||||
|
||||
### Creating a Personal Access Token
|
||||
|
||||
To create a personal access token, you'll need to log in to your account and navigate to the "Users" section and look for your user or create a [service user](#) to use for your API requests.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-overview.png" alt="personal-access-token-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
From there, you can create a new token and specify the permissions that the token should have.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-creation.png" alt="personal-access-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
After the token was generated successfully you will see a plain version of your token to copy and store in a secure place.
|
||||
Be aware that once you close the popup it is impossible to see the plain version of the token again as NetBird only stores a hashed version of the token.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-example.png" alt="personal-access-token-example" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
It's important to keep your personal access tokens secure, as they can provide access to sensitive data and actions within your account. You should treat your personal access tokens like you would treat your password and never share them with anyone else.
|
||||
</Note>
|
||||
|
||||
### Using Personal Access Tokens
|
||||
|
||||
Once you have created a personal access token, you can use it to authenticate requests to a web service that supports token-based authentication. To use a personal access token, you typically include it as an authentication header in your API requests.
|
||||
|
||||
For example, if you were using the GitHub API, you might include your personal access token like this:
|
||||
|
||||
With this header included, the GitHub API would authenticate your request using your personal access token and grant you access to the resources that the token has been authorized to access.
|
||||
119
src/pages/docs/how-to/access-control.mdx
Normal file
119
src/pages/docs/how-to/access-control.mdx
Normal file
@@ -0,0 +1,119 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern";
|
||||
|
||||
<HeroPattern/>
|
||||
|
||||
# Access Control
|
||||
NetBird allows administrators to restrict access to resources (peers) by creating access rules and
|
||||
defining what peer groups are permitted to establish connections with one another.
|
||||
|
||||
<div class="videowrapper">
|
||||
|
||||
<iframe src="https://www.youtube.com/embed/WvbkACjdsHA" allow="fullscreen;" width="800" height="500" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}></iframe>
|
||||
|
||||
</div>
|
||||
|
||||
## Introduction
|
||||
A NetBird account comes with a `Default` rule that allows all peers of the account to connect to each other forming a full mesh network.
|
||||
In most cases, this is the desired state for a small network or network that has low-security requirements.
|
||||
When you need to restrict access to certain resources that belong to specific users or services within your organization, you can create rules that dictate who can access what.
|
||||
|
||||
Access control rules make use of groups to control connections between peers; these groups can be added as `Source` or `Destination` of a rule and will be evaluated when the Management service distributes the list of peers across your network.
|
||||
|
||||
## Concepts
|
||||
### Groups
|
||||
A NetBird group works and follows a similar concept to tags in other platforms; they are easily created and can be associated with peers and used in rules to control traffic within your network.
|
||||
|
||||
Some characteristics of groups:
|
||||
- They are unique.
|
||||
- One group can have multiple peers.
|
||||
- Peers can belong to multiple groups.
|
||||
- Rules can have multiple groups in their `Source` and `Destination` lists.
|
||||
- They are created in the `Access Control` or `Peers` tabs.
|
||||
- They can only be deleted via API.
|
||||
- There is a default group called `All`.
|
||||
|
||||
<Note>
|
||||
You can assign groups automatically with the [peer auto-grouping feature](/overview/setup-keys#peer-auto-grouping).
|
||||
</Note>
|
||||
|
||||
### The All Group
|
||||
The `All` group is a default group to which every peer in your network is automatically added to. This group cannot be modified or deleted.
|
||||
### Rules
|
||||
Rules are lists of `Source` and `Destination` groups of peers that can communicate with each other.
|
||||
Rules are processed when the Management service distributes a network map to all peers of your account. Because you can only create ALLOW rules, there is no processing
|
||||
order or priority, so the decision to distribute peer information is based on its association with a group belonging to an existing rule.
|
||||
|
||||
Currently, the communication between lists of groups in source and destination lists of a rule is bidirectional,
|
||||
meaning that destinations can also initiate connections to a group of peers listed in the source field of the rule.
|
||||
|
||||
The behavior of a network without any rules is to deny traffic. No peers will be able to communicate with each other.
|
||||
|
||||
<Note>
|
||||
If you need to allow peers from the same group to communicate with each other, just add the same group to the `Source` and `Destination` lists.
|
||||
</Note>
|
||||
|
||||
### The Default Rule
|
||||
The `Default` rule is created when you first create your account. This rule is very permissive because it allows communication between all peers in your network.
|
||||
It uses the [`All`](#the-all-group) group as a source and destination. If you want to have better
|
||||
control over your network, it is recommended that you delete this rule and create more restricted rules with custom groups.
|
||||
|
||||
<Note>
|
||||
If you need to restrict communication within your network, you can create new rules and use different groups, and then remove the default rule to achieve the desired behavior.
|
||||
</Note>
|
||||
|
||||
### Multiple Mesh Networks
|
||||
As mentioned above, rules are bidirectional, which is basically the control of how your network will behave as a mesh network.
|
||||
|
||||
There is a `Default` rule, which configures a Default mesh connection between all peers of your network. With rules, you can define smaller mesh networks by grouping peers and adding these groups to `Source` and `Destination` lists.
|
||||
## Managing Rules
|
||||
|
||||
### Creating Rules
|
||||
After accessing the `Access Control` tab, you can click on the `Add Rule` button to create a new rule. This will open a screen
|
||||
where you need to name the rule, set its status, and add groups to the source and destination lists.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/create-rule.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>
|
||||
|
||||
If required, you can create new groups by simply entering new names in the input box for either source or destination lists.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/create-group-in-rule.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 are done configuring the rule, click the `Create` button to save it. You will then see your new rule in the table.
|
||||
<p align="center">
|
||||
<img src="/img/overview/new-rule-list.png" alt="high-level-dia" width="600" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Because of its permissiveness, new rules will take effect once you remove the `Default` rule.
|
||||
</Note>
|
||||
|
||||
### Adding peers to groups
|
||||
If you create a new group when defining a rule, you will need to associate peers with this group.
|
||||
You can do it by accessing the `Peers` tab and clicking the `Groups` column of any peer you want to associate with the new group.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/associate-peer-groups.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>
|
||||
|
||||
<Note>
|
||||
You can assign groups automatically with the [peer auto-grouping feature](/overview/setup-keys#peer-auto-grouping).
|
||||
</Note>
|
||||
|
||||
### Updating Rules
|
||||
To update a rule, you can click on the rule's `Name` or on either `Sources` and `Destinations` columns. You could also click the menu
|
||||
button of a rule and select `View`. This will open the same screen where you can update rule groups, description, or status.
|
||||
### Disabling Rules
|
||||
To disable a rule, you should follow the steps of [updating rules](#updating-rules) changing its status, and then click on Save.
|
||||
### Deleting Rules
|
||||
To delete a rule, you should click on the rule's menu and choose `Delete`. A confirmation window will pop up.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/delete-rule-menu.png" alt="high-level-dia" width="600" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/delete-rule-popup.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>
|
||||
32
src/pages/docs/how-to/activity.mdx
Normal file
32
src/pages/docs/how-to/activity.mdx
Normal file
@@ -0,0 +1,32 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern";
|
||||
|
||||
<HeroPattern/>
|
||||
|
||||
# Activity
|
||||
|
||||
## 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="/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>
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</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 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
|
||||
158
src/pages/docs/how-to/dns.mdx
Normal file
158
src/pages/docs/how-to/dns.mdx
Normal file
@@ -0,0 +1,158 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern";
|
||||
|
||||
<HeroPattern/>
|
||||
|
||||
# DNS
|
||||
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
Nameservers is available for NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later.
|
||||
</Note>
|
||||
|
||||
### 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.
|
||||
<Note>
|
||||
Custom port support is not builtin into most operating systems. At the time of release, the supported systems are:
|
||||
- MacOS
|
||||
- Linux with systemd-resolved
|
||||
</Note>
|
||||
#### 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.
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
#### Distribution groups
|
||||
Distribution defines that peers that belong to groups set in this field will receive the nameserver configuration.
|
||||
<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 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="/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="/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="/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="/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="/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>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
#### 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="/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="/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
|
||||
189
src/pages/docs/how-to/network-routes.mdx
Normal file
189
src/pages/docs/how-to/network-routes.mdx
Normal file
@@ -0,0 +1,189 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern";
|
||||
|
||||
<HeroPattern/>
|
||||
|
||||
# Network Routes
|
||||
|
||||
## 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="/img/how-to-guides/netbird-network-routes.png" alt="high-level-dia" />
|
||||
</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 simple! :)
|
||||
</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, a routing peer, and some parameters available for managing priority and masquerading.
|
||||
<Note>
|
||||
Network routes is available for 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 node that will route packets between your routed network and the other NetBird peers.
|
||||
<Note>
|
||||
Only Linux OS nodes can be assigned as routing peers.
|
||||
</Note>
|
||||
#### 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.
|
||||
<Note>
|
||||
It doesn't remove the need for the routing peer to be connected to these peers
|
||||
</Note>
|
||||
|
||||
### 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="/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="/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="/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="/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="/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>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
#### 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="/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
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
<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](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) 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 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="/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>
|
||||
|
||||
<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>
|
||||
|
||||
### 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
|
||||
7
src/pages/docs/how-to/peers.mdx
Normal file
7
src/pages/docs/how-to/peers.mdx
Normal file
@@ -0,0 +1,7 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern";
|
||||
|
||||
<HeroPattern/>
|
||||
|
||||
# Peers
|
||||
|
||||
tba
|
||||
55
src/pages/docs/how-to/settings.mdx
Normal file
55
src/pages/docs/how-to/settings.mdx
Normal file
@@ -0,0 +1,55 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern";
|
||||
|
||||
<HeroPattern/>
|
||||
|
||||
# Settings
|
||||
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
Expired peers will appear in the peers' view with the status `needs login`.
|
||||
|
||||
<p align="center">
|
||||
<img src="/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="/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>
|
||||
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
### 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="/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
|
||||
64
src/pages/docs/how-to/setup-keys.mdx
Normal file
64
src/pages/docs/how-to/setup-keys.mdx
Normal file
@@ -0,0 +1,64 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern";
|
||||
|
||||
<HeroPattern/>
|
||||
|
||||
# Setup Keys
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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).
|
||||
|
||||
By default, we generate 2 setup keys right after account creation. You can easily add new or revoke keys.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/setup-keys.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>
|
||||
|
||||
<Note>
|
||||
When revoking a key, all machines authenticated with this key will remain connected in the network. The same logic applies when the key expires.
|
||||
</Note>
|
||||
### Expiration
|
||||
|
||||
Setup keys are set to expire after 30 days. When expired, the setup key can't be used anymore.
|
||||
|
||||
## Peer Auto-grouping
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/peer-auto-tagging-setupkey.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>
|
||||
|
||||
NetBird offers a powerful [Access Control feature](/overview/acls) 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 align="center">
|
||||
<img src="/img/architecture/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" width="500" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Auto-assign groups will apply only to newly registered machines.
|
||||
</Note>
|
||||
|
||||
84
src/pages/docs/how-to/users.mdx
Normal file
84
src/pages/docs/how-to/users.mdx
Normal file
@@ -0,0 +1,84 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern";
|
||||
|
||||
<HeroPattern/>
|
||||
|
||||
# Users
|
||||
|
||||
## Service Users
|
||||
|
||||
Service users are a type of account that allow applications or services to access resources and perform actions within your organization.
|
||||
|
||||
### What are Service Users used for?
|
||||
|
||||
Service users are typically used to authenticate requests to a web service on behalf of an application or a service. They are an alternative to using a personal account, and can provide additional security by allowing you to limit the scope of access granted to the service user.
|
||||
|
||||
Service users can be used in a variety of scenarios, including:
|
||||
|
||||
- **Automated scripts**: If you need to run automated scripts that access resources within your organization, you can use service users instead of storing your login credentials in plain text.
|
||||
- **Third-party integrations**: If you want to integrate your resources with a third-party service, you can use a service user to provide access to your data without giving the third-party service access to your personal account.
|
||||
- **Access control**: If you need to grant access to a specific set of resources to a particular application or service, you can create a service user with the necessary permissions.
|
||||
|
||||
### Creating a Service User
|
||||
|
||||
To create a service user, you'll need to log in to your organization's account and navigate to the "Service Users" section of your account settings.
|
||||
<p align="center">
|
||||
<img src="/img/overview/service-user-overview.png" alt="service-user-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
From there, you can create a new service user and specify the permissions that the user should have.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/service-user-creation.png" alt="service-user-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
It's important to keep your service users secure, as they can provide access to sensitive data and actions within your organization. You should treat your service users like you would treat your own personal account and limit the scope of access granted to the service user.
|
||||
</Note>
|
||||
|
||||
|
||||
## Personal Access Tokens
|
||||
|
||||
Personal access tokens are a type of authentication credential that allow you to access your account and perform actions on behalf of yourself or your organization.
|
||||
|
||||
### What are Personal Access Tokens used for?
|
||||
|
||||
Personal access tokens are typically used to authenticate API requests to a web service. They are an alternative to using your username and password, and can provide additional security by allowing you to limit the scope of access granted to the token.
|
||||
|
||||
Personal access tokens can be used in a variety of scenarios, including:
|
||||
|
||||
- **Automated scripts**: If you need to run automated scripts that access your account, you can use personal access tokens instead of storing your login credentials in plain text.
|
||||
- **Third-party integrations**: If you want to integrate your account with a third-party service, you can use a personal access token to provide access to your data without giving the third-party service your login credentials.
|
||||
- **Command-line tools**: If you use command-line tools to interact with your account, you can use personal access tokens to authenticate those requests.
|
||||
|
||||
### Creating a Personal Access Token
|
||||
|
||||
To create a personal access token, you'll need to log in to your account and navigate to the "Users" section and look for your user or create a [service user](#) to use for your API requests.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-overview.png" alt="personal-access-token-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
From there, you can create a new token and specify the permissions that the token should have.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-creation.png" alt="personal-access-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
After the token was generated successfully you will see a plain version of your token to copy and store in a secure place.
|
||||
Be aware that once you close the popup it is impossible to see the plain version of the token again as NetBird only stores a hashed version of the token.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-example.png" alt="personal-access-token-example" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
It's important to keep your personal access tokens secure, as they can provide access to sensitive data and actions within your account. You should treat your personal access tokens like you would treat your password and never share them with anyone else.
|
||||
</Note>
|
||||
|
||||
### Using Personal Access Tokens
|
||||
|
||||
Once you have created a personal access token, you can use it to authenticate requests to a web service that supports token-based authentication. To use a personal access token, you typically include it as an authentication header in your API requests.
|
||||
|
||||
For example, if you were using the GitHub API, you might include your personal access token like this:
|
||||
|
||||
With this header included, the GitHub API would authenticate your request using your personal access token and grant you access to the resources that the token has been authorized to access.
|
||||
@@ -1,420 +0,0 @@
|
||||
import {HeroPattern} from "@/components/HeroPattern"; import {Button, Note} from "@/components/mdx";
|
||||
|
||||
<HeroPattern />
|
||||
|
||||
export const title = 'How-to Guides'
|
||||
|
||||
## 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="/img/how-to-guides/netbird-network-routes.png" alt="high-level-dia" />
|
||||
</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 simple! :)
|
||||
</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, a routing peer, and some parameters available for managing priority and masquerading.
|
||||
<Note>
|
||||
Network routes is available for 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 node that will route packets between your routed network and the other NetBird peers.
|
||||
<Note>
|
||||
Only Linux OS nodes can be assigned as routing peers.
|
||||
</Note>
|
||||
#### 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.
|
||||
<Note>
|
||||
It doesn't remove the need for the routing peer to be connected to these peers
|
||||
</Note>
|
||||
|
||||
### 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="/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="/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="/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="/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="/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>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
#### 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="/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
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
<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](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) 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 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="/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>
|
||||
|
||||
<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>
|
||||
|
||||
### 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
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
Nameservers is available for NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later.
|
||||
</Note>
|
||||
|
||||
### 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.
|
||||
<Note>
|
||||
Custom port support is not builtin into most operating systems. At the time of release, the supported systems are:
|
||||
- MacOS
|
||||
- Linux with systemd-resolved
|
||||
</Note>
|
||||
#### 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.
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
#### Distribution groups
|
||||
Distribution defines that peers that belong to groups set in this field will receive the nameserver configuration.
|
||||
<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 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="/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="/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="/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="/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="/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>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
#### 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="/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="/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
|
||||
|
||||
## 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="/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>
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</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 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
|
||||
|
||||
## 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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
Expired peers will appear in the peers' view with the status `needs login`.
|
||||
|
||||
<p align="center">
|
||||
<img src="/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="/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>
|
||||
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
### 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="/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
|
||||
Reference in New Issue
Block a user