Consolidate YAML network configuration across Ubuntu

Registered by Martin Pitt on 2016-06-13

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 /e/n/*.yaml and writes configuration to /run to hand off control of devices to the specified networking daemon.
- Wifi and WWAN get managed by NetworkManager
- Any other configured devices get handled by networkd by default, unless explicitly marked as managed by a specific manager (NetworkManager)
- Devices not covered by the network config do not get touched at all.
- Usable in initramfs (few dependencies and fast)
- No persistent generated config, only original YAML config
- Default policy applies with no config file present
- Parser supports multiple config files to allow applications (libvirt, lxd) to package up expected network config (virbr0, lxdbr0), or to change the global default policy to use NetworkManager for everything.
- Retains the flexibility to change backends/policy later or adjust to “apt purge network-manager” as generated configuration is ephemeral

Blueprint information

Steve Langasek
Martin Pitt
Needs approval
Mathieu Trudel-Lapierre
Pending Approval
Series goal:
Accepted for yakkety
Good progress
Milestone target:
milestone icon ubuntu-16.09
Started by
Martin Pitt on 2016-06-20


Launchpad project with code:

v1 YAML reference (for feature parity):


Work Items

Work items for ubuntu-16.07:
[cyphermox] NetworkManager: ship restricted policy (unmanaged-devices=except:type:wifi,except:type:wwan) by default in the .deb, so that it DTRT on servers, cloud, etc: DONE
[cyphermox] NetworkManager: on upgrades, revert the restricted policy in postinst, to avoid breaking running servers and desktop: DONE
write the YAML specification, announce for public discussion/review: DONE
implementation: change the default policy globally or a by-type level: DONE
implementation: merging of multiple YAML files: DONE
implementation: general YAML parsing and structure: DONE
implementation: type ethernet: DONE
implementation: type bridge: DONE
implementation: disallow name globbing with NM (not supported): DONE
implementation: add gcov and code coverage: DONE
implementation: type wifi: DONE
implementation: add manual addresses: DONE
package and land in Yakkety: DONE

Work items for ubuntu-16.08:
discuss YAML syntax for VLANS (new device type with mandatory "id" and "link" fields): DONE
write MIR (#1608926) and seed: DONE
add "netplan apply" verb for applying changes in-place: DONE
make "netplan apply" get along with interface renaming: DONE
read config from /run/netplan/ for one-shot tests (copy to /run, apply, if still online → copy to /etc/): DONE
read config from /lib/netplan/ for policies shipped in packages: DONE
add "ifupdown-migrate" command to convert simple /etc/network/interfaces{,.d} to netplan: DONE
implementation: add dhcp6: DONE
implementation: add gateway for manual addresses: DONE
implementation: type vlan: DONE
implementation: type bond: DONE
disable NM's 10-globally-managed-devices.conf if global renderer is set to NM: DONE
livecd-rootfs: disable restricted NM policy on desktop+touch (via YAML config), so that NM manages all devices there (needs bug 1614043 fixed first): DONE
ubiquity: clean up obsolete and no-op /etc/network/interfaces and /etc/iftab code: DONE

Work items for ubuntu-16.11:
implementation: add nameservers: DONE

Work items for ubuntu-16.12:
create syntax proposal for arbitrary routes, discuss with MaaS/server/cyphermox/mwhudson: DONE
[cyphermox] implementation: add routes: DONE

Work items for ubuntu-17.01:
[cyphermox] implement bond features from v1 YAML: DONE
[cyphermox] implement bridge features from v1 YAML: DONE

Work items for ubuntu-17.02:
[raharper] cloud-init: allow v2 yaml to be specified in userdata, pass it through, deprecate v1: INPROGRESS
[raharper] port MaaS/curtin to pass-through v2 YAML: TODO
[cyphermox] release netplan 0.17 with bond & bridge: DONE
[cyphermox] move up interface into a bridge with keeping the connection (needs fixed): BLOCKED
[cyphermox] automatically enable ifupdown migration on upgrades from earlier Ubuntu releases (after all installers got updated to emit netplan): BLOCKED
[cyphermox] update d-i (netcfg) to move from ifupdown to YAML: POSTPONED