Netplan Design
From:     https://netplan.io/design


Design Key Goals Requirements Design Overview
Network Config Format General Structure Device Cofig IDs Physical Devs
Virtual Devs Commands Use Cases Discovery (Subiquity)
Data Oracle (cloud-init, MAAS, Gadget snap) Device Add Using a Previously Configed Dev Update Network Config on PKG Install
Device Config Removal 



Netplan design

There are central network config files for Snappy, Server, Client, MAAS, 
cloud-init in /etc/netplan/*.yaml. All installers only generate such a file, no
/etc/network/interfaces any more. There is also a netplan command line tool to 
drive some operations.

Systems are configured during early boot with a "network renderer" which reads 
/etc/netplan/*.yaml and writes configuration to /run to hand off control of 
devices to the specified networking daemon.




Key goals




Requirements




Design overview






Network Config format

This is called "version 2", as current MAAS/curtin already use a different YAML 
format that is called "version 1".




General structure

The top-level node 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:", "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.

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




Physical devices

Examples: ethernet, wifi

These can dynamically come and go between reboots and even during runtime 
(hotplugging). 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.

With specific knowledge (taken from the admin, a gadget snap, etc.), or by using
unique properties such as path or MAC, match rules can be written so that they 
only match one device. Then the "set-name:" property can be used to give that 
device a more specific/desirable/nicer name than the default from udev's 
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).

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 we have done network device configuration
since the mists of 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

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.
Complex example

This shows most available features that are planned for the initial 16.10 
implementation:

network:
  version: 2

  # if specified globally, can only realistically have that value, as
  # networkd cannot render wifi/3G. This would be shipped as a separate
  # config.d/ by desktop images
  # it can also be specified by-type or by-device
  renderer: network-manager
  ethernets:
    # opaque ID for physical interfaces with match rules
    # only referred to by other stanzas
    id0:
      match:
        macaddress: 00:11:22:33:44:55
      wakeonlan: true
      dhcp4: true
      addresses:
        - 192.168.14.2/24
        - 2001:1::1/64
      lom:
        # example for explicitly setting a backend (default would be networkd)
        match:
          driver: ixgbe
        # you are responsible for setting tight enough match rules
        # that only match one device if you use set-name
        set-name: lom1
        dhcp6: true
      switchports:
        # all cards on second PCI bus
        # unconfigured by themselves will be added to br0 below
        match:
          name: enp2*
        mtu: 1280
    wifis:
      all-wlans:
      # useful on a system where you know there is
      # only ever going to be one device
      match: {}
      access-points:
        "Joe's home":
          # mode defaults to "managed" (client), key type to wpa-psk
          password: "s3kr1t"
      # this creates an AP on wlp1s0 using hostapd
      # no match rules, thus ID is the interface name
      wlp1s0:
        access-points:
          "guest":
            mode: ap
            channel: 11
            # no WPA config implies default of open
    bridges:
      # the key name is the name for virtual (created) interfaces;
      # no 'match' or 'set-name' attributes are allowed.
      br0:
        # IDs of the components
        # switchports expands into multiple interfaces
        interfaces: [wlp1s0, switchports]
        dhcp4: true
      routes:
        - to: 0.0.0.0/0
        via: 11.0.0.1
        metric: 3
      nameservers:
        search: [foo.local, bar.local]
        addresses: [8.8.8.8]
    




Commands



	



Use cases

Some of the possible ways of using netplan are captured below.




Discovery (Subiquity)

Cathy boots the latest Ubuntu Server Image on her Intel NUC via USB key. The 
NUC has both a wired ethernet port and a wireless NIC builtin and has added a 
third USB-NIC as well, though it's not currently connected. During the 
installation, the installer presents Cathy with the 3 interfaces. Cathy selects
the wired ethernet device; it was the only one with an IP configured via DHCP. 
After the installation is complete Cathy reboots her NUC and finds the followin
in /etc/netplan/01-install.yaml:

network:
  version: 2
  ethernets:
    # configured by subiquity
    eno1:
      dhcp4: true

The installer wrote out a config which included elements for the explicitly 
chosen/configured wired device. The other NICs are unconfigured, as the 
installer should not make any assumptions about their future usage or 
configuration.




Data oracle (cloud-init, MAAS, gadget snap)

A user creates a cloud-init userdata file for a cloud instance that will get two
network cards attached. That cloud-init file contains a network definition that 
configures a bond device from these two.

The gadget snap for a router specifies that all ethernet interfaces on the 
second PCI bus belong to the builtin switch, and configures a bridge for them. 
The other ethernet interface is renamed to "eth-uplink" to provide a more 
specific and useful name for it.

In general there are many situations where users (via the installer), hardware 
vendors, or cloud management software can make assumptions about the nature, 
number, and purpose of network interfaces -- these should be expressible in 
terms of specific interface names and vendor-provided configuration for them.




Device Add

Alice plugs a USB nic into her Intel NUC after installing Ubuntu Server. The 
default policy for server uses networkd, and does not attempt to do any 
networking configuration for devices that are not already present in 
/etc/netplan/.




Using a previously configured device

Sally plugs in USB NIC that previously had been configured and expects that it 
retains the same configuration despite being connected in a different port.

On device removal, no config change has been made. If the server was rebooted, 
then when processing e/n/c, we will write out the config again in /run/network,
including MATCH rules for .LINK to retain the name and likely the same MATCH 
rules .NETWORK to apply the same config.

(Note: This behaviour is already how NM/networkd/ifupdown etc. behave -- this 
use case is just for a complete behaviour description.)




Update network config on package install

lxd, libvirt, and others might include network config by shipping a 
/{etc,lib}/netplan/*.yaml snippet, for e. g. setting up a bridge (virbr0, 
lxdbr0).




Device configuration removal

Alice is done with the usb0 device that was added and now wants to purge the 
configuration from the system.