Understanding Netplan

Understanding Netplan

Netplan is Ubuntu's network configuration abstraction layer. Instead of writing backend-specific config files for either networkd or NetworkManager, you write a single YAML file and Netplan generates the appropriate backend config. This simplifies network configuration and makes it consistent across Ubuntu desktop, server, and cloud deployments.

Why Netplan was created

Without Netplan (old way):
  /etc/network/interfaces   → directly by ifupdown
  /etc/NetworkManager/...   → directly by NetworkManager
  Two different config systems, incompatible with each other

With Netplan:
  /etc/netplan/*.yaml (YOUR config)
         ↓ netplan generate
  /run/systemd/network/*.network  (for networkd backend)
  /run/NetworkManager/system-connections/  (for NM backend)

One config format, two possible backends, both managed by Netplan.

Netplan YAML syntax overview

# All Netplan files start with:
network:
  version: 2
  renderer: networkd    # or NetworkManager (default on Ubuntu Desktop)

  # Then one or more device type sections:
  ethernets:     # Wired Ethernet
  wifis:         # Wi-Fi
  bonds:         # Bonded interfaces
  bridges:       # Linux bridges
  vlans:         # VLAN interfaces

# Show currently generated backend config
sudo netplan generate    # Writes to /run/systemd/network/ without applying
ls /run/systemd/network/

# Apply config (generate + reload backend)
sudo netplan apply

networkd vs NetworkManager

# Check which renderer is active
systemctl is-active systemd-networkd
systemctl is-active NetworkManager

Bonds, bridges, and VLANs

# Bond example (two NICs as one redundant interface)
# /etc/netplan/00-bond.yaml:
network:
  version: 2
  bonds:
    bond0:
      interfaces: [ens3, ens4]
      parameters:
        mode: active-backup
        primary: ens3
      dhcp4: false
      addresses: [192.168.1.10/24]
      routes:
        - to: default
          via: 192.168.1.1

# VLAN example
network:
  version: 2
  ethernets:
    ens3:
      dhcp4: false
  vlans:
    vlan10:
      id: 10
      link: ens3
      addresses: [10.10.10.5/24]
    vlan20:
      id: 20
      link: ens3
      addresses: [10.20.0.5/24]

Debugging Netplan errors

# Validate YAML syntax and Netplan logic
sudo netplan generate 2>&1    # Shows errors without applying

# Check for YAML syntax errors specifically
python3 -c "import yaml; yaml.safe_load(open('/etc/netplan/00-installer-config.yaml'))"

# After applying, check if networkd accepted the config
sudo networkctl status ens3

# View generated networkd config
cat /run/systemd/network/10-netplan-ens3.network

# Check journal for network errors
sudo journalctl -u systemd-networkd -b --no-pager | grep -i error

📝 NOTE: Netplan YAML files must have permissions 600 (not world-readable) when they contain credentials like Wi-Fi passwords. Netplan will warn and may refuse to apply if the file is too permissive. Fix: sudo chmod 600 /etc/netplan/*.yaml

Conclusion

Netplan is a wrapper that translates your YAML network config into either systemd-networkd or NetworkManager format. Ubuntu Server uses networkd as the default backend. Always run sudo netplan try to test changes before committing — the 120-second rollback is critical when working on remote servers. For complex configurations like bonding and VLANs, netplan generate shows the generated backend config without applying it, which helps verify the output is correct before applying.