netbirdio / netbird

Connect your devices into a single secure private WireGuard®-based mesh network with SSO/MFA and simple access controls.

🐣 New Release! Device Posture Checks. Learn more

Start using NetBird at netbird.io
See Documentation
Join our Slack channel

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.

Open-Source Network Security in a Single Platform

Key features

Connectivity	Management	Security	Automation	Platforms
Kernel WireGuard	Admin Web UI	SSO & MFA support	Public API	Linux
Peer-to-peer connections	Auto peer discovery and configuration	Access control - groups & rules	Setup keys for bulk network provisioning	Mac
Connection relay fallback	IdP integrations	Activity logging	Self-hosting quickstart script	Windows
Routes to external networks	Private DNS	Device posture checks	IdP groups sync with JWT	Android
NAT traversal with BPF	Multiuser support	Peer-to-peer encryption		iOS
		Quantum-resistance with Rosenpass		OpenWRT
		Periodic re-authentication		Serverless
				Docker

Quickstart with NetBird Cloud

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

Quickstart with self-hosted NetBird

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 the Advanced guide with a custom identity provider for installations with different IDPs.

Infrastructure requirements:

• A Linux VM with at least 1CPU and 2GB of memory.
• The VM should be publicly accessible on TCP ports 80 and 443 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 distributions Usually available in the official repositories and can be installed with sudo apt install jq or sudo yum install jq
• curl installed. Usually available in the official repositories and can be installed with sudo apt install curl or sudo 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 via docker-compose

A bit on NetBird internals

• Every machine in the network runs NetBird Agent (or Client) that manages WireGuard.
• Every agent connects to Management Service that holds network state, manages peer IPs, and distributes network updates to agents (peers).
• NetBird agent uses WebRTC ICE implemented in pion/ice library to discover connection candidates when establishing a peer-to-peer connection between machines.
• Connection candidates are discovered with the help of STUN servers.
• Agents negotiate a connection through Signal 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 called TURN, 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 complete architecture overview for details.

Community projects

• NetBird installer script
• NetBird ansible collection by Dominion Solutions

Note: The main branch may be in an unstable or even broken state during development. For stable versions, see releases.

Support acknowledgement

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

Testimonials

We use open-source technologies like WireGuard®, Pion ICE (WebRTC), Coturn, and Rosenpass. 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).

Legal

WireGuard and the WireGuard logo are registered trademarks of Jason A. Donenfeld.

netbird's Issues

Dead code?

Hi, I while studying your implementation I was wondering where wiretrustee/iface/nat_linux.go is used within the project?

Where do you need to configure NATing fir wiretrustee?
Maybe that file should be removed if its not used.

Extend Management service to support user registartion

What
Add a REST endpoint to the Management server that registers a user.
There should be just one user (admin) and once it was registered there should be no registration required.
Similar to https://github.com/subspacecloud/subspace

Why
This is an essential step before enabling a peer management system.

How

• Create a REST API layer in management/ (see request/response below)

• Provision database table user and store required data (id, email, password hash).

• Additionally add a flag (most likely in db) indicating that the initial registration has been done.

• Create a follow-up story to extend registration with SSO

• endpoint to register a user

  • request: email, password
  • response: ok

Add AUth0 registration to the Management service

Client logs to a separate file

Right now logs are written to the syslog.
Should be a separate file in /var/log/wiretrustee

[Video] How to make Photoprism hosted at home available from anywhere

Try using connection candidates with wg before starting a proxy

Currently, all Wireguard data is passed through the Wireguard proxy even though the connection candidates could be directly passed as peers to Wireguard. I think we only really need the proxy if a TCP TURN relay is used.

[Video] How to make Nextcloud hosted at home available from anywhere

REST endpoint to store user registration data

https://github.com/wiretrustee/wiretrustee/projects/1#card-62350370

Peer registration endpoint (simplified version)

Endpoint to register a new peer.

The request should contain:

• Protocol version
• Peer Wireguard Public Key
• Setup key (pre-authorized key, the one generated on the server)
• local file storage

Please, consider the extension of the protocol (new fields, encryption, etc)

TURN auth

Update signal gRpc service libs

see management doc
management/README.md

Add health check to the Signal gRpc service

https://github.com/grpc/grpc-go/tree/master/examples/features/health

Extend Management to support peer changes distribution

When a new peer is added other peers have to be notified of a newcomer

Extend Management Service to distribute Peer configurations (Wireguard configurations)

Depends on #18
Each peer has to receive an initial config to setup Wireguard and enable connections to other peers:

PeerManagement.Sync message should include:

• Wiretrustee peer configuration (stun, turn, signal, etc)
• Wireguard configuration (Wg IP, etc)
• Peer configuration (public key, Wg allowed IPs, etc)
  Think of what is missing

Release 0.1.0 beta

• Documentation
• Explanatory videos
• TURN auth
• TURN auto cert
• UI Dashboard
  • Auth0 sign-up/login
  • Peers view (list, delete, disable)
  • Setup Keys view (list, delete disable)
  • Add Peer view (getting started)
• UI Dashboard Build
• Management HTTP API
• Management gRPC API
• Client sync with Management gRPC
• extract Auth0 creds

Merge Wiretrustee init command with wiretrustee up

On ./wiretrustee up check the state if the peer was not already initialized and logged in (config.json) and do:

• Generate private and public key
• Call the Peer Management Service with the public key (can be combined with 2.1.3)
• Peer Management Service will add the peer and reply with an IP and all allowed peers (public keys). Everything by default.
• When a new peer has been added all other peers have to be notified of a new peer (public key). Refreshing their state.
• remove ./wiretrustee init
• remove ./wiretrustee add-peer

Wireguard interface not up

Hello everyone

I have a 5.10 kernel:

uname -a

Linux debian-1cpu-1gb-sg-sin1 5.10.0-0.bpo.7-amd64 #1 SMP Debian 5.10.40-1~bpo10+1 (2021-06-04) x86_64 GNU/Linux

The wireguard kernel module has been loaded:

modprobe wireguard
lsmod | grep wireguard

wireguard              94208  0
libchacha20poly1305    16384  1 wireguard
ip6_udp_tunnel         16384  1 wireguard
udp_tunnel             20480  1 wireguard
libblake2s             16384  1 wireguard
curve25519_x86_64      49152  1 wireguard
libcurve25519_generic    49152  2 curve25519_x86_64,wireguard

After starting wiretrustee, there is no wiretrustee0 interface:

systemctl status wiretrustee.service

● wiretrustee.service - Wiretrustee Service
   Loaded: loaded (/lib/systemd/system/wiretrustee.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2021-07-05 14:41:31 UTC; 6min ago
 Main PID: 799 (wiretrustee)
    Tasks: 3 (limit: 1135)
   Memory: 6.7M
   CGroup: /system.slice/wiretrustee.service
           └─799 /usr/local/bin/wiretrustee up --config /etc/wiretrustee/config.json --log-level debug

ip a

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host 
       valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 46:d1:1a:9d:07:2e brd ff:ff:ff:ff:ff:ff
    inet xxx.xxx.xxx.xxx/22 brd xxx.xxx.xxx.xxx scope global dynamic eth0
       valid_lft 85710sec preferred_lft 85710sec
    inet6 fe80::44d1:1aff:fe9d:72e/64 scope link 
       valid_lft forever preferred_lft forever

What did i do wrong? Any suggestions, thanks

Signal client should support server with TLS

See example for the management service
#71 (comment)

Management client should support server with TLS

See
#71 (comment)

Extend Management Service RegisterPeer endpoint to support message encryption

Change service definition in
management/proto/management.proto

Use EncryptedMessage logic instead
see (Sync endpoint)

Connection fails to restart on network switch

What?

1. connect 2 peers
2. switch network on one of the peers (e.g. connect to a different wifi net or just turn wifi off/on)
3. peer will attempt to reconnect but will fail in some cases
4. connection won't be established anymore

Why?
When a peer goes offline (e.g. wi-fi network switch) a connection to signal drops. While it will be reestablished later, a process of Connection.Restart() has been already triggered and an attempt to signal fails. Restart doesn't continue.

Extract common server logic to a separate package

create a common package:
move:

• encryption (move from signal to common)
• lets-encrypt logic (move from cmd root to common)

Support peer registration on management service (client)

Important see if can be combined with
#16

What?
Register peer on the Management service
Why?
Every new peer has to be registered on the management system.
This is required to support dynamic peer distribution.
All newly registered peers public keys will be distributed to the other parties.

How?

• implement gRpc client of management/
  see management tests for example (use TLS, e.g. https://gist.github.com/nleiva/90f5bd042763f9b6bca9acbaae993288#file-grpc-lets-encrypt-go-L4)
• add setupKey support on up
• Management system Register endpoint can be called on every start
• think of storing setup key in the local config (not in plain text?)

IPv6 support

Hello,

In the README I only see IPv4 subnets, is wiretrustee working with IPv6 subnets? If not, is it possible to add a support for IPv6?

Update build and documentation for management service

Update build and documentation for management service to account for the separated binary.

• update build
• use separated docker hub image repository
• update documentation
• update infrastructure_files
• Link docker hub documentation

Set up basic peer-management gRpc server

a separate management gRpc server with a basic protocol definition and a health check endpoint

• healthcheck endpoint
• healthcheck test
• protobuf servcie descption
• command in cmd/ to start the server (similar to signal)
• docker image

When peer is deleted from the Dashboard the grpc stream isn't dropped

Create a docker image of the signal service

Panic when unable to add-peer due to permissions

As an un elevated user:

~/wiretrustee ❯ wiretrustee add-peer --allowedIPs 10.30.30.2/32 --key MY3paM+bln5PEoNahHMjzTUg3embjlsVOEIhPqyFC1o=
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x18 pc=0x15d5def]

goroutine 1 [running]:
github.com/wiretrustee/wiretrustee/cmd.glob..func1(0x1ba3fe0, 0xc0000bff40, 0x0, 0x4)
	/home/runner/work/wiretrustee/wiretrustee/cmd/addpeer.go:26 +0xcf
github.com/spf13/cobra.(*Command).execute(0x1ba3fe0, 0xc0000bfec0, 0x4, 0x4, 0x1ba3fe0, 0xc0000bfec0)
	/home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:856 +0x2c2
github.com/spf13/cobra.(*Command).ExecuteC(0x1ba49e0, 0x0, 0x162fc20, 0xc00008c058)
	/home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:960 +0x375
github.com/spf13/cobra.(*Command).Execute(...)
	/home/runner/go/pkg/mod/github.com/spf13/[email protected]/command.go:897
github.com/wiretrustee/wiretrustee/cmd.Execute(...)
	/home/runner/work/wiretrustee/wiretrustee/cmd/root.go:31
main.main()
	/home/runner/work/wiretrustee/wiretrustee/main.go:9 +0x2e

When performing the same action with sudo:

~/wiretrustee 15s ❯ sudo wiretrustee add-peer --allowedIPs 10.30.30.2/32 --key MY3paM+bln5PEoNahHMjzTUg3embjlsVOEIhPqyFC1o=
~/wiretrustee ❯

Simplify signal gRpc client

Instead of using sync groups to wait until stream is connected or retry mechanisms try using
with grpc.WaitForReady(true)

See examples:
https://github.com/grpc/grpc-go/blob/master/examples/features/wait_for_ready/main.go

https://github.com/grpc/grpc-go/blob/master/examples/features/retry/client/main.go

peer Registration Race when client connects to the signal server

What?
Due to the async nature of gRPC bi-directional streams, the client gets successfully connected to the stream before the Signal server registers it in the registry. Therefore signal/client.WaitConnected() returns before the peer was registered.
This is visible in the test environments when signal and peers are "close", not likely to happen in the production scenario.

Why?
A peer has to start communication with other peers only when it has been registered therefore signal/client.WaitConnected() should unblock when the peer has been actually registered on signal

How?
We could introduce additional methods to register peer on signal or use meta headers of gRPC on ConnectStream

Enable TLS on Signal

see #52 (similar implementation)

Enable TLS on peer-management service

TLS with Let's encrypt.
Should be automated.

Web UI for login and registration

• host under app.wiretrustee.com
• registration screen
• login screen
• Auth0 logic
• • redirect
• • token verification
• • basic user database to keep registered user id (Auth0)

Extend client to support peer changes distribution

When a new peer is added other peers have to be notified of a newcomer

TURN autocert

Self contained signal

In order to ensure that different pieces of the code is self contained, we need to move signal client and server to their own folders

• separate client and server
• move cmd to signal
• update builds

Docker images not found wiretrustee/signal and wiretrustee/management

I can't pulll docker images, looking at the hub, repository is empty, no pulls and no tags.

Add windows support

Add client support for Windows.

Peer management service

What
Backend Support for #19

Why
Since the introduction of the management system, a peer needs a way to authenticate itself and fetch necessary info (e.g. a list of peers to connect to)

How

• Provision peer database table to contain peer (device) info

Implement the following API endpoints (gRPC) in /signal

• endpoint to validate peer existence
• • request: peer auth token (setup-key), peer pub key
• • response: 200 if exists, 404 otherwise
• endpoint to register a peer (device)
• • request: peer auth token (setup-key), peer pub key, peer hostname, peer mac
• • response: ip
• endpoint to fetch a list of peers (public keys) to connect to
• • request: peer auth token (setup-key), peer pub key
• • response: listy of peers to connect to with the corresponsing ips

Stop client when it receives permission denied from the management service

When a peer is removed from Management (e.g. via Dashboard) the client app keeps trying to connect and gets permission denied response.

At this point, we should stop the client.

Web UI Dashboard

Dockerize peer-management service

Support live peer list update

Support live update of peers without requiring a restart.

Relates to #19

Chat

I didn't find any mention of a chat, so I added one on matrix: https://matrix.to/#/#wiretrustee:matrix.org

Extend Wiretrustee client with a new command login

./wiretrustee login
will request the user to login into his Google account

• User will have to authenticate and get OAuth credential
• • Open a browser from the terminal and make user login (Check for options) and get the token

Add health check to the Management gRpc service

https://github.com/grpc/grpc-go/tree/master/examples/features/health

Also, Remove the custom isHealthy endpoint from the service definition

Error while connecting peer

Trying to connect peer using cmd
sudo wiretrustee add-peer --allowedIPs 10.30.30.2/32 --key '<PEER2 PUBLIC KEY>'

ERROR :
received a new message from Peer [fingerprint: peer1 publickey]"
error while handling message of Peer [key: ] error: [wrongly addressed message ]

[Video] How to connect to your Raspberry PI from anywhere

Encrypt signal Message body (sProto.Message)

What?
Encrypt the body of a message being sent to a remote peer through signal

Why?
Peers exchange credentials and external addresses (e.g. open UDP ports) via signal.
Even if introducing TLS between a peer and a signal server the owner of a signal server might be able to see the body of the message. To hide sensitive info the message body has to be encrypted so that only the remote peer could decrypt it.

How?

1. change signal protocol (message body string -> byte[])
2. Use signal.EncryptMessage function to create encrypted message body

Optional: Consider using Wireguard public key fingerprint to identify peer on a signal server instead of plain Wireguard public key