ubuntu-netplan

ubuntu-netplan

Netplan is Ubuntu's network-configuration abstraction: declarative YAML under /etc/netplan/ that netplan renders to a backend — systemd-networkd (servers, the default) or NetworkManager (desktop) — and uses to bring the network up. This skill is authoring-led (produce correct YAML from a description) with a strong validation/debug path, aimed at on-prem / air-gapped Ubuntu Server LTS.

Netplan is also the shared network substrate for the sibling skills: cloud-init's network-config v2 is netplan format, and an autoinstall network: block is netplan v2. See Boundaries at the end.

Authoring workflow

1. Confirm target & renderer. Server → renderer: networkd (the default). Desktop/Wi-Fi → renderer: NetworkManager. Check the running version with netplan info (24.04 ships ~1.0.x, 26.04 tracks 1.2.x — see version notes).
2. Pick the device type(s): ethernets, bonds, bridges, vlans, vrfs, tunnels, dummy-devices, virtual-ethernets, wifis, modems. Stack them bottom-up: ethernets → bond → vlans-on-bond → bridges-on-bond/vlan.
3. Write the YAML under /etc/netplan/, choosing a filename that orders correctly (see precedence). Use 2-space indentation, never tabs.
4. Validate without applying: netplan generate (fails loudly on errors).
5. Apply safely. On a remote/SSH host use netplan try (auto-rollback), never a blind netplan apply — see "Apply safely".
6. Verify: netplan status --all, ip addr, ip route, and reachability.

The envelope

Every file is wrapped in:

network:
  version: 2                 # only 2 is accepted (v1 does not exist for netplan)
  renderer: networkd         # default if omitted; or NetworkManager
  ethernets: { ... }
  bonds: { ... }
  # ...other device types

File model & precedence (a real source of bugs)

• Files live in /etc/netplan/*.yaml (also /run/netplan/ > /etc/netplan/ > /lib/netplan/ by directory priority).
• Same filename in a higher-priority dir fully replaces the lower one.
• Different filenames are merged in lexicographic order of the basename, across all directories. So 20-foo.yaml overrides 10-bar.yaml even if 10-bar.yaml sits in a higher-priority directory.
• Per-key merge: scalars → later wins; sequences are concatenated, not replaced (two files each listing addresses: will accumulate both — a classic "why do I have an extra IP?" trap); mappings → merged key by key.
• Conventional files commonly present: 50-cloud-init.yaml (written by cloud-init), 00-installer-config.yaml (Subiquity), 90-NM-<uuid>.yaml (NetworkManager desktop). Use a high number like 99-*.yaml for hand overrides.
• Permissions: netplan only warns if a file is group/other-readable; it does not refuse or auto-fix. YAML can hold Wi-Fi/WireGuard/EAP secrets, so chmod 600 /etc/netplan/*.yaml, root-owned. Files netplan writes itself (netplan set) are already 0600.