Using netplan gives a central location to describe simple-to-complex networking configurations that function from desktop to server and from cloud to IoT devices. Specifically, for systems with networkd, this relieves the user from having to configure up to three different files per device or configuration.
Users should save configurations under /etc/netplan with a .yaml extension (e.g. /etc/netplan/config.yaml).
Then run sudo netplan apply and the configuration is parsed, written, and applied to the system. Since the file is written to disk the the configuration will persist between reboots.
If a user wishes to verify that a configuration file is valid it is recommended to first pass the configuration through a YAML syntax validator. This is done to validate the syntactic validity of the file.
Next, a user can run sudo netplan generate to validate the configuration is correctly parsed by netplan and written to disk. However, be warned that once generated the new configuration is written to disk the configuration is activated on next boot. Therefore, backing up a current working configuration is highly recommended.
Configuration files can exist in three different locations with the precedence from most important to least as follows:
Alphabetically later files, no matter what directory in, will amend keys if the key does not already exist and override previous keys if they do.
Previously users were used to using the ifconfig command. Users should now familiarize themselves with the more powerful ip command. Manually modifying network devices is now accomplished via the ip command.
As an example to bring up an interface and bring it back down:
ip link set enp3s0 up
ip link set enp3s0 down
See man ip for more information on how to manipulate the state of routing, network devices, interfaces and tunnels.
Interfaces that are not required for booting or should not be waited on during boot should have the optional: true key added to them. This will prevent long delays in booting for interfaces that may not come up.
Netplan is only meant to translate configuration into the appropriate files for the backend specified. It does not display IP information by itself, since it does not manage those by itself.
To get the most accurate state of the IP addresses for the system using the ip addr command.
To determine the current DNS servers used by the system run systemd-resolve --status (or resolvectl in 18.04 and higher) and look for the 'DNS Servers:' entry to see what DNS server is used.
To deconfigure an interface, remove the configuration for the device from the netplan .yaml file and run sudo netplan apply.
Note: netplan apply does not remove virtual devices, such as bridges and bonds, that have been created, even if they are no longer described in the Netplan configuration. That is because Netplan operates statelessly and is not aware of the previously defined virtual devices.
If the interface is not configured in a .yaml file in the /etc/netplan directory, it is not configured at boot. To remove an interface manually at runtime, run ip link del dev <interface>.
Alternatively, create a temporary backup of the YAML state in /etc/netplan: mkdir -p /tmp/old_state/etc && cp -r /etc/netplan /tmp/old_state/etc/. After creating such state, remove the interface from /etc/netplan using, for example: rm /etc/netplan/interface-to-delete.yaml, and then apply the original state: netplan apply --state /tmp/old_state
Users of ifupdown may be familiar with using hook scripts (e.g pre-up, post-up, etc.) in their interfaces file. Netplan configuration does not currently support hook scripts in its configuration definition.
Instead to achieve this functionality with the networkd renderer users can use networkd-dispatcher. The package provides users and legacy packages hook points when specific network states are reached to aid in reacting to network state. Below is a table mapping networking states and hooks available:
| Hook | ifupdown | NetworkManager | networkd-dispatcher |
|---|---|---|---|
| pre-up | if-pre-up.d | pre-up.d | no-carrier.d * dormant.d * carrier.d * configuring.d * |
| post-up | if-up.d | up.d | degraded.d * routable.d * configured.d * |
| pre-down | if-down.d | pre-down.d | N/A ** |
| post-down | if-post-down.d | down.d | off.d * |
Note that systemd-networkd is tracking the “pre-up” and “post-up” states in finer granularity. It is recommended to make use of the “configuring.d” and “routable.d” hooks accordingly. A detailed definition of the other operational/setup states can be found at networkctl(1).
* In networkd-dispatcher, the hooks run asychronous; that is they will not block transition into another state.
** systemd-networkd does not keep an internal state, but uses the kernel’s internal netlink state. Therefore, it cannot know about a “pre-down” state, once netlink reports an interface to be down (i.e. “ip link set eth0 down”) the interface is considered off and the off.d hooks are triggered. There is not other information or D-Bus property available, other than the netlink state.
See the example below and man networkd-dispatcher for more information.
The following is an example of using networkd-dispatcher to run existing ifup hooks via a script installed in /etc/networkd-dispatcher/routable.d/50-ifup-hooks:
#!/bin/sh
for d in up post-up; do
hookdir=/etc/network/if-${d}.d
[ -e $hookdir ] && /bin/run-parts $hookdir
done
exit 0
Similarly, here is an example of an ifdown hook installed in /etc/networkd-dispatcher/off.d/50-ifdown-hooks:
#!/bin/sh
for d in down post-down; do
hookdir=/etc/network/if-${d}.d
[ -e $hookdir ] && /bin/run-parts $hookdir
done
exit 0
First, if netplan does not have the features or functionality for a particular use-case we would really like to know about it. Please help us and the community by filing a bug against netplan on Launchpad.
On a running system, netplan can be removed by installing ifupdown, configuring /etc/network/interfaces manually as users have done before and finally removing the netplan.io package altogether. To apply the new setup without rebooting, users can restart the affected interfaces (i.e. using the ifdown/ifup commands) and then stop/disable the systemd-networkd and systemd-networkd.socket units respectively.
At install time, a user can opt to use ifupdown by preseeding netcfg/do_not_use_netplan=true. This is done by adding the preseed line to the command line when booting the installation media (i.e. at install media boot menu, press F6, type 'e', and add to the command line).
When debugging Netplan first verify the YAML used to setup the configuration. Review and collect all *.yaml files under /lib/netplan/, /etc/netplan/, and /run/netplan/. Ensure that the files are indeed accurately describing the expected configuration (e.g. correct adapter name, correct subnets, valid YAML).
Next, searching or asking a question on Ask Ubuntu for a variety of community support, ask on the networking sub-forum of the Ubuntu Forums, or stop by the #netplan IRC channel on Libera Chat to ask questions.
Also available are a couple Ubuntu wiki pages that provide general Network help and a page on how to capture Network Manager logs to aid in filing a bug.
Finally, if there is a bug use the links at the bottom of the page to report a bug with Netplan.