Netplan Configuration on Ubuntu VPS: Static IP & Networking

October 2026 · 8 min read

Since Ubuntu 18.04, Canonical replaced the traditional /etc/network/interfaces with Netplan as the default network configuration tool. Netplan uses YAML files to define network settings and generates configuration for a backend renderer — either systemd-networkd (server default) or NetworkManager (desktop). This abstraction layer makes it straightforward to configure bonding, VLANs, bridges, and routing policies, but a single YAML indentation mistake can bring your network down. This guide covers everything from basic static IP assignment to advanced multi-IP and bridge setups.

Understanding Netplan Architecture

Netplan sits between your YAML configuration and the actual network renderer:

Configuration files live in /etc/netplan/, typically named 00-installer-config.yaml or 50-cloud-init.yaml depending on how Ubuntu was installed.

# List existing config files
ls /etc/netplan/

# View current configuration
cat /etc/netplan/*.yaml

Find Your Network Interface Name

Ubuntu uses predictable network interface names such as ens3, eth0, or enp1s0. Always identify the correct interface name before editing Netplan:

# List all interfaces
ip link show

# Show IP addresses
ip addr

# Compact overview
ip -br link

Configure a Static IP Address

The most common VPS task — assigning a static IP instead of DHCP. The example below uses interface ens3:

sudo nano /etc/netplan/00-installer-config.yaml

File contents (use spaces, never tabs — YAML does not allow tab indentation):

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: false
      dhcp6: false
      addresses:
        - 203.0.113.10/24
      routes:
        - to: default
          via: 203.0.113.1
      nameservers:
        addresses:
          - 1.1.1.1
          - 8.8.8.8
        search:
          - example.com

After saving, apply the configuration:

# Validate syntax only (no apply)
sudo netplan generate

# Apply with automatic rollback after 120 seconds if not confirmed
sudo netplan try

# Apply permanently
sudo netplan apply

Assign Multiple IP Addresses

If your VPS has additional dedicated IPs, add them all to the addresses list:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: false
      addresses:
        - 203.0.113.10/24
        - 203.0.113.11/24
        - 203.0.113.12/24
      routes:
        - to: default
          via: 203.0.113.1
      nameservers:
        addresses:
          - 1.1.1.1
          - 8.8.8.8

DHCP Configuration

For cloud VPS instances where the IP is assigned dynamically:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: true
      dhcp6: false
      dhcp4-overrides:
        use-dns: true
        use-routes: true

Dual-Stack IPv4 and IPv6

Add both IPv4 and IPv6 addresses with their respective gateways:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: false
      dhcp6: false
      addresses:
        - 203.0.113.10/24
        - 2001:db8::10/64
      routes:
        - to: default
          via: 203.0.113.1
        - to: ::/0
          via: 2001:db8::1
      nameservers:
        addresses:
          - 1.1.1.1
          - 2606:4700:4700::1111

Bridge Interface for VMs and LXC Containers

When using a VPS as a hypervisor for LXC containers or KVM virtual machines, create a bridge interface:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: false
  bridges:
    br0:
      interfaces: [ens3]
      dhcp4: false
      addresses:
        - 203.0.113.10/24
      routes:
        - to: default
          via: 203.0.113.1
      nameservers:
        addresses:
          - 1.1.1.1
          - 8.8.8.8
      parameters:
        stp: false
        forward-delay: 0

VLAN Configuration

For networks requiring VLAN tagging:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: false
  vlans:
    vlan100:
      id: 100
      link: ens3
      addresses:
        - 10.0.100.10/24
    vlan200:
      id: 200
      link: ens3
      addresses:
        - 10.0.200.10/24

Verify Netplan Is Working Correctly

# Check interface addresses
ip addr show

# View routing table
ip route show

# Test internet connectivity
ping -c 4 1.1.1.1

# Test DNS resolution
dig google.com @1.1.1.1

# Check systemd-networkd status
systemctl status systemd-networkd

# Full network link status overview
networkctl status

Common Errors and Fixes

Error: "Invalid YAML — found character '\t' that cannot start any token"

YAML does not allow tab characters for indentation — only spaces. This error appears when you paste config from an editor that converted spaces to tabs:

# Check for tab characters in the file
cat -A /etc/netplan/00-installer-config.yaml | grep '\^I'

# Replace tabs with spaces
sed -i 's/\t/  /g' /etc/netplan/00-installer-config.yaml

# Validate syntax again
sudo netplan generate

Error: "Permissions for /etc/netplan/... are too open"

Netplan files must be readable only by root to prevent privilege escalation:

# Fix file permissions
sudo chmod 600 /etc/netplan/*.yaml
sudo chown root:root /etc/netplan/*.yaml

# Apply configuration
sudo netplan apply

Error: "networkd-dispatcher: Failed to connect to dbus"

systemd-networkd is not running or dbus is unavailable:

# Start and enable systemd-networkd
sudo systemctl enable --now systemd-networkd

# Check dbus
systemctl status dbus

# Restart networkd-dispatcher
sudo systemctl restart networkd-dispatcher

Network dropped after netplan apply — SSH locked out

If you used netplan apply instead of netplan try and lost connectivity, you must access the VPS console through your provider's control panel:

# Access console via provider dashboard, then:
sudo journalctl -u systemd-networkd -n 50

# Restore backup config
sudo cp /etc/netplan/00-installer-config.yaml.bak /etc/netplan/00-installer-config.yaml
sudo netplan apply

Error: "route already exists" after netplan apply

A duplicate default route already exists in the kernel routing table:

# View current routing table
ip route show

# Remove conflicting default route
sudo ip route del default

# Re-apply netplan
sudo netplan apply

Frequently Asked Questions

How is Netplan different from /etc/network/interfaces?

Netplan is an abstraction layer that generates configuration for an underlying renderer (systemd-networkd or NetworkManager) rather than managing the network directly. This means a single YAML file covers server and desktop, and supports modern features like WireGuard tunnels and VLAN tagging natively. The /etc/network/interfaces file still works on Debian and older Ubuntu but is considered legacy — Ubuntu has not recommended it since 18.04.

cloud-init keeps overwriting my Netplan config on every reboot. How do I stop it?

Many VPS providers use cloud-init to generate /etc/netplan/50-cloud-init.yaml at boot, overwriting manual changes. Disable cloud-init network management permanently:

# Disable cloud-init network config
echo "network: {config: disabled}" | sudo tee /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg

# Or create a custom config with a lower number (applied first)
sudo nano /etc/netplan/01-custom.yaml

Does Netplan support WireGuard VPN tunnels?

Yes, from Netplan 0.99+ you can define WireGuard tunnels directly in YAML without separate wg-quick configuration:

network:
  version: 2
  tunnels:
    wg0:
      mode: wireguard
      key: /etc/wireguard/privatekey
      addresses:
        - 10.0.0.1/24
      peers:
        - keys:
            public: <peer-public-key>
          allowed-ips: [0.0.0.0/0]
          endpoint: vpn.example.com:51820