Netplan by example

netplan is the default network configuration system for new installs of Ubuntu 18.04 (Bionic).

It uses YAML to configure network interfaces, instead of /etc/network/interfaces. I've been testing netplan for a while, so in light of the release of Bionic, here's my set of examples, caveats, tips and tricks.

Contents

• General tips and tricks
• Matching
• Basic IPv4 configuration
• MTUs
• Bridges, Bonds and VLANs
• Wifi
• IPv6
• Supplementing or replacing netplan
• Going Further

General tips and tricks

• Tabs are not allowed in YAML and currently you get a very useless error message if you use them: "Invalid YAML at //etc/netplan/10-bridge.yaml line 5 column 0: found character that cannot start any token". If you see this, check for tabs!
• Indentation matters in YAML. Make sure that things line up where they're supposed to.
• Rebooting is somewhat more reliable than netplan apply, but make sure there are no errors in your YAML before you reboot or no network interfaces will come up. (netplan generate is handy for checking)

Matching

To tell netplan about a device, you need to tell it how to locate that device. This used to be done by name in the ifupdown world, but in netplan this is done with a match stanza. For example, to match a device with a particular MAC:

network:
    version: 2
    ethernets:
        ens3:
            match:
                macaddress: 52:54:00:f0:bc:02
            dhcp4: true

In the old world you'd match by the name ens3 and not specify a MAC. This is not how netplan works - in netplan what matters is the match stanza.

Always use MAC addresses to specify your ethernet devices. You can match in other ways, but don't. Specifically, don't match by name, a world of weird bugs awaits.

The Basics (IPv4)

This is well covered online, but for completeness, a static address and gateway can be configured like so:

network:
    version: 2
    ethernets:
        ens8:
            match:
                macaddress: 52:54:00:f9:e9:dd
            addresses: [10.10.10.2/24]
            gateway4: 10.10.10.1

Multiple IPs can be specified:

network:
    version: 2
    ethernets:
        ens8:
            match:
                macaddress: 52:54:00:f9:e9:dd
            addresses: 
                - 10.10.10.2/24
                - 192.168.123.12/24
            gateway4: 10.10.10.1

And you can use DHCP and static IPs together - this will give an interface both static and dynamic address:

network:
    version: 2
    ethernets:
        ens3:
            match:
                macaddress: 52:54:00:f0:bc:02
            addresses: [10.10.10.123/24]
            dhcp4: true

MTUs

This is a common source of pain, and I've posted about it before. In short, always match by MAC address and you should be fine.

network:
    version: 2
    ethernets:
        ens3:
            dhcp4: true
            match:
                macaddress: 52:54:00:f0:bc:02
            mtu: 1280

For virtual devices, I've had most success setting the MTUs on the underlying devices and making sure they are matched by MAC.

Bridges, Bonds and VLANs

This is generally well documented on the netplan examples page at netplan.io.

One thing that is not well documented is anonymous bridges - bridges that do not have their own IP addresses. This requires a bit of a hack at the moment, see Anonymous bridges in netplan.

Wifi

See the examples on netplan.io or my post Connecting to a wifi network with netplan.

IPv6

This is a big topic - for full details on setting it up see this post. 

To disable IPv6 autoconfiguration, you can turn off accept-ra like so:

network:
    version: 2
    ethernets:
        ens3:
            dhcp4: true
            match:
                macaddress: 52:54:00:f0:bc:02
            accept-ra: false

Note that this won't immediately remove any existing IPv6 addresses, nor will it prevent the creation of a link-local address (the fe80:: addresses). To disable IPv6 completely for an interface, use sysctl.

Supplementing or replacing netplan

Getting ifupdown back is easy: apt install ifupdown. Netplan and ifupdown can coexist, or you can remove netplan: the package is netplan.io.

You can also take advantage of the fact that netplan just generates systemd-networkd or NetworkManager files and use it as a jumping off point for direct configuration of those backends. netplan puts the generated files in /run - for systemd-networkd it's /run/systemd/network/. You can, for example, copy the files for an interface to /etc/systemd/network, configure the interface there and then remove it from netplan.

Going Further

• There is a lot of information in the man page: man netplan, 
• A nice selection of examples and other information is at netplan.io. 
• #netplan on Freenode
• Code at GitHub - CanonicalLtd/netplan