netplan commands: the missing manuals

What do netplan apply, netplan generate, and netplan try do? The netplan man page just talks about the YAML configuration file format and don't describe the commands. So consider this a set of draft manpages - my hope is that it will fill in the gaps. I will try to get them merged to the main repository.

Background

To understand the netplan commands, it's helpful to know the very basics of the netplan design.

Using netplan is a 2 step process:

1. Netplan takes YAML files - usually from /etc/netplan/*.yaml - and converts them into configuration that is read by a backend. 
2. This backend interacts with the kernel to actually configure the devices.

Netplan currently supports systemd-networkd and NetworkManager as backends. So it will convert your configuration into the configuration that they read, and then they will actually apply it to the machine. Netplan doesn't do any configuration itself.

With this in mind, we can understand the components

netplan generate

NAME

netplan generate - generate backend configuration from netplan YAML files

SYNOPSIS

    netplan [--debug] generate -h | --help
    netplan [--debug] generate [--root-dir ROOT_DIR] [--mapping MAPPING]

DESCRIPTION

netplan generate converts netplan YAML into configuration files understood by the backends (systemd-networkd or NetworkManager).

You will not normally need to run this directly as it is run by netplan apply or at boot.

OPTIONS

•  -h, --help: Print basic help.
• --debug: Print debugging output during the process.
• --root-dir ROOT_DIR: Instead of looking in /{lib,etc,run}/netplan, look in /ROOT_DIR/{lib,etc,run}/netplan
• --mapping MAPPING: Instead of generating output files, parse the configuration files and print some internal information about the device specified in MAPPING.

HANDLING MULTIPLE FILES

There are 3 locations that netplan generate considers:

• /lib/netplan/*.yaml
• /etc/netplan/*.yaml
• /run/netplan/*.yaml

Multiple files are considered as follows.

If there are multiple files with exactly the same name, then only one will be read. This process is called shadowing. A file in /run/netplan will shadow - completely replace - a file with the same name in /etc/netplan. A file in /etc/netplan will itself shadow a file in /lib/netplan. Or in other words, /run/netplan is top priority, then /etc/netplan, with /lib/netplan at the bottom of the heap.

If there are files with different names, then they are considered in lexicographical order - regardless of the directory they are in - and later files update earlier files. So 10-foo.yaml will be updated by 20-abc.yaml.

In updating, if you have two of the same key/setting, the following rules apply:

• If the values are YAML 'scalar' values - e.g. booleans, numbers and strings - the old value is overwritten by the new value.
• If the values are lists, the lists are concatenated - the new values are appended to the old list.
• If the values are dictionaries, netplan will examine the elements of the dictionaries in turn using these rules.

netplan apply

NAME

netplan apply - apply configuration from netplan YAML files to a running system

SYNOPSIS

    netplan [--debug] apply -h | --help
    netplan [--debug] apply

DESCRIPTION

netplan apply regenerates backend configuration (i.e. does a generate step), and then tells backends to apply it to the running system.

OPTIONS

•  -h, --help: Print basic help.
• --debug: Print debugging output during the process.

DISCUSSION

netplan apply may unbind network interfaces that are down from the drivers and rebind them. This gives udev renaming rules an opportunity to run, and therefore is helpful for matches by name. Note that this process is not always robust and may lead to devices disappearing or being unexpectedly renamed.

netplan apply will also not remove virtual devices (e.g. bridges and bonds) that have been created, even if they are no longer described in the netplan configuration.

In both of these cases the problems can be avoided or resolved by rebooting.

netplan try

NAME

netplan try - try a configuration, optionally rolling it back

SYNOPSIS

    netplan [--debug] try -h | --help
    netplan [--debug] try [--config-file CONFIG_FILE] [--timeout TIMEOUT]

DESCRIPTION

netplan try allows a configuration to be tested and automatically rolled back if the user does not confirm within 120 seconds. This is especially useful on remote systems as (absent bugs) it will prevent an administrator from being permanently locked out of systems in the case of a network configuration error.

OPTIONS

•  -h, --help: Print basic help.
• --debug: Print debugging output during the process.
• --config-file CONFIG_FILE: In addition to the usual configuration, apply CONFIG_FILE.
• --timeout TIMEOUT: Wait for TIMEOUT seconds before reverting. Defaults to 120. Note that some network configurations (e.g. STP) may take over a minute to settle.

DISCUSSION

netplan try has all the same caveats that netplan apply has - as it uses the same procedures. It also has some known bugs, so make sure to check if the resulting network configuration has in fact been reverted!

Minor commands

There are a couple of minor commands that probably don't deserve man pages but might be handy to know about.

netplan ip leases

This prints some info on current IP address leases.

ifupdown-migrate

There is a (currently hidden) ability to migrate simple ifupdown (/etc/network/interfaces) configurations to equivalent netplan configurations. To explore this, run: ENABLE_TEST_COMMANDS=1 netplan migrate -h

Be warned that:

• the scope of supported configurations is pretty small
• by default, if migration succeeds, this will disable your old ifupdown configuration. It's not lost, just moved aside and disabled. --dry-run is your friend.