Friday 5 May 2017

Quick and easy network configuration with Netplan

Earlier this week I uploaded netplan 0.21 in artful, with SRUs in progress for the stable releases. There are still lots of features coming up, but it's also already quite useful. You can already use it to describe typical network configurations on desktop and servers, all the way to interesting, complicated setups like bond over a bridge over multiple VLANs...

Getting started

The simplest netplan configuration might look like this:

# Let NetworkManager manage all devices on this system
  version: 2
  renderer: NetworkManager
At boot, netplan will see this configuration (which happens to be installed already on all new systems since 16.10) and generate a single , empty file: /run/NetworkManager/conf.d/10-globally-managed-devices.conf. This tells the system that NetworkManager is the only renderer for network configuration on the system, and will manage all devices by default.

Working from there: a simple server

Let's look at it on a hypothetical web server; such as for my favourite test:

  version: 2
      dhcp4: true
This incredibly simple configuration tells the system that the eth0 device is to be brought up using DHCP4. Netplan also supports DHCPv6, as well as static IPs, setting routes, etc.

Building up to something more complex

Let's say I want a team of two NICs, and use them to reach VLAN 108 on my network:

              version: 2
                  dhcp4: n
                  mtu: 1280
                  dhcp4: n
                  - eth1
                  - eth0
                  mtu: 9000
                  link: bond0
                  id: 108

I think you can see just how simple it is to configure even pretty complex networks, all in one file. The beauty in it is that you don't need to worry about what will actually set this up for you.

A choice of backends

Currently, netplan supports either NetworkManager or systemd-networkd as a backend. The default is to use systemd-networkd, but given that it does not support wireless networks, we still rely on NetworkManager to do just that.

This is why you don't need to care what supports your config in the end: netplan abstracts that for you. It generates the required config based on the "renderer" property, so that you don't need to know how to define the special device properties in each backend.

As I mentioned previously, we are still hard at work adding more features, but the core is there: netplan can set up bonds, bridges, vlans, standalone network interfaces, and do so for both static or DHCP addresses. It also supports many of the most common bridge and bond parameters used to tweak the precise behaviour of bonded or bridged devices.

Coming up...

I will be adding proper support for setting a "cloned" MAC on a device. I'm reviewing the code already to do this, and ironing out the last issues.

There are also plans on better handling administrative states for devices; along with a few bugs that relate to support MaaS, where having a simple configuration style really shines.

I'm really excited for where netplan is going. It seems like it has a lot of potential to address some of the current shortcomings in other tools. I'm also really happy to hear of stories of how it is being used in the wild, so if you use it, don't hesitate to let me know about it!


All of the work on netplan happens on Launchpad. Its source code is at; we always welcome new contributions.


Hi-Angel said...

netplan vs Network Manager — what's the difference? E.g. why not just migrate to Network Manager? I thought the idea behind NM is pretty much the same: unification of `ifconfig`, `iwconfig`, `xl2tpd-control`, etc into a single `nmcli`.

Matt Trudel said...

You don't have to use NetworkManager with netplan; but you can. The difference is that NetworkManager is a real network management system, whereas netplan is an abstraction of those, so that you can control, say, one system that runs NetworkManager, and another that uses systemd-networkd instead, all using the exact same syntax; you don't need to learn the different configuration files syntaxes and nomenclature.

systemd-networkd gets you some pretty good integration with the rest of the boot process when you need to deal with fairly simple configurations that must come up at boot; whereas NetworkManager has a lot of flexibility to handle wifi, VPNs, etc. and things changing during the running time of the system.

netplan just goes around both to keep you from looking at many different manpages and documentation websites, so the same config can work on either systemd-networkd or NetworkManager.

Unknown said...

Does the project Netplan support the syntax of Open vSwitch?

Stephen Boston said...

Thank you for this post.
With 17.10, Ubuntu is withdrawing ifup/down so configuration of static IPs is not available through the network interfaces file. Netplan is the way.
I like it but it took a lot of tries to get a plan up. Your examples showed me a more economical syntax.

I use VBox with two network interfaces and I haven't managed to get that working yet. So far my only success has been using two yamls. One loads at boot and then I load the other manually. I continue to experiment.

Now in passing I saw somewhere else mentioning that netplan works for wifi in combination with wpa_supplicant.
I avoid NM because I couldn't find a way to avoid keeping the GUI as boss.

Christian said...

Can I just run directly '#netplan apply' to apply the configuration to the renderes or do I have to run '#netplan generate' first?

Navigator Systems said...

This is a simple Network configuration. Does NetPlan support wireless Network?

Matt Trudel said...

Василий Алексеенко: OpenVSwitch was brought up as a possible backend, or to generally have support for it, but other features have taken precedence. I'm happy to review Git pull requests (Netplan is now at, but unfortunately I don't know all that much about openvswitch yet.

Christian: Yes you can! There is no need to run 'netplan generate' first, it's done for you when you run 'netplan apply'.

serverental: Netplan supports wireless in simple forms for now. That means just WPA Personal, using a pre-shared key. This already covers about 80% of uses, just not all of them. We're aware of this limitation, and we'll look at adding better wireless in the future.

Stephen Boston: Some configurations might be harder than others to get right without looking up the documentation. Check out; there's a reference document there that lists all the supported keys to tweak exactly how you want your network to be. We'll add more and better examples on the website too, so if you want to share what you want to do, we can probably cover that as an example!