Jump to content

Systemd/networkd: Difference between revisions

Systemd/networkd (view source)

Revision as of 21:33, 24 April 2024

4,885 bytes added ,  24 April
m
no edit summary
VisualWikitext
imported>Mweinelt
mNo edit summary
mNo edit summary
 
(32 intermediate revisions by 11 users not shown)
Line 1: Line 1:
Networkd is the network configuration component of the systemd software suite. It is well integrated into NixOS below {{Nixos:option|systemd.network}} and should be preferred over {{Nixos:option|networking.interfaces}} options for most use cases, since it receives far superior maintenance.
{{Systemd/breadcrumb}}
{{DISPLAYTITLE:systemd-networkd}}
[https://www.freedesktop.org/software/systemd/man/systemd-networkd.html systemd-networkd] is the network configuration component of the [[systemd]][[Category:systemd]] software suite. It is well integrated into NixOS below {{Nixos:option|systemd.network}} and should be preferred over {{Nixos:option|networking.interfaces}} options for most use cases, since it receives far superior maintenance.


Configuration for networkd is split into three sections.
Configuration for networkd is split into three sections.
Line 14: Line 16:


== Basics ==
== Basics ==
=== When to use ===
=== When to use ===


Use systemd-networkd for setups that rely on static configuration, that doesn't change much
Use systemd-networkd for setups that rely on static configuration, that doesn't change much during its lifetime, that does not require varying profiles for a single interface. Common examples are:
during its lifetime, that does not require varying profiles for a single interface. Common
examples are:
* Servers/Routers
* Servers/Routers
* Always-On VPN Tunnels
* Always-On VPN Tunnels
Line 26: Line 27:
* Selectively used VPN tunnels
* Selectively used VPN tunnels


These use cases are better served by [[NetworkManager]] and its various frontends,
These use cases are better served by [[NetworkManager]] and its various frontends, that provides a better integrated user experience for various desktop systems.
that provides a better integrated user experience for various desktop systems.


{{Note|Both systemd-networkd and NetworkManager can exist in parallel on the same machine,
{{Note|Both systemd-networkd and NetworkManager can exist in parallel on the same machine,
Line 41: Line 41:


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


=== Configuring ===
=== Configuring ===
Line 69: Line 71:
</nowiki>}}
</nowiki>}}


Note that we usually prefix the configuration file with a number. This can be important,
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 alphanumerically, and uses the first match for each interface as its configuration. This happens separately for <code>.link</code>, <code>.netdev</code> and <code>.network</code> files, so that you can have one configuration of each type per interface.
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
=== Debugging ===
for <code>.link</code>, <code>.netdev</code> and <code>.network</code> files, so
 
that you can have one configuration of each type per interface.
When things don't work as expected, the journal for <code>systemd-networkd.service</code> should be consulted. Unfortunately, by default the log is not very useful in its default loglevel. Increasing the loglevel can be done using the <code>SYSTEMD_LOG_LEVEL</code> environment variable.
 
<syntaxhighlight lang="nix">
systemd.services."systemd-networkd".environment.SYSTEMD_LOG_LEVEL = "debug";
</syntaxhighlight>


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


* <code>systemd.network.links</code> only gets applied at boot time
Some limitations might be surprising, so it is probably helpful to get them out of the way early.
* <code>systemd.network.netdevs</code> does not modify existing network interfaces
 
** https://github.com/systemd/systemd/issues/9627
* {{Nixos:option|systemd.network.links}}
** Executed by udev and only applied on boot
* {{Nixos:option|systemd.network.netdevs}}
** Does not modify properties (e.g., MTU, VLAN ID, VXLAN ID, Wireguard Peers) of existing netdevs
*** https://github.com/systemd/systemd/issues/9627


=== network-online.target ===
=== network-online.target ===
Line 110: Line 118:


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
systemd.network."50-enp3s0" = {
systemd.network.networks."50-enp3s0" = {
   matchConfig.Name = "enp3s0";
   matchConfig.Name = "enp3s0";
   # acquire a DHCP lease on link up
   # acquire a DHCP lease on link up
Line 126: Line 134:
entirely, because a working <code>network-online.target</code> is required for some
entirely, because a working <code>network-online.target</code> is required for some
services to properly start without race conditions.
services to properly start without race conditions.
Also consider enabling the <code>systemd.network.wait-online.anyInterface</code> option,
which makes networkd consider the network online when any interface is online,
as opposed to all that have a positive value for <code>linkConfig.RequiredForOnline</code>.
This is useful on portable machines with a wired and a wireless interface, for example.


Recommended documentation:
Recommended documentation:
Line 144: Line 157:
     matchConfig.Name = "enp1s0";
     matchConfig.Name = "enp1s0";
     networkConfig = {
     networkConfig = {
      # start a DHCP Client for IPv4 Addressing/Routing
       DHCP = "ipv4";
       DHCP = "ipv4";
      # accept Router Advertisements for Stateless IPv6 Autoconfiguraton (SLAAC)
       IPv6AcceptRA = true;
       IPv6AcceptRA = true;
     };
     };
     # making routing on this interface a dependency for network-online.target
     # make routing on this interface a dependency for network-online.target
     linkConfig.RequiredForOnline = "routable";
     linkConfig.RequiredForOnline = "routable";
   };
   };
Line 163: Line 178:
     matchConfig.Name = "enp1s0";
     matchConfig.Name = "enp1s0";
     address = [
     address = [
        # configure addresses including subnet mask
      # configure addresses including subnet mask
        "192.0.2.100/24"
      "192.0.2.100/24"
        "2001:DB8::2/64"
      "2001:DB8::2/64"
     ];
     ];
     routes = [
     routes = [
Line 172: Line 187:
       { routeConfig.Gateway = "192.0.2.1"; }
       { routeConfig.Gateway = "192.0.2.1"; }
       # or when the gateway is not on the same network
       # or when the gateway is not on the same network
       { routeConfig = {
       {
        Gateway = "172.31.1.1";
        routeConfig = {
        GatewayOnLink = true;
          Gateway = "172.31.1.1";
      }; }
          GatewayOnLink = true;
        };
      }
     ];
     ];
     # make the routes on this interface a dependency for network-online.target
     # make the routes on this interface a dependency for network-online.target
Line 186: Line 203:
VLANs can be configured on top of hardlinks as well as virtual links, like bonding interfaces. They provide separate logical networks over physical links.
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 <code>enp1s0</code>. The VLAN interfaces become available <code>vlan10</code> and <code>vlan20</code> and can receive additional configuration.
In this example we tag two VLANs with Ids 10 and 20 on a physical link <code>enp1s0</code>. The VLAN interfaces become available as <code>vlan10</code> and <code>vlan20</code> and can receive additional configuration.


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
Line 212: Line 229:
         # tag vlan on this link
         # tag vlan on this link
         vlan = [
         vlan = [
           vlan10
           "vlan10"
           vlan20
           "vlan20"
         ];
         ];
        networkConfig.LinkLocalAddressing = "no";
        linkConfig.RequiredForOnline = "carrier";
       };
       };
       "40-vlan10" = {
       "40-vlan10" = {
Line 225: Line 244:
       };
       };
     };
     };
  };
</syntaxhighlight>
=== Bridge ===
Given multiple interfaces, that are connected into a bridge will act like a common switch and forward Ethernet frames between all connected bridge ports. The Linux bridge supports various features, like spanning tree, bridge port isolation or acting as a multicast router.
The configuration on top of the bridge interface depends on the desired functionality, e.g., configuring an IP address would make the bridge host reachable on the Ethernet segment.
Recommended documentation:
* [https://www.freedesktop.org/software/systemd/man/systemd.network.html#%5BBridge%5D%20Section%20Options <nowiki>[Bridge]</nowiki> configuration reference]
<syntaxhighlight lang="nix">
  systemd.network = {
    netdevs = {
      # Create the bridge interface
      "20-br0" = {
        netdevConfig = {
          Kind = "bridge";
          Name = "br0";
        };
      };
    };
    networks = {
      # Connect the bridge ports to the bridge
      "30-enp1s0" = {
        matchConfig.Name = "enp1s0";
        networkConfig.Bridge = "br0";
        linkConfig.RequiredForOnline = "enslaved";
      };
      "30-enp2s0" = {
        matchConfig.Name = "enp2s0";
        networkConfig.Bridge = "br0";
        linkConfig.RequiredForOnline = "enslaved";
      };
      # Configure the bridge for its desired function
      "40-br0" = {
        matchConfig.Name = "br0";
        bridgeConfig = {};
        # Disable address autoconfig when no IP configuration is required
        #networkConfig.LinkLocalAddressing = "no";
        linkConfig = {
          # or "routable" with IP addresses configured
          RequiredForOnline = "carrier";
        };
      };
    };
  };
</syntaxhighlight>
</syntaxhighlight>


=== Bonding ===
=== Bonding ===


Given two hardlinks <code>enp2s0</code> and <code>enp3s0</code> create a virtual <code>bond0</code> interface using Dynamic LACP (802.3ad), hashing outgoing packets using a packet's Layer3/4 (OSI Layer) information.
Given two hardlinks <code>enp2s0</code> and <code>enp3s0</code> create a virtual <code>bond0</code> interface using Dynamic LACP (802.3ad), hashing outgoing packets using a packet's layer 3/4 (network/transport layer in the OSI model) information.


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
Line 264: Line 331:
   };
   };
</syntaxhighlight>
</syntaxhighlight>
=== Router Advertisement ===
Router advertisements are way to allow clients to achieve stateless autoconfiguration (SLAAC). The most prominent setup is where the router announces a prefix onto a LAN segment, which the receiving client can use to set up an address on that prefix, and configure the sender as its default gateway.
In this example the router will announce a static IPv6 prefix on the <code>lan</code> interface from it's automatically configured link local address on that link. The router does not generally require a unique local or globally reachable address on the link, unless you also want to host services like DNS and NTP on that LAN segment.
Recommended documentation:
* [https://www.freedesktop.org/software/systemd/man/systemd.network.html#%5BIPv6SendRA%5D%20Section%20Options <nowiki>[IPv6SendRa]</nowiki> configuration reference]
<syntaxhighlight lang="nix">
  systemd.network = {
    networks = {
      "30-lan" = {
        matchConfig.Name = "lan";
        address = [ "2001:db8:1122:3344::1/64" ];
        networkConfig = {
          IPv6SendRA = true;
        };
        ipv6Prefixes = [
          {
            # Announce a static prefix
            ipv6PrefixConfig.Prefix = "2001:db8:1122:3344::/64";
          }
        ];
        ipv6SendRAConfig = {
          # Provide a DNS resolver
          EmitDNS = true;
          DNS = "2001:db8:1122:3344::1";
        };
      };
    };
  };
</syntaxhighlight>
An extended form of this setup uses DHCPv6 prefix delegation to acquire a dynamic prefix over a WAN link, which then gets distributed onto designated LAN segments.
=== WireGuard ===
WireGuard can also be set up using <code>systemd.network.netdevs</code>. More details can be found at [[WireGuard#Setting up WireGuard with systemd-networkd]].


== User configurations ==
== User configurations ==
Line 274: Line 381:
* [https://gist.github.com/mweinelt/b78f7046145dbaeab4e42bf55663ef44 NixOS 22.11 VDSL Router (VLANs on top of Bonding, IPv6 Prefix-Delegation, pppd Integration)] by [https://github.com/mweinelt mweinelt]
* [https://gist.github.com/mweinelt/b78f7046145dbaeab4e42bf55663ef44 NixOS 22.11 VDSL Router (VLANs on top of Bonding, IPv6 Prefix-Delegation, pppd Integration)] by [https://github.com/mweinelt mweinelt]


[[Category: Networking]]
[[Category:systemd]]
[[Category:Networking]]
Klinger
trusted
602

edits

Retrieved from "https://wiki.nixos.org/wiki/Special:MobileDiff/10539...12528"