"Netplan reference"

Top-level configuration structure

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

network:
  version: NUMBER
  renderer: STRING
  bonds: MAPPING
  bridges: MAPPING
  ethernets: MAPPING
  modems: MAPPING
  tunnels: 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 Wifi 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 behavior overrides are available. Most currently only have any effect when using the networkd backend, 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 backend 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 backend, 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 backend.

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 wifi interfaces, as well as individual wifi 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 Ethernets 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 backend. 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 WiFi access points.

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

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

Note that systemd-networkd does not natively support wifi, so you need wpasupplicant installed if you let the networkd renderer handle wifi.

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 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
      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. Please see https://en.wikipedia.org/wiki/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 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"

Backend-specific configuration parameters

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