"Netplan reference"

YAML configuration

Top-level configuration structure

The general structure of a Netplan YAML file is shown below.

network:
  version: NUMBER
  renderer: STRING
  bonds: MAPPING
  bridges: MAPPING
  dummy-devices: MAPPING
  ethernets: MAPPING
  modems: MAPPING
  tunnels: MAPPING
  virtual-ethernets: MAPPING
  vlans: MAPPING
  vrfs: MAPPING
  wifis: MAPPING
  nm-devices: MAPPING

All the properties for all the device types will be described in the next sections.

Properties for physical device types

These properties are used with physical devices such as Ethernet and Wi-Fi network interfaces.

Note: Some options 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 options like: wakeonlan or *-offload.

Properties for all device types

DHCP Overrides

Several DHCP behaviour overrides are available. Most currently only have any effect when using the networkd back end, with the exception of use-routes and route-metric.

Overrides only have an effect if the corresponding dhcp4 or dhcp6 is set to true.

If both dhcp4 and dhcp6 are true, the networkd back end requires that dhcp4-overrides and dhcp6-overrides contain the same keys and values. If the values do not match, an error will be shown and the network configuration will not be applied.

When using the NetworkManager back end, different values may be specified for dhcp4-overrides and dhcp6-overrides, and will be applied to the DHCP client processes as specified in the Netplan YAML.

Routing

Complex routing is possible with Netplan. Standard static routes as well as policy routing using routing tables are supported via the networkd back end.

These options are available for all types of interfaces.

Default routes

The most common need for routing concerns the definition of default routes to reach the wider internet. Those default routes can only defined once per IP family and routing table. A typical example would look like the following:

network:
  ethernets:
    eth0:
      [...]
      routes:
        - to: default # could be 0.0.0.0/0 optionally
          via: 10.0.0.1
          metric: 100
          on-link: true
        - to: default # could be ::/0 optionally
          via: cf02:de:ad:be:ef::2
    eth1:
      [...]
      routes:
        - to: default
          via: 172.134.67.1
          metric: 100
          on-link: true
          # Not on the main routing table,
          # does not conflict with the eth0 default route
      table: 76

Authentication

Netplan supports advanced authentication settings for Ethernet and Wi-Fi interfaces, as well as individual Wi-Fi networks, by means of the auth block.

Properties for device type ethernets

Status: Optional.

Purpose: Use the ethernets key to configure Ethernet interfaces.

Structure: The key consists of a mapping of Ethernet interface IDs. Each ethernet has a number of configuration options. You don’t need to define each interface by their name inside the ethernets mapping. You can use any ID that describes the interface and match the actual network card using the match key. The general configuration structure for Ethernet is shown below.

network:
  ethernets:
    device-id:
      ...

device-id is the interface identifier. If you use the interface name as the ID, Netplan will match that interface.

Consider the example below. In this case, an interface called eth0 will be configured with DHCP.

network:
  ethernets:
    eth0:
      dhcp4: true

The device-id can be any descriptive name your find meaningful. Although, if it doesn’t match a real interface name, you must use the property match to identify the device you want to configure.

The example below defines an Ethernet connection called isp-interface (supposedly an external interface connected to the Internet Service Provider) and uses match to apply the configuration to the physical device with MAC address aa:bb:cc:00:11:22.

network:
  ethernets:
    isp-interface:
      match:
        macaddress: aa:bb:cc:00:11:22
      dhcp4: true

Ethernet device definitions, beyond common ones described above, also support some additional properties that can be used for SR-IOV devices.

Properties for device type modems

Status: Optional.

Purpose: Use the modems key to configure modem interfaces. GSM/CDMA modem configuration is only supported for the NetworkManager back end. systemd-networkd does not support modems.

Structure: The key consists of a mapping of modem IDs. Each modem has a number of configuration options. The general configuration structure for Modems is shown below.

network:
  version: 2
  renderer: NetworkManager
  modems:
    cdc-wdm1:
      mtu: 1600
      apn: ISP.CINGULAR
      username: ISP@CINGULARGPRS.COM
      password: CINGULAR1
      number: "*99#"
      network-id: 24005
      device-id: da812de91eec16620b06cd0ca5cbc7ea25245222
      pin: 2345
      sim-id: 89148000000060671234
      sim-operator-id: 310260

Requires feature: modems

Properties for device type wifis

Status: Optional.

Purpose: Use the wifis key to configure Wi-Fi access points.

Structure: The key consists of a mapping of Wi-Fi IDs. Each wifi has a number of configuration options. The general configuration structure for Wi-Fi is shown below.

network:
  version: 2
  wifis:
    wlp0s1:
      access-points:
        "network_ssid_name":
          password: "**********"

Note that systemd-networkd does not have native support Wi-Fi, so you need wpasupplicant installed if you let the networkd renderer handle Wi-Fi.

Properties for device type bridges

Status: Optional.

Purpose: Use the bridges key to create Bridge interfaces.

Structure: The key consists of a mapping of Bridge interface names. Each bridge has an optional list of interfaces that will be bridged together. The interfaces listed in the interfaces key (enp5s0 and enp5s1 below) must also be defined in your Netplan configuration. The general configuration structure for Bridges is shown below.

network:
  bridges:
    br0:
      interfaces:
        - enp5s0
        - enp5s1
      dhcp4: true
      ...

When applied, a virtual interface of type bridge called br0 will be created in the system.

The specific settings for bridges are defined below.

Properties for device type dummy-devices

Status: Optional.

Purpose: Use the dummy-devices key to create virtual interfaces.

Structure: The key consists of a mapping of interface names. Dummy devices are virtual devices that can be used to route packets to without actually transmitting them.

network:
  dummy-devices:
    dm0:
      addresses:
        - 192.168.0.123/24
      ...

When applied, a virtual interface called dm0 will be created in the system.

See the “Properties for all device types” section for the list of properties that can be used with this type of interface.

Properties for device type bonds

Status: Optional.

Purpose: Use the bonds key to create Bond (Link Aggregation) interfaces.

Structure: The key consists of a mapping of Bond interface names. Each bond has an optional list of interfaces that will be part of the aggregation. The interfaces listed in the interfaces key must also be defined in your Netplan configuration. The general configuration structure for Bonds is shown below.

network:
  bonds:
    bond0:
      interfaces:
        - enp5s0
        - enp5s1
        - enp5s2
      parameters:
        mode: active-backup
      ...

When applied, a virtual interface of type bond called bond0 will be created in the system.

The specific settings for bonds are defined below.

Properties for device type tunnels

Status: Optional.

Purpose: Use the tunnels key to create virtual tunnel interfaces.

Structure: The key consists of a mapping of tunnel interface names. Each tunnel requires the identification of the tunnel mode (see the section mode below for the list of supported modes). The general configuration structure for Tunnels is shown below.

network:
  tunnels:
    tunnel0:
      mode: SCALAR
      ...

When applied, a virtual interface called tunnel0 will be created in the system. Its operation mode is defined by the property mode.

Tunnels allow traffic to pass as if it was between systems on the same local network, although systems may be far from each other but reachable via the Internet. They may be used to support IPv6 traffic on a network where the ISP does not provide the service, or to extend and “connect” separate local networks. See Tunneling_protocol for more general information about tunnels.

The specific settings for tunnels are defined below.

WireGuard specific keys:

VXLAN specific keys:

Properties for device type virtual-ethernets

Status: Optional.

Purpose: Use the virtual-ethernets key to create virtual Ethernet interfaces.

Structure: The key consists of a mapping of veth interface names. Each veth requires a peer. In order to have a fully working veth pair, both devices must be defined, i.e., only setting the peer key with the peer name is not enough, the peer interface must also be defined and set the first one as its peer. The general configuration structure for virtual Ethernet is shown below.

network:
  virtual-ethernets:
    veth0:
      peer: veth1
    veth1:
      peer: veth0

When applied, two virtual interfaces called veth0 and veth1 will be created in the system.

Virtual Ethernet devices act as tunnels forwarding traffic from one interface to the other. They can be used to connect two separate virtual networks such as network namespaces and bridges. It’s not possible to move virtual-ethernets to different namespaces through Netplan at the present moment.

The specific settings for virtual-ethernets are defined below.

Below is a complete example that uses a pair of virtual Ethernet devices to create a link between two bridges:

network:
  version: 2
  renderer: networkd
  virtual-ethernets:
    veth0-peer1:
      peer: veth0-peer2
    veth0-peer2:
      peer: veth0-peer1

  bridges:
    br0:
      interfaces:
        - veth0-peer1
    br1:
      interfaces:
        - veth0-peer2

Properties for device type vlans

Status: Optional.

Purpose: Use the vlans key to create VLAN interfaces.

Structure: The key consists of a mapping of VLAN interface names. The interface used in the link option (enp5s0 in the example below) must also be defined in the Netplan configuration. The general configuration structure for VLANs is shown below.

network:
  vlans:
    vlan123:
      id: 123
      link: enp5s0
      dhcp4: yes

The specific settings for VLANs are defined below.

Example:

network:
  ethernets:
    eno1: {...}
  vlans:
    en-intra:
      id: 1
      link: eno1
      dhcp4: yes
    en-vpn:
      id: 2
      link: eno1
      addresses: [...]

Properties for device type vrfs

Status: Optional.

Purpose: Use the vrfs key to create Virtual Routing and Forwarding (VRF) interfaces.

Structure: The key consists of a mapping of VRF interface names. The interface used in the link option (enp5s0 in the example below) must also be defined in the Netplan configuration. The general configuration structure for VRFs is shown below.

network:
  renderer: networkd
  vrfs:
    vrf1:
      table: 1
      interfaces:
        - enp5s0
      routes:
        - to: default
          via: 10.10.10.4
      routing-policy:
        - from: 10.10.10.42

Example:

network:
  vrfs:
    vrf20:
      table: 20
      interfaces: [ br0 ]
      routes:
        - to: default
          via: 10.10.10.3
      routing-policy:
        - from: 10.10.10.42
    [...]
  bridges:
    br0:
      interfaces: []

Properties for device type nm-devices

Status: Optional. Its use is not recommended.

Purpose: Use the nm-devices key to configure device types that are not supported by Netplan. This is NetworkManager specific configuration.

Structure: The key consists of a mapping of NetworkManager connections. The nm-devices device type is for internal use only and should not be used in normal configuration files. It enables a fallback mode for unsupported settings, using the passthrough mapping. The general configuration structure for NM connections is shown below.

network:
  version: 2
  nm-devices:
    NM-db5f0f67-1f4c-4d59-8ab8-3d278389cf87:
      renderer: NetworkManager
      networkmanager:
        uuid: "db5f0f67-1f4c-4d59-8ab8-3d278389cf87"
        name: "myvpnconnection"
        passthrough:
          connection.type: "vpn"
          vpn.ca: "path to ca.crt"
          vpn.cert: "path to client.crt"
          vpn.cipher: "AES-256-GCM"
          vpn.connection-type: "tls"
          vpn.dev: "tun"
          vpn.key: "path to client.key"
          vpn.remote: "1.2.3.4:1194"
          vpn.service-type: "org.freedesktop.NetworkManager.openvpn"

Back end-specific configuration parameters

In addition to the other fields available to configure interfaces, some back ends may require to record some of their own parameters in Netplan, especially if the Netplan definitions are generated automatically by the consumer of that back end. Currently, this is only used with NetworkManager.