Netplan

Cheatsheet#netplan

Netplan is the default network configuration abstraction tool on modern Ubuntu systems (/etc/netplan/*.yaml). It uses YAML configuration files and generates backends for networkd (systemd-networkd) or NetworkManager.

Essential Netplan Commands

# Apply configuration immediately
sudo netplan apply
 
# Test configuration with auto-rollback if not confirmed within 120s (SAFE FOR REMOTE SSH)
sudo netplan try
 
# View current network interface status & IP addresses
sudo netplan status
 
# Debug YAML parsing issues or output generated config
sudo netplan --debug apply

Security Warning: Netplan configuration files MUST have strict permissions (600). Run sudo chmod 600 /etc/netplan/*.yaml if Netplan warns about unsafe permissions.

Basic DHCP Configuration

/etc/netplan/01-netcfg.yaml

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

Static IP Address Configuration

Standard configuration for servers with static IPv4, default gateway, and custom DNS servers.

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
      addresses:
        - 192.168.1.100/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses:
          - 1.1.1.1
          - 8.8.8.8
          - 8.8.4.4

Multiple IP Addresses on Single Interface

Useful for web servers hosting multiple sites or secondary IP bindings.

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
      addresses:
        - 10.0.0.50/24
        - 10.0.0.51/24
        - 10.0.0.52/24
      routes:
        - to: default
          via: 10.0.0.1
      nameservers:
        addresses:
          - 1.1.1.1
          - 1.0.0.1

Custom Static Routes

Adding specific static routes for private networks or jump servers.

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
      addresses:
        - 192.168.10.15/24
      routes:
        # Default gateway
        - to: default
          via: 192.168.10.1
        # Custom static route to 10.50.0.0/16 via internal gateway 192.168.10.254
        - to: 10.50.0.0/16
          via: 192.168.10.254
          metric: 100
      nameservers:
        addresses:
          - 192.168.10.1

Bridge Configuration (KVM / Virtualization)

Bridge physical interface eth0 to virtual bridge br0 for virtual machines (KVM/QEMU).

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
      dhcp6: false
  bridges:
    br0:
      interfaces: [eth0]
      dhcp4: false
      addresses:
        - 192.168.1.200/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses:
          - 1.1.1.1
      parameters:
        stp: false
        forward-delay: 0

Wi-Fi Configuration

Connecting a server or desktop to Wi-Fi using Netplan and NetworkManager.

network:
  version: 2
  renderer: NetworkManager
  wifis:
    wlan0:
      dhcp4: true
      access-points:
        "MY_WIFI_SSID":
          password: "WIFI_PASSWORD"

Common Netplan Troubleshooting & Pitfalls

1. Tab Characters Error (`Invalid YAML`)

YAML does NOT allow tabs (\t). Always use 2 spaces for indentation.

# Test for tab characters in netplan files
grep -P "\t" /etc/netplan/*.yaml

2. Unsafe Permissions Warning

Netplan will refuse or warn if permissions are too open:

sudo chmod 600 /etc/netplan/*.yaml
sudo netplan apply

3. Deprecated Gateway Syntax (`gateway4`)

In older Ubuntu versions, gateway4: 192.168.1.1 was used. It is now deprecated. Always use routes instead:

# DEPRECATED (Do not use)
# gateway4: 192.168.1.1
 
# CORRECT (Modern Netplan)
routes:
  - to: default
    via: 192.168.1.1

Cheatsheets