nixos/netbird: add client options for DNS, routing, SSH, rosenpass an…

[shuuri-labs]

…d connection

Motivation

The NetBird client module currently requires users to manually set NB_* environment variables via the environment option to configure features like DNS, routing, SSH, Rosenpass, and self-hosted server URLs. However, environment uses NixOS module merging, which rejects conflicts with module-computed keys (like NB_STATE_DIR), making it awkward to use as an escape hatch.

Rather than adding individual typed options for every upstream setting (which RFC 0042 recommends against) this adds a proper extraEnvironment escape hatch and documents how to use it alongside the existing config option.

Changes

• extraEnvironment option: New attrsOf str option that merges with computed environment variables using //, so user values cleanly override module defaults. This is the RFC 0042 "structural escape hatch" pattern.
• Documentation rewrite (netbird.md): Replaces the minimal docs with categorized examples showing how to configure DNS, routing, firewall, Rosenpass, SSH, connection behavior, hostname/debug, and self-hosted deployments using extraEnvironment and config. Links to the upstream env var reference.
• Redirects (redirects.json): Adds entries for the new documentation sections.
• Tests (nixos/tests/netbird.nix): Adds test clients exercising both escape hatches - envtest verifies NB_* vars from extraEnvironment appear in the systemd service environment, configtest verifies config values appear in config.d/50-nixos.json.
• Hardened option description: Updates the rosenpass cross-reference to point at extraEnvironment instead of a non-existent typed option.

How to test

nix build .#checks.x86_64-linux.nixosTests.netbird -L

Things done

• Built on platform:
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• Tested, as applicable:
  • NixOS tests in nixos/tests.
  • Package tests at passthru.tests.
  • Tests in lib/tests or pkgs/test for functions and "core" functionality.
• Ran nixpkgs-review on this PR. See nixpkgs-review usage.
• Tested basic functionality of all binary files, usually in ./result/bin/.
• Nixpkgs Release Notes
  • Package update: when the change is major or breaking.
• NixOS Release Notes
  • Module addition: when adding a new NixOS module.
  • Module update: when the change is significant.
• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

[eyJhb]

Most of what this PR does seems to go against https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md . Having these options just adds more maintenance burden onto the module, while also somewhat limiting it.

I think the reasonable thing to do, would instead be to explain better how services.netbird.clients.<name>.environment works, ie. link to the Netbird documentation specifying you can do NB_<flag-name>.

In theory the module (the one currently merged into nixpkgs), could also make use of deprecating some of the options, as they don't make any sense to include in the module.

[shuuri-labs]

@eyJhb thanks for taking a look at this + directing me to RFC 0042. The convention makes sense to me and definitely seems more "nix-y" than what I had done before.

In this latest version I've removed all the typed options and instead added:

• An extraEnvironment option - an attrsOf str that merges with the module's computed env vars using //, so user values cleanly override defaults. This should adhere to the RFC 0042 "structural escape hatch" pattern. (The existing environment option uses module merging which rejects conflicts with computed keys like NB_STATE_DIR, so extraEnvironment is needed as a separate option.)

• A rewritten netbird.md that explains both escape hatches (extraEnvironment for NB_* env vars, config for config.json keys), shows categorized examples for each feature area (DNS, routing, rosenpass, SSH, etc.), and links to the upstream env var reference.

• Updated tests

Also realized I forgot to set myself as the maintainer for this module (whoops), so I've done that too.

[woile]

Why has been this setting removed from the docs?

[woile]

Again, why do we need extraEnvironment? All the examples now are with extraEnvironment instead of environment. I still don't get why is extraEnvironment introduced 🤔 Could you expand and show examples comparing against environment?

[RafaelKr]

For reference shuuri-labs @ #487367 (comment):

I'm no longer with netbird, and since I've switched to Tailscale in my own homelab, so I'll be ceasing work on this PR.