Systemd/networkd: Difference between revisions

From NixOS Wiki
imported>Mweinelt
imported>Mweinelt
network-online.target
Line 25: Line 25:
can write your complete network setup in native networkd configuration, you should
can write your complete network setup in native networkd configuration, you should
stay away from that option.
stay away from that option.
=== network-online.target ===
While <code>network.target</code> only requires the network management stack
to be up, which means it does not care about network interfaces being configured,
the <code>network-online.target</code> waits until a defined set of network
interfaces are in a state, that by its configuration is considered online.
When networkd is enabled, the <code>network-online.target</code> is implemented
through the <code>systemd-networkd-wait-online.service</code>, which makes
sure interfaces configured through networkd are in their expected operational state.
The current operational state of network interfaces can be learned from <code>networkctl</code>.
<syntaxhighlight lang="bash">
❯ networkctl
IDX LINK          TYPE    OPERATIONAL SETUP   
  1 lo            loopback carrier    unmanaged
  2 enp10s0      ether    routable    unmanaged
  3 wlp9s0        wlan    no-carrier  unmanaged
</syntaxhighlight>
For most network interfaces that will mean that they have <code>routable</code>
network connectivity, but in more complex setups some links may be content with more
simple states like <code>carrier</code> or <code>enslaved</code>. Interfaces that
are managed by networkd, but not always in use, shouldn't be required for
<code>network-online.target</code>
<syntaxhighlight lang="nix">
systemd.network."50-enp3s0" = {
  matchConfig.Name = "enp3s0";
  # acquire a DHCP lease, when connected
  networkConfig.DHCP = "yes";
  # this port is not always connected and not required to be online
  linkConfig.RequiredForOnline = "no";
};
</syntaxhighlight>
Note that the default value for <code>linkConfig.RequiredForOnline</code> is unexpectedly
<code>"yes"</code>, which often leads to a failing <code>network-online.target</code>.
Setting individual interfaces to <code>"no"</code> is a perfectly valid choice
and should be considered, before disabling the <code>systemd-networkd-wait-online.service</code>
entirely, because a working <code>network-online.target</code> is required for some
services to properly start without race conditions.
Further details in the upstream documentation:
* [https://www.freedesktop.org/software/systemd/man/systemd.network.html#RequiredForOnline= RequiredForOnline=]
* [https://www.freedesktop.org/software/systemd/man/networkctl.html#%0A%20%20%20%20%20%20%20%20%20%20list%0A%20%20%20%20%20%20%20%20%20%20PATTERN%E2%80%A6%0A%20%20%20%20%20%20%20%20 List of operational interface states]


== Examples ==
== Examples ==

Revision as of 16:59, 26 March 2023

Networkd is the network configuration component of the systemd software suite. It is well integrated into NixOS below systemd.network and should be preferred over networking.interfaces options for most use cases, since it receives far superior maintenance.

Configuration for networkd is split into three sections.

In most simple scenarios configuring existing network devices is what you want to do.

Enabling

To be able to use networkd configuration it needs to be enabled first.

systemd.network.enable = true;

Some guides will mention the networking.useNetworkd option, which offers translation of some networking.* options into networkd. If you can write your complete network setup in native networkd configuration, you should stay away from that option.

network-online.target

While network.target only requires the network management stack to be up, which means it does not care about network interfaces being configured, the network-online.target waits until a defined set of network interfaces are in a state, that by its configuration is considered online.

When networkd is enabled, the network-online.target is implemented through the systemd-networkd-wait-online.service, which makes sure interfaces configured through networkd are in their expected operational state.

The current operational state of network interfaces can be learned from networkctl.

 networkctl
IDX LINK          TYPE     OPERATIONAL SETUP     
  1 lo            loopback carrier     unmanaged
  2 enp10s0       ether    routable    unmanaged
  3 wlp9s0        wlan     no-carrier  unmanaged

For most network interfaces that will mean that they have routable network connectivity, but in more complex setups some links may be content with more simple states like carrier or enslaved. Interfaces that are managed by networkd, but not always in use, shouldn't be required for network-online.target

systemd.network."50-enp3s0" = {
  matchConfig.Name = "enp3s0";
  # acquire a DHCP lease, when connected
  networkConfig.DHCP = "yes";
  # this port is not always connected and not required to be online
  linkConfig.RequiredForOnline = "no";
};

Note that the default value for linkConfig.RequiredForOnline is unexpectedly "yes", which often leads to a failing network-online.target.

Setting individual interfaces to "no" is a perfectly valid choice and should be considered, before disabling the systemd-networkd-wait-online.service entirely, because a working network-online.target is required for some services to properly start without race conditions.

Further details in the upstream documentation:

Examples

Examples should be concise and give proper hints on how to achieve a reliably working network-online.target.

DHCP

Assuming your *wired* interface that should run DHCP is called enp1s0, this configuration will enable DHCP.

  systemd.network.networks."10-dhcp-wan" = {
    matchConfig.Name = "enp1s0";
    linkConfig.RequiredForOnline = true; # Necessary if you want to make network-online.target dependent on this interface being online.
    DHCP = "yes";
  };

Bonding

Given two hardlinks enp2s0 and enp3s0 create a virtual bond0 interface using Dynamic LACP (802.3ad), hashing outgoing packets using a packet's Layer3/4 (OSI Layer) information.

  systemd.network = {
    netdevs = {
      "10-bond0" = {
        netdevConfig = {
          Kind = "bond";
          Name = "bond0";
        };
        bondConfig = {
          Mode = "802.3ad";
          TransmitHashPolicy = "layer3+4";
        };
      };
    };
    networks = {
      "30-enp2s0" = {
        matchConfig.Name = "enp2s0";
        networkConfig.Bond = "bond0";
      };
      "30-enp3s0" = {
        matchConfig.Name = "enp3s0";
        networkConfig.Bond = "bond0";
      };
      "40-bond0" = {
        matchConfig.Name = "bond0";
        linkConfig = {
          RequiredForOnline = "carrier";
        };
        networkConfig.LinkLocalAddressing = "no";
      };
    };
  };