Repository files navigation

Start using NetBird atnetbird.io
SeeDocumentation
Join ourSlack channel or ourCommunity forum

New: NetBird terraform provider

NetBird combines a configuration-free peer-to-peer private network and a centralized access control system in a single platform, making it easy to create secure private networks for your organization or home.

Connect. NetBird creates a WireGuard-based overlay network that automatically connects your machines over an encrypted tunnel, leaving behind the hassle of opening ports, complex firewall rules, VPN gateways, and so forth.

Secure. NetBird enables secure remote access by applying granular access policies while allowing you to manage them intuitively from a single place. Works universally on any infrastructure.

• Download and install NetBird athttps://app.netbird.io/install
• Follow the steps to sign-up with Google, Microsoft, GitHub or your email address.
• Check NetBirdadmin UI.
• Add more machines.

This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM.Follow theAdvanced guide with a custom identity provider for installations with different IDPs.

Infrastructure requirements:

• A Linux VM with at least1CPU and2GB of memory.
• The VM should be publicly accessible on TCP ports80 and443 and UDP ports:3478,49152-65535.
• Public domain name pointing to the VM.

Software requirements:

• Docker installed on the VM with the docker-compose plugin (Docker installation guide) or docker with docker-compose in version 2 or higher.
• jq installed. In most distributionsUsually available in the official repositories and can be installed withsudo apt install jq orsudo yum install jq
• curl installed.Usually available in the official repositories and can be installed withsudo apt install curl orsudo yum install curl

Steps

• Download and run the installation script:

export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh| bash

• Once finished, you can manage the resources viadocker-compose

• Every machine in the network runsNetBird Agent (or Client) that manages WireGuard.
• Every agent connects toManagement Service that holds network state, manages peer IPs, and distributes network updates to agents (peers).
• NetBird agent uses WebRTC ICE implemented inpion/ice library to discover connection candidates when establishing a peer-to-peer connection between machines.
• Connection candidates are discovered with the help ofSTUN servers.
• Agents negotiate a connection throughSignal Service passing p2p encrypted messages with candidates.
• Sometimes the NAT traversal is unsuccessful due to strict NATs (e.g. mobile carrier-grade NAT) and a p2p connection isn't possible. When this occurs the system falls back to a relay server calledTURN, and a secure WireGuard tunnel is established via the TURN server.

Coturn is the one that has been successfully used for STUN and TURN in NetBird setups.

See a completearchitecture overview for details.

• NetBird installer script
• NetBird ansible collection by Dominion Solutions

Note: Themain branch may be in anunstable or even broken state during development.For stable versions, seereleases.

In November 2022, NetBird joined theStartUpSecure program sponsored by The Federal Ministry of Education and Research of The Federal Republic of Germany. Together withCISPA Helmholtz Center for Information Security NetBird brings the security best practices and simplicity to private networking.

We use open-source technologies likeWireGuard®,Pion ICE (WebRTC),Coturn, andRosenpass. We very much appreciate the work these guys are doing and we'd greatly appreciate if you could support them in any way (e.g., by giving a star or a contribution).

This repository is licensed under BSD-3-Clause license that applies to all parts of the repository except for the directories management/, signal/ and relay/.Those directories are licensed under the GNU Affero General Public License version 3.0 (AGPLv3). See the respective LICENSE files inside each directory.

WireGuard and theWireGuard logo areregistered trademarks of Jason A. Donenfeld.