NAME

netplan - YAML network configuration abstraction for various backends

SYNOPSIS

netplan [ COMMAND | help ]

COMMANDS

See netplan help for a list of available commands on this system.

DESCRIPTION

Introduction

Distribution installers, cloud instantiation, image builds for particular devices, or any other way to deploy an operating system put its desired network configuration into YAML configuration file(s). During early boot, the netplan "network renderer" runs which reads /{lib,etc,run}/netplan/*.yaml and writes configuration to /run to hand off control of devices to the specified networking daemon.

General structure

netplan's configuration files use the YAML http://yaml.org/spec/1.1/current.html format. All /{lib,etc,run}/netplan/*.yaml are considered. Lexicographically later files (regardless of in which directory they are) amend (new mapping keys) or override (same mapping keys) previous ones. A file in /run/netplan completely shadows a file with same name in /etc/netplan, and a file in either of those directories shadows a file with the same name in /lib/netplan.

The top-level node in a netplan configuration file is a network: mapping that contains version: 2 (the YAML currently being used by curtin, MaaS, etc. is version 1), and then device definitions grouped by their type, such as ethernets:, modems:, wifis:, or bridges:. These are the types that our renderer can understand and are supported by our backends.

Each type block contains device definitions as a map where the keys (called "configuration IDs") are defined as below.

Device configuration IDs

The key names below the per-device-type definition maps (like ethernets:) are called "ID"s. They must be unique throughout the entire set of configuration files. Their primary purpose is to serve as anchor names for composite devices, for example to enumerate the members of a bridge that is currently being defined.

(Since 0.97) If an interface is defined with an ID in a configuration file; it will be brought up by the applicable renderer. To not have netplan touch an interface at all, it should be completely omitted from the netplan configuration files.

There are two physically/structurally different classes of device definitions, and the ID field has a different interpretation for each:

Physical devices

(Examples: ethernet, modem, wifi) These can dynamically come and go between reboots and even during runtime (hot plugging). In the generic case, they can be selected by match: rules on desired properties, such as name/name pattern, MAC address, driver, or device paths. In general these will match any number of devices (unless they refer to properties which are unique such as the full path or MAC address), so without further knowledge about the hardware these will always be considered as a group.

It is valid to specify no match rules at all, in which case the ID field is simply the interface name to be matched. This is mostly useful if you want to keep simple cases simple, and it's how network device configuration has been done for a long time.

If there are match: rules, then the ID field is a purely opaque name which is only being used for references from definitions of compound devices in the config.

Virtual devices

(Examples: veth, bridge, bond, vrf) These are fully under the control of the config file(s) and the network stack. I. e. these devices are being created instead of matched. Thus match: and set-name: are not applicable for these, and the ID field is the name of the created virtual device.

Common properties for physical device types

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.

Common 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:

eth0:
  [...]
  routes:
    - to: default # could be 0/0 or 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:

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:

GSM/CDMA modem configuration is only supported for the NetworkManager backend. systemd-networkd does not support modems.

Requires feature: modems

Properties for device type wifis:

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:

Properties for device type bonds:

Properties for device type tunnels:

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.

WireGuard specific keys:

VXLAN specific keys:

Properties for device type vlans:

Example:

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

Properties for device type vrfs:

Example:

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:

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.

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.

SEE ALSO

netplan-generate(8), netplan-apply(8), netplan-try(8), netplan-get(8), netplan-set(8), netplan-dbus(8), systemd-networkd(8), NetworkManager(8)

AUTHORS

Mathieu Trudel-Lapierre (<cyphermox@ubuntu.com>); Martin Pitt (<martin.pitt@ubuntu.com>); Lukas Märdian (<slyon@ubuntu.com>).