1SYSTEMD.NETDEV(5) systemd.network SYSTEMD.NETDEV(5)
2
6 systemd.netdev - Virtual Network Device configuration
7
9 netdev.netdev
10
12 Network setup is performed by systemd-networkd(8).
13 Virtual Network Device files must have the extension .netdev; other
15 extensions are ignored. Virtual network devices are created as soon as
16 networkd is started. If a netdev with the specified name already
17 exists, networkd will use that as-is rather than create its own. Note
18 that the settings of the pre-existing netdev will not be changed by
19 networkd.
20 The .netdev files are read from the files located in the system network
22 directory /usr/lib/systemd/network, the volatile runtime network
23 directory /run/systemd/network and the local administration network
24 directory /etc/systemd/network. All configuration files are
25 collectively sorted and processed in lexical order, regardless of the
26 directories in which they live. However, files with identical filenames
27 replace each other. Files in /etc have the highest priority, files in
28 /run take precedence over files with the same name in /usr/lib. This
29 can be used to override a system-supplied configuration file with a
30 local file if needed; a symlink in /etc with the same name as a
31 configuration file in /usr/lib, pointing to /dev/null, disables the
32 configuration file entirely.
33
35 The following kinds of virtual network devices may be configured in
36 .netdev files:
37 Table 1. Supported kinds of virtual network devices
39 ┌──────────┬────────────────────────────┐
40 │Kind │ Description │
41 ├──────────┼────────────────────────────┤
42 │bond │ A bond device is an │
43 │ │ aggregation of all its │
44 │ │ slave devices. See Linux │
45 │ │ Ethernet Bonding Driver │
46 │ │ HOWTO[1] for details.Local │
47 │ │ configuration │
48 ├──────────┼────────────────────────────┤
49 │bridge │ A bridge device is a │
50 │ │ software switch, each of │
51 │ │ its slave devices and the │
52 │ │ bridge itself are ports of │
53 │ │ the switch. │
54 ├──────────┼────────────────────────────┤
55 │dummy │ A dummy device drops all │
56 │ │ packets sent to it. │
57 ├──────────┼────────────────────────────┤
58 │gre │ A Level 3 GRE tunnel over │
59 │ │ IPv4. See RFC 2784[2] for │
60 │ │ details. │
61 ├──────────┼────────────────────────────┤
62 │gretap │ A Level 2 GRE tunnel over │
63 │ │ IPv4. │
64 ├──────────┼────────────────────────────┤
65 │ip6gre │ A Level 3 GRE tunnel over │
66 │ │ IPv6. │
67 ├──────────┼────────────────────────────┤
68 │ip6tnl │ An IPv4 or IPv6 tunnel │
69 │ │ over IPv6 │
70 ├──────────┼────────────────────────────┤
71 │ip6gretap │ An Level 2 GRE tunnel over │
72 │ │ IPv6. │
73 ├──────────┼────────────────────────────┤
74 │ipip │ An IPv4 over IPv4 tunnel. │
75 ├──────────┼────────────────────────────┤
76 │ipvlan │ An ipvlan device is a │
77 │ │ stacked device which │
78 │ │ receives packets from its │
79 │ │ underlying device based on │
80 │ │ IP address filtering. │
81 ├──────────┼────────────────────────────┤
82 │macvlan │ A macvlan device is a │
83 │ │ stacked device which │
84 │ │ receives packets from its │
85 │ │ underlying device based on │
86 │ │ MAC address filtering. │
87 ├──────────┼────────────────────────────┤
88 │sit │ An IPv6 over IPv4 tunnel. │
89 ├──────────┼────────────────────────────┤
90 │tap │ A persistent Level 2 │
91 │ │ tunnel between a network │
92 │ │ device and a device node. │
93 ├──────────┼────────────────────────────┤
94 │tun │ A persistent Level 3 │
95 │ │ tunnel between a network │
96 │ │ device and a device node. │
97 ├──────────┼────────────────────────────┤
98 │veth │ An ethernet tunnel between │
99 │ │ a pair of network devices. │
100 ├──────────┼────────────────────────────┤
101 │vlan │ A VLAN is a stacked device │
102 │ │ which receives packets │
103 │ │ from its underlying device │
104 │ │ based on VLAN tagging. See │
105 │ │ IEEE 802.1Q[3] for │
106 │ │ details. │
107 ├──────────┼────────────────────────────┤
108 │vti │ An IPv4 over IPSec tunnel. │
109 ├──────────┼────────────────────────────┤
110 │vxlan │ A virtual extensible LAN │
111 │ │ (vxlan), for connecting │
112 │ │ Cloud computing │
113 │ │ deployments. │
114 └──────────┴────────────────────────────┘
115
117 A virtual network device is only created if the "[Match]" section
118 matches the current environment, or if the section is empty. The
119 following keys are accepted:
120 Host=
122 Matches against the hostname or machine ID of the host. See
123 "ConditionHost=" in systemd.unit(5) for details.
124 Virtualization=
126 Checks whether the system is executed in a virtualized environment
127 and optionally test whether it is a specific implementation. See
128 "ConditionVirtualization=" in systemd.unit(5) for details.
129 KernelCommandLine=
131 Checks whether a specific kernel command line option is set (or if
132 prefixed with the exclamation mark unset). See
133 "ConditionKernelCommandLine=" in systemd.unit(5) for details.
134 Architecture=
136 Checks whether the system is running on a specific architecture.
137 See "ConditionArchitecture=" in systemd.unit(5) for details.
138
140 The "[NetDev]" section accepts the following keys:
141 Description=
143 A free-form description of the netdev.
144 Name=
146 The interface name used when creating the netdev. This option is
147 compulsory.
148 Kind=
150 The netdev kind. This option is compulsory. See the "Supported
151 netdev kinds" section for the valid keys.
152 MTUBytes=
154 The maximum transmission unit in bytes to set for the device. The
155 usual suffixes K, M, G, are supported and are understood to the
156 base of 1024. This key is not currently suported for "tun" or "tap"
157 devices.
158 MACAddress=
160 The MAC address to use for the device. If none is given, one is
161 generated based on the interface name and the machine-id(5). This
162 key is not currently suported for "tun" or "tap" devices.
163
165 The "[VLAN]" section only applies for netdevs of kind "vlan", and
166 accepts the following key:
167 Id=
169 The VLAN ID to use. An integer in the range 0–4094. This option is
170 compulsory.
171
173 The "[MACVLAN]" section only applies for netdevs of kind "macvlan", and
174 accepts the following key:
175 Mode=
177 The MACVLAN mode to use. The supported options are "private",
178 "vepa", "bridge", and "passthru".
179
181 The "[IPVLAN]" section only applies for netdevs of kind "ipvlan", and
182 accepts the following key:
183 Mode=
185 The IPVLAN mode to use. The supported options are "L2" and "L3".
186
188 The "[VXLAN]" section only applies for netdevs of kind "vxlan", and
189 accepts the following keys:
190 Id=
192 The VXLAN ID to use.
193 Group=
195 An assigned multicast group IP address.
196 TOS=
198 The Type Of Service byte value for a vxlan interface.
199 TTL=
201 A fixed Time To Live N on Virtual eXtensible Local Area Network
202 packets. N is a number in the range 1-255. 0 is a special value
203 meaning that packets inherit the TTL value.
204 MacLearning=
206 A boolean. When true, enables dynamic MAC learning to discover
207 remote MAC addresses.
208 FDBAgeingSec=
210 The lifetime of Forwarding Database entry learnt by the kernel in
211 seconds.
212 ARPProxy=
214 A boolean. When true, enables ARP proxy.
215 L2MissNotification=
217 A boolean. When true, enables netlink LLADDR miss notifications.
218 L3MissNotification=
220 A boolean. When true, enables netlink IP ADDR miss notifications.
221 RouteShortCircuit=
223 A boolean. When true route short circuit is turned on.
224
226 The "[Tunnel]" section only applies for netdevs of kind "ipip", "sit",
227 "gre", "gretap", "ip6gre", "ip6gretap", "vti", and "ip6tnl" and accepts
228 the following keys:
229 Local=
231 A static local address for tunneled packets. It must be an address
232 on another interface of this host.
233 Remote=
235 The remote endpoint of the tunnel.
236 TOS=
238 The Type Of Service byte value for a tunnel interface. For details
239 about the TOS see the Type of Service in the Internet Protocol
240 Suite[4] document.
241 TTL=
243 A fixed Time To Live N on tunneled packets. N is a number in the
244 range 1-255. 0 is a special value meaning that packets inherit the
245 TTL value. The default value for IPv4 tunnels is: inherit. The
246 default value for IPv6 tunnels is: 64.
247 DiscoverPathMTU=
249 A boolean. When true, enables Path MTU Discovery on the tunnel.
250 Mode=
252 An "ip6tnl" tunnels can have three modes "ip6ip6" for IPv6 over
253 IPv6, "ipip6" for IPv4 over IPv6 or "any" for either.
254
256 The "[Peer]" section only applies for netdevs of kind "veth" and
257 accepts the following key:
258 Name=
260 The interface name used when creating the netdev. This option is
261 compulsory.
262 MACAddress=
264 The peer MACAddress, if not set it is generated in the same way as
265 the MAC address of the main interface.
266
268 The "[Tun]" section only applies for netdevs of kind "tun", and accepts
269 the following keys:
270 OneQueue=
272 Takes a boolean argument. Configures whether all packets are queued
273 at the device (enabled), or a fixed number of packets are queued at
274 the device and the rest at the "qdisc". Defaults to "no".
275 MultiQueue=
277 Takes a boolean argument. Configures whether to use multiple file
278 descriptors (queues) to parallelize packets sending and receiving.
279 Defaults to "no".
280 PacketInfo=
282 Takes a boolean argument. Configures whether packets should be
283 prepened with four extra bytes (two flag bytes and two protocol
284 bytes). If disabled it indicates that the packets will be pure IP
285 packets. Defaults to "no".
286 User=
288 User to grant access to the /dev/net/tun device.
289 Group=
291 Group to grant access to the /dev/net/tun device.
292
294 The "[Tap]" section only applies for netdevs of kind "tap", and accepts
295 the same keys as the "[Tun]" section.
296
298 The "[Bond]" section accepts the following key:
299 Mode=
301 Specifies one of the bonding policies. The default is "balance-rr"
302 (round robin). Possible values are "balance-rr", "active-backup",
303 "balance-xor", "broadcast", "802.3ad", "balance-tlb", and
304 "balance-alb".
305 TransmitHashPolicy=
307 Selects the transmit hash policy to use for slave selection in
308 balance-xor, 802.3ad, and tlb modes. Possible values are "layer2",
309 "layer3+4", "layer2+3", "encap2+3", "802.3ad", and "encap3+4".
310 LACPTransmitRate=
312 Specifies the rate with which link partner transmits Link
313 Aggregation Control Protocol Data Unit packets in 802.3ad mode.
314 Possible values are "slow", which requests partner to transmit
315 LACPDUs every 30 seconds, and "fast", which requests partner to
316 transmit LACPDUs every second. The default value is "slow".
317 MIIMonitorSec=
319 Specifies the frequency that Media Independent Interface link
320 monitoring will occur. A value of zero disables MII link
321 monitoring. This values is rounded down to the nearest millisecond.
322 The default value is 0.
323 UpDelaySec=
325 Specifies the delay before a link is enabled after a link up status
326 has been detected. This value is rounded down to a multiple of
327 MIIMonitorSec. The default value is 0.
328 DownDelaySec=
330 Specifies the delay before a link is disabled after a link down
331 status has been detected. This value is rounded down to a multiple
332 of MIIMonitorSec. The default value is 0.
333
335 Example 1. /etc/systemd/network/bridge.netdev
336 [NetDev]
338 Name=bridge0
339 Kind=bridge
340 Example 2. /etc/systemd/network/vlan1.netdev
342 [Match]
344 Virtualization=no
345 [NetDev]
347 Name=vlan1
348 Kind=vlan
349 [VLAN]
351 Id=1
352 Example 3. /etc/systemd/network/ipip.netdev
354 [NetDev]
356 Name=ipip-tun
357 Kind=ipip
358 MTUBytes=1480
359 [Tunnel]
361 Local=192.168.223.238
362 Remote=192.169.224.239
363 TTL=64
364 Example 4. /etc/systemd/network/tap.netdev
366 [NetDev]
368 Name=tap-test
369 Kind=tap
370 [Tap]
372 MultiQueue=true
373 PacketInfo=true
374 Example 5. /etc/systemd/network/sit.netdev
376 [NetDev]
378 Name=sit-tun
379 Kind=sit
380 MTUBytes=1480
381 [Tunnel]
383 Local=10.65.223.238
384 Remote=10.65.223.239
385 Example 6. /etc/systemd/network/gre.netdev
387 [NetDev]
389 Name=gre-tun
390 Kind=gre
391 MTUBytes=1480
392 [Tunnel]
394 Local=10.65.223.238
395 Remote=10.65.223.239
396 Example 7. /etc/systemd/network/vti.netdev
398 [NetDev]
400 Name=vti-tun
401 Kind=vti
402 MTUBytes=1480
403 [Tunnel]
405 Local=10.65.223.238
406 Remote=10.65.223.239
407 Example 8. /etc/systemd/network/veth.netdev
409 [NetDev]
411 Name=veth-test
412 Kind=veth
413 [Peer]
415 Name=veth-peer
416 Example 9. /etc/systemd/network/dummy.netdev
418 [NetDev]
420 Name=dummy-test
421 Kind=dummy
422 MACAddress=12:34:56:78:9a:bc
423
425 systemd(1), systemd-networkd(8), systemd.link(5), systemd.network(5)
426
428 1. Linux Ethernet Bonding Driver HOWTO
429 https://www.kernel.org/doc/Documentation/networking/bonding.txt
430 2. RFC 2784
432 https://tools.ietf.org/html/rfc2784
433 3. IEEE 802.1Q
435 http://www.ieee802.org/1/pages/802.1Q.html
436 4. Type of Service in the Internet Protocol Suite
438 http://tools.ietf.org/html/rfc1349
439systemd 219 SYSTEMD.NETDEV(5)