Quickstart Guide
Step-by-step video guide on YouTube:
This guide describes how to quickly get started with NetBird and create a secure private network with two connected machines.
One machine is a Linux laptop, and the other one a EC2 node running on AWS. Both machines are running Linux but NetBird also works on Windows, MacOS nad popular mobile platforms like Android and iOS.
- Sign-up at https://app.netbird.io/
You can use your Google, GitHub or Microsoft account.
- After a successful login you will be redirected to the
Peers
screen which is empty because you don't have any peers yet.
The Add peer
window should automatically pop up, but if it doesn't, click Add new peer
to add a new machine.
- Choose your machine operating system (in our case it is
Linux
) and proceed with the installation steps.
- If you installed NetBird Desktop UI you can use it to connect to the network instead of running
netbird up
command. Look forNetBird
in your application list, run it, and clickConnect
.
- At this point a browser window pops up starting a device registration process. Click confirm and follow the steps if required.
- On the EC2 node repeat the installation steps and run
netbird up
command.
sudo netbird up
- Copy the verification URL from the terminal output and paste it in your browser. Repeat step #5
- Return to
Peers
and you should notice 2 new machines with statusonline
- To test the connection you could try pinging devices:
On your laptop:
ping 100.64.0.2
On the EC2 node:
ping 100.64.0.1
- Done! You now have a secure peer-to-peer private network configured.
- Make sure to star us on GitHub
- Follow us on Twitter
- Join our Slack Channel
- NetBird release page on GitHub: releases
Installation
Linux
APT/Debian
- Add the repository:
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg -y
curl -sSL https://pkgs.wiretrustee.com/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/wiretrustee-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/wiretrustee-archive-keyring.gpg] https://pkgs.wiretrustee.com/debian stable main' | sudo tee /etc/apt/sources.list.d/wiretrustee.list
- Update APT's cache
sudo apt-get update
- Install the package
# for CLI only
sudo apt-get install netbird
# for GUI package
sudo apt-get install netbird-ui
RPM/Red hat
- Add the repository:
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
[Wiretrustee]
name=Wiretrustee
baseurl=https://pkgs.wiretrustee.com/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
- Install the package
# for CLI only
sudo yum install netbird
# for GUI package
sudo yum install netbird-ui
Fedora
- Create the repository file:
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
[Wiretrustee]
name=Wiretrustee
baseurl=https://pkgs.wiretrustee.com/yum/
enabled=1
gpgcheck=0
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
repo_gpgcheck=1
EOF
- Import the file
sudo dnf config-manager --add-repo /etc/yum.repos.d/wiretrustee.repo
- Install the package
# for CLI only
sudo dnf install netbird
# for GUI package
sudo dnf install netbird-ui
NixOS 22.11+/unstable
- Edit your
configuration.nix
{ config, pkgs, ... }:
{
services.netbird.enable = true; # for netbird service & CLI
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
}
- Build and apply new configuration
sudo nixos-rebuild switch
macOS
Homebrew install
- Download and install homebrew at https://brew.sh/
- If wiretrustee was previously installed with homebrew, you will need to run:
# Stop and uninstall daemon service:
sudo wiretrustee service stop
sudo wiretrustee service uninstall
# unlik the app
brew unlink wiretrustee
netbird will copy any existing configuration from the Wiretrustee's default configuration paths to the new NetBird's default location
- Install the client
# for CLI only
brew install netbirdio/tap/netbird
# for GUI package
brew install --cask netbirdio/tap/netbird-ui
- If you installed CLI only, you need to install and start the client daemon service:
sudo netbird service install
sudo netbird service start
Windows
- Checkout NetBird releases
- Download the latest Windows release installer
netbird_installer_<VERSION>_windows_amd64.exe
(Switch VERSION to the latest): - Proceed with the installation steps
- This will install the UI client in the C:\Program Files\NetBird and add the daemon service
- After installing, you can follow the steps from Running NetBird with SSO Login steps.
To uninstall the client and service, you can use Add/Remove programs
⚠️ In case of any issues with the connection on Windows check the firewall settings. With default Windows 11 firewall setup there could be connectivity issue related to egress traffic.
Recommended way is to add NetBird in firewall settings:
- Go to "Control panel".
- Select "Windows Defender Firewall".
- Select "Advanced settings".
- Select "Outbound Rules" -> "New rule".
- In the new rule select "Program" and click "Next".
- Point to the NetBird installation exe file (usually in
C:\Program Files\NetBird\netbird.exe
) and click "Next". - Select "Allow the connection" and click "Next".
- Select the network in which rule should be applied (Domain, Private, Public) according to your needs and click "Next".
- Provide rule name (e.g. "Netbird Egress Traffic") and click "Finish".
- Disconnect and connect to NetBird.
Binary Install
Installation from binary (CLI only)
- Checkout NetBird releases
- Download the latest release:
curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
You need to replace some variables from the URL above:
- Replace VERSION with the latest released verion.
- Replace OS with "linux", "darwin" for MacOS or "windows"
- Replace Arch with your target system CPU archtecture
- Decompress
tar xcf ./netbird_<VERSION>.tar.gz
sudo mv netbird /usr/bin/netbird
sudo chown root:root /usr/bin/netbird
sudo chmod +x /usr/bin/netbird
After that you may need to add /usr/bin in your PATH environment variable:
export PATH=$PATH:/usr/bin
- Install and run the service
sudo netbird service install
sudo netbird service start
Running NetBird with SSO Login
Desktop UI Application
If you installed the Desktop UI client, you can launch it and click on Connect.
It will open your browser, and you will be prompt for email and password. Follow the instructions.
CLI
Alternatively, you could use command line. Simply run
netbird up
It will open your browser, and you will be prompt for email and password. Follow the instructions.
Check connection status:
netbird status
Running NetBird with a Setup Key
In case you are activating a server peer, you can use a setup key as described in the steps below.
This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
- Login to the Management Service. You need to have a
setup key
in hand (see setup keys).
For all systems:
netbird up --setup-key <SETUP KEY>
For Docker, you can run with the following command:
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:<TAG>
TAG > 0.6.0 version
Alternatively, if you are hosting your own Management Service provide --management-url
property pointing to your Management Service:
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
You could also omit the
--setup-key
property. In this case, the tool will prompt for the key.
- Check connection status:
netbird status
- Check your IP:
On macOS :
sudo ifconfig utun100
On Linux:
ip addr show wt0
On Windows:
netsh interface ip show config name="wt0"
Running NetBird in Docker
Set the NB_SETUP_KEY
environment variable and run the command.
You can pass other settings as environment variables. See environment variables for details.
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
See Docker example for details.
Troubleshooting
-
If you are using self-hosted version and haven't specified
--management-url
, the client app will use the default URL which ishttps://api.wiretrustee.com:33073
. -
If you have specified a wrong
--management-url
(e.g., just by mistake when self-hosting) to override it you can do the following:
netbird down
netbird up --management-url https://<CORRECT HOST:PORT>/
To override it see the solution #1 above.