Netplan on Ubuntu - declarative network configuration

Netplan is the default network configuration layer on Ubuntu and the modern Debian installer. It reads YAML files in /etc/netplan/ and applies them via a renderer: either NetworkManager (desktop and laptop default) or systemd-networkd (server default).

Where the config lives

ls -la /etc/netplan/
cat /etc/netplan/*.yaml

Common filenames: 00-installer-config.yaml, 50-cloud-init.yaml, 01-netcfg.yaml. Netplan merges all files in lexical order; later files override earlier ones.

A basic static configuration

# /etc/netplan/01-netcfg.yaml
network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: no
      dhcp6: no
      addresses:
        - 10.0.0.10/24
        - 2001:db8:85a3:1::10/64
      routes:
        - to: default
          via: 10.0.0.1
        - to: "::/0"
          via: fe80::1
          on-link: true
      nameservers:
        addresses:
          - 1.1.1.1
          - 8.8.8.8
        search:
          - example.com

Both address families need their own default route. to: default in Netplan means the IPv4 default only, so IPv6 needs an explicit to: "::/0". With dhcp6: no the host also stops accepting router advertisements, and RAs are normally the only other source of an IPv6 default route - so without that second route the host answers on its own subnet and cannot originate IPv6 traffic off-link.

A route for 2001:db8:85a3:1::/64 would be the wrong fix: the kernel already installs a connected route for the prefix in addresses:, so it changes nothing. on-link: true is required because the next hop is a link-local address, which is not covered by any configured prefix.

Apply it:

sudo netplan generate          # generate the renderer config
sudo netplan try               # apply for 120s, roll back on timeout
sudo netplan apply             # apply and persist

netplan try is the safe option: it applies the change and reverts automatically after 120 seconds unless confirmed with Enter. Use it when applying remotely.

DHCP and IPv6 SLAAC

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: true
      dhcp6: true

dhcp4: true enables a DHCPv4 client — but which client depends on the renderer, and that determines where you go looking when a lease misbehaves:

Neither of them is dhclient. The ISC client was dropped from modern Ubuntu server images, so there is no dhclient process to ps for, no /var/lib/dhcp/dhclient.leases, and no /etc/dhcp/dhclient-exit-hooks.d/ to drop a hook into. Netplan compiles your YAML into /run/systemd/network/10-netplan-*.network and hands it to networkd; the DHCP request comes from PID 1’s network manager, not from a separate daemon.

dhcp6: true enables DHCPv6. For SLAAC only (no DHCPv6), use accept-ra: true and leave dhcp6: no.

VLAN and bond configuration

Netplan handles VLANs, bonds, and bridges declaratively:

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: no
  bonds:
    bond0:
      interfaces: [eth0, eth1]
      addresses:
        - 10.0.0.10/24
  vlans:
    vlan100:
      id: 100
      link: bond0
      addresses:
        - 10.100.0.10/24

Switching renderers

network:
  version: 2
  renderer: NetworkManager    # or networkd

Switching the renderer is safe but disruptive. NetworkManager expects to manage connections itself, including Wi-Fi; on a headless server, networkd is usually correct.

After changing renderers:

sudo systemctl restart systemd-networkd
sudo systemctl restart NetworkManager    # only if you switched to it

Common mistakes

• Wrong indentation: YAML is whitespace-sensitive. Use exactly two spaces per level.
• Mixing renderers: do not have two config files pointing to different renderers. Netplan picks one; the other is ignored.
• Forgetting dhcp4: no: a dhcp4: true default may override your static configuration on every renewal.
• Wrong default route syntax: routes: with to: default and via: is the correct form. The old gateway4:/gateway6: keys are deprecated, not removed — netplan generate prints a warning and then applies them anyway, emitting a Gateway= line into the generated .network file. That distinction matters when you inherit someone else’s config: a gateway4: line you assume is inert is in fact the source of your default route. Migrate it to routes: [{to: default, via: 192.0.2.1}], which gateway4: cannot match because it has no way to express a metric or a routing table.

Knowledge check