Difference between revisions of "Systemd-networkd"

From ArchWiki
Jump to navigation Jump to search
m (→‎[Match]: Fix a typo)
 
(192 intermediate revisions by 56 users not shown)
Line 1: Line 1:
 
{{Lowercase title}}
 
{{Lowercase title}}
[[Category:Network configuration]]
+
[[Category:Network managers]]
 
[[Category:Virtualization]]
 
[[Category:Virtualization]]
 
[[es:Systemd-networkd]]
 
[[es:Systemd-networkd]]
Line 6: Line 6:
 
[[ja:systemd-networkd]]
 
[[ja:systemd-networkd]]
 
[[ru:Systemd-networkd]]
 
[[ru:Systemd-networkd]]
 +
[[zh-hans:Systemd-networkd]]
 
{{Related articles start}}
 
{{Related articles start}}
 
{{Related|systemd}}
 
{{Related|systemd}}
 +
{{Related|systemd-resolved}}
 
{{Related|systemd-nspawn}}
 
{{Related|systemd-nspawn}}
 
{{Related|Network bridge}}
 
{{Related|Network bridge}}
Line 18: Line 20:
  
 
== Basic usage ==
 
== Basic usage ==
The {{Pkg|systemd}} package is part of the default Arch installation and contains all needed files to operate a wired network.  Wireless adapters can be setup by other services, such as [[wpa_supplicant]], which are covered later in this article.
+
The {{Pkg|systemd}} package is part of the default Arch installation and contains all needed files to operate a wired network.  Wireless adapters, covered later in this article, can be set up by services, such as [[wpa_supplicant]] or [[iwd]].
  
 
=== Required services and setup ===
 
=== Required services and setup ===
  
To use ''systemd-networkd'', [[start]] the following two services and [[enable]] them to run on system boot:
+
To use ''systemd-networkd'', [[start/enable]] {{ic|systemd-networkd.service}}.
  
* {{ic|systemd-networkd.service}}
+
It is optional to also [[start/enable]] {{ic|systemd-resolved.service}}, which is a network name resolution service to local applications, considering the following points:
* {{ic|systemd-resolved.service}}
 
  
{{Note|''systemd-resolved'' is actually required only if you are specifying DNS entries in ''.network'' files or if you want to obtain DNS addresses from networkd's DHCP client.}}
+
* The [[systemd-resolved]] service is required if DNS entries are specified in ''.network'' files,
 
+
* It can be used to automatically obtain DNS addresses from the network DHCP client,
For compatibility with [[resolv.conf]], delete or rename the existing file and create the following symbolic link:
+
* It is important to understand how [[resolv.conf]] and ''systemd-resolved'' interact to properly configure the DNS that will be used, some explanations are provided in [[systemd-resolved]].
 
+
* Note that ''systemd-resolved'' can also be used without ''systemd-networkd''.
# ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
 
 
 
Optionally, if you wish to use the local DNS stub resolver of ''systemd-resolved'' (and thus use LLMNR and DNS merging per interface), replace {{ic|dns}} with {{ic|resolve}} in {{ic|/etc/nsswitch.conf}}:
 
 
 
hosts: files '''resolve''' myhostname
 
 
 
See {{ic|man systemd-resolved}} and {{ic|man resolved.conf}} and [https://github.com/systemd/systemd/blob/master/README#L205 Systemd README].
 
 
 
{{Note|Systemd's {{ic|resolve}} may not search the local domain when given just the hostname, even when {{ic|1=UseDomains=yes}} or {{ic|1=Domains=[domain-list]}} is present in the appropriate {{ic|.network}} file, and that file produces the expected {{ic|search [domain-list]}} in {{ic|resolv.conf}}. If you run into this problem:
 
* Switch to using fully-qualified domain names
 
* Use {{ic|/etc/hosts}} to resolve hostnames
 
* Fall back to using glibc's {{ic|dns}} instead of using systemd's {{ic|resolve}}}}
 
  
 
=== Configuration examples ===
 
=== Configuration examples ===
All configurations in this section are stored as {{ic|foo.network}} in {{ic|/etc/systemd/network}}. For a full listing of options and processing order, see [[#Configuration files]] and the {{ic|systemd.network}} man page.
+
All configurations in this section are stored as {{ic|foo.network}} in {{ic|/etc/systemd/network/}}. For a full listing of options and processing order, see [[#Configuration files]] and {{man|5|systemd.network}}.
  
 
Systemd/udev automatically assigns predictable, stable network interface names for all local Ethernet, WLAN, and WWAN interfaces. Use {{ic|networkctl list}} to list the devices on the system.
 
Systemd/udev automatically assigns predictable, stable network interface names for all local Ethernet, WLAN, and WWAN interfaces. Use {{ic|networkctl list}} to list the devices on the system.
  
After making changes to a configuration file, reload the networkd daemon.
+
After making changes to a configuration file, [[restart]] {{ic|systemd-networkd.service}}.
  
# systemctl restart systemd-networkd
+
{{Note|
 
+
* The options specified in the configuration files are case sensitive.
{{Note|In the examples below, '''enp1s0''' is the wired adapter and '''wlp2s0''' is the wireless adapter. These names can be different on different systems.}}
+
* In the examples below, {{ic|enp1s0}} is the wired adapter and {{ic|wlp2s0}} is the wireless adapter. These names can be different on different systems. It is also possible to use a wildcard, e.g. {{ic|1=Name=en*}}.
 +
* If you want to disable IPv6, see [[IPv6#systemd-networkd_2|IPv6#systemd-networkd]].
 +
* Set {{ic|1=DHCP=yes}} to accept an IPv4 '''and''' IPv6 DHCP request to the {{ic|[Network]}} section.
 +
}}
  
 
==== Wired adapter using DHCP ====
 
==== Wired adapter using DHCP ====
{{hc|/etc/systemd/network/''wired''.network|<nowiki>
+
{{hc|/etc/systemd/network/20-wired.network|2=
 
[Match]
 
[Match]
 
Name=enp1s0
 
Name=enp1s0
  
 
[Network]
 
[Network]
DHCP=ipv4</nowiki>
+
DHCP=ipv4
 
}}
 
}}
  
 
==== Wired adapter using a static IP ====
 
==== Wired adapter using a static IP ====
{{hc|/etc/systemd/network/''wired''.network|<nowiki>
+
{{hc|/etc/systemd/network/20-wired.network|2=
 
[Match]
 
[Match]
 
Name=enp1s0
 
Name=enp1s0
Line 71: Line 63:
 
[Network]
 
[Network]
 
Address=10.1.10.9/24
 
Address=10.1.10.9/24
Gateway=10.1.10.1</nowiki>
+
Gateway=10.1.10.1
 +
DNS=10.1.10.1
 +
#DNS=8.8.8.8
 
}}
 
}}
  
See the {{ic|systemd.network(5)}} man page for more network options such as specifying DNS servers and a broadcast address.
+
{{ic|1=Address=}} can be used more than once to configure multiple IPv4 or IPv6 addresses. See [[#network files]] or {{man|5|systemd.network}} for more options.
  
 
==== Wireless adapter ====
 
==== Wireless adapter ====
In order to connect to a wireless network with ''systemd-networkd'', a wireless adapter configured with another service such as [[wpa_supplicant]] is required.  In this example, the corresponding systemd service file that needs to be enabled is {{ic|wpa_supplicant@wlp2s0.service}}.
+
In order to connect to a wireless network with ''systemd-networkd'', a wireless adapter configured with another application such as [[WPA supplicant]] or [[Iwd]] is required.
  
{{hc|/etc/systemd/network/''wireless''.network|<nowiki>
+
{{hc|/etc/systemd/network/25-wireless.network|<nowiki>
 
[Match]
 
[Match]
 
Name=wlp2s0
 
Name=wlp2s0
Line 91: Line 85:
 
==== Wired and wireless adapters on the same machine ====
 
==== Wired and wireless adapters on the same machine ====
  
This setup will enable a DHCP IP for both a wired and wireless connection making use of the metric directive to allow the kernel the decide on-the-fly which one to use.  This way, no connection downtime is observed when the wired connection is unplugged.
+
This setup will enable a DHCP IP for both a wired and wireless connection making use of the metric directive to allow the kernel to decide on-the-fly which one to use.  This way, no connection downtime is observed when the wired connection is unplugged.
  
 
The kernel's route metric (same as configured with ''ip'') decides which route to use for outgoing packets, in cases when several match. This will be the case when both wireless and wired devices on the system have active connections. To break the tie, the kernel uses the metric. If one of the connections is terminated, the other automatically wins without there being a gap with nothing configured (ongoing transfers may still not deal with this nicely but that is at a different OSI layer).
 
The kernel's route metric (same as configured with ''ip'') decides which route to use for outgoing packets, in cases when several match. This will be the case when both wireless and wired devices on the system have active connections. To break the tie, the kernel uses the metric. If one of the connections is terminated, the other automatically wins without there being a gap with nothing configured (ongoing transfers may still not deal with this nicely but that is at a different OSI layer).
  
{{Note|The '''Metric''' option is for static routes while the '''RouteMetric''' option is for setups not using static routes.}}
+
{{Note|The {{ic|Metric}} option is for static routes while the {{ic|RouteMetric}} option is for setups not using static routes. See {{man|5|systemd.network}} for more details.}}
  
{{hc|/etc/systemd/network/''wired''.network|<nowiki>
+
{{hc|/etc/systemd/network/20-wired.network|2=
 
[Match]
 
[Match]
 
Name=enp1s0
 
Name=enp1s0
Line 105: Line 99:
  
 
[DHCP]
 
[DHCP]
RouteMetric=10
+
RouteMetric=10}}
</nowiki>}}
 
  
{{hc|/etc/systemd/network/''wireless''.network|<nowiki>
+
{{hc|/etc/systemd/network/25-wireless.network|2=
 
[Match]
 
[Match]
 
Name=wlp2s0
 
Name=wlp2s0
Line 116: Line 109:
  
 
[DHCP]
 
[DHCP]
RouteMetric=20
+
RouteMetric=20}}
</nowiki>}}
 
  
==== IPv6 privacy extensions ====
+
==== Renaming an interface ====
  
{{Note|Broken on v228 https://github.com/systemd/systemd/issues/2242}}
+
Instead of [[Network configuration#Change interface name|editing udev rules]], a ''.link'' file can be used to rename an interface. A useful example is to set a predictable interface name for a USB-to-Ethernet adapter based on its MAC address, as those adapters are usually given different names depending on which USB port they are plugged into.
If you are using IPv6 you might also want to set the {{ic|IPv6PrivacyExtensions}} option as settings placed in {{ic|/etc/sysctl.d/40-ipv6.conf}} are not honored.
 
  
{{hc|/etc/systemd/network/''wireless''.network|<nowiki>
+
{{hc|head=/etc/systemd/network/10-ethusb0.link|output=
 
[Match]
 
[Match]
Name=wlp2s0
+
MACAddress=12:34:56:78:90:ab
  
[Network]
+
[Link]
DHCP=yes
+
Description=USB to Ethernet Adapter
IPv6PrivacyExtensions=true
+
Name=ethusb0
 +
}}
  
[DHCP]
+
{{Note|Any user-supplied ''.link'' '''must''' have a lexically earlier file name than the default config {{ic|99-default.link}} in order to be considered at all. For example, name the file {{ic|10-ethusb0.link}} and not {{ic|ethusb0.link}}.}}
RouteMetric=20
 
</nowiki>}}
 
  
 
== Configuration files ==
 
== Configuration files ==
  
Configuration files are located in {{ic|/usr/lib/systemd/network}}, the volatile runtime network directory {{ic|/run/systemd/network}} and, the local administration network directory {{ic|/etc/systemd/network}}. Files in {{ic|/etc/systemd/network}} have the highest priority.
+
Configuration files are located in {{ic|/usr/lib/systemd/network}}, the volatile runtime network directory {{ic|/run/systemd/network}} and the local administration network directory {{ic|/etc/systemd/network}}. Files in {{ic|/etc/systemd/network}} have the highest priority.
  
There are three types of configuration files.  
+
There are three types of configuration files. They all use a format similar to [[systemd#Writing unit files|systemd unit files]].  
  
* '''.network''' files. They will apply a network configuration for a ''matching'' device
+
* '''''.network''''' files. They will apply a network configuration for a ''matching'' device
* '''.netdev''' files. They will create a ''virtual network device'' for a ''matching'' environment
+
* '''''.netdev''''' files. They will create a ''virtual network device'' for a ''matching'' environment
* '''.link''' files. When a network device appears, [[udev]] will look for the first ''matching'' '''.link''' file
+
* '''''.link''''' files. When a network device appears, [[udev]] will look for the first ''matching'' ''.link'' file
  
 
They all follow the same rules:  
 
They all follow the same rules:  
  
 
* If '''all''' conditions in the {{ic|[Match]}} section are matched, the profile will be activated
 
* If '''all''' conditions in the {{ic|[Match]}} section are matched, the profile will be activated
* an empty {{ic|[Match]}} section means the profile will apply in any case (can be compared to the {{ic|*}} joker)
+
* an empty {{ic|[Match]}} section means the profile will apply in any case (can be compared to the {{ic|*}} wildcard)
* each entry is a key with the {{ic|1=NAME=VALUE}} syntax
 
 
* all configuration files are collectively sorted and processed in lexical order, regardless of the directory in which they live
 
* all configuration files are collectively sorted and processed in lexical order, regardless of the directory in which they live
 
* files with identical name replace each other
 
* files with identical name replace each other
  
 
{{Tip|
 
{{Tip|
* to override a system-supplied file in {{ic|/usr/lib/systemd/network}} in a permanent manner (i.e even after upgrade), place a file with same name in {{ic|/etc/systemd/network}} and symlink it to {{ic|/dev/null}}
+
* To override a system-supplied file in {{ic|/usr/lib/systemd/network}} in a permanent manner (i.e even after upgrade), place a file with same name in {{ic|/etc/systemd/network}} and symlink it to {{ic|/dev/null}}
* the {{ic|*}} joker can be used in {{ic|VALUE}} (e.g {{ic|en*}} will match any Ethernet device)
+
* The {{ic|*}} wildcard can be used in {{ic|VALUE}} (e.g {{ic|en*}} will match any Ethernet device), a boolean can be simple written as {{ic|yes}} or {{ic|no}}.
* following this [https://mailman.archlinux.org/pipermail/arch-general/2014-March/035381.html Arch-general thread], the best practice is to setup specific container network settings ''inside the container'' with '''networkd''' configuration files.
+
* Following this [https://mailman.archlinux.org/pipermail/arch-general/2014-March/035381.html Arch-general thread], the best practice is to setup specific container network settings ''inside the container'' with '''networkd''' configuration files.
 +
* Systemd accepts the values {{ic|1, true, yes, on}} for a true boolean, and the values {{ic|0, false, no, off}} for a false boolean
 
}}
 
}}
  
Line 164: Line 154:
 
These files are aimed at setting network configuration variables, especially for servers and containers.
 
These files are aimed at setting network configuration variables, especially for servers and containers.
  
Below is a basic structure of a {{ic|''MyProfile''.network}} file:
+
''.network'' files have the following sections: {{ic|[Match]}}, {{ic|[Link]}}, {{ic|[Network]}}, {{ic|[Address]}}, {{ic|[Route]}}, and {{ic|[DHCP]}}. Below are commonly configured keys for each section. See {{man|5|systemd.network}} for more information and examples.
  
{{hc|/etc/systemd/network/''MyProfile''.network|
+
==== [Match] ====
[Match]
 
''a vertical list of keys''
 
  
[Network]
+
{| class = "wikitable"
''a vertical list of keys''
+
! Parameter !! Description !! Accepted Values !! Default Value
 +
|-
 +
| {{ic|1=Name=}} || Match device names, e.g. {{ic|en*}}. By prefixing with {{ic|!}}, the list can be inverted. || white-space separated device names with globs, logical negation ({{ic|!}}) ||
 +
|-
 +
| {{ic|1=MACAddress=}} || Match MAC addresses, e.g. {{ic|1=MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF}} || whitespace-separated MAC addresses in full colon-, hyphen- or dot-delimited hexadecimal ||
 +
|-
 +
| {{ic|1=Host=}} || Match the hostname or machine ID of the host. || hostname string with globs, [https://jlk.fjfi.cvut.cz/arch/manpages/man/machine-id.5.en machine ID] ||
 +
|-
 +
| {{ic|1=Virtualization=}} || Check whether the system is executed in a virtualized environment. {{ic|1=Virtualization=false}} will only match your host machine, while {{ic|1=Virtualization=true}} matches any container or VM. It is possible to check for a specific virtualization type or implementation. || boolean, logical negation ({{ic|!}}), type ({{ic|vm}}, {{ic|container}}), implementation ({{ic|qemu}}, {{ic|kvm}}, {{ic|zvm}}, {{ic|vmware}}, {{ic|microsoft}}, {{ic|oracle}}, {{ic|xen}}, {{ic|bochs}}, {{ic|uml}}, {{ic|bhyve}}, {{ic|qnx}}, {{ic|openvz}}, {{ic|lxc}}, {{ic|lxc-libvirt}}, {{ic|systemd-nspawn}}, {{ic|docker}}, {{ic|podman}}, {{ic|rkt}}, {{ic|wsl}}, {{ic|acrn}}) ||
 +
|}
  
[Address]
+
==== [Link] ====
''a vertical list of keys''
 
  
[Route]
+
* {{ic|1=MACAddress=}} useful for [[MAC_address_spoofing#systemd-networkd|MAC address spoofing]]
''a vertical list of keys''
+
* {{ic|1=MTUBytes=}} setting a larger MTU value (e.g. when using [[jumbo frames]]) can significantly speed up your network transfers
}}
+
* {{ic|1=Multicast}} allow the usage of [[wikipedia:Multicast_address|multicast]] on interface(s)
  
==== [Match] section ====
+
==== [Network] ====
 
 
Most common keys are:
 
 
 
* {{ic|1=Name=}} the device name (e.g Br0, enp4s0, en*)
 
* {{ic|1=Host=}} the machine hostname
 
* {{ic|1=Virtualization=}} check whether the system is executed in a virtualized environment or not. A {{ic|1=Virtualization=no}} key will only apply on your host machine, while {{ic|1=Virtualization=yes}} apply to any container or VM.
 
  
==== [Network] section ====
+
{| class = "wikitable"
 +
! Parameter !! Description !! Accepted Values !! Default Value
 +
|-
 +
| {{ic|1=DHCP=}} || Controls DHCPv4 and/or DHCPv6 client support. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}
 +
|-
 +
| {{ic|1=DHCPServer=}} || If enabled, a DHCPv4 server will be started. || boolean || {{ic|false}}
 +
|-
 +
| {{ic|1=MulticastDNS=}} || Enables [https://tools.ietf.org/html/rfc6762 multicast DNS] support. When set to {{ic|resolve}}, only resolution is enabled, but not host or service registration and announcement. || boolean, {{ic|resolve}} || {{ic|false}}
 +
|-
 +
| {{ic|1=DNSSEC=}} || Controls DNSSEC DNS validation support on the link. When set to {{ic|allow-downgrade}}, compatibility with non-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case. || boolean, {{ic|allow-downgrade}} || {{ic|false}}
 +
|-
 +
| {{ic|1=DNS=}} || Configure static [[DNS]] addresses. May be specified more than once. || [http://man7.org/linux/man-pages/man3/inet_pton.3.html {{ic|inet_pton}}] ||
 +
|-
 +
| {{ic|1=Domains=}} || A list of domains which should be resolved using the DNS servers on this link. [https://www.freedesktop.org/software/systemd/man/systemd.network.html#Domains= more information] || domain name, optionally prefixed with a tilde ({{ic|~}}) ||
 +
|-
 +
| {{ic|1=IPForward=}} || If enabled, incoming packets on any network interface will be forwarded to any other interfaces according to the routing table. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}
 +
|-
 +
| {{ic|1=IPv6PrivacyExtensions=}} || Configures use of stateless temporary addresses that change over time (see [https://tools.ietf.org/html/rfc4941 RFC 4941]). When {{ic|prefer-public}}, enables the privacy extensions, but prefers public addresses over temporary addresses. When {{ic|kernel}}, the kernel's default setting will be left in place. || boolean, {{ic|prefer-public}}, {{ic|kernel}} || {{ic|false}}
 +
|}
  
Most common keys are:
+
==== [Address] ====
  
* {{ic|1=DHCP=}} enables [[Wikipedia:Dynamic Host Configuration Protocol|DHCPv4]] and/or DHCPv6 support. Accepts {{ic|yes}}, {{ic|no}}, {{ic|ipv4}} or {{ic|ipv6}}
+
* {{ic|1=Address=}} this option is '''mandatory''' unless DHCP is used
* {{ic|1=DNS=}} is a [[Wikipedia:Domain Name System|DNS]] server address. You can specify this option more than once
 
* {{ic|1=Bridge=}} is the name of the bridge to add the link to
 
* {{ic|1=IPForward=}} defaults to {{ic|no}}. It enables IP forwarding, performing the forwarding according to the routing table and is required for setting up [[Internet sharing]]. Note that turning {{ic|1=IPForward=}} on applies to ''all'' network interfaces.
 
* {{ic|1=Domains=}} a list of the domains used for DNS host name resolution.
 
  
Please see {{ic|systemd.network(5)}} for details.
+
==== [Route] ====
  
==== [Address] section ====
+
* {{ic|1=Gateway=}} this option is '''mandatory''' unless DHCP is used
Most common key in the {{ic|[Address]}} section is:
+
* {{ic|1=Destination=}} the destination prefix of the route, possibly followed by a slash and the prefix length
  
* {{ic|1=Address=}} is a static '''IPv4''' or '''IPv6''' address and its prefix length, separated by a {{ic|/}} character (e.g {{ic|192.168.1.90/24}}). This option is '''mandatory''' unless DHCP is used.
+
If {{ic|1=Destination}} is not present in {{ic|[Route]}} section this section is treated as a default route.
 +
{{Tip|You can put the {{ic|1=Address=}} and {{ic|1=Gateway=}} keys in the {{ic|[Network]}} section as a short-hand if {{ic|1=[Address]}} section contains only an Address key and {{ic|1=[Route]}} section contains only a Gateway key.}}
  
==== [Route] section ====
+
==== [DHCP] ====
Most common key in the {{ic|[Route]}} section is:
 
  
* {{ic|1=Gateway=}} is the address of your machine gateway. This option is '''mandatory''' unless DHCP is used.
+
{| class = "wikitable
For an exhaustive key list, please refer to {{ic|systemd.network(5)}}
+
! Parameter !! Description !! Accepted Values !! Default Value
 
+
|-
{{Tip|you can put the {{ic|1=Address=}} and {{ic|1=Gateway=}} keys in the {{ic|[Network]}} section as a short-hand if {{ic|1=Address=}} contains only an Address key and {{ic|1=Gateway=}} section contains only a Gateway key
+
| {{ic|1=UseDNS=}} || controls whether the DNS servers advertised by the DHCP server are used || boolean || {{ic|true}}
}}
+
|-
 +
| {{ic|1=Anonymize=}} || when true, the options sent to the DHCP server will follow the [https://tools.ietf.org/html/rfc7844 RFC7844] (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information || boolean || {{ic|false}}
 +
|-
 +
| {{ic|1=UseDomains=}} || controls whether the domain name received from the DHCP server will be used as DNS search domain. If set to {{ic|route}}, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching. This option can sometimes fix local name resolving when using [[systemd-resolved]] || boolean, {{ic|route}} || {{ic|false}}
 +
|}
  
 
=== netdev files ===
 
=== netdev files ===
  
These files will create virtual network devices.
+
These files will create virtual network devices. They have two sections: {{ic|[Match]}} and {{ic|[NetDev]}}. Below are commonly configured keys for each section. See {{man|5|systemd.netdev}} for more information and examples.
 
 
Below is a basic structure of a ''Mydevice''.netdev file:
 
 
 
{{hc|/etc/systemd/network/''MyDevice''.netdev|
 
[Match]
 
''a vertical list of keys''
 
 
 
[NetDev]
 
''a vertical list of keys''
 
}}
 
  
 
==== [Match] section ====
 
==== [Match] section ====
  
Most common keys are {{ic|1=Host=}} and {{ic|1=Virtualization=}}
+
* {{ic|1=Host=}} the hostname
 +
* {{ic|1=Virtualization=}} check if running in a VM
  
 
==== [NetDev] section ====
 
==== [NetDev] section ====
Line 236: Line 235:
 
Most common keys are:
 
Most common keys are:
  
* {{ic|1=Name=}} is the interface name used when creating the netdev. This option is '''compulsory'''
+
* {{ic|1=Name=}} the interface name. '''mandatory'''
* {{ic|1=Kind=}} is the netdev kind. For example, ''bridge'', ''bond'', ''vlan'', ''veth'', ''sit'', etc. are supported. This option is '''compulsory'''
+
* {{ic|1=Kind=}} e.g. ''bridge'', ''bond'', ''vlan'', ''veth'', ''sit'', etc. '''mandatory'''
 
 
For an exhaustive key list, please refer to {{ic|systemd.netdev(5)}}
 
  
 
=== link files ===
 
=== link files ===
  
These files are an alternative to custom udev rules and will be applied by [[udev]] as the device appears.
+
These files are an alternative to custom udev rules and will be applied by [[udev]] as the device appears. They have two sections: {{ic|[Match]}} and {{ic|[Link]}}. Below are commonly configured keys for each section. See {{man|5|systemd.link}} for more information and examples.
 
 
Below is a basic structure of a ''Mydevice''.link file:
 
 
 
{{hc|/etc/systemd/network/''MyDevice''.link|
 
[Match]
 
''a vertical list of keys''
 
  
[Link]
+
{{Tip|Use {{ic|# udevadm test-builtin net_setup_link /sys/path/to/network/device}} to diagnose problems with ''.link'' files.}}
''a vertical list of keys''
 
}}
 
 
 
The {{ic|[Match]}} section will determine if a given link file may be applied to a given device, when the {{ic|[Link]}} section specifies the device configuration.
 
  
 
==== [Match] section ====
 
==== [Match] section ====
  
Most common keys are {{ic|1=MACAddress=}}, {{ic|1=Host=}} and {{ic|1=Virtualization=}}.
+
* {{ic|1=MACAddress=}} the MAC address
 
+
* {{ic|1=Host=}} the host name
{{ic|1=Type=}} is the device type (e.g. vlan)
+
* {{ic|1=Virtualization=}}  
 +
* {{ic|1=Type=}} the device type e.g. vlan
  
 
==== [Link] section ====
 
==== [Link] section ====
  
Most common keys are:
+
* {{ic|1=MACAddressPolicy=}} persistent or random addresses, or
 
+
* {{ic|1=MACAddress=}} a specific address
{{ic|1=MACAddressPolicy=}} is either ''persistent'' when the hardware has a persistent MAC address (as most hardware should) or ''random'' , which allows to give a random MAC address when the device appears.
 
 
 
{{ic|1=MACAddress=}} shall be used when no {{ic|1=MACAddressPolicy=}} is specified.
 
  
 
{{Note|the system {{ic|/usr/lib/systemd/network/99-default.link}} is generally sufficient for most of the basic cases.}}
 
{{Note|the system {{ic|/usr/lib/systemd/network/99-default.link}} is generally sufficient for most of the basic cases.}}
Line 275: Line 260:
 
== Usage with containers ==
 
== Usage with containers ==
  
The service is available with {{Pkg|systemd}} >= 210. You will want to [[systemd#Basic systemctl usage|enable and start]] the {{ic|systemd-networkd.service}} on the host and container.
+
The service is available with {{Pkg|systemd}}. You will want to [[enable]] and [[start]] the {{ic|systemd-networkd.service}} unit on the host and container.
 
 
For debugging purposes, it is strongly advised to [[install]] the {{Pkg|bridge-utils}}, {{Pkg|net-tools}} and {{Pkg|iproute2}} packages.
 
  
If you are using ''systemd-nspawn'', you may need to modify the {{ic|systemd-nspawn@.service}} and append boot options to the {{ic|ExecStart}} line. Please refer to {{ic|man 1 systemd-nspawn}} for an exhaustive list of options.
+
For debugging purposes, it is strongly advised to [[install]] the {{Pkg|bridge-utils}}, {{Pkg|net-tools}}, and {{Pkg|iproute2}} packages.
  
Note that if you want to take advantage of automatic DNS configuration from DHCP, you need to enable {{ic|systemd-resolved}} and symlink {{ic|/run/systemd/resolve/resolv.conf}} to {{ic|/etc/resolv.conf}}. See {{ic|systemd-resolved.service(8)}} for more details.
+
If you are using [[systemd-nspawn]], you may need to modify the {{ic|systemd-nspawn@.service}} and append boot options to the {{ic|ExecStart}} line. Please refer to {{man|1|systemd-nspawn}} for an exhaustive list of options.
  
{{Style|Too many points for a tip, some of them are very similar so they could be merged.}}
+
Note that if you want to take advantage of automatic DNS configuration from DHCP, you need to enable {{ic|systemd-resolved}} and symlink {{ic|/run/systemd/resolve/resolv.conf}} to {{ic|/etc/resolv.conf}}. See {{man|8|systemd-resolved.service}} for more details.
  
{{Tip|1=Before you start to configure your container network, it is useful to:
+
Before you start to configure your container network, it is useful to:
* disable all your [[netctl]] services. This will avoid any potential conflicts with {{ic|systemd-networkd}} and make all your configurations easier to test. Furthermore, odds are high you will end with few or even no [[netctl]] activated profiles. The {{ic|netctl list}} command will output a list of all your profiles, with the activated one being starred.
+
* disable all your [[netctl]] (host and container), [[dhcpcd]] (host and container), [[systemd-networkd]] (container only) and {{ic|systemd-nspawn@.service}} (host only) services to avoid potential conflicts and to ease debugging
* disable the {{ic|systemd-nspawn@.service}} and use the {{ic|systemd-nspawn -bnD /path_to/your_container/}} command as root to boot the container. To log off and shutdown inside the container {{ic|systemctl poweroff}} is used as root. Once the network setting meets your requirements, [[systemd#Basic systemctl usage|enable and start]] {{ic|systemd-nspawn@.service}}
+
* make sure [[Internet sharing#Enable packet forwarding|packet forwarding]] is enabled if you want to let containers access the internet. Make sure that your ''.network'' file does not accidentally turn off forwarding because if you do not have a {{ic|1=IPForward=1}} setting in it, {{ic|systemd-networkd}} will turn off forwarding on this interface, even if you have it enabled globally.
* disable the {{ic|dhcpcd.service}} if enabled on your system, since it activates ''dhcpcd'' on '''all''' interfaces
 
* make sure you have no [[netctl]] profiles activated in the container, and ensure that {{ic|systemd-networkd.service}} is neither enabled nor started
 
 
* make sure you do not have any [[iptables]] rules which can block traffic
 
* make sure you do not have any [[iptables]] rules which can block traffic
* make sure ''packet forwarding'' is [[Internet sharing#Enable packet forwarding|enabled]] if you want to let containers access the internet. Make sure that your {{ic|.network}} file does not accidentally turn off forwarding because if you do not have a {{ic|1=IPForward=1}} setting in it, {{ic|systemd-networkd}} will turn off forwarding on this interface, even if you have it enabled globally.
 
 
* when the daemon is started the systemd {{ic|networkctl}} command displays the status of network interfaces.
 
* when the daemon is started the systemd {{ic|networkctl}} command displays the status of network interfaces.
}}
 
  
{{Note|For the set-up described below,  
+
For the set-up described below,  
 
* we will limit the output of the {{ic|ip a}} command to the concerned interfaces
 
* we will limit the output of the {{ic|ip a}} command to the concerned interfaces
 
* we assume the ''host'' is your main OS you are booting to and the ''container'' is your guest virtual machine
 
* we assume the ''host'' is your main OS you are booting to and the ''container'' is your guest virtual machine
 
* all interface names and IP addresses are only examples
 
* all interface names and IP addresses are only examples
}}
 
  
 
=== Basic DHCP network ===
 
=== Basic DHCP network ===
Line 340: Line 318:
 
  # ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
 
  # ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
  
See {{ic|systemd-resolved.service(8)}} for more details.
+
See {{man|8|systemd-resolved.service}} for more details.
 +
 
 +
{{Note|Users accessing a system partition via {{ic|/usr/bin/arch-chroot}} from {{pkg|arch-install-scripts}}, will need to create the symlink outside of the chroot, on the mounted partition.  This is due to arch-chroot linking the file to the live environment.}}
  
 
=== DHCP with two distinct IP ===
 
=== DHCP with two distinct IP ===
Line 346: Line 326:
 
==== Bridge interface ====
 
==== Bridge interface ====
  
Create a virtual bridge interface  
+
First, create a virtual bridge interface. We tell systemd to create a device named ''br0'' that functions as an ethernet bridge.
  
{{hc|/etc/systemd/network/''MyBridge''.netdev|<nowiki>
+
{{hc|/etc/systemd/network/''MyBridge''.netdev|2=
 
[NetDev]
 
[NetDev]
 
Name=br0
 
Name=br0
Kind=bridge
+
Kind=bridge}}
</nowiki>}}
+
 
 +
[[Restart]] {{ic|systemd-networkd.service}} to have systemd create the bridge.
  
 
On host and container:
 
On host and container:
Line 361: Line 342:
 
}}
 
}}
  
Note that the interface br0 is listed but is DOWN.
+
Note that the interface ''br0'' is listed but is still DOWN at this stage.
  
 
==== Bind ethernet to bridge ====
 
==== Bind ethernet to bridge ====
 +
The next step is to add to the newly created bridge a network interface. In the example below, we add any interface that matches the name ''en*'' into the bridge ''br0''.
  
Modify the {{ic|/etc/systemd/network/''MyDhcp''.network}} to remove the DHCP, as the bridge requires an interface to bind to with no IP, and add a key to bind this device to br0. Let us change its name to a more relevant one.
+
{{hc|/etc/systemd/network/''bind''.network|2=
 
 
{{hc|/etc/systemd/network/''MyEth''.network|<nowiki>
 
 
[Match]
 
[Match]
 
Name=en*
 
Name=en*
  
 
[Network]
 
[Network]
Bridge=br0
+
Bridge=br0}}
</nowiki>}}
+
The ethernet interface must not have DHCP or an IP address associated as the bridge requires an interface to bind to with no IP: modify the corresponding {{ic|/etc/systemd/network/''MyEth''.network}} accordingly to remove the addressing.
  
 
==== Bridge network ====
 
==== Bridge network ====
  
Create a network profile for the Bridge
+
Now that the bridge has been created and has been bound to an existing network interface, the IP configuration of the bridge interface must be specified. This is defined in a third ''.network'' file, the example below uses DHCP.
  
{{hc|/etc/systemd/network/''MyBridge''.network|<nowiki>
+
{{hc|/etc/systemd/network/''mybridge''.network|2=
 
[Match]
 
[Match]
 
Name=br0
 
Name=br0
  
 
[Network]
 
[Network]
DHCP=ipv4
+
DHCP=ipv4}}
</nowiki>}}
 
  
 
==== Add option to boot the container ====
 
==== Add option to boot the container ====
Line 423: Line 402:
 
==== Notice ====
 
==== Notice ====
  
* we have now one IP address for Br0 on the host, and one for host0 in the container
+
* we have now one IP address for {{ic|br0}} on the host, and one for {{ic|host0}} in the container
 
* two new interfaces have appeared: {{ic|vb-''MyContainer''}} in the host and {{ic|host0}} in the container. This comes as a result of the {{ic|1=--network-bridge=br0}} option. This option ''implies'' another option, {{ic|--network-veth}}. This means a ''virtual Ethernet link'' has been created between host and container.
 
* two new interfaces have appeared: {{ic|vb-''MyContainer''}} in the host and {{ic|host0}} in the container. This comes as a result of the {{ic|1=--network-bridge=br0}} option. This option ''implies'' another option, {{ic|--network-veth}}. This means a ''virtual Ethernet link'' has been created between host and container.
 
* the DHCP address on {{ic|host0}} comes from the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file.
 
* the DHCP address on {{ic|host0}} comes from the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file.
Line 459: Line 438:
  
 
Setting a static IP for each device can be helpful in case of deployed web services (e.g FTP, http, SSH). Each device will keep the same MAC address across reboots if your system {{ic|/usr/lib/systemd/network/99-default.link}} file has the {{ic|1=MACAddressPolicy=persistent}} option (it has by default). Thus, you will easily route any service on your Gateway to the desired device.
 
Setting a static IP for each device can be helpful in case of deployed web services (e.g FTP, http, SSH). Each device will keep the same MAC address across reboots if your system {{ic|/usr/lib/systemd/network/99-default.link}} file has the {{ic|1=MACAddressPolicy=persistent}} option (it has by default). Thus, you will easily route any service on your Gateway to the desired device.
First, we shall get rid of the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file. To do it in a permanent way (e.g even after upgrades), do the following on container.  This will mask the file {{ic|/usr/lib/systemd/network/80-container-host0.network}} since files of the same name in {{ic|/etc/systemd/network}} take priority over {{ic|/usr/lib/systemd/network}}.
 
  
# ln -sf /dev/null /etc/systemd/network/80-container-host0.network
+
The following configuration needs to be done for this setup:
 
+
* on host
Then, [[systemd#Basic systemctl usage|enable and start]] {{ic|systemd-networkd}} on your container.
 
  
The needed configuration files:
+
The configuration is very similar to that of [[#DHCP with two distinct IP]]. First, a virtual bridge interface needs to be created and the main physical interface needs to be bound to it. This task can be accomplished with the following two files, with contents equal to those available at the DHCP section.
* on host
 
{{Accuracy|In the listing of configuration files, /etc/systemd/network/MyBridge.netdev has the .netdev extension.  But, the MyBridge.network example file has the .network extension.}}
 
  
 
  /etc/systemd/network/''MyBridge''.netdev
 
  /etc/systemd/network/''MyBridge''.netdev
 
  /etc/systemd/network/''MyEth''.network
 
  /etc/systemd/network/''MyEth''.network
  
A modified ''MyBridge''.network
+
Next, you need to configure the IP and DNS of the newly created virtual bridge interface. The following ''MyBridge''.network provides an example configuration:
  
 
{{hc|/etc/systemd/network/''MyBridge''.network|<nowiki>
 
{{hc|/etc/systemd/network/''MyBridge''.network|<nowiki>
Line 485: Line 460:
  
 
* on container
 
* on container
 +
 +
First, we shall get rid of the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file, which provides a DHCP configuration for the default network interface of the container. To do it in a permanent way (e.g. even after {{pkg|systemd}} upgrades), do the following on the container. This will mask the file {{ic|/usr/lib/systemd/network/80-container-host0.network}} since files of the same name in {{ic|/etc/systemd/network}} take priority over {{ic|/usr/lib/systemd/network}}. Keep in mind that this file can be kept if you only want a static IP on the host, and want the IP address of your containers to be assigned via DHCP.
 +
 +
# ln -sf /dev/null /etc/systemd/network/80-container-host0.network
 +
 +
Then, configure an static IP for the default {{ic|host0}} network interface and [[systemd#Basic systemctl usage|enable and start]] {{ic|systemd-networkd.service}} on your container. An example configuration is provided below:
  
 
{{hc|/etc/systemd/network/''MyVeth''.network|<nowiki>
 
{{hc|/etc/systemd/network/''MyVeth''.network|<nowiki>
Line 495: Line 476:
 
Gateway=192.168.1.254
 
Gateway=192.168.1.254
 
</nowiki>}}
 
</nowiki>}}
 +
 +
== Interface and desktop integration ==
 +
 +
''systemd-networkd'' does not have a proper interactive management interface neither via command-line nor graphical.
 +
Still, some tools are available to either display the current state of the network, receive notifications or interact with the wireless configuration:
 +
 +
* ''networkctl'' (via CLI) offers a simple dump of the network interface states.
 +
 +
* When ''networkd'' is configured with [[wpa_supplicant]], both ''wpa_cli'' and ''wpa_gui'' offer the ability to associate and configure WLAN interfaces dynamically.
 +
 +
* {{AUR|networkd-notify-git}} can generate simple notifications in response to network interface state changes (such as connection/disconnection and re-association).
 +
 +
* The {{AUR|networkd-dispatcher}} daemon allows executing scripts in response to network interface state changes, similar to ''NetworkManager-dispatcher''.
 +
 +
* As for the DNS resolver ''systemd-resolved'', information about current DNS servers can be visualized with {{ic|resolvectl status}}.
 +
 +
== Troubleshooting ==
 +
=== Mount services at boot fail ===
 +
If running services like [[Samba]]/[[NFS]] which fail if they are started before the network is up, you may want to [[enable]] the {{ic|systemd-networkd-wait-online.service}}. This is, however, rarely necessary because most networked daemons start up okay, even if the network has not been configured yet.
 +
 +
=== systemd-resolve not searching the local domain ===
 +
 +
{{Move|systemd-resolved|The problem is with [[systemd-resolved]].}}
 +
 +
[[systemd-resolved]] may not search the local domain when given just the hostname, even when {{ic|1=UseDomains=yes}} or {{ic|1=Domains=[domain-list]}} is present in the appropriate ''.network'' file, and that file produces the expected {{ic|search [domain-list]}} in {{ic|resolv.conf}}. You can run {{ic|networkctl status}} or {{ic|resolvectl status}} to check if the search domains are actually being picked up.
 +
 +
Possible workarounds:
 +
 +
* Disable [[systemd-resolved#LLMNR|LLMNR]] to let ''systemd-resolved'' immediately continue with appending the DNS suffixes
 +
* Trim {{ic|/etc/nsswitch.conf}}'s {{ic|hosts}} database (e.g., by removing {{ic|1=[!UNAVAIL=return]}} option after {{ic|resolve}} service)
 +
* Switch to using fully-qualified domain names
 +
* Use {{ic|/etc/hosts}} to resolve hostnames
 +
* Fall back to using glibc's {{ic|dns}} instead of using systemd's {{ic|resolve}}
 +
 +
=== Connected second PC unable to use bridged LAN ===
 +
 +
{{Move|Network configuration|Not specific to systemd-networkd.}}
 +
 +
First PC have two LAN. Second PC have one LAN and connected to first PC. Lets go second PC to give all access to LAN after bridged interface:
 +
 +
{{Expansion|Explain what the settings actually do.}}
 +
 +
# sysctl net.bridge.bridge-nf-filter-pppoe-tagged=0
 +
# sysctl net.bridge.bridge-nf-filter-vlan-tagged=0
 +
# sysctl net.bridge.bridge-nf-call-ip6tables=0
 +
# sysctl net.bridge.bridge-nf-call-iptables=0
 +
# sysctl net.bridge.bridge-nf-call-arptables=0
  
 
== See also ==
 
== See also ==

Latest revision as of 23:23, 1 October 2019

systemd-networkd is a system daemon that manages network configurations. It detects and configures network devices as they appear; it can also create virtual network devices. This service can be especially useful to set up complex network configurations for a container managed by systemd-nspawn or for virtual machines. It also works fine on simple connections.

Basic usage

The systemd package is part of the default Arch installation and contains all needed files to operate a wired network. Wireless adapters, covered later in this article, can be set up by services, such as wpa_supplicant or iwd.

Required services and setup

To use systemd-networkd, start/enable systemd-networkd.service.

It is optional to also start/enable systemd-resolved.service, which is a network name resolution service to local applications, considering the following points:

  • The systemd-resolved service is required if DNS entries are specified in .network files,
  • It can be used to automatically obtain DNS addresses from the network DHCP client,
  • It is important to understand how resolv.conf and systemd-resolved interact to properly configure the DNS that will be used, some explanations are provided in systemd-resolved.
  • Note that systemd-resolved can also be used without systemd-networkd.

Configuration examples

All configurations in this section are stored as foo.network in /etc/systemd/network/. For a full listing of options and processing order, see #Configuration files and systemd.network(5).

Systemd/udev automatically assigns predictable, stable network interface names for all local Ethernet, WLAN, and WWAN interfaces. Use networkctl list to list the devices on the system.

After making changes to a configuration file, restart systemd-networkd.service.

Note:
  • The options specified in the configuration files are case sensitive.
  • In the examples below, enp1s0 is the wired adapter and wlp2s0 is the wireless adapter. These names can be different on different systems. It is also possible to use a wildcard, e.g. Name=en*.
  • If you want to disable IPv6, see IPv6#systemd-networkd.
  • Set DHCP=yes to accept an IPv4 and IPv6 DHCP request to the [Network] section.

Wired adapter using DHCP

/etc/systemd/network/20-wired.network
[Match]
Name=enp1s0

[Network]
DHCP=ipv4

Wired adapter using a static IP

/etc/systemd/network/20-wired.network
[Match]
Name=enp1s0

[Network]
Address=10.1.10.9/24
Gateway=10.1.10.1
DNS=10.1.10.1
#DNS=8.8.8.8

Address= can be used more than once to configure multiple IPv4 or IPv6 addresses. See #network files or systemd.network(5) for more options.

Wireless adapter

In order to connect to a wireless network with systemd-networkd, a wireless adapter configured with another application such as WPA supplicant or Iwd is required.

/etc/systemd/network/25-wireless.network
[Match]
Name=wlp2s0

[Network]
DHCP=ipv4

If the wireless adapter has a static IP address, the configuration is the same (except for the interface name) as in a wired adapter.

Wired and wireless adapters on the same machine

This setup will enable a DHCP IP for both a wired and wireless connection making use of the metric directive to allow the kernel to decide on-the-fly which one to use. This way, no connection downtime is observed when the wired connection is unplugged.

The kernel's route metric (same as configured with ip) decides which route to use for outgoing packets, in cases when several match. This will be the case when both wireless and wired devices on the system have active connections. To break the tie, the kernel uses the metric. If one of the connections is terminated, the other automatically wins without there being a gap with nothing configured (ongoing transfers may still not deal with this nicely but that is at a different OSI layer).

Note: The Metric option is for static routes while the RouteMetric option is for setups not using static routes. See systemd.network(5) for more details.
/etc/systemd/network/20-wired.network
[Match]
Name=enp1s0

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=10
/etc/systemd/network/25-wireless.network
[Match]
Name=wlp2s0

[Network]
DHCP=ipv4

[DHCP]
RouteMetric=20

Renaming an interface

Instead of editing udev rules, a .link file can be used to rename an interface. A useful example is to set a predictable interface name for a USB-to-Ethernet adapter based on its MAC address, as those adapters are usually given different names depending on which USB port they are plugged into.

/etc/systemd/network/10-ethusb0.link
[Match]
MACAddress=12:34:56:78:90:ab

[Link]
Description=USB to Ethernet Adapter
Name=ethusb0
Note: Any user-supplied .link must have a lexically earlier file name than the default config 99-default.link in order to be considered at all. For example, name the file 10-ethusb0.link and not ethusb0.link.

Configuration files

Configuration files are located in /usr/lib/systemd/network, the volatile runtime network directory /run/systemd/network and the local administration network directory /etc/systemd/network. Files in /etc/systemd/network have the highest priority.

There are three types of configuration files. They all use a format similar to systemd unit files.

  • .network files. They will apply a network configuration for a matching device
  • .netdev files. They will create a virtual network device for a matching environment
  • .link files. When a network device appears, udev will look for the first matching .link file

They all follow the same rules:

  • If all conditions in the [Match] section are matched, the profile will be activated
  • an empty [Match] section means the profile will apply in any case (can be compared to the * wildcard)
  • all configuration files are collectively sorted and processed in lexical order, regardless of the directory in which they live
  • files with identical name replace each other
Tip:
  • To override a system-supplied file in /usr/lib/systemd/network in a permanent manner (i.e even after upgrade), place a file with same name in /etc/systemd/network and symlink it to /dev/null
  • The * wildcard can be used in VALUE (e.g en* will match any Ethernet device), a boolean can be simple written as yes or no.
  • Following this Arch-general thread, the best practice is to setup specific container network settings inside the container with networkd configuration files.
  • Systemd accepts the values 1, true, yes, on for a true boolean, and the values 0, false, no, off for a false boolean

network files

These files are aimed at setting network configuration variables, especially for servers and containers.

.network files have the following sections: [Match], [Link], [Network], [Address], [Route], and [DHCP]. Below are commonly configured keys for each section. See systemd.network(5) for more information and examples.

[Match]

Parameter Description Accepted Values Default Value
Name= Match device names, e.g. en*. By prefixing with !, the list can be inverted. white-space separated device names with globs, logical negation (!)
MACAddress= Match MAC addresses, e.g. MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF whitespace-separated MAC addresses in full colon-, hyphen- or dot-delimited hexadecimal
Host= Match the hostname or machine ID of the host. hostname string with globs, machine ID
Virtualization= Check whether the system is executed in a virtualized environment. Virtualization=false will only match your host machine, while Virtualization=true matches any container or VM. It is possible to check for a specific virtualization type or implementation. boolean, logical negation (!), type (vm, container), implementation (qemu, kvm, zvm, vmware, microsoft, oracle, xen, bochs, uml, bhyve, qnx, openvz, lxc, lxc-libvirt, systemd-nspawn, docker, podman, rkt, wsl, acrn)

[Link]

  • MACAddress= useful for MAC address spoofing
  • MTUBytes= setting a larger MTU value (e.g. when using jumbo frames) can significantly speed up your network transfers
  • Multicast allow the usage of multicast on interface(s)

[Network]

Parameter Description Accepted Values Default Value
DHCP= Controls DHCPv4 and/or DHCPv6 client support. boolean, ipv4, ipv6 false
DHCPServer= If enabled, a DHCPv4 server will be started. boolean false
MulticastDNS= Enables multicast DNS support. When set to resolve, only resolution is enabled, but not host or service registration and announcement. boolean, resolve false
DNSSEC= Controls DNSSEC DNS validation support on the link. When set to allow-downgrade, compatibility with non-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case. boolean, allow-downgrade false
DNS= Configure static DNS addresses. May be specified more than once. inet_pton
Domains= A list of domains which should be resolved using the DNS servers on this link. more information domain name, optionally prefixed with a tilde (~)
IPForward= If enabled, incoming packets on any network interface will be forwarded to any other interfaces according to the routing table. boolean, ipv4, ipv6 false
IPv6PrivacyExtensions= Configures use of stateless temporary addresses that change over time (see RFC 4941). When prefer-public, enables the privacy extensions, but prefers public addresses over temporary addresses. When kernel, the kernel's default setting will be left in place. boolean, prefer-public, kernel false

[Address]

  • Address= this option is mandatory unless DHCP is used

[Route]

  • Gateway= this option is mandatory unless DHCP is used
  • Destination= the destination prefix of the route, possibly followed by a slash and the prefix length

If Destination is not present in [Route] section this section is treated as a default route.

Tip: You can put the Address= and Gateway= keys in the [Network] section as a short-hand if [Address] section contains only an Address key and [Route] section contains only a Gateway key.

[DHCP]

Parameter Description Accepted Values Default Value
UseDNS= controls whether the DNS servers advertised by the DHCP server are used boolean true
Anonymize= when true, the options sent to the DHCP server will follow the RFC7844 (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information boolean false
UseDomains= controls whether the domain name received from the DHCP server will be used as DNS search domain. If set to route, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching. This option can sometimes fix local name resolving when using systemd-resolved boolean, route false

netdev files

These files will create virtual network devices. They have two sections: [Match] and [NetDev]. Below are commonly configured keys for each section. See systemd.netdev(5) for more information and examples.

[Match] section

  • Host= the hostname
  • Virtualization= check if running in a VM

[NetDev] section

Most common keys are:

  • Name= the interface name. mandatory
  • Kind= e.g. bridge, bond, vlan, veth, sit, etc. mandatory

link files

These files are an alternative to custom udev rules and will be applied by udev as the device appears. They have two sections: [Match] and [Link]. Below are commonly configured keys for each section. See systemd.link(5) for more information and examples.

Tip: Use # udevadm test-builtin net_setup_link /sys/path/to/network/device to diagnose problems with .link files.

[Match] section

  • MACAddress= the MAC address
  • Host= the host name
  • Virtualization=
  • Type= the device type e.g. vlan

[Link] section

  • MACAddressPolicy= persistent or random addresses, or
  • MACAddress= a specific address
Note: the system /usr/lib/systemd/network/99-default.link is generally sufficient for most of the basic cases.

Usage with containers

The service is available with systemd. You will want to enable and start the systemd-networkd.service unit on the host and container.

For debugging purposes, it is strongly advised to install the bridge-utils, net-tools, and iproute2 packages.

If you are using systemd-nspawn, you may need to modify the systemd-nspawn@.service and append boot options to the ExecStart line. Please refer to systemd-nspawn(1) for an exhaustive list of options.

Note that if you want to take advantage of automatic DNS configuration from DHCP, you need to enable systemd-resolved and symlink /run/systemd/resolve/resolv.conf to /etc/resolv.conf. See systemd-resolved.service(8) for more details.

Before you start to configure your container network, it is useful to:

  • disable all your netctl (host and container), dhcpcd (host and container), systemd-networkd (container only) and systemd-nspawn@.service (host only) services to avoid potential conflicts and to ease debugging
  • make sure packet forwarding is enabled if you want to let containers access the internet. Make sure that your .network file does not accidentally turn off forwarding because if you do not have a IPForward=1 setting in it, systemd-networkd will turn off forwarding on this interface, even if you have it enabled globally.
  • make sure you do not have any iptables rules which can block traffic
  • when the daemon is started the systemd networkctl command displays the status of network interfaces.

For the set-up described below,

  • we will limit the output of the ip a command to the concerned interfaces
  • we assume the host is your main OS you are booting to and the container is your guest virtual machine
  • all interface names and IP addresses are only examples

Basic DHCP network

This setup will enable a DHCP IP for host and container. In this case, both systems will share the same IP as they share the same interfaces.

/etc/systemd/network/MyDhcp.network
[Match]
Name=en*

[Network]
DHCP=ipv4

Then, enable and start systemd-networkd.service on your container.

You can of course replace en* by the full name of your ethernet device given by the output of the ip link command.

  • on host and container:
$ ip a
2: enp7s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 14:da:e9:b5:7a:88 brd ff:ff:ff:ff:ff:ff
    inet 192.168.1.72/24 brd 192.168.1.255 scope global enp7s0
       valid_lft forever preferred_lft forever
    inet6 fe80::16da:e9ff:feb5:7a88/64 scope link 
       valid_lft forever preferred_lft forever

By default, hostname received from the DHCP server will be used as the transient hostname.

To change it add UseHostname=false in section [DHCPv4]

/etc/systemd/network/MyDhcp.network
[DHCPv4]
UseHostname=false

If you did not want to configure a DNS in /etc/resolv.conf and want to rely on DHCP for setting it up, you need to enable systemd-resolved.service and symlink /run/systemd/resolve/resolv.conf to /etc/resolv.conf

# ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf

See systemd-resolved.service(8) for more details.

Note: Users accessing a system partition via /usr/bin/arch-chroot from arch-install-scripts, will need to create the symlink outside of the chroot, on the mounted partition. This is due to arch-chroot linking the file to the live environment.

DHCP with two distinct IP

Bridge interface

First, create a virtual bridge interface. We tell systemd to create a device named br0 that functions as an ethernet bridge.

/etc/systemd/network/MyBridge.netdev
[NetDev]
Name=br0
Kind=bridge

Restart systemd-networkd.service to have systemd create the bridge.

On host and container:

$ ip a
3: br0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default 
    link/ether ae:bd:35:ea:0c:c9 brd ff:ff:ff:ff:ff:ff

Note that the interface br0 is listed but is still DOWN at this stage.

Bind ethernet to bridge

The next step is to add to the newly created bridge a network interface. In the example below, we add any interface that matches the name en* into the bridge br0.

/etc/systemd/network/bind.network
[Match]
Name=en*

[Network]
Bridge=br0

The ethernet interface must not have DHCP or an IP address associated as the bridge requires an interface to bind to with no IP: modify the corresponding /etc/systemd/network/MyEth.network accordingly to remove the addressing.

Bridge network

Now that the bridge has been created and has been bound to an existing network interface, the IP configuration of the bridge interface must be specified. This is defined in a third .network file, the example below uses DHCP.

/etc/systemd/network/mybridge.network
[Match]
Name=br0

[Network]
DHCP=ipv4

Add option to boot the container

As we want to give a separate IP for host and container, we need to Disconnect networking of the container from the host. To do this, add this option --network-bridge=br0 to your container boot command.

# systemd-nspawn --network-bridge=br0 -bD /path_to/my_container

Result

  • on host
$ ip a
3: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default 
    link/ether 14:da:e9:b5:7a:88 brd ff:ff:ff:ff:ff:ff
    inet 192.168.1.87/24 brd 192.168.1.255 scope global br0
       valid_lft forever preferred_lft forever
    inet6 fe80::16da:e9ff:feb5:7a88/64 scope link 
       valid_lft forever preferred_lft forever
6: vb-MyContainer: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state UP group default qlen 1000
    link/ether d2:7c:97:97:37:25 brd ff:ff:ff:ff:ff:ff
    inet6 fe80::d07c:97ff:fe97:3725/64 scope link 
       valid_lft forever preferred_lft forever
  • on container
$ ip a
2: host0: <BROADCAST,MULTICAST,ALLMULTI,AUTOMEDIA,NOTRAILERS,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
    link/ether 5e:96:85:83:a8:5d brd ff:ff:ff:ff:ff:ff
    inet 192.168.1.73/24 brd 192.168.1.255 scope global host0
       valid_lft forever preferred_lft forever
    inet6 fe80::5c96:85ff:fe83:a85d/64 scope link 
       valid_lft forever preferred_lft forever

Notice

  • we have now one IP address for br0 on the host, and one for host0 in the container
  • two new interfaces have appeared: vb-MyContainer in the host and host0 in the container. This comes as a result of the --network-bridge=br0 option. This option implies another option, --network-veth. This means a virtual Ethernet link has been created between host and container.
  • the DHCP address on host0 comes from the system /usr/lib/systemd/network/80-container-host0.network file.
  • on host
$ brctl show
bridge name	bridge id		STP enabled	interfaces
br0		8000.14dae9b57a88	no		enp7s0
							vb-MyContainer

the above command output confirms we have a bridge with two interfaces binded to.

  • on host
$ ip route
default via 192.168.1.254 dev br0 
192.168.1.0/24 dev br0  proto kernel  scope link  src 192.168.1.87
  • on container
$ ip route
default via 192.168.1.254 dev host0 
192.168.1.0/24 dev host0  proto kernel  scope link  src 192.168.1.73

the above command outputs confirm we have activated br0 and host0 interfaces with an IP address and Gateway 192.168.1.254. The gateway address has been automatically grabbed by systemd-networkd

$ cat /run/systemd/resolve/resolv.conf
nameserver 192.168.1.254

Static IP network

Setting a static IP for each device can be helpful in case of deployed web services (e.g FTP, http, SSH). Each device will keep the same MAC address across reboots if your system /usr/lib/systemd/network/99-default.link file has the MACAddressPolicy=persistent option (it has by default). Thus, you will easily route any service on your Gateway to the desired device.

The following configuration needs to be done for this setup:

  • on host

The configuration is very similar to that of #DHCP with two distinct IP. First, a virtual bridge interface needs to be created and the main physical interface needs to be bound to it. This task can be accomplished with the following two files, with contents equal to those available at the DHCP section.

/etc/systemd/network/MyBridge.netdev
/etc/systemd/network/MyEth.network

Next, you need to configure the IP and DNS of the newly created virtual bridge interface. The following MyBridge.network provides an example configuration:

/etc/systemd/network/MyBridge.network
[Match]
Name=br0

[Network]
DNS=192.168.1.254
Address=192.168.1.87/24
Gateway=192.168.1.254
  • on container

First, we shall get rid of the system /usr/lib/systemd/network/80-container-host0.network file, which provides a DHCP configuration for the default network interface of the container. To do it in a permanent way (e.g. even after systemd upgrades), do the following on the container. This will mask the file /usr/lib/systemd/network/80-container-host0.network since files of the same name in /etc/systemd/network take priority over /usr/lib/systemd/network. Keep in mind that this file can be kept if you only want a static IP on the host, and want the IP address of your containers to be assigned via DHCP.

# ln -sf /dev/null /etc/systemd/network/80-container-host0.network

Then, configure an static IP for the default host0 network interface and enable and start systemd-networkd.service on your container. An example configuration is provided below:

/etc/systemd/network/MyVeth.network
[Match]
Name=host0

[Network]
DNS=192.168.1.254
Address=192.168.1.94/24
Gateway=192.168.1.254

Interface and desktop integration

systemd-networkd does not have a proper interactive management interface neither via command-line nor graphical. Still, some tools are available to either display the current state of the network, receive notifications or interact with the wireless configuration:

  • networkctl (via CLI) offers a simple dump of the network interface states.
  • When networkd is configured with wpa_supplicant, both wpa_cli and wpa_gui offer the ability to associate and configure WLAN interfaces dynamically.
  • networkd-notify-gitAUR can generate simple notifications in response to network interface state changes (such as connection/disconnection and re-association).
  • The networkd-dispatcherAUR daemon allows executing scripts in response to network interface state changes, similar to NetworkManager-dispatcher.
  • As for the DNS resolver systemd-resolved, information about current DNS servers can be visualized with resolvectl status.

Troubleshooting

Mount services at boot fail

If running services like Samba/NFS which fail if they are started before the network is up, you may want to enable the systemd-networkd-wait-online.service. This is, however, rarely necessary because most networked daemons start up okay, even if the network has not been configured yet.

systemd-resolve not searching the local domain

Tango-go-next.pngThis article or section is a candidate for moving to systemd-resolved.Tango-go-next.png

Notes: The problem is with systemd-resolved. (Discuss in Talk:Systemd-networkd#)

systemd-resolved may not search the local domain when given just the hostname, even when UseDomains=yes or Domains=[domain-list] is present in the appropriate .network file, and that file produces the expected search [domain-list] in resolv.conf. You can run networkctl status or resolvectl status to check if the search domains are actually being picked up.

Possible workarounds:

  • Disable LLMNR to let systemd-resolved immediately continue with appending the DNS suffixes
  • Trim /etc/nsswitch.conf's hosts database (e.g., by removing [!UNAVAIL=return] option after resolve service)
  • Switch to using fully-qualified domain names
  • Use /etc/hosts to resolve hostnames
  • Fall back to using glibc's dns instead of using systemd's resolve

Connected second PC unable to use bridged LAN

Tango-go-next.pngThis article or section is a candidate for moving to Network configuration.Tango-go-next.png

Notes: Not specific to systemd-networkd. (Discuss in Talk:Systemd-networkd#)

First PC have two LAN. Second PC have one LAN and connected to first PC. Lets go second PC to give all access to LAN after bridged interface:

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Explain what the settings actually do. (Discuss in Talk:Systemd-networkd#)
# sysctl net.bridge.bridge-nf-filter-pppoe-tagged=0
# sysctl net.bridge.bridge-nf-filter-vlan-tagged=0
# sysctl net.bridge.bridge-nf-call-ip6tables=0
# sysctl net.bridge.bridge-nf-call-iptables=0
# sysctl net.bridge.bridge-nf-call-arptables=0

See also