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

Move the documentation repository to a public repo

Browse Source 
Added a LICENSE and documentation on how to contribute

Updated CI/CD to use the root level code
This commit is contained in:
mlsmaycon
2022-06-20 19:05:25 +02:00
parent 219bc7b9f4
commit 98751bc1f4
64 changed files with 10203 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/overview/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "How NetBird Works",
"position": 2
}

105
docs/overview/acls.md Normal file
View File

@@ -0,0 +1,105 @@
---
sidebar_position: 4
---
# 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.
## 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`.
### 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.
:::tip
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.
:::
### 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.
:::tip
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.
:::
### 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="/docs/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="/docs/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="/docs/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>
:::caution Reminder
Because of its permissiveness, new rules will take effect once you remove the `Default` rule.
:::
#### 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="/docs/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>
### 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="/docs/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="/docs/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>

123
docs/overview/architecture.md Normal file
View File

@@ -0,0 +1,123 @@
---
sidebar_position: 1
---
# 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="/docs/img/architecture/high-level-dia.png" alt="high-level-dia" width="781"/>
</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="/docs/img/architecture/mesh.png" alt="high-level-dia"/>
</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="/docs/img/architecture/management.png" alt="management-dia"/>
</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.
:::important
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.
:::
### 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="/docs/img/architecture/signal.png" alt="signal-dia"/>
</p>
:::important
Messages that are sent over Signal are **peer-to-peer encrypted**, so Signal can't see the contents.
:::
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="/docs/img/architecture/relay.png" alt="relay-dia"/>
</p>
:::important
Similar to Signal, traffic that flows through the Relay can't be decrypted due to the **Wireguard peer-to-peer encryption**.
:::
It runs in the cloud or can be self-hosted.
### STUN (NAT Traversal)

5
docs/overview/dns.md Normal file
View File

@@ -0,0 +1,5 @@
---
sidebar_position: 5
---
# Private DNS

26
docs/overview/general-flow.md Normal file
View File

@@ -0,0 +1,26 @@
---
sidebar_position: 2
---
# 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.

36
docs/overview/setup-keys.md Normal file
View File

@@ -0,0 +1,36 @@
---
sidebar_position: 3
---
# 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
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.
![](/img/architecture/setup-keys.png)
:::tip revoking a key
When revoking a key, all machines authenticated with this key will remain connected in the network. The same logic applies when the key expires.
:::
### Expiration
Setup keys are set to expire after 30 days. When expired, the setup key can't be used anymore.