Skip to main content

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

  • 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

Comments

  1. _why_ netplan.io makes no mention of the match stanza on most examples? This is crazy! I've been trying to get a config to work for several MONTHS and it wasn't working as expected and when it did work it was very unstable. No tutorial fixed it and I've been dealing with this for MONTHS. I added the match stanza and now it's working as expected. Thank you so much!

    ReplyDelete

Post a Comment

Popular posts from this blog

Connecting to a wifi network with netplan

How do you connect to a a wifi network with netplan? I hang out on the #netplan IRC channel on Freenode, and this comes up every so often. netplan - the default network configuration tool in Ubuntu 17.10 onwards - currently supports WPA2 Personal networks, and open (unencrypted) networks only. If you need something else, consider using NetworkManager directly, or falling back to ifupdown and wpa_supplicant for a little longer. Without further ado, here are tested, working YAML files for connection to my local WPA2 and unencrypted network. The only things that have been changed are the SSIDs and password. Both networks have a router providing dhcp4. In both cases I assume there's only one wifi device in the system - if this is not true, replace match: {} with something more specific. You can drop these in  /etc/netplan and run netplan generate; netplan apply  and things should work. The network will also be brought up on subsequent boots. Note that, as always in YAML, ind

Anonymous bridges in netplan

netplan is the default network configuration system for new installs of Ubuntu 18.04 (Bionic). Introduced as the default in Artful, it replaces /etc/network/interfaces . One question that gets asked repeatedly is: "How do I set up an anonymous bridge in netplan?" (An anonymous bridge, I discovered, is one where the bridge doesn't have an IP address; it's more akin to a switch or hub.) It's been approached on  Launchpad , and comes up on the IRC channel. If you're trying to create a bridge without an IP address, the obvious first thing to try is this: network: version: 2 ethernets: ens8: match: macaddress: 52:54:00:f9:e9:dd ens9: match: macaddress: 52:54:00:56:0d:ce bridges: br0: interfaces: [ens8, ens9] This is neat, plausible, and wrong - the bridge will be created but will stay 'down'. Per ip a : 5: br0: <BROADCAST,MULTICAST> mtu 15