Netbird

Netbird is an open-source, peer-to-peer VPN powered by Wireguard. The network's access controls and coordination are handled by a management server, which can either be the Netbird company's instance or a self-hosted instance.

Setup

Basic Client Setup

To set up a Netbird client (peer), you will need to first create a setup key as described in the Netbird setup key documentation.

Then, add the following to your NixOS module and rebuild your system:

{
  services.netbird.clients.wt0 = {

    # Automatically login to your Netbird network with a setup key
    # This is mostly useful for server computers.
    # For manual setup instructions, see the wiki page section below.
    login = {
      enable = true;

      # Path to a file containing the setup key for your peer
      # NOTE: if your setup key is reusable, make sure it is not copied to the Nix store.
      setupKeyFile = "/path/to/your/setup-key";
    };

    # Port used to listen to wireguard connections
    port = 51821;

    # Set this to true if you want the GUI client
    ui.enable = false;

    # This opens ports required for direct connection without a relay
    openFirewall = true;

    # This opens necessary firewall ports in the Netbird client's network interface
    openInternalFirewall = true;
  };
}

The above configuration will create a command called netbird-wt0 available on PATH.

If you did not enable the login configuration above, you will need to manually login using the command: netbird-wt0 login

Once logged in, you can confirm the peer's connection using the command: netbird-wt0 status

Routing Peer Setup

To set up a routing peer, follow the #Basic Client Setup, then add the following line to your NixOS module:

services.netbird.useRoutingFeatures = "both";

This enables IP forwarding, which is required for routing peers.

Management Server Setup

☶︎

This article or section needs to be expanded. Further information may be found in the related discussion page. Please consult the pedia article metapage for guidelines on contributing.

Configuration

DNS Resolution

To get Netbird's client-side DNS resolution to work, you must use systemd-resolved for your system's DNS by adding:

services.resolved.enable = true;

Troubleshooting

For issues setting up a client, consult the official Netbird "Troubleshooting client issues" documentation.

NetBird UI not working?

When your system is connected to your NetBird network, but the UI does not reflect this (and does not seem to do anything when you click 'Connect', then your user is probably not part of the netbird-wt0 group. To fix this, add this group to your user section in your NixOS config, i.e.

extraGroups = [ "networkmanager" "wheel" "netbird-wt0" ];

Then save the file and rebuild - sudo nixos-rebuild switch. After a reboot, the UI should work.