3-4: Netbird

Once you’re connected to your cloud VM, we’re ready to set up Netbird.

DNS

Warning

This part will cost some money. Even if you’re using free tier cloud servers, acquiring a domain name requires a purchase.

But actually, the first thing we’re going to do is not in the terminal at all. We’ll need a domain name to use with our management server. You can purchase a domain from several locations. I use Namecheap, but there are others. Pick a domain that you like, and you’re willing to keep for a long time if this network is intended for continued use.

You can also use a subdomain of a domain you already own.

Either way, you’ll want to create an A record for the domain that points to your cloud VM’s public IP address. For the root domain, the “host” value is @.

Give it like an hour for DNS records to propagate, then head back to your SSH session on the cloud VM.

Installation/Setup

Let’s do a general overview of the architecture.

architecture-beta
    service internet(internet)[Internet]
    group netbird[Netbird Server]
    group docker(server)[Docker] in netbird

    service caddy(cloud)[Caddy] in netbird
    service netbirdserver(server)[Netbird Wireguard] in docker
    service netbirddashboard(server)[Netbird Dashboard] in docker

    internet:R -- L:caddy
    caddy:B -- L:netbirddashboard
    internet:B -- L:netbirdserver
    netbirdserver:R -- L:netbirddashboard

The Netbird application is a containerized deployment, so we’ll be installing Docker. The application comprises two services: the Wireguard server and the Dashboard UI. The server is exposed on the UDP port we opened up, and the Dashboard will be served over HTTPS via Caddy.

Caddy will handle the acquisition and renewal of our TLS certificate for the domain, and provide the dashboard via reverse proxy.

Caddy

Ubuntu’s repository version of Caddy is woefully out-of-date. Instead, we’ll grab the latest version from Github. Head to the latest release, and find the amd64.deb. You’ll probably have to “show all assets” to find it—Caddy builds for a lot of platforms.

Here’s an example with version 2.11.3, the latest as of this writing.

wget https://github.com/caddyserver/caddy/releases/download/v2.11.3/caddy_2.11.3_linux_amd64.deb.pem
sudo dpkg -i caddy_2.11.3_linux_amd64.deb.pem
rm caddy_2.11.3_linux_amd64.deb.pem

Caddy will install itself as a service, so we’re pretty much good to go.

Docker

Follow Docker’s install instructions for Ubuntu, or whatever distribution you’ve chosen.

Install Script

Once Docker is installed, we can use the Netbird one-liner install script to begin configuring Netbird itself. Except, it’s kind of funky with Caddy.

mkdir netbird
cd netbird
curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

We make a netbird folder because the script generates several files, and I just think it’s messy to have them in your home folder root.

You’ll be prompted for a domain name for Netbird. Enter whatever you configured in your DNS console.

Choose 4 (Caddy) when asked about reverse proxies.

Choose Y for binding container ports to localhost only.

Leave the Docker network for Caddy empty, as it’s running on the host.

At this point, the script will hang because it instructs you to configure Caddy—which you can’t do while it’s hanging. Does it expect a terminal multiplexer? Maybe! But we won’t bother. Press Ctrl+C to exit the installer.

If you ls, you’ll see several files were created:

caddyfile-netbird.txt: Config snippet to add to /etc/caddy/Caddyfile
config.yaml: The Netbird config file. This gets mounted into the server container
dashboard.env: The dashboard config. This gets mounted into the dashboard container
docker-compose.yml: The Compose file that defines the services.

The caddyfile-netbird.txt can be copied over to /etc/caddy/Caddyfile in its entirety, unless you’re using Caddy for something else—in which case, simply add the snippet to the existing file. But if this server is dedicated to Netbird:

sudo cp caddyfile-netbird.txt /etc/caddy/Caddyfile
sudo chown caddy: /etc/caddy/Caddyfile
sudo systemctl daemon-reload
sudo systemctl restart caddy

That’s Caddy sorted! It just went and grabbed a certificate for your chosen domain.

Let’s bring Netbird up with Docker compose.

sudo docker compose pull
sudo docker compose up -d

Now, AS FAST AS POSSIBLE, visit your domain. You’ll be taken to a setup page to create your admin user/password. Once that’s sorted, you have yourself a brand new Netbird instance to play with. Congratulations!

Feel free to skip the “Get started” questionnaire. We’ll build it all out together.

Peers

Our network is made of Peers, so we’ll want to add some. There’s a bit of a catch, though: Netbird authentication sessions expire by default. That is, unless you sign in with a Setup Key—basically preauthorization for the Peer. When we set up Netbird with one of these keys, sessions last indefinitely. That might not be what you want, but in general I don’t want to have to reauthenticate my trusted devices to my network.

So let’s go make some setup keys before adding Peers.

Setup Keys

Click on “Setup Keys” in the sidebar or navigate to /setup-keys in the Netbird Dashboard.

You’ll usually want to create a setup key for a given user or set of devices. Make the key reusable to enroll multiple devices. Keys can expire or not, depending on the “Expires In” setting. You can also set a maximum number of uses.

When providing setup keys to other users, consider using one-off or limited-use keys so they can’t be abused. Expirations would also be a good idea.

You can also add users of a given setup key to a group upon enrollment. Groups allow you to scope permissions and configurations. You can create new groups right from the add dialog.

When you create a key, it will be shown one time, so copy it down (maybe into a password manager?). You can also click “Setup Netbird” right from the creation popup and receive installation/setup instructions for how to use netbird up with the setup key.

Networks

Netbird has kind of two ways to think about network resources. The older “Network Routes,” which closely mirrors the “subnet router” model we’ve already explored, and the new “Networks” model. We’ll try to use the new one.

A “Network” in Netbird is just a container for many “Resources,” or network destinations. A “Resource” might be an IP address, a domain name, or even a full subnet.

Here I’m adding a “Home Subnet” resource.

A resource is paired with one or more access policies, allowing individual Peers or Groups access. You can refine policies by port/protocol if you wish.

Once you add your first Resource, you’ll be asked to add a Routing Peer to the Network.

Routing Peers are similar to “subnet routers” in Tailscale and our own Lighthouse buildout. They are any Peer that can offer access to resource in the defined Network. You’ll want to add Peers with unique visibility to resources nothing else can see. For example, if you have a jumpbox in your homelab, add all your homelab subnets as Resources and the jumpbox as a Routing Peer.

DNS

Netbird provides two ways to manage DNS. You can add DNS servers to be used by Peers in a network.

Nameservers

With Nameservers, you can configure well-known DNS resolvers like Google, Cloudflare, or Quad9. Alternatively, you can add custom servers. They don’t have to be in private networks, but they can be. This might be useful if you have a homelab DNS server you want Peers to use when connected. You could also use this to prevent the DNS leakage we’ve discussed previously.

Zones

If you don’t want to configure a separate server, but you do want to provide in-network DNS resolution of certain domains/domain names, you can configure Zones in Netbird. These are provided to Peers in a given group, and allow a sort of ad-hoc DNS resolution. Here I’m creating a home.lab Zone and adding a jumpbox record to it.

How are Networks, Resources, and Routing Peers related?
Why might you want to define multiple access policies?
Why would you want to consider configuring a custom DNS server in your network?

Wireguard From Scratch