Defines what version of the configuration format is used. The only value supported is 2. Defaults to 2 if not defined.

Defines what network configuration tool will be used to set up your configuration. Valid values are networkd and NetworkManager. Defaults to networkd if not defined.

Creates and configures link aggregation (bonding) devices.

Creates and configures bridge devices.

Creates and configures virtual devices.

Configures physical Ethernet interfaces.

Configures modems

Creates and configures different types of virtual tunnels.

Creates and configures Virtual Ethernet (veth) devices.

Creates and configures VLANs.

Configures Virtual Routing and Forwarding (VRF) devices.

Configures physical Wi-Fi interfaces as client, adhoc or access point.

nm-devices are used in situations where Netplan doesn't support the connection type. The raw configuration expected by NetworkManager can be defined and will be passed as is (passthrough) to the .nmconnection file. Users will not normally use this type of device.

This selects a subset of available physical devices by various hardware properties. The following configuration will then apply to all matching devices, as soon as they appear. All specified properties must match.

network:


  ethernets:


    myinterface:


      match:


        name: enp2*
    

network:


  ethernets:


    interface0:


      match:


        macaddress: 11:22:33:AA:BB:FF
    

network:


  ethernets:


    nic0:


      match:


        driver: ixgbe


        name: en*s0
    

network:


  ethernets:


    nic0:


      match:


        driver: ["bcmgenet", "smsc*"]


        name: en*
    

When matching on unique properties such as path or MAC, or with additional assumptions such as "there will only ever be one Wi-Fi device", match rules can be written so that they only match one device. Then this property can be used to give that device a more specific or desirable name than the default from udev ifnames. Any additional device that satisfies the match rules will then fail to get renamed and keep the original kernel name (and dmesg will show an error).

Enable wake on LAN. Off by default.

(networkd back end only) Whether to emit LLDP packets. Off by default.

(networkd back end only) If set to true (false), the hardware offload for checksumming of ingress network packets is enabled (disabled). When unset, the kernel's default will be used.

(networkd back end only) If set to true (false), the hardware offload for checksumming of egress network packets is enabled (disabled). When unset, the kernel's default will be used.

(networkd back end only) If set to true (false), the TCP Segmentation Offload (TSO) is enabled (disabled). When unset, the kernel's default will be used.

(networkd back end only) If set to true (false), the TCP6 Segmentation Offload (tx-tcp6-segmentation) is enabled (disabled). When unset, the kernel's default will be used.

(networkd back end only) If set to true (false), the Generic Segmentation Offload (GSO) is enabled (disabled). When unset, the kernel's default will be used.

(networkd back end only) If set to true (false), the Generic Receive Offload (GRO) is enabled (disabled). When unset, the kernel's default will be used.

(networkd back end only) If set to true (false), the Large Receive Offload (LRO) is enabled (disabled). When unset, the kernel's default will be used.

This provides additional configuration for the openvswitch network device. If Open vSwitch is not available on the system, Netplan treats the presence of openvswitch configuration as an error.

Any supported network device that is declared with the openvswitch mapping (or any bond/bridge that includes an interface with an openvswitch configuration) will be created in openvswitch instead of the defined renderer. In the case of a vlan definition declared the same way, Netplan will create a fake VLAN bridge in openvswitch with the requested vlan properties.

•

addresses (sequence of scalars)

•

connection-mode (scalar)

Example:

openvswitch:


  ports:


    - [patch0-1, patch1-0]
    

•

ca-cert (scalar)

•

certificate (scalar)

•

private-key (scalar)

Use the given networking back end for this definition. Currently supported are networkd and NetworkManager. This property can be specified globally in network:, for a device type (in e.g. ethernets:) or for a particular device definition. Default is networkd.

(Since 0.99) The renderer property has one additional acceptable value for VLAN objects (i.e. defined in vlans:): sriov. If a VLAN is defined with the sriov renderer for an SR-IOV Virtual Function interface, this causes Netplan to set up a hardware VLAN filter for it. There can be only one defined per VF.

Enable DHCP for IPv4. Off by default.

Enable DHCP for IPv6. Off by default. This covers both stateless DHCP - where the DHCP server supplies information like DNS name servers but not the IP address - and stateful DHCP, where the server provides both the address and the other information.

If you are in an IPv6-only environment with completely stateless auto-configuration (SLAAC with RDNSS), this option can be set to cause the interface to be brought up. (Setting accept-ra alone is not sufficient.) Auto-configuration will still honour the contents of the router advertisement and only use DHCP if requested in the RA.

Note that rdnssd(8) is required to use RDNSS with networkd. No extra software is required for NetworkManager.

Enable IPv6 Privacy Extensions (RFC 4941) for the specified interface, and prefer temporary addresses. Defaults to false - no privacy extensions. There is currently no way to have a private address but prefer the public address.

Configure the link-local addresses to bring up. Valid options are ipv4 and ipv6, which respectively allow enabling IPv4 and IPv6 link local addressing. If this field is not defined, the default is to enable only IPv6 link-local addresses. If the field is defined but configured as an empty set, IPv6 link-local addresses are disabled as well as IPv4 link- local addresses.

This feature enables or disables link-local addresses for a protocol, but the actual implementation differs per back end. On networkd, this directly changes the behaviour and may add an extra address on an interface. When using the NetworkManager back end, enabling link-local has no effect if the interface also has DHCP enabled.

(networkd back end only) Allow the specified interface to be configured even if it has no carrier.

Designate the connection as "critical to the system", meaning that special care will be taken by to not release the assigned IP when the daemon is restarted. (not recognised by NetworkManager)

(networkd back end only) Sets the source of DHCP (v4) client identifier. If mac is specified, the MAC address of the link is used. If this option is omitted, or if duid is specified, networkd will generate an RFC4361-compliant client identifier for the interface by combining the link's IAID and DUID.

(networkd back end only) Overrides default DHCP behaviour; see the DHCP Overrides section below.

(networkd back end only) Overrides default DHCP behaviour; see the DHCP Overrides section below.

Accept Router Advertisement that would have the kernel configure IPv6 by itself. When enabled, accept Router Advertisements. When disabled, do not respond to Router Advertisements. If unset use the host kernel default setting.

Add static addresses to the interface in addition to the ones received through DHCP or RA. Each sequence entry is in CIDR notation, i.e. of the form addr/prefixlen. addr is an IPv4 or IPv6 address as recognised by inet_pton(3) and prefixlen the number of bits of the subnet.

For virtual devices (bridges, bonds, VLAN) if there is no address configured and DHCP is disabled, the interface may still be brought online, but will not be addressable from the network.

In addition to the addresses themselves one can specify configuration parameters as mappings. Current supported options are:

network:


  ethernets:


    eth0:


      addresses:


        - "10.0.0.15/24":


            lifetime: 0


            label: "maas"


        - "2001:1::1/64"
    

Configure method for creating the address for use with RFC4862 IPv6 Stateless Address Auto-configuration (only supported with NetworkManager back end). Possible values are eui64 or stable-privacy.

Define an IPv6 address token for creating a static interface identifier for IPv6 Stateless Address Auto-configuration. This is mutually exclusive with ipv6-address-generation.

Deprecated, see Default routes. Set default gateway for IPv4/6, for manual address configuration. This requires setting addresses too. Gateway IP addresses must be in a form recognised by inet_pton(3). There should only be a single gateway per IP address family set in your global configuration, to make it unambiguous. If you need multiple default routes, please define them via routing-policy.

Set DNS servers and search domains, for manual address configuration. There are two supported fields: addresses: is a list of IPv4 or IPv6 addresses similar to gateway*, and search: is a list of search domains.

Set the device's MAC address. The MAC address must be in the form "XX:XX:XX:XX:XX:XX". The following special options are also accepted: permanent and random. In addition to these options, the NetworkManager renderer also accepts stable and preserve.

Note: This will not work reliably for devices matched by name only and rendered by networkd, due to interactions with device renaming in udev. Match devices by MAC when setting MAC addresses.

Set the Maximum Transmission Unit for the interface. The default is 1500. Valid values depend on your network interface.

Note: This will not work reliably for devices matched by name only and rendered by networkd, due to interactions with device renaming in udev. Match devices by MAC when setting MTU.

An optional device is not required for booting. Normally, networkd will wait some time for device to become configured before proceeding with booting. However, if a device is marked as optional, networkd will not wait for it. This is only supported by networkd, and the default is false.

Specify types of addresses that are not required for a device to be considered online. This changes the behaviour of back ends at boot time to avoid waiting for addresses that are marked optional, and thus consider the interface as "usable" sooner. This does not disable these addresses, which will be brought up anyway.

Allows specifying the management policy of the selected interface. By default, Netplan brings up any configured interface if possible. Using the activation-mode setting users can override that behaviour by either specifying manual, to hand over control over the interface state to the administrator or (for networkd back end only) off to force the link in a down state at all times. Any interface with activation-mode defined is implicitly considered optional. Supported officially as of networkd v248+.

Configure static routing for the device; see the Routing section below.

Configure policy routing for the device; see the Routing section below.

Takes a boolean. Configures whether ARP and ND neighbour suppression is enabled for this bridge port. When unset, the kernel's default will be used.

Takes a boolean. Configures whether traffic may be sent back out of the bridge port on which it was received. When this flag is false, then the bridge will not forward traffic back out of the receiving port. When unset, the backend's default will be used.

Takes a boolean. Configures whether MAC address learning is enabled for this bridge port. When unset, the kernel's default will be used. Currently supported on the networkd backend only.

The dhcp4-overrides and dhcp6-override mappings override the default DHCP behaviour.

The routes block defines standard static routes for an interface. At least to must be specified. If type is local or nat a default scope of host is assumed. If type is unicast and no gateway (via) is given or type is broadcast, multicast or anycast a default scope of link is assumed. Otherwise, a global scope is the default setting.

For from, to and via, both IPv4 and IPv6 addresses are recognised, and must be in the form addr/prefixlen or addr.

The routing-policy block defines extra routing policy for a network, where traffic may be handled specially based on the source IP, firewall marking, etc.

For from, to, both IPv4 and IPv6 addresses are recognised, and must be in the form addr/prefixlen or addr.

Specifies authentication settings for a device of type ethernets:, or an access-points: entry on a wifis: device.

The auth block supports the following properties:

The following properties can be used if key-management is eap or 802.1x:

(SR-IOV devices only) The link property declares the device as a Virtual Function of the selected Physical Function device, as identified by the given Netplan ID.

(SR-IOV devices only) In certain special cases VFs might need to be configured outside of Netplan. For such configurations virtual-function-count can be optionally used to set an explicit number of Virtual Functions for the given Physical Function. If unset, the default is to create only as many VFs as are defined in the Netplan configuration. This should be used for special cases only.

Requires feature: sriov

(SR-IOV devices only) Change the operational mode of the embedded switch of a supported SmartNIC PCI device (e.g. Mellanox ConnectX-5). Possible values are switchdev or legacy, if unspecified the vendor's default configuration is used.

Requires feature: eswitch-mode

(SR-IOV devices only) Delay rebinding of SR-IOV virtual functions to its driver after changing the embedded-switch-mode setting to a later stage. Can be enabled when bonding/VF LAG is in use. Defaults to false.

Requires feature: eswitch-mode

(InfiniBand devices only) Change the operational mode of a IPoIB device. Possible values are datagram or connected. If unspecified the kernel's default configuration is used.

Requires feature: infiniband

Set the carrier APN (Access Point Name). This can be omitted if auto-config is enabled.

Specify whether to try and auto-configure the modem by doing a lookup of the carrier against the Mobile Broadband Provider database. This may not work for all carriers.

Specify the device ID (as given by the WWAN management service) of the modem to match. This can be found using mmcli.

Specify the Network ID (GSM LAI format). If this is specified, the device will not roam networks.

The number to dial to establish the connection to the mobile broadband network. (Deprecated for GSM)

Specify the password used to authenticate with the carrier network. This can be omitted if auto-config is enabled.

Specify the SIM PIN to allow it to operate if a PIN is set.

Specify the SIM unique identifier (as given by the WWAN management service) which this connection applies to. If given, the connection will apply to any device also allowed by device-id which contains a SIM card matching the given identifier.

Specify the MCC/MNC string (such as 310260 or 21601) which identifies the carrier that this connection should apply to. If given, the connection will apply to any device also allowed by device-id and sim-id which contains a SIM card provisioned by the given operator.

Specify the username used to authenticate with the carrier network. This can be omitted if auto-config is enabled.

This provides pre-configured connections to NetworkManager. Note that users can of course select other access points/SSIDs. The keys of the mapping are the SSIDs, and the values are mappings with the following supported properties:

This enables WakeOnWLan on supported devices. Not all drivers support all options. May be any combination of any, disconnect, magic_pkt, gtk_rekey_failure, eap_identity_req, four_way_handshake, rfkill_release or tcp (NetworkManager only). Or the exclusive default flag (the default).

This can be used to define the radio's regulatory domain, to make use of additional Wi-Fi channels outside the "world domain". Takes an ISO/ IEC 3166 country code (like GB) or 00 to reset to the "world domain". See wireless-regdb (https://git.kernel.org/pub/scm/linux/kernel/git/sforshee/wireless-regdb.git/tree/db.txt) for available values.

Requires dependency: iw, if it is to be used outside the networkd (wpasupplicant) back end.

All devices matching this ID list will be added to the bridge. This may be an empty list, in which case the bridge will be brought online with no member interfaces.

Customisation parameters for special bridging options. Time intervals may need to be expressed as a number of seconds or milliseconds: the default value type is specified below. If necessary, time intervals can be qualified using a time suffix (such as s for seconds, ms for milliseconds) to allow for more control over its behaviour.

Example:

network:


  ethernets:


    eth0:


      dhcp4: false


    eth1:


      dhcp4: false


  bridges:


    br0:


      interfaces: [eth0, eth1]


      parameters:


        port-priority:


          eth0: 10


          eth1: 20
    

Example:

network:


  ethernets:


    eth0:


      dhcp4: false


    eth1:


      dhcp4: false


  bridges:


    br0:


      interfaces: [eth0, eth1]


      parameters:


        path-cost:


          eth0: 100


          eth1: 200
    

All devices matching this ID list will be added to the bond.

Customisation parameters for special bonding options. Time intervals may need to be expressed as a number of seconds or milliseconds: the default value type is specified below. If necessary, time intervals can be qualified using a time suffix (such as s for seconds, ms for milliseconds) to allow for more control over its behaviour.

Defines the tunnel mode. Valid options are sit, gre, ip6gre, ipip, ipip6, ip6ip6, vti, vti6, wireguard, vxlan, gretap and ip6gretap modes. In addition, the NetworkManager back end supports isatap tunnels.

Defines the address of the local endpoint of the tunnel. (For VXLAN) This should match one of the parent's IP addresses or make use of the networkd special values.

Defines the address of the remote endpoint of the tunnel or multicast group IP address for VXLAN.

Defines the Time To Live (TTL) of the tunnel. Takes a number in the range 1..255.

Define keys to use for the tunnel. The key can be a number or a dotted quad (an IPv4 address). For wireguard it can be a base64-encoded private key or (as of networkd v242+) an absolute path to a file, containing the private key (since 0.100). It is used for identification of IP transforms. This is only required for vti and vti6 when using the networkd back end.

This field may be used as a scalar (meaning that a single key is specified and to be used for input, output and private key), or as a mapping, where you can further specify input/output/private.

Example:

network:


  renderer: NetworkManager


  tunnels:


    wg0:


      mode: wireguard


      port: 5182


      key:


        private-key-flags:


          - agent-owned


      peers:


        - keys:


            public: rlbInAj0qV69CysWPQY7KEBnKxpYCpaWqOs/dLevdWc=


          allowed-ips: [0.0.0.0/0, "2001:fe:ad:de:ad:be:ef:1/24"]


          keepalive: 23


          endpoint: 1.2.3.4:5
    

Alternate name for the key field. See above.

Firewall mark for outgoing WireGuard packets from this interface, optional.

UDP port to listen at or auto. Optional, defaults to auto.

A list of peers, each having keys documented below.

•

public (scalar) – since 0.100

•

shared (scalar) – since 0.100

The VXLAN Network Identifier (VNI or VXLAN Segment ID). Takes a number in the range 1..16777215.

Netplan ID of the parent device definition to which this VXLAN gets connected.

The Type Of Service byte value for a VXLAN interface.

Takes a boolean. When true, enables dynamic MAC learning to discover remote MAC addresses.

The lifetime of Forwarding Database entry learned by the kernel, in seconds.

Configures maximum number of FDB entries.

Takes a boolean. When true, bridge-connected VXLAN tunnel endpoint answers ARP requests from the local bridge on behalf of remote Distributed Overlay Virtual Ethernet (DOVE) clients. Defaults to false.

Takes the flags l2-miss and l3-miss to enable netlink LLADDR and/or netlink IP address miss notifications.

Takes a boolean. When true, route short circuiting is turned on.

Takes the flags udp, zero-udp6-tx, zero-udp6-rx, remote-tx and remote-rx to enable transmitting UDP checksums in VXLAN/IPv4, send/receive zero checksums in VXLAN/IPv6 and enable sending/receiving checksum offloading in VXLAN.

Takes the flags group-policy and generic-protocol to enable the "Group Policy" and/or "Generic Protocol" VXLAN extensions.

Configures the default destination UDP port. If the destination port is not specified then Linux kernel default will be used. Set to 4789 to get the IANA assigned value.

Configures the source port range for the VXLAN. The kernel assigns the source UDP port based on the flow to help the receiver to do load balancing. When this option is not set, the normal range of local UDP ports is used. Uses the form [LOWER, UPPER].

Specifies the flow label to use in outgoing packets. The valid range is 0-1048575.

Allows setting the IPv4 Do not Fragment (DF) bit in outgoing packets. Takes a boolean value. When unset, the kernel default will be used.

Defines the virtual-ethernet peer. The peer interface must also be a virtual-ethernet device.

VLAN ID, a number between 0 and 4094.

Netplan ID of the underlying device definition on which this VLAN gets created.

The numeric routing table identifier. This setting is compulsory.

All devices matching this ID list will be added to the VRF. This may be an empty list, in which case the VRF will be brought online with no member interfaces.

Configure static routing for the device; see the Routing section. The table value is implicitly set to the VRF table.

Configure policy routing for the device; see the Routing section. The table value is implicitly set to the VRF table.

Keeps the NetworkManager-specific configuration parameters used by the daemon to recognise connections.