Systemd networkd documentation experience feedback notes


I am learning how to configure NixOS for a firewalling router appliance.
I’m running into gaps in my own knowledge and rough patches in documentation.
I thought it might be helpful to share my thoughts and feelings on the matter to potentially inform targeted documentation improvements. If y’all would prefer I provide feedback in another way, do DM me and we’ll figure it out :).

system assumptions

  • NixOS Tapir (23.11)

rambling notes on my experience

I do not expect an answer for the questions below. Simply feel it helpful to post my current experience.

  • For practical guidance I have found the wiki page more helpful than the official manual.
  • For practical guidance on configuring systemd networkd I find Arch Linux wiki’s page very helpful.
  • I read somewhere using systemd.networkd is still considered experimental. Yet the official manual provides an example of how to configure systemd networkd: NixOS 23.11 manual | Nix & NixOS. Thus, I’m feeling confused. Did I misread systemd support is experimental?
  • I am confused which NixOS option(s) I need to use, `
  • The wiki states one should not use the nixOS option networking.useNetworkd. Is that true? I’m assuming so based on setting = true; and omitting the networking.useNetworkd setting in my router’s /etc/nixos/configuration.nix.

Hi and thanks for your post!

Probably not - systemd-networkd itself is not experimental, but its module integration into NixOS is; in general, there’s little focus on networking in this community (you can help change this!) will also enable systemd.networkd.enable, but it doesn’t hurt to have both explicitly enabled; I tend to do this in these cases, so it’s clearer what’s actually enabled at any point.

The wiki states:

Some guides will mention the networking.useNetworkd option, which in addition to enabling systemd-networkd, also offers translation of some networking.interfaces and networking.useDHCP options into networkd. If you can write your complete network setup in native networkd configuration, you should stay away from that option.

If I understand correctly, the suggestion is to avoid spreading your network-related configuration across multiple modules if possible; this is likely just because interactions between the different modules can make debugging harder. Here’s what the networking.interfaces.<name>.ipv4.routes source has to say.

1 Like

uh, no it doesn’t, and the fact that the docs suggest this is a bug. Plus, that option is the enable option for<name>.enable, not But is about enabling stage 1 networking, and only if you’re using the non-default systemd-based initrd.

1 Like

Oof, thanks for catching this! I shouldn’t try replying to things before being fully awake.

It actually looks like there isn’t any options.systemd.networkd anyway (just and, though<name>.enable and<name>.enable both refer to systemd.networkd; these docs definitely need attention.

@efx: You probably just want to set = true and forget about entirely, unless you want to boot the device from another location on your network.

Thanks for the replies folks! I most appreciate the feedback. I’ll take some time later this week to digest the insights :).

Another stream of consciousness note.
I stumbled across this bug: NetworkManager's nm-online kills nixos-rebuild · Issue #180175 · NixOS/nixpkgs · GitHub.
I kept thinking I’d done something wrong in my configuration.nix, LOL. I may switch to unstable. Or perhaps backporting that fix to Tapir.