What is it

Netplan is a YAML network configuration abstraction for various backends (NetworkManager, networkd).

It is a utility for easily configuring networking on a system. It can be used by writing a YAML description of the required network interfaces with what they should be configured to do. From this description it will generate the required configuration for a chosen renderer tool.

Netplan reads network configuration from /etc/netplan/*.yaml which are written by administrators, installers, cloud image instantiations, or other OS deployments. During early boot it then generates backend specific configuration files in /run to hand off control of devices to a particular networking daemon.

Supported renderers

• NetworkManager

• systemd-networkd

The default renderer, if otherwise unspecified, is systemd-networkd.

How do I use it?

Commands

Netplan uses a set of subcommands to drive its behavior:

• netplan generate: Use /etc/netplan to generate the required configuration for the renderers.

• netplan apply: Apply all configuration for the renderers, restarting them as necessary.

• netplan ifupdown-migrate: Attempt to generate an equivalent configuration to what is specified in /etc/network/interfaces.

Configuration

Obviously, without configuration, netplan will not do anything. The most useful configuration snippet (to bring up things via dhcp) is as follows:

network:
  version: 2
  renderer: NetworkManager

This will make NetworkManager manage all devices (and by default, any ethernet device will come up with DHCP once carrier is detected).

Using networkd as a renderer does not let devices automatically come up using DHCP; each interface needs to be specified in a file in /etc/netplan for its configuration to be written and for it to be used in networkd.

Getting help

Frequently-asked questions

How do I bring interfaces up or down?

While we recommend that people do not change the state of network interfaces without a good reason and simply let the renderer configured in netplan handle the network interfaces it is meant to configure, you can always modify interface settings manually via the ip command.

To bring up an interface:

ip link set eth0 up

To bring and interface down:

ip link set eth0 down

See man ip for more information on how you can manipulate the state of network interfaces.

How can I look up the currently applied addresses for my system?

Netplan is only meant to translate configuration into the appropriate files for the backend you want to use. It does not display IP information by itself, since it does not manage those by itself.

You can always get the most accurate state of the IP addresses for your system using the ip addr command.

How can I add pre-up, post-up, etc. hook scripts?

While the netplan configuration does not include support for hook scripts, you can add systemd unit jobs with the appropriate Requires: and After: fields to run arbitrary commands once the network is up.

The same is possible with NetworkManager by writing a script watching for the right event in /etc/NetworkManager/dispatcher.d. See the NetworkManager(8) manpage for details.

I really do need ifupdown, can I still use it?

If you run into a case where you do need to use ifupdown instead of netplan, we would really like to know about it, so you should file a bug in Launchpad.

While we don't recommend doing so, you can remove netplan and install ifupdown after install, and fill in /etc/network/interfaces manually to configure your network the way you want it.

You can also opt to use ifupdown instead of netplan at installation by preseeding netcfg/do_not_use_netplan=true (adding it the the command-line when you boot the Ubuntu Server installation media, in grub (when you see the menu hit "e" to edit; or in the bootsplash by hitting F6). This will fallback to installing ifupdown and configuring it for the network devices set up during the installation.

Documentation

Help for netplan is always available on Ubuntu systems through the man 5 netplan command.

Also, online HTML documentation is available here: http://people.canonical.com/~mtrudel/netplan/

IRC

Netplan developers are reachable on IRC on the Freenode network, in the channel #netplan.

How can I contribute?

Netplan is developed using git on Launchpad, and uses merge proposals.

You can find the source code here: https://code.launchpad.net/netplan

The main Launchpad project page is here: https://launchpad.net/netplan

We try to stick to an agreed-upon design document; see Netplan Design