Systemd/networkd

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.

• systemd.network.links reconfigures existing network devices
  • https://www.freedesktop.org/software/systemd/man/systemd.link.html
  • actually implemented by udev, not networkd
• systemd.network.netdevs creates virtual network devices
  • https://www.freedesktop.org/software/systemd/man/systemd.netdev.html
• systemd.network.networks configures network devices
  • https://www.freedesktop.org/software/systemd/man/systemd.network.html

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

Basics

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.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.

Configuring

The configuration of networkd happens through one or multiple configuration files per interface stored in /etc/systemd/network.

The following declaration in your NixOS configuration

  systemd.network.networks."10-lan" = {
    matchConfig.Name = "lan";
    networkConfig.DHCP = "ipv4";
  };

renders the following network configuration:

/etc/systemd/network/10-lan.network

[Match]
Name=lan

[Network]
DHCP=ipv4

Note that we usually prefix the configuration file with a number. This can be important, because networkd collects all available configuration files, then sorts them alphabetically, and uses the first match for each interface as its configuration. This happens separately for .link, .netdev and .network files, so that you can have one configuration of each type per interface.

Limitations

Some limitations might be surprising, so it is probably helpful to get them out of the way early.

• systemd.network.links only gets applied at boot time
• systemd.network.netdevs does not modify existing network interfaces
  • https://github.com/systemd/systemd/issues/9627

Interfaces are set up in a one-shot fashion with networkd. That means it sets them up once and doesn't expect them to change significantly during their lifetime.

This means that networkd is not well suited to manage scenarios where multiple profiles can be configured onto an interface, or an interface is only selectively up. This is mostly the case for WLAN on mobile devices, and occassional usage of VPN tunnels. Use Networkmanager to cover these use cases, it can run in paralle with networkd, as long as they aren't set up to manage the same interfaces.

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 on link up
  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.

Recommended documentation:

• Network Configuration Synchronization Points
• RequiredForOnline=
• List of operational interface states

Examples

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

DHCP/RA

Common scenario for dynamic configuration, DHCP for IPv4 and router advertisements for IPv6 connectivity. Make network-online.target wait until addresses and routes are configured.

  systemd.network.networks."10-wan" = {
    matchConfig.Name = "enp1s0";
    networkConfig = {
      DHCP = "ipv4";
      IPv6AcceptRA = true;
    };
    # making routing on this interface a dependency for network-online.target
    linkConfig.RequiredForOnline = "routable";
  };

Static

Apply a static address and routing configuration onto enp1s0.

When the gateway is not on the same prefix as the address configured, as is customary on some cloud providers, you usually also need to set GatewayOnLink, to indicate the gateway is directly reachable on the interface.

  systemd.network.networks."10-wan" = {
    # match the interface by name
    matchConfig.Name = "enp1s0";
    address = [
        # configure addresses including subnet mask
        "192.0.2.100/24"
        "2001:DB8::2/64"
    ];
    routes = [
      # create default routes for both IPv6 and IPv4
      { routeConfig.Gateway = "fe80::1"; }
      { routeConfig.Gateway = "192.0.2.1"; }
      # or when the gateway is not on the same network
      { routeConfig = {
        Gateway = "172.31.1.1";
        GatewayOnLink = true;
      }; }
    ];
    # make the routes on this interface a dependency for network-online.target
    linkConfig.RequiredForOnline = "routable";
  };

VLAN

VLANs can be configured on top of hardlinks as well as virtual links, like bonding interfaces. They provide separate logical networks over physical links.

In this example we tag two VLANs with Ids 10 and 20 on a physical link enp1s0. The VLAN interfaces become available vlan10 and vlan20 and can receive additional configuration.

  systemd.network = {
    netdevs = {
      "20-vlan10" = {
        netdevConfig = {
          Kind = "vlan";
          Name = "vlan10";
        };
        vlanConfig.Id = 10;
      };
      "20-vlan20" = {
        netdevConfig = {
          Kind = "vlan";
          Name = "vlan20";
        };
        vlanConfig.Id = 20;
      };
    };

    networks = {
      "30-enp1s0" = {
        matchConfig.Name = "enp1s0";
        # tag vlan on this link
        vlan = [
          vlan10
          vlan20
        ];
      };
      "40-vlan10" = {
        matchConfig.Name = "vlan10";
        # add relevant configuration here
      };
      "40-vlan20" = {
        matchConfig.Name = "vlan20";
        # add relevant configuration here
      };
    };

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";
      };
    };
  };

User configurations

This section allows references to actual user configurations. They show how individual configuration snippets get integrated as a whole and serve as real world examples.

When adding new links, please describe the primary features of your setup and against which NixOS version it was last updated.

• NixOS 22.11 VDSL Router (VLANs on top of Bonding, IPv6 Prefix-Delegation, pppd Integration) by mweinelt