diff --git a/public/docs-static/img/architecture/high-level-dia.png b/public/docs-static/img/architecture/high-level-dia.png index 71066048..8b8d0748 100644 Binary files a/public/docs-static/img/architecture/high-level-dia.png and b/public/docs-static/img/architecture/high-level-dia.png differ diff --git a/public/docs-static/img/architecture/management.png b/public/docs-static/img/architecture/management.png index 3b22aedf..f4e5923e 100644 Binary files a/public/docs-static/img/architecture/management.png and b/public/docs-static/img/architecture/management.png differ diff --git a/public/docs-static/img/architecture/mesh.png b/public/docs-static/img/architecture/mesh.png index 12ac5292..27bab4c9 100644 Binary files a/public/docs-static/img/architecture/mesh.png and b/public/docs-static/img/architecture/mesh.png differ diff --git a/public/docs-static/img/architecture/relay.png b/public/docs-static/img/architecture/relay.png index c95d503e..10b90d92 100644 Binary files a/public/docs-static/img/architecture/relay.png and b/public/docs-static/img/architecture/relay.png differ diff --git a/public/docs-static/img/architecture/signal.png b/public/docs-static/img/architecture/signal.png index 4c575029..36c7ce46 100644 Binary files a/public/docs-static/img/architecture/signal.png and b/public/docs-static/img/architecture/signal.png differ diff --git a/src/pages/about-netbird/how-netbird-works.mdx b/src/pages/about-netbird/how-netbird-works.mdx index d7b7a556..1295709c 100644 --- a/src/pages/about-netbird/how-netbird-works.mdx +++ b/src/pages/about-netbird/how-netbird-works.mdx @@ -5,42 +5,46 @@ 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). +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. +and [software](https://github.com/netbirdio/netbird) developed by NetBird 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. +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. +It can be a Linux server running in the cloud or on-premises, a personal laptop, mobile phone, or even a Raspberry PI.

high-level-dia

-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. +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.

high-level-dia

-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. +While it is possible to create a full mesh network, it might be not a desirable outcome. +In this case, [groups and access controls](/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. +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. +After installation, NetBird client requires login that can be done through Identity Provider (IDP) like Okta 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 100.64.0.0/10. * **Synchronizing network changes to peers.** The Management Service keeps a control channel open to each peer sending network updates. @@ -49,7 +53,7 @@ After that, they are able to establish a connection to the new peer. * **Creating and managing access control rules.** * **Managing private DNS.** [DNS](/how-to/manage-dns-in-your-network) allows referring to each of the peers with a fully qualified domain name (FQDN). * **Logging network activity.** -* **Wireguard key rotation.** Coming Soon. +* **Managing users.** The Management service runs in the cloud NetBird-managed. It can also be self-hosted. @@ -65,14 +69,20 @@ 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](/how-to/register-machines-using-setup-keys) so that the peer can be associated with the organization's account. +* **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](/how-to/register-machines-using-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. +Each peer receives initial configuration and a list of peers with corresponding public keys and IP addresses so that it can establish a point-to-point connection. +* **Establishing point-to-point 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. +The remote peer does the same and once the peers can reach each other, they establish an encrypted WireGuard tunnel. +* **Applying access control policies.** The client application applies access control rules that are received from the Management service. +It uses system's available firewall manager like `nftables` to apply the rules. +* **Applying DNS settings.** The client application runs an [embedded DNS resolver](https://netbird.io/knowledge-hub/using-xdp-ebpf-to-share-default-dns-port-between-resolvers) and ensures that the machine can resolve other peers' FQDNs in the `netbird.cloud` namespaces. +It also applies other DNS settings that are received from the Management service. 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. @@ -84,7 +94,8 @@ The Signal Service or simply Signal is a lightweight piece of software that help 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. +* **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.

@@ -92,7 +103,7 @@ This is done through Signal. After a connection has been established, Signal ste

- Messages that are sent over Signal are **peer-to-peer encrypted**, so Signal can't see the contents. + Messages that are sent over Signal are **point-to-point 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/Web/API/WebRTC_API/Signaling_and_video_calling#the_signaling_server). @@ -102,39 +113,14 @@ It runs in the cloud NetBird-managed and can be self-hosted. 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. +The purpose of this service is to be a "plan B" and relay traffic between peers in case a point-to-point connection isn't possible.

relay-dia

- Similar to Signal, traffic that flows through the Relay can't be decrypted due to the **Wireguard peer-to-peer encryption**. + Similar to Signal, traffic that flows through the Relay can't be decrypted due to the **WireGuard point-to-point encryption**. 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 100.64.0.0/10. -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.