Skip to main content

Install and Setup the Netbird Wireguard System

Netbird is a new offering in the Wireguard “flat” network space. They offer a great set of options and some fairly simple setup.  We'll be installing this on a VPS from Digital Ocean toady.  

Netbird reached out and asked if I'd be willing to cover their offering.  I am an open source advocate, and since they are making this awesome offering open source, it only makes sense that I cover it!  The best news is, they did not pay me to cover this.  I do it, because this is what i do.  They did however, offer up a discount code for all of you to try out their paid services.  Their pricing model is already extremely affordable, so getting a 20% discount on top of that is just amazing, and I truly appreciate them offering this out to my viewers!

You can get a 20% discount on a Team or Business plan by signing up for the plan, then emailing the discount code AWESOME_OSS to hello@netbird.io from the email address you use to sign up for the service.  It's that simple!

Full transparency:  I do have a Digital Ocean affiliate link in the description of this video.  If you use it you'll get anywhere from $50 to $100 for 60 days to try out the services and offerings of Digital Ocean.  If you stay with the service, I will eventually get a credit on my account as well. If you don't like the service and cancel, then I won't.  Simple as that.

What you'll need

  • A server (highly recommend a cloud hosted VPS for a VPN server) - Netbird recommends 1 CPU with 2 GB RAM minimum.  This is a $12 / month server on Digital Ocean.
  • Docker and Docker Compose installed.
  • Curl installed
  • jq installed
  • A domain name with an A record pointing to your public IP address (the server's public IP)
  • About 20 minutes of your time.

Quick Step List

  1. Update your server / VPS to make sure you have the most recent packages and patches available.
  2. Install Docker and Docker-Compose
  3. Install jq and curl.
  4. Setup your domain name and A-record. NOTE: If you are using Cloudflare, you need to enable gRPC on the domain network.
  5. Check your server hosts file (/etc/hosts) and make sure that the FQDN (your domain / sub-domain) is not being pointed to by localhost 127.0.0.1 or the loopback address 127.0.1.1 (this caused me some trouble in getting the client to connect properly).
  6. Once all of this is setup, run the quick-start script on the Netbird page. https://docs.netbird.io/selfhosted/selfhosted-quickstart
  7. When complete, you'll be up and running. You'll have Zitadel setup for authentication, and Netbird setup with a management service that can be accessed via CLI or Web GUI.  
  8. Install the Netbird client.  Find the client for your OS, and install it.  If using Linux, as with most tools like this, there is only a CLI option, but hopefully Netbird will get us a nice GUI option in the future.

Detailed Steps

First, let's setup our domain name and A-Record.  

You need to own a domain, or go register a new domain.  You'll need to have a public IPv4 address to the server where you plan to run Netbird.  There are a whole host of ports that need to be available from the server as well, so we really need to make sure that we have all the ports forwarded if you are running behind a firewall, or from your LAN.  In my case, I prefer to run a VPN from a VPS as this gives much better up-time, and isn't dependent on my home network being available. 

I created a new droplet on Digital Ocean at the $12 / month rate which is 1 CPU and 2 GB or RAM, as detailed on the Netbird quick start guide.

Next, make sure to setup a new domain / subdomain name.  In my case I went to Cloudflare to my domain “opensourceisawesome.com”.  I selected to add a new A-Record, and copied the public IPv4 address from Digital Ocean for my new VPS, and pasted it into the A-Record I created.  Now I have the domain netbird.opensourceisawesome.com pointing to my public IP address on Digital Ocean.

NOTE: In Cloudflare, you need to enable "gRPC" for the domain you are setting this up on. You can do this by clicking on the domain, the selecting 'Network' from the left side menu.  In there you'll find an option for "gRPC". Make sure this is enabled.

Now, I'll login to my VPS via SSH to continue my setup.

Fix Localhost / Loopback Issues

Quickly, look at the 'hosts' file, and make sure that you don't have your domain / subdomain name on the same line as either localhost or the loopback addresses (127.0.0.1 or 127.0.1.1). 

In my case, I saw this

127.0.0.1          localhost
127.0.1.1          netbird.opensourceisawesome.com netbird

This caused issues when trying to connect my clients.  Make sure to remove the entry if your subdomain or domain are on either of these lines. Afterward you should see something like this only:

127.0.0.1          localhost

This will allow your domain to be reached properly if your DNS A-Record is setup correctly.

Install Docker-CE and Docker Compose

Next, we'll install Docker and Docker Compose.  I have a script that will help you install this on the various Linux distributions out there.  You can run the script by doing the following:

wget -O install-docker.sh https://gitlab.com/bmcgonag/docker_installs/-/raw/main/install_docker_nproxyman.sh?ref_type=heads

This will pull down the script, and name it “install-docker.sh”. 

Next, make the script executable with

chmod +x install-docker.sh

Then run the script with

./install-docker.sh

You'll be prompted for your sudo password if you are not running as root.  After that answer ‘y’ to any items you want to install.  In this instance we just need the first two options: Docker-CE and Docker Compose.  You can answer ‘n’ to the rest of the options.

The script will install Docker-CE and Docker Compose, as well as setting the currently logged in user in the ‘docker’ group, and create a new docker network.  You won't need the docker network in this case. 

To make sure your group privileges are set on your user, you should log out and back in after the script completes.

Next, let's install jq and curl.  I'm using Ubuntu, so I'll give those commands here, but if you use a different Linux variant, make sure to use the proper package manager for your distribution.

Install jq and curl

sudo apt install jq curl -y

When that completes, we'll be ready to run the one-liner command that Netbird provides to get us up and running quickly and easily.

Run the install script for Netbird:

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

where you change out the NETBIRD_DOMAIN for your actual FQDN.

In my case I ran

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

Allow the script to complete. You'll have several docker containers running when it's done and at the bottom, you should see a message saying that the install is complete, and providing you a link to your new Netbird management site, as well as an initial username and password.

Copy the password, and username, and then open the site. You should be greeted by a Zitadel login page. Enter the username provided, then click 'Next'. 

Now enter the password provided, and click 'Next'. 

Here you'll be prompted to setup MFA (Multi-factor Authentication).  Feel free to use whatever works best for you. I chose to setup a TOTP using Bitwarden.   Verify the code, or method you choose, then continue.  You'll be prompted to change the password, and asked for the verification code / method one more time.  After that process, you'll be directed to the Netbird management page.

It's time to add a client. 

Adding a Client

NOTE: I did not have to run the Netbird client as sudo, which is a change from how Tailscale works.

Once you are at the Management console for Netbird, you can click the "Add a Peer" button.  When you do you'll be presented with a pop-up message showing you a one liner to install the Netbird client on a Linux pc.  You'll also be shown a multi-line method if you prefer to do it that way.  At the bottom of the pop-up you'll be given a one-line command to connect your client to your Netbird server after the client application is successfully installed.

If you are on Windows, MacOS, Android, etc, just make sure that the tab on the pop-up is set to the OS you are using and follow the instructions as provided. 

For Linux, we can install the client with this command:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

After the install completes, you'll see a message saying to use netbird up to connect  If you use this command, it will attempt to connect you to the Netbird.io servers, and not your self-hosted server.  To connect to your server, go back to your management page and scroll to the bottom of the 'Add Peer' pop-up window.  There you'll find a more full command to bring up your Netbird client on your self hosted server. It should look something like

netbird up --management-url https://netbird.youramazingdomain.com

Where you'll switth out the URL https://netbird.yojramazingdomain.com for your actual netbird server url. 

When you do this, if you are doing so from a desktop machine, you'll see a browser window open up, and ask you to authenticate with your Netbird credentials.  Authenticate, and you'll be told your setup is successful. You can close the browser window, and now do

netbird status

in your terminal, to see that Netbird is connected.

What about a server with no GUI?

You can also setup your Netbird VPN on a server with no GUI.  Using the command line, install the Netbird client in the same way as above. Once installed, you'll need to go to your management ui in a browser, and select the "Setup Keys" tab.  Here click the button for "Add Key".

Fill in a name for your key to identify it easily in a list. 

Next, choose how many machines you want to setup using this key.  Maybe you have 10 servers you need to add. You can do this more rapidly by using the same key for each , instead of separate keys for each.

If you are setting up devices in groups, select the group for the devices that will use this key, and finally set an expiration for using this key. 

Click "Create Key". 

Copy the Key!  The won't show you this key again, so copy it as soon as you see it and store it in a password manager or encrypted file.

Now, on your server use the command line to add your device to the Netbird network with this command line structure:

netbird up --management-url https://netbird.youramazingdomain.com --setup-key 9129F217-15CA-4DA0-2107-8ED020109879  <--- not a real key

You server is now connected, no separate authentication needed since you used the setup key.  You can use all the Netbird CLI commands to bring your client up / down, check status, and so on.

Congratulations! You are now setup with a Wireguard VPN using Netbird.  You have a great Web based management portal, and you have Multi-factor authentication using Zitadel for your user management.

A brief word on User Management

While there is a "Users" tab on your Netbird management interface, in order to add users, since it's using Zitadel for Authentication, you need to add the users through Zitadel.  The good news is this is a fully functional Zitadel Authentication and IdP server.  You can get to the console at

https://netbird.youramazingdomain.com/ui/console

Login, using your admin credentials, and from there you can complete the Zitadel setup with branding, and user grants, as well as use Zitadel for other SSO systems you want to authenticate with. 

This isn't a tutorial on Zitadel, but I felt like this was important for you to know. We'll cover Zitadel some other time. 

Support My Channel and Content

Support my Channel and ongoing efforts through Patreon:
https://www.patreon.com/awesomeopensource

Back to top