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

Move docs to root

Browse Source
This commit is contained in:
braginini
2023-05-23 21:34:03 +02:00
parent 8d913a349d
commit 04ea9c4991
32 changed files with 100 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

58
src/pages/about-netbird/faq.mdx Normal file
View File

@@ -0,0 +1,58 @@
import {Note} from "@/components/mdx";
export const title = 'FAQ'
## What firewall ports should I open to use NetBird?
### Incoming ports
NetBird's agent doesn't require any incoming port to be open; It negotiates the connection with the support of the signal and relay services.
### Outgoing ports
NetBird usually won't need open ports, but sometimes you or your IT team needs to secure and verify
all outgoing traffic, and that may affect how NetBird clients connect to the [control layer](/about-netbird/how-netbird-works)
and negotiate the peer-to-peer connections.
Below is the list of NetBird hosted endpoints and ports they listen to:
* Management service:
* **Endpoint**: api.wiretrustee.com
* **Port**: TCP/443
* Signal service:
* **Endpoint**: signal2.wiretrustee.com
* **Port**: TCP/443
* Relay (TURN) service:
* **Endpoint**: turn.netbird.io
* **Port range**: UDP/5555-65535
## Why and what are the anonymous usage metrics?
### Why we added metrics collection?
As an open-source project and business, making decisions based on data is essential. We will know our adoption rate, feature usage, and client type with anonymous metrics.
<Note>
The collection is strict to our management system.
</Note>
If the metric collection infringes any internal regulation or policy, it can be disabled by setting the flag `--disable-anonymous-metrics=true` to the management service startup command.
### What are the metrics being collected?
We are collecting the following metrics:
* Number of accounts
* Number of users
* Number of peers
* Number of active peers in the last 24 hours
* Number of peers per operating system
* Number of setup keys usage
* Number of peers activated by users
* Number of rules
* Number of groups
* Number of routes
* Number of nameservers
* Service uptime
* Service version
* Metrics generation time
### Metrics UUID
We are using an installation ID for each management service which is generated once and stored in your management store database. It doesn't have any trace of any other private information, and it helps distinguish each deployment.
### Metrics pusher IP
We are not storing the pusher IP address; it gets discarded once the request is complete.

140
src/pages/about-netbird/how-netbird-works.mdx Normal file
View File

@@ -0,0 +1,140 @@
import {Note} from "@/components/mdx";
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>
<img src="/docs-static/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>
<img src="/docs-static/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](/how-to/manage-network-access) 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](/how-to/register-machines-using-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](docs/how-to/manage-dns-in-your-network) 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>
<img src="/docs-static/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>
<img src="/docs-static/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/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>
<img src="/docs-static/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 &#40;NAT Traversal&#41;)
## 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](/how-to/register-machines-using-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.

31
src/pages/about-netbird/netbird-vs-traditional-vpn.mdx Normal file
View File

@@ -0,0 +1,31 @@
# NetBird vs. Traditional VPN
## Traditional VPN challenges
In the traditional VPN model, everything converges on a centralized, protected network where all the clients are connecting to a central VPN server.
An increasing amount of connections can easily overload the VPN server.
Even a short downtime of a server can cause expensive system disruptions, and a remote team's inability to work.
Centralized VPNs imply all the traffic going through the central server causing network delays and increased traffic usage.
Such systems require an experienced team to set up and maintain.
Configuring firewalls, setting up NATs, SSO integration, and managing access control lists can be a nightmare.
Traditional centralized VPNs are often compared to a [castle-and-moat](https://en.wikipedia.org/wiki/Moat) model
in which once accessed, user is trusted and can access critical infrastructure and resources without any restrictions.
## NetBird benefits
NetBird decentralizes networks using direct point-to-point connections, as opposed to traditional models.
Consequently, network performance is increased since traffic flows directly between the machines bypassing VPN servers or gateways.
To achieve this, NetBird client applications employ signalling servers to find other machines and negotiate connections.
These are 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)
Thanks to [NAT traversal techniques](https://en.wikipedia.org/wiki/NAT_traversal),
outlined in the [Why Wireguard with NetBird](/about-netbird/why-wireguard-with-netbird) section,
NetBird installation doesn't require complex network and firewall configuration.
It just works, minimising the maintenance effort.
Finally, each machine or device in the NetBird network verifies incoming connections accepting only the trusted ones.
This is ensured by Wireguard's [Crypto Routing concept](https://www.wireguard.com/#cryptokey-routing).

222
src/pages/about-netbird/other.mdx Normal file
View File

@@ -0,0 +1,222 @@
import {Note} from "@/components/mdx";
export const title = 'Other'
## Google Summer of Code Ideas - 2022
This page lists the all project ideas for [Google Summer of Code 2022](https://summerofcode.withgoogle.com/).
We require all applicants to complete a [task](#task).
Join our [Slack channel](https://join.slack.com/t/wiretrustee/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A) and talk to your potential mentors!
### Task
The goal of the task is to get familiar with the system by setting up a self-hosted version of Netbrid.
1. Carefully review projects' documentation.
2. Deploy a self-hosted version of NetBird.
3. Register at least 2 peers in the system (can be a laptop, server or even Raspberry PI).
<Note>
It is possible to set up multiple peers on the same machine. Find out how!
</Note>
4. Ping machines and make sure that they are reachable.
5. We might ask you to provide a generated [setup key](/how-to/setup-keys) so that we could test your setup.
Please reach out to us with any questions. We believe you will have some! :)
In case this task seems to be difficult, no worries!
You could skip #1 and #2 starting with #3 using managed version of NetBird (https://app.netbird.io).
### Project Ideas
There are a few categories that our ideas fall into:
* **UI** - mostly around our Management service Dashboard ([Github repo](https://github.com/netbirdio/dashboard))
* **Client** - our client application ([Github Repo](https://github.com/netbirdio/netbird/tree/main/client))
* **Server** - our Management and Signal server applications ([Management Github Repo](https://github.com/netbirdio/netbird/tree/main/management) and [Signal Github Repo](https://github.com/netbirdio/netbird/tree/main/signal))
* **Portability** - ability to run client and server applications on different platforms (e.g. OpenWRT)
* **Infrastructure** - deployment, CI/CD, scaling, infrastructure as code improvements, etc.
* **Integrations** - integration between the project and different platforms, like CI/CD, Kubernetes or specific cloud providers.
### Idea: Make NetBird run on routers
<Note>
OpenWrt is an open-source project for embedded operating systems based on Linux, primarily used on embedded devices to route network traffic.
https://openwrt.org/
</Note>
NetBird runs on different platforms and can also be compiled to run on routers. For that, we are thinking to work on this support for the popular wireless router OpenWRT.
We are already building, but we lack packaging and repository for distribution and this is the main goal of this task.
> **Category:** Portability/Infrastructure
>
> **Goal:** Create OpenWRT package (ipk) for one of the popular routers. Setup CI/CD ipk build flow with Github Actions.
>
> **Skills:** Golang, Linux, bash, OpenWRT, cmake
>
> **Project Size:** 175 hours
>
> **Rating:** easy
>
> **Possible mentor:** [Maycon Santos](https://github.com/mlsmaycon)
>
> **Reference:** https://medium.com/@theshemul/make-golang-program-for-router-39bf18529b18
>
> **Reference:** https://openwrt.org/docs/guide-developer/packages
### Idea: Software Firewall with eBPF
<Note>
eBPF is a revolutionary technology with origins in the Linux kernel that can run sandboxed programs in an operating system kernel.
https://ebpf.io/
</Note>
When running on machines NetBird client application tries to be as efficient as possible.
On Linux machines NetBird can use kernel modules like Wireguard and features like eBPF to be the most efficient.
Besides connectivity, NetBird can control access. Right now it is achieved on a connection level -
if a peer is in the allowed list, it can connect. If not, the connection is rejected.
It is more advantageous to work on a finer level - defining what packets to allow/block and on which ports.
For that eBPF can be integrated into the client application.
The flow could be the following: client receives rules from the Management service and creates ePBF.
> **Category:** Client/Server
>
> **Goal:** MVP of a eBPF port filtering on client applications (Linux)
>
> **Skills:** Golang, Linux
>
> **Project Size:** 350 hours
>
> **Rating:** hard
>
> **Possible mentor:** [Mikhail Bragin](https://github.com/braginini)
>
> **Reference:** https://ebpf.io/
### Idea: NetBird client running in the browser
<Note>
WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine.
Wasm is designed as a portable compilation target for programming languages, enabling deployment on the web for client
and server applications.
</Note>
NetBird requires a client application installed to connect machines to each other.
In some environments it might not be possible or forbidden to install applications.
But there always might be an option to run a browser!
The idea of this project is to make NetBird run in the browser using WASM and WebRTC.
A user would log in to the Management Dashboard and open a virtual terminal (e.g. https://xtermjs.org/).
Browser will then establish a connection to the network and user would be able to access remote servers.
> **Category:** UI/Client/Server
>
> **Goal:** Interactive console running in the browser establishing connection to the NetBird network.
>
> **Skills:** Golang, Linux, Javascript
>
> **Project Size:** 350 hours
>
> **Rating:** hard
>
> **Possible mentor:** [Mikhail Bragin](https://github.com/braginini) / [Maycon Santos](https://github.com/mlsmaycon)
>
> **Reference:** https://webassembly.org/
>
> **Reference:** https://webrtc.org/
>
> **Reference:** https://xtermjs.org/
### Idea: Integrate NetBird with Kubernetes
<Note>
Kubernetes, also known as K8s, is an open-source system for automating deployment, scaling, and management of containerized applications.
</Note>
Having a private Kubernetes cluster is a best practices that come with some connectivity challenges,
especially to operators and developers that need to access resources running within the cluster like services,
pods and the Kubernetes API.
The idea of this project is to integrate NetBird with Kubernetes by creating a controller that would add an agent
per cluster node and would handle the login process of the agent and store the states in form of Kubernetes secrets.
As Kubernetes is a cloud-native platform, you can imagine that are some caveats that we will have to deal with, like nodes being removed and added all the time,
different network controllers, and different cloud environments.
> **Category:** Client/Infrastructure/Integrations
>
> **Goal:** Integrate NetBird with Kubernetes for automatic provision of agents.
>
> **Skills:** Golang, Linux, Kubernetes API
>
> **Project Size:** 350 hours
>
> **Rating:** hard
>
> **Possible mentor:** [Maycon Santos](https://github.com/mlsmaycon), [Sang Woo Bae](https://github.com/shatoboar)
>
> **Reference:** https://kubernetes.io/
>
> **Reference:** https://kubernetes.io/docs/concepts/architecture/controller/
>
> **Reference:** https://kubernetes.io/blog/2021/06/21/writing-a-controller-for-pod-labels/
### Idea: NetBird Github Action
<Note>
GitHub Actions makes it easy to automate all your software workflows, now with world-class CI/CD. Build, test, and deploy your code right from GitHub.
Make code reviews, branch management, and issue triaging work the way you want.
</Note>
We love Github Actions, because of its primary concept, Actions. They allow us to automate complex workflows and provide a simple interface
to be configured and executed before building or testing our code.
The idea of this project is to create a NetBird agent action, that would download and run an ephemeral agent on Github Actions workflows. The benefits of this
could be great as it would allow many users that rely on the public runners to access private resources, in a secure and dynamic way.
> **Category:** Server/Client/Integrations
>
> **Goal:** Create a NetBird Github Action.
>
> **Skills:** Golang, Bash, Javascript
>
> **Project Size:** 175 hours
>
> **Rating:** easy
>
> **Possible mentor:** [Maycon Santos](https://github.com/mlsmaycon)
>
> **Reference:** https://docs.github.com/en/actions
>
> **Reference:** https://docs.netbird.io/getting-started/quickstart
>
> **Reference:** https://docs.github.com/en/actions/creating-actions/about-custom-actions
### Idea: Mobile Client APPs
Nowadays people are always connected with mobile phones and very often they need to access remote resources with them.
The idea of this project is to create a NetBird mobile app for either Android or iOS that would follow one of the principles of our product, simplicity.
Initially we think to export our Go APIs using GoMobile that would help with a good chuck of the heavy lifting.
> **Category:** UI/Client/Portability
>
> **Goal:** Create a NetBird Mobile Client App.
>
> **Skills:** Golang, Java/Kotlin, XCode, Flutter+Dart
>
> **Project Size:** 350 hours
>
> **Rating:** hard
>
> **Possible mentor:** [Mikhail Bragin](https://github.com/braginini)
>
>
> **Reference:** https://github.com/golang/mobile
>
> **Reference:** https://medium.com/stack-me-up/meet-the-coolest-tech-marriage-flutter-go-369cf11367c9

36
src/pages/about-netbird/why-wireguard-with-netbird.mdx Normal file
View File

@@ -0,0 +1,36 @@
# Why Wireguard with NetBird?
WireGuard is a modern and extremely fast VPN tunnel utilizing state-of-the-art [cryptography](https://www.wireguard.com/protocol/)
and NetBird uses Wireguard to establish a secure tunnel between machines.
Built with simplicity in mind, Wireguard ensures that traffic between two machines is encrypted and flowing, however, it requires a few things to be done beforehand.
First, in order to connect, the machines have to be configured.
On each machine, you need to generate private and public keys and prepare a WireGuard configuration file.
The configuration also includes a private IP address that should be unique per machine.
Secondly, to accept the incoming traffic, the machines have to trust each other.
The generated public keys have to be pre-shared on the machines.
This works similarly to SSH with its authorised_keys file.
Lastly, the connectivity between the machines has to be ensured.
To make machines reach one another, you are required to set a WireGuard endpoint property which indicates the IP address and port of the remote machine to connect to.
On many occasions, machines are hidden behind firewalls and NAT devices,
meaning that you may need to configure a port forwarding or open holes in your firewall to ensure the machines are reachable.
The undertakings mentioned above might not be complicated if you have just a few machines, but the complexity grows as the number of machines increases.
NetBird simplifies the setup by automatically generating private and public keys, assigning unique private IP addresses, and takes care of sharing public keys between the machines.
It is worth mentioning that the private key never leaves the machine.
So only the machine that owns the key can decrypt traffic addressed to it.
The same applies also to the relayed traffic mentioned below.
Furthermore, NetBird ensures connectivity by leveraging advanced [NAT traversal techniques](https://en.wikipedia.org/wiki/NAT_traversal)
and removing the necessity of port forwarding, opening holes in the firewall, and having a public static IP address.
In cases when a direct peer-to-peer connection isn't possible, all traffic is relayed securely between peers.
NetBird also monitors the connection health and restarts broken connections.
There are a few more things that we are working on to make secure private networks simple. A few examples are ACLs, MFA and activity monitoring.
Check out the WireGuard [Quick Start](https://www.wireguard.com/quickstart/) guide to learn more about configuring "plain" WireGuard without NetBird.