1netplan(5) netplan(5)
2
6 netplan - YAML network configuration abstraction for various backends
7
9 netplan [ COMMAND | help ]
10
12 See netplan help for a list of available commands on this system.
13
15 Introduction
16 Distribution installers, cloud instantiation, image builds for particu‐
17 lar devices, or any other way to deploy an operating system put its de‐
18 sired network configuration into YAML configuration file(s). During
19 early boot, the netplan “network renderer” runs which reads
20 /{lib,etc,run}/netplan/*.yaml and writes configuration to /run to hand
21 off control of devices to the specified networking daemon.
22 • Configured devices get handled by systemd-networkd by default, unless
24 explicitly marked as managed by a specific renderer (NetworkManager)
25 • Devices not covered by the network config do not get touched at all.
27 • Usable in initramfs (few dependencies and fast)
29 • No persistent generated config, only original YAML config
31 • Parser supports multiple config files to allow applications like lib‐
33 virt or lxd to package up expected network config (virbr0, lxdbr0),
34 or to change the global default policy to use NetworkManager for ev‐
35 erything.
36 • Retains the flexibility to change backends/policy later or adjust to
38 removing NetworkManager, as generated configuration is ephemeral.
39 General structure
41 netplan’s configuration files use the YAML
42 (http://yaml.org/spec/1.1/current.html) format. All
43 /{lib,etc,run}/netplan/*.yaml are considered. Lexicographically later
44 files (regardless of in which directory they are) amend (new mapping
45 keys) or override (same mapping keys) previous ones. A file in
46 /run/netplan completely shadows a file with same name in /etc/netplan,
47 and a file in either of those directories shadows a file with the same
48 name in /lib/netplan.
49 The top-level node in a netplan configuration file is a network: map‐
51 ping that contains version: 2 (the YAML currently being used by curtin,
52 MaaS, etc. is version 1), and then device definitions grouped by their
53 type, such as ethernets:, modems:, wifis:, or bridges:. These are the
54 types that our renderer can understand and are supported by our back‐
55 ends.
56 Each type block contains device definitions as a map where the keys
58 (called “configuration IDs”) are defined as below.
59 Device configuration IDs
61 The key names below the per-device-type definition maps (like ether‐
62 nets:) are called “ID”s. They must be unique throughout the entire set
63 of configuration files. Their primary purpose is to serve as anchor
64 names for composite devices, for example to enumerate the members of a
65 bridge that is currently being defined.
66 (Since 0.97) If an interface is defined with an ID in a configuration
68 file; it will be brought up by the applicable renderer. To not have
69 netplan touch an interface at all, it should be completely omitted from
70 the netplan configuration files.
71 There are two physically/structurally different classes of device defi‐
73 nitions, and the ID field has a different interpretation for each:
74 Physical devices
76 (Examples: ethernet, modem, wifi) These can dynamically come and
77 go between reboots and even during runtime (hotplugging). In
78 the generic case, they can be selected by match: rules on de‐
79 sired properties, such as name/name pattern, MAC address, driv‐
80 er, or device paths. In general these will match any number of
81 devices (unless they refer to properties which are unique such
82 as the full path or MAC address), so without further knowledge
83 about the hardware these will always be considered as a group.
84 It is valid to specify no match rules at all, in which case the
86 ID field is simply the interface name to be matched. This is
87 mostly useful if you want to keep simple cases simple, and it’s
88 how network device configuration has been done for a long time.
89 If there are match: rules, then the ID field is a purely opaque
91 name which is only being used for references from definitions of
92 compound devices in the config.
93 Virtual devices
95 (Examples: veth, bridge, bond) These are fully under the control
96 of the config file(s) and the network stack. I. e. these de‐
97 vices are being created instead of matched. Thus match: and
98 set-name: are not applicable for these, and the ID field is the
99 name of the created virtual device.
100 Common properties for physical device types
102 match (mapping)
103 This selects a subset of available physical devices by various
104 hardware properties. The following configuration will then ap‐
105 ply to all matching devices, as soon as they appear. All speci‐
106 fied properties must match.
107 name (scalar)
109 Current interface name. Globs are supported, and the
110 primary use case for matching on names, as selecting one
111 fixed name can be more easily achieved with having no
112 match: at all and just using the ID (see above). (Net‐
113 workManager: as of v1.14.0)
114 macaddress (scalar)
116 Device’s MAC address in the form “XX:XX:XX:XX:XX:XX”.
117 Globs are not allowed.
118 driver (scalar or sequence of scalars) – sequence since 0.104
120 Kernel driver name, corresponding to the DRIVER udev
121 property. A sequence of globs is supported, any of which
122 must match. Matching on driver is only supported with
123 networkd.
124 Examples:
126 • all cards on second PCI bus:
128 match:
130 name: enp2*
131 • fixed MAC address:
133 match:
135 macaddress: 11:22:33:AA:BB:FF
136 • first card of driver ixgbe:
138 match:
140 driver: ixgbe
141 name: en*s0
142 • first card with a driver matching bcmgenet or smsc*:
144 match:
146 driver: ["bcmgenet", "smsc*"]
147 name: en*
148 set-name (scalar)
150 When matching on unique properties such as path or MAC, or with
151 additional assumptions such as “there will only ever be one wifi
152 device”, match rules can be written so that they only match one
153 device. Then this property can be used to give that device a
154 more specific/desirable/nicer name than the default from udev’s
155 ifnames. Any additional device that satisfies the match rules
156 will then fail to get renamed and keep the original kernel name
157 (and dmesg will show an error).
158 wakeonlan (bool)
160 Enable wake on LAN. Off by default.
161 Note: This will not work reliably for devices matched by name
163 only and rendered by networkd, due to interactions with device
164 renaming in udev. Match devices by MAC when setting wake on
165 LAN.
166 emit-lldp (bool) – since 0.99
168 (networkd backend only) Whether to emit LLDP packets. Off by
169 default.
170 receive-checksum-offload (bool) – since 0.104
172 (networkd backend only) If set to true, the hardware offload for
173 checksumming of ingress network packets is enabled. When unset,
174 the kernel’s default will be used.
175 transmit-checksum-offload (bool) – since 0.104
177 (networkd backend only) If set to true, the hardware offload for
178 checksumming of egress network packets is enabled. When unset,
179 the kernel’s default will be used.
180 tcp-segmentation-offload (bool) – since 0.104
182 (networkd backend only) If set to true, the TCP Segmentation
183 Offload (TSO) is enabled. When unset, the kernel’s default will
184 be used.
185 tcp6-segmentation-offload (bool) – since 0.104
187 (networkd backend only) If set to true, the TCP6 Segmentation
188 Offload (tx-tcp6-segmentation) is enabled. When unset, the ker‐
189 nel’s default will be used.
190 generic-segmentation-offload (bool) – since 0.104
192 (networkd backend only) If set to true, the Generic Segmentation
193 Offload (GSO) is enabled. When unset, the kernel’s default will
194 be used.
195 generic-receive-offload (bool) – since 0.104
197 (networkd backend only) If set to true, the Generic Receive Off‐
198 load (GRO) is enabled. When unset, the kernel’s default will be
199 used.
200 large-receive-offload (bool) – since 0.104
202 (networkd backend only) If set to true, the Generic Receive Off‐
203 load (GRO) is enabled. When unset, the kernel’s default will be
204 used.
205 openvswitch (mapping) – since 0.100
207 This provides additional configuration for the network device
208 for openvswitch. If openvswitch is not available on the system,
209 netplan treats the presence of openvswitch configuration as an
210 error.
211 Any supported network device that is declared with the open‐
213 vswitch mapping (or any bond/bridge that includes an interface
214 with an openvswitch configuration) will be created in open‐
215 vswitch instead of the defined renderer. In the case of a vlan
216 definition declared the same way, netplan will create a fake
217 VLAN bridge in openvswitch with the requested vlan properties.
218 external-ids (mapping) – since 0.100
220 Passed-through directly to OpenVSwitch
221 other-config (mapping) – since 0.100
223 Passed-through directly to OpenVSwitch
224 lacp (scalar) – since 0.100
226 Valid for bond interfaces. Accepts active, passive or
227 off (the default).
228 fail-mode (scalar) – since 0.100
230 Valid for bridge interfaces. Accepts secure or stand‐
231 alone (the default).
232 mcast-snooping (bool) – since 0.100
234 Valid for bridge interfaces. False by default.
235 protocols (sequence of scalars) – since 0.100
237 Valid for bridge interfaces or the network section. List
238 of protocols to be used when negotiating a connection
239 with the controller. Accepts OpenFlow10, OpenFlow11,
240 OpenFlow12, OpenFlow13, OpenFlow14, OpenFlow15 and Open‐
241 Flow16.
242 rstp (bool) – since 0.100
244 Valid for bridge interfaces. False by default.
245 controller (mapping) – since 0.100
247 Valid for bridge interfaces. Specify an external Open‐
248 Flow controller.
249 addresses (sequence of scalars)
251 Set the list of addresses to use for the con‐
252 troller targets. The syntax of these addresses is
253 as defined in ovs-vsctl(8). Example: addresses:
254 [tcp:127.0.0.1:6653, "ssl:[fe80::1234%eth0]:6653"]
255 connection-mode (scalar)
257 Set the connection mode for the controller. Sup‐
258 ported options are in-band and out-of-band. The
259 default is in-band.
260 ports (sequence of sequence of scalars) – since 0.100
262 OpenvSwitch patch ports. Each port is declared as a pair
263 of names which can be referenced as interfaces in depen‐
264 dent virtual devices (bonds, bridges).
265 Example:
267 openvswitch:
269 ports:
270 - [patch0-1, patch1-0]
271 ssl (mapping) – since 0.100
273 Valid for global openvswitch settings. Options for con‐
274 figuring SSL server endpoint for the switch.
275 ca-cert (scalar)
277 Path to a file containing the CA certificate to be
278 used.
279 certificate (scalar)
281 Path to a file containing the server certificate.
282 private-key (scalar)
284 Path to a file containing the private key for the
285 server.
286 Common properties for all device types
288 renderer (scalar)
289 Use the given networking backend for this definition. Currently
290 supported are networkd and NetworkManager. This property can be
291 specified globally in network:, for a device type (in e. g.
292 ethernets:) or for a particular device definition. Default is
293 networkd.
294 (Since 0.99) The renderer property has one additional acceptable
296 value for vlan objects (i. e. defined in vlans:): sriov. If a
297 vlan is defined with the sriov renderer for an SR-IOV Virtual
298 Function interface, this causes netplan to set up a hardware
299 VLAN filter for it. There can be only one defined per VF.
300 dhcp4 (bool)
302 Enable DHCP for IPv4. Off by default.
303 dhcp6 (bool)
305 Enable DHCP for IPv6. Off by default. This covers both state‐
306 less DHCP - where the DHCP server supplies information like DNS
307 nameservers but not the IP address - and stateful DHCP, where
308 the server provides both the address and the other information.
309 If you are in an IPv6-only environment with completely stateless
311 autoconfiguration (SLAAC with RDNSS), this option can be set to
312 cause the interface to be brought up. (Setting accept-ra alone
313 is not sufficient.) Autoconfiguration will still honour the con‐
314 tents of the router advertisement and only use DHCP if requested
315 in the RA.
316 Note that rdnssd(8) is required to use RDNSS with networkd. No
318 extra software is required for NetworkManager.
319 ipv6-mtu (scalar) – since 0.98
321 Set the IPv6 MTU (only supported with networkd backend). Note
322 that needing to set this is an unusual requirement.
323 Requires feature: ipv6-mtu
325 ipv6-privacy (bool)
327 Enable IPv6 Privacy Extensions (RFC 4941) for the specified in‐
328 terface, and prefer temporary addresses. Defaults to false - no
329 privacy extensions. There is currently no way to have a private
330 address but prefer the public address.
331 link-local (sequence of scalars)
333 Configure the link-local addresses to bring up. Valid options
334 are `ipv4' and `ipv6', which respectively allow enabling IPv4
335 and IPv6 link local addressing. If this field is not defined,
336 the default is to enable only IPv6 link-local addresses. If the
337 field is defined but configured as an empty set, IPv6 link-local
338 addresses are disabled as well as IPv4 link- local addresses.
339 This feature enables or disables link-local addresses for a pro‐
341 tocol, but the actual implementation differs per backend. On
342 networkd, this directly changes the behavior and may add an ex‐
343 tra address on an interface. When using the NetworkManager
344 backend, enabling link-local has no effect if the interface also
345 has DHCP enabled.
346 Example to enable only IPv4 link-local: link-local: [ ipv4 ] Ex‐
348 ample to enable all link-local addresses: link-local: [ ipv4,
349 ipv6 ] Example to disable all link-local addresses: link-local:
350 [ ]
351 ignore-carrier (bool) – since 0.104
353 (networkd backend only) Allow the specified interface to be con‐
354 figured even if it has no carrier.
355 critical (bool)
357 Designate the connection as “critical to the system”, meaning
358 that special care will be taken by to not release the assigned
359 IP when the daemon is restarted. (not recognized by NetworkMan‐
360 ager)
361 dhcp-identifier (scalar)
363 (networkd backend only) Sets the source of DHCPv4 client identi‐
364 fier. If mac is specified, the MAC address of the link is used.
365 If this option is omitted, or if duid is specified, networkd
366 will generate an RFC4361-compliant client identifier for the in‐
367 terface by combining the link’s IAID and DUID.
368 dhcp4-overrides (mapping)
370 (networkd backend only) Overrides default DHCP behavior; see the
371 DHCP Overrides section below.
372 dhcp6-overrides (mapping)
374 (networkd backend only) Overrides default DHCP behavior; see the
375 DHCP Overrides section below.
376 accept-ra (bool)
378 Accept Router Advertisement that would have the kernel configure
379 IPv6 by itself. When enabled, accept Router Advertisements.
380 When disabled, do not respond to Router Advertisements. If un‐
381 set use the host kernel default setting.
382 addresses (sequence of scalars and mappings)
384 Add static addresses to the interface in addition to the ones
385 received through DHCP or RA. Each sequence entry is in CIDR no‐
386 tation, i. e. of the form addr/prefixlen. addr is an IPv4 or
387 IPv6 address as recognized by inet_pton(3) and prefixlen the
388 number of bits of the subnet.
389 For virtual devices (bridges, bonds, vlan) if there is no ad‐
391 dress configured and DHCP is disabled, the interface may still
392 be brought online, but will not be addressable from the network.
393 In addition to the addresses themselves one can specify configu‐
395 ration parameters as mappings. Current supported options are:
396 lifetime (scalar) – since 0.100
398 Default: forever. This can be forever or 0 and corre‐
399 sponds to the PreferredLifetime option in systemd-net‐
400 workd’s Address section. Currently supported on the net‐
401 workd backend only.
402 label (scalar) – since 0.100
404 An IP address label, equivalent to the ip address label
405 command. Currently supported on the networkd backend on‐
406 ly.
407 Example: addresses: [192.168.14.2/24, "2001:1::1/64"]
409 Example:
411 ethernets:
413 eth0:
414 addresses:
415 - 10.0.0.15/24:
416 lifetime: 0
417 label: "maas"
418 - "2001:1::1/64"
419 ipv6-address-generation (scalar) – since 0.99
421 Configure method for creating the address for use with RFC4862
422 IPv6 Stateless Address Autoconfiguration (only supported with
423 NetworkManager backend). Possible values are eui64 or stable-
424 privacy.
425 ipv6-address-token (scalar) – since 0.100
427 Define an IPv6 address token for creating a static interface
428 identifier for IPv6 Stateless Address Autoconfiguration. This
429 is mutually exclusive with ipv6-address-generation.
430 gateway4, gateway6 (scalar)
432 Deprecated, see Default routes. Set default gateway for IPv4/6,
433 for manual address configuration. This requires setting ad‐
434 dresses too. Gateway IPs must be in a form recognized by in‐
435 et_pton(3). There should only be a single gateway per IP ad‐
436 dress family set in your global config, to make it unambiguous.
437 If you need multiple default routes, please define them via
438 routing-policy.
439 Example for IPv4: gateway4: 172.16.0.1 Example for IPv6: gate‐
441 way6: "2001:4::1"
442 nameservers (mapping)
444 Set DNS servers and search domains, for manual address configu‐
445 ration. There are two supported fields: addresses: is a list of
446 IPv4 or IPv6 addresses similar to gateway*, and search: is a
447 list of search domains.
448 Example:
450 ethernets:
452 id0:
453 [...]
454 nameservers:
455 search: [lab, home]
456 addresses: [8.8.8.8, "FEDC::1"]
457 macaddress (scalar)
459 Set the device’s MAC address. The MAC address must be in the
460 form “XX:XX:XX:XX:XX:XX”.
461 Note: This will not work reliably for devices matched by name
463 only and rendered by networkd, due to interactions with device
464 renaming in udev. Match devices by MAC when setting MAC ad‐
465 dresses.
466 Example:
468 ethernets:
470 id0:
471 match:
472 macaddress: 52:54:00:6b:3c:58
473 [...]
474 macaddress: 52:54:00:6b:3c:59
475 mtu (scalar)
477 Set the Maximum Transmission Unit for the interface. The de‐
478 fault is 1500. Valid values depend on your network interface.
479 Note: This will not work reliably for devices matched by name
481 only and rendered by networkd, due to interactions with device
482 renaming in udev. Match devices by MAC when setting MTU.
483 optional (bool)
485 An optional device is not required for booting. Normally, net‐
486 workd will wait some time for device to become configured before
487 proceeding with booting. However, if a device is marked as op‐
488 tional, networkd will not wait for it. This is only supported
489 by networkd, and the default is false.
490 Example:
492 ethernets:
494 eth7:
495 # this is plugged into a test network that is often
496 # down - don't wait for it to come up during boot.
497 dhcp4: true
498 optional: true
499 optional-addresses (sequence of scalars)
501 Specify types of addresses that are not required for a device to
502 be considered online. This changes the behavior of backends at
503 boot time to avoid waiting for addresses that are marked option‐
504 al, and thus consider the interface as “usable” sooner. This
505 does not disable these addresses, which will be brought up any‐
506 way.
507 Example:
509 ethernets:
511 eth7:
512 dhcp4: true
513 dhcp6: true
514 optional-addresses: [ ipv4-ll, dhcp6 ]
515 activation-mode (scalar) – since 0.103
517 Allows specifying the management policy of the selected inter‐
518 face. By default, netplan brings up any configured interface if
519 possible. Using the activation-mode setting users can override
520 that behavior by either specifying manual, to hand over control
521 over the interface state to the administrator or (for networkd
522 backend only) off to force the link in a down state at all
523 times. Any interface with activation-mode defined is implicitly
524 considered optional. Supported officially as of networkd v248+.
525 Example:
527 ethernets:
529 eth1:
530 # this interface will not be put into an UP state automatically
531 dhcp4: true
532 activation-mode: manual
533 routes (sequence of mappings)
535 Configure static routing for the device; see the Routing section
536 below.
537 routing-policy (sequence of mappings)
539 Configure policy routing for the device; see the Routing section
540 below.
541 DHCP Overrides
543 Several DHCP behavior overrides are available. Most currently only
544 have any effect when using the networkd backend, with the exception of
545 use-routes and route-metric.
546 Overrides only have an effect if the corresponding dhcp4 or dhcp6 is
548 set to true.
549 If both dhcp4 and dhcp6 are true, the networkd backend requires that
551 dhcp4-overrides and dhcp6-overrides contain the same keys and values.
552 If the values do not match, an error will be shown and the network con‐
553 figuration will not be applied.
554 When using the NetworkManager backend, different values may be speci‐
556 fied for dhcp4-overrides and dhcp6-overrides, and will be applied to
557 the DHCP client processes as specified in the netplan YAML.
558 dhcp4-overrides, dhcp6-overrides (mapping)
560 The dhcp4-overrides and dhcp6-overrides mappings override the
561 default DHCP behavior.
562 use-dns (bool)
564 Default: true. When true, the DNS servers received from
565 the DHCP server will be used and take precedence over any
566 statically configured ones. Currently only has an effect
567 on the networkd backend.
568 use-ntp (bool)
570 Default: true. When true, the NTP servers received from
571 the DHCP server will be used by systemd-timesyncd and
572 take precedence over any statically configured ones.
573 Currently only has an effect on the networkd backend.
574 send-hostname (bool)
576 Default: true. When true, the machine’s hostname will be
577 sent to the DHCP server. Currently only has an effect on
578 the networkd backend.
579 use-hostname (bool)
581 Default: true. When true, the hostname received from the
582 DHCP server will be set as the transient hostname of the
583 system. Currently only has an effect on the networkd
584 backend.
585 use-mtu (bool)
587 Default: true. When true, the MTU received from the DHCP
588 server will be set as the MTU of the network interface.
589 When false, the MTU advertised by the DHCP server will be
590 ignored. Currently only has an effect on the networkd
591 backend.
592 hostname (scalar)
594 Use this value for the hostname which is sent to the DHCP
595 server, instead of machine’s hostname. Currently only
596 has an effect on the networkd backend.
597 use-routes (bool)
599 Default: true. When true, the routes received from the
600 DHCP server will be installed in the routing table nor‐
601 mally. When set to false, routes from the DHCP server
602 will be ignored: in this case, the user is responsible
603 for adding static routes if necessary for correct network
604 operation. This allows users to avoid installing a de‐
605 fault gateway for interfaces configured via DHCP. Avail‐
606 able for both the networkd and NetworkManager backends.
607 route-metric (scalar)
609 Use this value for default metric for automatically-added
610 routes. Use this to prioritize routes for devices by
611 setting a lower metric on a preferred interface. Avail‐
612 able for both the networkd and NetworkManager backends.
613 use-domains (scalar) – since 0.98
615 Takes a boolean, or the special value “route”. When
616 true, the domain name received from the DHCP server will
617 be used as DNS search domain over this link, similar to
618 the effect of the Domains= setting. If set to “route”,
619 the domain name received from the DHCP server will be
620 used for routing DNS queries only, but not for searching,
621 similar to the effect of the Domains= setting when the
622 argument is prefixed with “~”.
623 Requires feature: dhcp-use-domains
625 Routing
627 Complex routing is possible with netplan. Standard static routes as
628 well as policy routing using routing tables are supported via the net‐
629 workd backend.
630 These options are available for all types of interfaces.
632 Default routes
634 The most common need for routing concerns the definition of default
635 routes to reach the wider Internet. Those default routes can only de‐
636 fined once per IP family and routing table. A typical example would
637 look like the following:
638 eth0:
640 [...]
641 routes:
642 - to: default # could be 0/0 or 0.0.0.0/0 optionally
643 via: 10.0.0.1
644 metric: 100
645 on-link: true
646 - to: default # could be ::/0 optionally
647 via: cf02:de:ad:be:ef::2
648 eth1:
649 [...]
650 routes:
651 - to: default
652 via: 172.134.67.1
653 metric: 100
654 on-link: true
655 table: 76 # Not on the main routing table, does not conflict with the eth0 default route
656 routes (mapping)
658 The routes block defines standard static routes for an inter‐
659 face. At least to must be specified. If type is local or nat a
660 default scope of host is assumed. If type is unicast and no
661 gateway (via) is given or type is broadcast, multicast or any‐
662 cast a default scope of link is assumend. Otherwise, a global
663 scope is the default setting.
664 For from, to, and via, both IPv4 and IPv6 addresses are recog‐
666 nized, and must be in the form addr/prefixlen or addr.
667 from (scalar)
669 Set a source IP address for traffic going through the
670 route. (NetworkManager: as of v1.8.0)
671 to (scalar)
673 Destination address for the route.
674 via (scalar)
676 Address to the gateway to use for this route.
677 on-link (bool)
679 When set to “true”, specifies that the route is directly
680 connected to the interface. (NetworkManager: as of
681 v1.12.0 for IPv4 and v1.18.0 for IPv6)
682 metric (scalar)
684 The relative priority of the route. Must be a positive
685 integer value.
686 type (scalar)
688 The type of route. Valid options are “unicast” (de‐
689 fault), “anycast”, “blackhole”, “broadcast”, “local”,
690 “multicast”, “nat”, “prohibit”, “throw”, “unreachable” or
691 “xresolve”.
692 scope (scalar)
694 The route scope, how wide-ranging it is to the network.
695 Possible values are “global”, “link”, or “host”.
696 table (scalar)
698 The table number to use for the route. In some scenar‐
699 ios, it may be useful to set routes in a separate routing
700 table. It may also be used to refer to routing policy
701 rules which also accept a table parameter. Allowed val‐
702 ues are positive integers starting from 1. Some values
703 are already in use to refer to specific routing tables:
704 see /etc/iproute2/rt_tables. (NetworkManager: as of
705 v1.10.0)
706 mtu (scalar) – since 0.101
708 The MTU to be used for the route, in bytes. Must be a
709 positive integer value.
710 congestion-window (scalar) – since 0.102
712 The congestion window to be used for the route, repre‐
713 sented by number of segments. Must be a positive integer
714 value.
715 advertised-receive-window (scalar) – since 0.102
717 The receive window to be advertised for the route, repre‐
718 sented by number of segments. Must be a positive integer
719 value.
720 routing-policy (mapping)
722 The routing-policy block defines extra routing policy for a net‐
723 work, where traffic may be handled specially based on the source
724 IP, firewall marking, etc.
725 For from, to, both IPv4 and IPv6 addresses are recognized, and
727 must be in the form addr/prefixlen or addr.
728 from (scalar)
730 Set a source IP address to match traffic for this policy
731 rule.
732 to (scalar)
734 Match on traffic going to the specified destination.
735 table (scalar)
737 The table number to match for the route. In some scenar‐
738 ios, it may be useful to set routes in a separate routing
739 table. It may also be used to refer to routes which also
740 accept a table parameter. Allowed values are positive
741 integers starting from 1. Some values are already in use
742 to refer to specific routing tables: see
743 /etc/iproute2/rt_tables.
744 priority (scalar)
746 Specify a priority for the routing policy rule, to influ‐
747 ence the order in which routing rules are processed. A
748 higher number means lower priority: rules are processed
749 in order by increasing priority number.
750 mark (scalar)
752 Have this routing policy rule match on traffic that has
753 been marked by the iptables firewall with this value.
754 Allowed values are positive integers starting from 1.
755 type-of-service (scalar)
757 Match this policy rule based on the type of service num‐
758 ber applied to the traffic.
759 Authentication
761 Netplan supports advanced authentication settings for ethernet and wifi
762 interfaces, as well as individual wifi networks, by means of the auth
763 block.
764 auth (mapping)
766 Specifies authentication settings for a device of type ether‐
767 nets:, or an access-points: entry on a wifis: device.
768 The auth block supports the following properties:
770 key-management (scalar)
772 The supported key management modes are none (no key man‐
773 agement); psk (WPA with pre-shared key, common for home
774 wifi); eap (WPA with EAP, common for enterprise wifi);
775 and 802.1x (used primarily for wired Ethernet connec‐
776 tions).
777 password (scalar)
779 The password string for EAP, or the pre-shared key for
780 WPA-PSK.
781 The following properties can be used if key-management is eap or
783 802.1x:
784 method (scalar)
786 The EAP method to use. The supported EAP methods are tls
787 (TLS), peap (Protected EAP), and ttls (Tunneled TLS).
788 identity (scalar)
790 The identity to use for EAP.
791 anonymous-identity (scalar)
793 The identity to pass over the unencrypted channel if the
794 chosen EAP method supports passing a different tunnelled
795 identity.
796 ca-certificate (scalar)
798 Path to a file with one or more trusted certificate au‐
799 thority (CA) certificates.
800 client-certificate (scalar)
802 Path to a file containing the certificate to be used by
803 the client during authentication.
804 client-key (scalar)
806 Path to a file containing the private key corresponding
807 to client-certificate.
808 client-key-password (scalar)
810 Password to use to decrypt the private key specified in
811 client-key if it is encrypted.
812 phase2-auth (scalar) – since 0.99
814 Phase 2 authentication mechanism.
815 Properties for device type ethernets:
817 Ethernet device definitions, beyond common ones described above, also
818 support some additional properties that can be used for SR-IOV devices.
819 link (scalar) – since 0.99
821 (SR-IOV devices only) The link property declares the device as a
822 Virtual Function of the selected Physical Function device, as
823 identified by the given netplan id.
824 Example:
826 ethernets:
828 enp1: {...}
829 enp1s16f1:
830 link: enp1
831 virtual-function-count (scalar) – since 0.99
833 (SR-IOV devices only) In certain special cases VFs might need to
834 be configured outside of netplan. For such configurations vir‐
835 tual-function-count can be optionally used to set an explicit
836 number of Virtual Functions for the given Physical Function. If
837 unset, the default is to create only as many VFs as are defined
838 in the netplan configuration. This should be used for special
839 cases only.
840 Requires feature: sriov
842 embedded-switch-mode (scalar) – since 0.104
844 (SR-IOV devices only) Change the operational mode of the embed‐
845 ded switch of a supported SmartNIC PCI device (e.g. Mellanox
846 ConnectX-5). Possible values are switchdev or legacy, if un‐
847 specified the vendor’s default configuration is used.
848 Requires feature: eswitch-mode
850 delay-virtual-functions-rebind (bool) – since 0.104
852 (SR-IOV devices only) Delay rebinding of SR-IOV virtual func‐
853 tions to its driver after changing the embedded-switch-mode set‐
854 ting to a later stage. Can be enabled when bonding/VF LAG is in
855 use. Defaults to false.
856 Requires feature: eswitch-mode
858 Properties for device type modems:
860 GSM/CDMA modem configuration is only supported for the NetworkManager
861 backend. systemd-networkd does not support modems.
862 Requires feature: modems
864 apn (scalar) – since 0.99
866 Set the carrier APN (Access Point Name). This can be omitted if
867 auto-config is enabled.
868 auto-config (bool) – since 0.99
870 Specify whether to try and autoconfigure the modem by doing a
871 lookup of the carrier against the Mobile Broadband Provider
872 database. This may not work for all carriers.
873 device-id (scalar) – since 0.99
875 Specify the device ID (as given by the WWAN management service)
876 of the modem to match. This can be found using mmcli.
877 network-id (scalar) – since 0.99
879 Specify the Network ID (GSM LAI format). If this is specified,
880 the device will not roam networks.
881 number (scalar) – since 0.99
883 The number to dial to establish the connection to the mobile
884 broadband network. (Deprecated for GSM)
885 password (scalar) – since 0.99
887 Specify the password used to authenticate with the carrier net‐
888 work. This can be omitted if auto-config is enabled.
889 pin (scalar) – since 0.99
891 Specify the SIM PIN to allow it to operate if a PIN is set.
892 sim-id (scalar) – since 0.99
894 Specify the SIM unique identifier (as given by the WWAN manage‐
895 ment service) which this connection applies to. If given, the
896 connection will apply to any device also allowed by device-id
897 which contains a SIM card matching the given identifier.
898 sim-operator-id (scalar) – since 0.99
900 Specify the MCC/MNC string (such as “310260” or “21601”) which
901 identifies the carrier that this connection should apply to. If
902 given, the connection will apply to any device also allowed by
903 device-id and sim-id which contains a SIM card provisioned by
904 the given operator.
905 username (scalar) – since 0.99
907 Specify the username used to authentiate with the carrier net‐
908 work. This can be omitted if auto-config is enabled.
909 Properties for device type wifis:
911 Note that systemd-networkd does not natively support wifi, so you need
912 wpasupplicant installed if you let the networkd renderer handle wifi.
913 access-points (mapping)
915 This provides pre-configured connections to NetworkManager.
916 Note that users can of course select other access points/SSIDs.
917 The keys of the mapping are the SSIDs, and the values are map‐
918 pings with the following supported properties:
919 password (scalar)
921 Enable WPA2 authentication and set the passphrase for it.
922 If neither this nor an auth block are given, the network
923 is assumed to be open. The setting
924 password: "S3kr1t"
926 is equivalent to
928 auth:
930 key-management: psk
931 password: "S3kr1t"
932 mode (scalar)
934 Possible access point modes are infrastructure (the de‐
935 fault), ap (create an access point to which other devices
936 can connect), and adhoc (peer to peer networks without a
937 central access point). ap is only supported with Net‐
938 workManager.
939 bssid (scalar) – since 0.99
941 If specified, directs the device to only associate with
942 the given access point.
943 band (scalar) – since 0.99
945 Possible bands are 5GHz (for 5GHz 802.11a) and 2.4GHz
946 (for 2.4GHz 802.11), do not restrict the 802.11 frequency
947 band of the network if unset (the default).
948 channel (scalar) – since 0.99
950 Wireless channel to use for the Wi-Fi connection. Be‐
951 cause channel numbers overlap between bands, this proper‐
952 ty takes effect only if the band property is also set.
953 hidden (bool) – since 0.100
955 Set to true to change the SSID scan technique for con‐
956 necting to hidden WiFi networks. Note this may have
957 slower performance compared to false (the default) when
958 connecting to publicly broadcast SSIDs.
959 wakeonwlan (sequence of scalars) – since 0.99
961 This enables WakeOnWLan on supported devices. Not all drivers
962 support all options. May be any combination of any, disconnect,
963 magic_pkt, gtk_rekey_failure, eap_identity_req, four_way_hand‐
964 shake, rfkill_release or tcp (NetworkManager only). Or the ex‐
965 clusive default flag (the default).
966 Properties for device type bridges:
968 interfaces (sequence of scalars)
969 All devices matching this ID list will be added to the bridge.
970 This may be an empty list, in which case the bridge will be
971 brought online with no member interfaces.
972 Example:
974 ethernets:
976 switchports:
977 match: {name: "enp2*"}
978 [...]
979 bridges:
980 br0:
981 interfaces: [switchports]
982 parameters (mapping)
984 Customization parameters for special bridging options. Time in‐
985 tervals may need to be expressed as a number of seconds or mil‐
986 liseconds: the default value type is specified below. If neces‐
987 sary, time intervals can be qualified using a time suffix (such
988 as “s” for seconds, “ms” for milliseconds) to allow for more
989 control over its behavior.
990 ageing-time (scalar)
992 Set the period of time to keep a MAC address in the for‐
993 warding database after a packet is received. This maps
994 to the AgeingTimeSec= property when the networkd renderer
995 is used. If no time suffix is specified, the value will
996 be interpreted as seconds.
997 priority (scalar)
999 Set the priority value for the bridge. This value should
1000 be a number between 0 and 65535. Lower values mean high‐
1001 er priority. The bridge with the higher priority will be
1002 elected as the root bridge.
1003 port-priority (scalar)
1005 Set the port priority to . The priority value is a num‐
1006 ber between 0 and 63. This metric is used in the desig‐
1007 nated port and root port selection algorithms.
1008 forward-delay (scalar)
1010 Specify the period of time the bridge will remain in Lis‐
1011 tening and Learning states before getting to the Forward‐
1012 ing state. This field maps to the ForwardDelaySec= prop‐
1013 erty for the networkd renderer. If no time suffix is
1014 specified, the value will be interpreted as seconds.
1015 hello-time (scalar)
1017 Specify the interval between two hello packets being sent
1018 out from the root and designated bridges. Hello packets
1019 communicate information about the network topology. When
1020 the networkd renderer is used, this maps to the Hel‐
1021 loTimeSec= property. If no time suffix is specified, the
1022 value will be interpreted as seconds.
1023 max-age (scalar)
1025 Set the maximum age of a hello packet. If the last hello
1026 packet is older than that value, the bridge will attempt
1027 to become the root bridge. This maps to the MaxAgeSec=
1028 property when the networkd renderer is used. If no time
1029 suffix is specified, the value will be interpreted as
1030 seconds.
1031 path-cost (scalar)
1033 Set the cost of a path on the bridge. Faster interfaces
1034 should have a lower cost. This allows a finer control on
1035 the network topology so that the fastest paths are avail‐
1036 able whenever possible.
1037 stp (bool)
1039 Define whether the bridge should use Spanning Tree Proto‐
1040 col. The default value is “true”, which means that Span‐
1041 ning Tree should be used.
1042 Properties for device type bonds:
1044 interfaces (sequence of scalars)
1045 All devices matching this ID list will be added to the bond.
1046 Example:
1048 ethernets:
1050 switchports:
1051 match: {name: "enp2*"}
1052 [...]
1053 bonds:
1054 bond0:
1055 interfaces: [switchports]
1056 parameters (mapping)
1058 Customization parameters for special bonding options. Time in‐
1059 tervals may need to be expressed as a number of seconds or mil‐
1060 liseconds: the default value type is specified below. If neces‐
1061 sary, time intervals can be qualified using a time suffix (such
1062 as “s” for seconds, “ms” for milliseconds) to allow for more
1063 control over its behavior.
1064 mode (scalar)
1066 Set the bonding mode used for the interfaces. The de‐
1067 fault is balance-rr (round robin). Possible values are
1068 balance-rr, active-backup, balance-xor, broadcast,
1069 802.3ad, balance-tlb, and balance-alb. For OpenVSwitch
1070 active-backup and the additional modes balance-tcp and
1071 balance-slb are supported.
1072 lacp-rate (scalar)
1074 Set the rate at which LACPDUs are transmitted. This is
1075 only useful in 802.3ad mode. Possible values are slow
1076 (30 seconds, default), and fast (every second).
1077 mii-monitor-interval (scalar)
1079 Specifies the interval for MII monitoring (verifying if
1080 an interface of the bond has carrier). The default is 0;
1081 which disables MII monitoring. This is equivalent to the
1082 MIIMonitorSec= field for the networkd backend. If no
1083 time suffix is specified, the value will be interpreted
1084 as milliseconds.
1085 min-links (scalar)
1087 The minimum number of links up in a bond to consider the
1088 bond interface to be up.
1089 transmit-hash-policy (scalar)
1091 Specifies the transmit hash policy for the selection of
1092 slaves. This is only useful in balance-xor, 802.3ad and
1093 balance-tlb modes. Possible values are layer2, layer3+4,
1094 layer2+3, encap2+3, and encap3+4.
1095 ad-select (scalar)
1097 Set the aggregation selection mode. Possible values are
1098 stable, bandwidth, and count. This option is only used
1099 in 802.3ad mode.
1100 all-slaves-active (bool)
1102 If the bond should drop duplicate frames received on in‐
1103 active ports, set this option to false. If they should
1104 be delivered, set this option to true. The default value
1105 is false, and is the desirable behavior in most situa‐
1106 tions.
1107 arp-interval (scalar)
1109 Set the interval value for how frequently ARP link moni‐
1110 toring should happen. The default value is 0, which dis‐
1111 ables ARP monitoring. For the networkd backend, this
1112 maps to the ARPIntervalSec= property. If no time suffix
1113 is specified, the value will be interpreted as millisec‐
1114 onds.
1115 arp-ip-targets (sequence of scalars)
1117 IPs of other hosts on the link which should be sent ARP
1118 requests in order to validate that a slave is up. This
1119 option is only used when arp-interval is set to a value
1120 other than 0. At least one IP address must be given for
1121 ARP link monitoring to function. Only IPv4 addresses are
1122 supported. You can specify up to 16 IP addresses. The
1123 default value is an empty list.
1124 arp-validate (scalar)
1126 Configure how ARP replies are to be validated when using
1127 ARP link monitoring. Possible values are none, active,
1128 backup, and all.
1129 arp-all-targets (scalar)
1131 Specify whether to use any ARP IP target being up as suf‐
1132 ficient for a slave to be considered up; or if all the
1133 targets must be up. This is only used for active-backup
1134 mode when arp-validate is enabled. Possible values are
1135 any and all.
1136 up-delay (scalar)
1138 Specify the delay before enabling a link once the link is
1139 physically up. The default value is 0. This maps to the
1140 UpDelaySec= property for the networkd renderer. This op‐
1141 tion is only valid for the miimon link monitor. If no
1142 time suffix is specified, the value will be interpreted
1143 as milliseconds.
1144 down-delay (scalar)
1146 Specify the delay before disabling a link once the link
1147 has been lost. The default value is 0. This maps to the
1148 DownDelaySec= property for the networkd renderer. This
1149 option is only valid for the miimon link monitor. If no
1150 time suffix is specified, the value will be interpreted
1151 as milliseconds.
1152 fail-over-mac-policy (scalar)
1154 Set whether to set all slaves to the same MAC address
1155 when adding them to the bond, or how else the system
1156 should handle MAC addresses. The possible values are
1157 none, active, and follow.
1158 gratuitous-arp (scalar)
1160 Specify how many ARP packets to send after failover.
1161 Once a link is up on a new slave, a notification is sent
1162 and possibly repeated if this value is set to a number
1163 greater than 1. The default value is 1 and valid values
1164 are between 1 and 255. This only affects active-backup
1165 mode.
1166 For historical reasons, the misspelling gratuitious-arp
1168 is also accepted and has the same function.
1169 packets-per-slave (scalar)
1171 In balance-rr mode, specifies the number of packets to
1172 transmit on a slave before switching to the next. When
1173 this value is set to 0, slaves are chosen at random. Al‐
1174 lowable values are between 0 and 65535. The default val‐
1175 ue is 1. This setting is only used in balance-rr mode.
1176 primary-reselect-policy (scalar)
1178 Set the reselection policy for the primary slave. On
1179 failure of the active slave, the system will use this
1180 policy to decide how the new active slave will be chosen
1181 and how recovery will be handled. The possible values
1182 are always, better, and failure.
1183 resend-igmp (scalar)
1185 In modes balance-rr, active-backup, balance-tlb and bal‐
1186 ance-alb, a failover can switch IGMP traffic from one
1187 slave to another.
1188 This parameter specifies how many IGMP membership reports
1190 are issued on a failover event. Values range from 0 to
1191 255. 0 disables sending membership reports. Otherwise,
1192 the first membership report is sent on failover and sub‐
1193 sequent reports are sent at 200ms intervals.
1194 learn-packet-interval (scalar)
1196 Specify the interval between sending learning packets to
1197 each slave. The value range is between 1 and 0x7fffffff.
1198 The default value is 1. This option only affects bal‐
1199 ance-tlb and balance-alb modes. Using the networkd ren‐
1200 derer, this field maps to the LearnPacketIntervalSec=
1201 property. If no time suffix is specified, the value will
1202 be interpreted as seconds.
1203 primary (scalar)
1205 Specify a device to be used as a primary slave, or pre‐
1206 ferred device to use as a slave for the bond (ie. the
1207 preferred device to send data through), whenever it is
1208 available. This only affects active-backup, balance-alb,
1209 and balance-tlb modes.
1210 Properties for device type tunnels:
1212 Tunnels allow traffic to pass as if it was between systems on the same
1213 local network, although systems may be far from each other but reach‐
1214 able via the Internet. They may be used to support IPv6 traffic on a
1215 network where the ISP does not provide the service, or to extend and
1216 “connect” separate local networks. Please see
1217 https://en.wikipedia.org/wiki/Tunneling_protocol for more general in‐
1218 formation about tunnels.
1219 mode (scalar)
1221 Defines the tunnel mode. Valid options are sit, gre, ip6gre,
1222 ipip, ipip6, ip6ip6, vti, vti6 and wireguard. Additionally, the
1223 networkd backend also supports gretap and ip6gretap modes. In
1224 addition, the NetworkManager backend supports isatap tunnels.
1225 local (scalar)
1227 Defines the address of the local endpoint of the tunnel.
1228 remote (scalar)
1230 Defines the address of the remote endpoint of the tunnel.
1231 ttl (scalar) – since 0.103
1233 Defines the TTL of the tunnel.
1234 key (scalar or mapping)
1236 Define keys to use for the tunnel. The key can be a number or a
1237 dotted quad (an IPv4 address). For wireguard it can be a
1238 base64-encoded private key or (as of networkd v242+) an absolute
1239 path to a file, containing the private key (since 0.100). It is
1240 used for identification of IP transforms. This is only required
1241 for vti and vti6 when using the networkd backend, and for gre or
1242 ip6gre tunnels when using the NetworkManager backend.
1243 This field may be used as a scalar (meaning that a single key is
1245 specified and to be used for input, output and private key), or
1246 as a mapping, where you can further specify input/output/pri‐
1247 vate.
1248 input (scalar)
1250 The input key for the tunnel
1251 output (scalar)
1253 The output key for the tunnel
1254 private (scalar) – since 0.100
1256 A base64-encoded private key required for WireGuard tun‐
1257 nels. When the systemd-networkd backend (v242+) is used,
1258 this can also be an absolute path to a file containing
1259 the private key.
1260 keys (scalar or mapping)
1262 Alternate name for the key field. See above.
1263 Examples:
1265 tunnels:
1267 tun0:
1268 mode: gre
1269 local: ...
1270 remote: ...
1271 keys:
1272 input: 1234
1273 output: 5678
1274 tunnels:
1276 tun0:
1277 mode: vti6
1278 local: ...
1279 remote: ...
1280 key: 59568549
1281 tunnels:
1283 wg0:
1284 mode: wireguard
1285 addresses: [...]
1286 peers:
1287 - keys:
1288 public: rlbInAj0qV69CysWPQY7KEBnKxpYCpaWqOs/dLevdWc=
1289 shared: /path/to/shared.key
1290 ...
1291 key: mNb7OIIXTdgW4khM7OFlzJ+UPs7lmcWHV7xjPgakMkQ=
1292 tunnels:
1294 wg0:
1295 mode: wireguard
1296 addresses: [...]
1297 peers:
1298 - keys:
1299 public: rlbInAj0qV69CysWPQY7KEBnKxpYCpaWqOs/dLevdWc=
1300 ...
1301 keys:
1302 private: /path/to/priv.key
1303 WireGuard specific keys:
1305 mark (scalar) – since 0.100
1307 Firewall mark for outgoing WireGuard packets from this inter‐
1308 face, optional.
1309 port (scalar) – since 0.100
1311 UDP port to listen at or auto. Optional, defaults to auto.
1312 peers (sequence of mappings) – since 0.100
1314 A list of peers, each having keys documented below.
1315 Example:
1317 tunnels:
1319 wg0:
1320 mode: wireguard
1321 key: /path/to/private.key
1322 mark: 42
1323 port: 5182
1324 peers:
1325 - keys:
1326 public: rlbInAj0qV69CysWPQY7KEBnKxpYCpaWqOs/dLevdWc=
1327 allowed-ips: [0.0.0.0/0, "2001:fe:ad:de:ad:be:ef:1/24"]
1328 keepalive: 23
1329 endpoint: 1.2.3.4:5
1330 - keys:
1331 public: M9nt4YujIOmNrRmpIRTmYSfMdrpvE7u6WkG8FY8WjG4=
1332 shared: /some/shared.key
1333 allowed-ips: [10.10.10.20/24]
1334 keepalive: 22
1335 endpoint: 5.4.3.2:1
1336 endpoint (scalar) – since 0.100
1338 Remote endpoint IPv4/IPv6 address or a hostname, followed by a
1339 colon and a port number.
1340 allowed-ips (sequence of scalars) – since 0.100
1342 A list of IP (v4 or v6) addresses with CIDR masks from which
1343 this peer is allowed to send incoming traffic and to which out‐
1344 going traffic for this peer is directed. The catch-all
1345 0.0.0.0/0 may be specified for matching all IPv4 addresses, and
1346 ::/0 may be specified for matching all IPv6 addresses.
1347 keepalive (scalar) – since 0.100
1349 An interval in seconds, between 1 and 65535 inclusive, of how
1350 often to send an authenticated empty packet to the peer for the
1351 purpose of keeping a stateful firewall or NAT mapping valid per‐
1352 sistently. Optional.
1353 keys (mapping) – since 0.100
1355 Define keys to use for the WireGuard peers.
1356 This field can be used as a mapping, where you can further spec‐
1358 ify the public and shared keys.
1359 public (scalar) – since 0.100
1361 A base64-encoded public key, required for WireGuard
1362 peers.
1363 shared (scalar) – since 0.100
1365 A base64-encoded preshared key. Optional for WireGuard
1366 peers. When the systemd-networkd backend (v242+) is
1367 used, this can also be an absolute path to a file con‐
1368 taining the preshared key.
1369 Properties for device type vlans:
1371 id (scalar)
1372 VLAN ID, a number between 0 and 4094.
1373 link (scalar)
1375 netplan ID of the underlying device definition on which this
1376 VLAN gets created.
1377 Example:
1379 ethernets:
1381 eno1: {...}
1382 vlans:
1383 en-intra:
1384 id: 1
1385 link: eno1
1386 dhcp4: yes
1387 en-vpn:
1388 id: 2
1389 link: eno1
1390 addresses: ...
1391 Properties for device type nm-devices:
1393 The nm-devices device type is for internal use only and should not be
1394 used in normal configuration files. It enables a fallback mode for un‐
1395 supported settings, using the passthrough mapping.
1396 Backend-specific configuration parameters
1398 In addition to the other fields available to configure interfaces, some
1399 backends may require to record some of their own parameters in netplan,
1400 especially if the netplan definitions are generated automatically by
1401 the consumer of that backend. Currently, this is only used with Net‐
1402 workManager.
1403 networkmanager (mapping) – since 0.99
1405 Keeps the NetworkManager-specific configuration parameters used
1406 by the daemon to recognize connections.
1407 name (scalar) – since 0.99
1409 Set the display name for the connection.
1410 uuid (scalar) – since 0.99
1412 Defines the UUID (unique identifier) for this connection,
1413 as generated by NetworkManager itself.
1414 stable-id (scalar) – since 0.99
1416 Defines the stable ID (a different form of a connection
1417 name) used by NetworkManager in case the name of the con‐
1418 nection might otherwise change, such as when sharing con‐
1419 nections between users.
1420 device (scalar) – since 0.99
1422 Defines the interface name for which this connection ap‐
1423 plies.
1424 passthrough (mapping) – since 0.102
1426 Can be used as a fallback mechanism to missing keyfile
1427 settings.
1428 Examples
1430 Configure an ethernet device with networkd, identified by its name, and
1431 enable DHCP:
1432 network:
1434 version: 2
1435 ethernets:
1436 eno1:
1437 dhcp4: true
1438 This is an example of a static-configured interface with multiple IPv4
1440 addresses and multiple gateways with networkd, with equal route metric
1441 levels, and static DNS nameservers (Google DNS for this example):
1442 network:
1444 version: 2
1445 renderer: networkd
1446 ethernets:
1447 eno1:
1448 addresses:
1449 - 10.0.0.10/24
1450 - 11.0.0.11/24
1451 nameservers:
1452 addresses:
1453 - 8.8.8.8
1454 - 8.8.4.4
1455 routes:
1456 - to: 0.0.0.0/0
1457 via: 10.0.0.1
1458 metric: 100
1459 - to: 0.0.0.0/0
1460 via: 11.0.0.1
1461 metric: 100
1462 This is a complex example which shows most available features:
1464 network:
1466 version: 2
1467 # if specified, can only realistically have that value, as networkd cannot
1468 # render wifi/3G.
1469 renderer: NetworkManager
1470 ethernets:
1471 # opaque ID for physical interfaces, only referred to by other stanzas
1472 id0:
1473 match:
1474 macaddress: 00:11:22:33:44:55
1475 wakeonlan: true
1476 dhcp4: true
1477 addresses:
1478 - 192.168.14.2/24
1479 - 192.168.14.3/24
1480 - "2001:1::1/64"
1481 nameservers:
1482 search: [foo.local, bar.local]
1483 addresses: [8.8.8.8]
1484 routes:
1485 - to: default
1486 via: 192.168.14.1
1487 - to: default
1488 via: "2001:1::2"
1489 - to: 0.0.0.0/0
1490 via: 11.0.0.1
1491 table: 70
1492 on-link: true
1493 metric: 3
1494 routing-policy:
1495 - to: 10.0.0.0/8
1496 from: 192.168.14.2/24
1497 table: 70
1498 priority: 100
1499 - to: 20.0.0.0/8
1500 from: 192.168.14.3/24
1501 table: 70
1502 priority: 50
1503 # only networkd can render on-link routes and routing policies
1504 renderer: networkd
1505 lom:
1506 match:
1507 driver: ixgbe
1508 # you are responsible for setting tight enough match rules
1509 # that only match one device if you use set-name
1510 set-name: lom1
1511 dhcp6: true
1512 switchports:
1513 # all cards on second PCI bus unconfigured by
1514 # themselves, will be added to br0 below
1515 match:
1516 name: enp2*
1517 mtu: 1280
1518 wifis:
1519 all-wlans:
1520 # useful on a system where you know there is
1521 # only ever going to be one device
1522 match: {}
1523 access-points:
1524 "Joe's home":
1525 # mode defaults to "infrastructure" (client)
1526 password: "s3kr1t"
1527 # this creates an AP on wlp1s0 using hostapd
1528 # no match rules, thus the ID is the interface name
1529 wlp1s0:
1530 access-points:
1531 "guest":
1532 mode: ap
1533 # no WPA config implies default of open
1534 bridges:
1535 # the key name is the name for virtual (created) interfaces
1536 # no match: and set-name: allowed
1537 br0:
1538 # IDs of the components; switchports expands into multiple interfaces
1539 interfaces: [wlp1s0, switchports]
1540 dhcp4: true
1541
1543 netplan-generate(8), netplan-apply(8), netplan-try(8), netplan-get(8),
1544 netplan-set(8), netplan-dbus(8), systemd-networkd(8), NetworkManager(8)
1545
1547 Mathieu Trudel-Lapierre (<cyphermox@ubuntu.com>); Martin Pitt (<mar‐
1548 tin.pitt@ubuntu.com>).
1549 netplan(5)