Netplan is a declarative network configuration utility for Linux that reads YAML files describing the desired network state and generates configuration for a backend renderer, either systemd-networkd or NetworkManager. In Linux networking, Netplan is the default configuration layer on Ubuntu since release 17.10 and is also used by cloud images that rely on cloud-init.
Netplan itself does not manage interfaces at runtime. It is a translator: it converts one human-readable description into the native format of the chosen renderer, which then brings links up, requests DHCP leases and installs routes. This design gives administrators one configuration syntax for servers, desktops and cloud instances.
How Netplan generates backend configuration
Netplan reads every *.yaml file from `/lib/netplan`, `/etc/netplan` and `/run/netplan`. Files with the same name in a later directory override earlier ones, and all remaining files are merged in lexical order, so 90-local.yaml can extend or override settings from 50-cloud-init.yaml.
The command `netplan generate` writes renderer files into the runtime directory, for example .network and .netdev units under /run/systemd/network or keyfiles for NetworkManager. `netplan apply` generates the files and then instructs the renderer to reconfigure the affected interfaces.
Because generated files live under /run, they are rebuilt at every boot by a systemd generator. Editing the generated files directly is pointless; the YAML in /etc/netplan is the single source of truth.
Structure of a Netplan YAML file
Every file starts with a `network:` root key, a version: 2 declaration and an optional renderer: setting. Devices are grouped by type, and each device carries its addressing, routing and DNS settings. The table lists the main device sections.
| Section | Describes | Typical keys |
|---|---|---|
| ethernets | Physical wired interfaces | match, set-name, dhcp4, addresses |
| wifis | Wireless interfaces | access-points, password |
| bonds | Link aggregation | interfaces, parameters.mode |
| bridges | Software bridges for VMs and containers | interfaces, parameters.stp |
| vlans | 802.1Q tagged subinterfaces | id, link |
| tunnels | GRE, VXLAN, WireGuard and similar | mode, local, remote, keys |
Common per-interface keys include `dhcp4` and `dhcp6`, static addresses in CIDR notation, routes with to and via, nameservers with addresses and search, and mtu. The older `gateway4` key is deprecated; a default route is now written as a route with to: default.
The `match` key selects a physical device by MAC address, driver or name pattern, and set-name renames it, which keeps configuration stable when kernel interface names change between hardware generations.
Choosing a renderer
The renderer decides which daemon actually manages the interfaces. Servers and cloud images normally use systemd-networkd, while desktops and laptops use NetworkManager for its roaming and user interface integration.
| Renderer | Best suited for | Strengths | Limitations |
|---|---|---|---|
| networkd | Servers, cloud, container hosts | Small, fast, predictable | No graphical tools, limited Wi-Fi roaming |
| NetworkManager | Desktops, laptops, mixed environments | Wi-Fi, VPN plugins, GUI and nmcli | Larger footprint, more moving parts |
Recent Netplan versions can also read back changes made in NetworkManager, storing them as YAML, so settings made through the desktop interface remain visible in the Netplan configuration rather than drifting apart from it.
When no renderer is named, Netplan defaults to networkd. Ubuntu Desktop ships a small file such as 01-network-manager-all.yaml that sets renderer: NetworkManager globally, while a renderer can also be set per device section, so a single machine may hand wired ports to networkd and wireless ports to NetworkManager.
Netplan compared with other networking tools
Netplan is a configuration front end, which distinguishes it from the runtime tools and firewall frameworks of the networking topic. The comparison below clarifies where each tool sits.
| Tool | Role | Persistence |
|---|---|---|
| Netplan | Declarative configuration generator | Persistent YAML files |
| NetworkManager | Connection management daemon | Keyfiles or Netplan YAML |
| systemd-networkd | Lightweight network daemon | .network and .netdev units |
| ip command | Direct runtime changes to links and routes | Lost at reboot |
| ifupdown | Classic Debian interface scripts | /etc/network/interfaces |
| nftables and UFW | Packet filtering | Separate firewall configuration |
A frequent source of confusion is testing with the ip command and then wondering why changes vanish after a reboot. The ip command changes the running kernel state only, while Netplan defines the state that is restored at every boot.
Safe changes and common mistakes
On remote machines, a wrong network setting can cut off the session that is making the change. The command netplan try addresses this risk: it applies the new configuration and reverts automatically after 120 seconds unless the administrator confirms it, and the timeout can be changed with --timeout.
- Tabs instead of spaces: YAML forbids tabs for indentation, and the file fails to parse.
- Wrong indentation level: a key placed one level too high silently applies to the wrong object or is rejected.
- World-readable files: Netplan warns when files are not mode
600, because they may contain Wi-Fi passwords. - Fighting cloud-init: cloud-init may rewrite
50-cloud-init.yaml; persistent overrides belong in a separate file or in a disabled cloud-init network setting. - Two DHCP sources: enabling DHCP and static addresses together without intent leads to unpredictable routes.
For troubleshooting, `netplan get` prints the merged configuration, netplan status summarizes interface state in newer releases, and netplan --debug generate shows exactly which files were read and which renderer files were written.
Stripped to the essentials
Netplan is a written plan for how a computer connects to networks. You describe in a simple text file which cable or wireless network to use, whether the address comes automatically or is fixed, and which servers translate names into addresses.
Netplan then hands that plan to the program that does the real work, much like an architect giving drawings to a builder. You edit the plan, not the building, and the computer follows the same plan every time it starts.
Where it is applied
A hosting provider deploys Ubuntu servers that run virtual machines. Each server has two 10-gigabit ports, and the virtual machines must sit on two VLANs, 100 for customer traffic and 200 for storage, with no single cable as a point of failure.
The administrator writes /etc/netplan/60-host.yaml with both ports under ethernets, an 802.3ad bond named bond0, two VLANs on top of the bond and a bridge on each VLAN. The customer bridge receives a static address and a default route; the storage bridge receives an address and mtu: 9000. The change is applied over SSH with netplan try, confirmed after the connection survives, and stored in configuration management.
Every new server receives the same file, and the network comes up identically on first boot. When a switch is replaced, traffic continues over the second port without any change on the host.