Overview
Netplan is a network configuration utility introduced in Ubuntu 17.10 that uses YAML files to describe network interfaces and renders them into the appropriate configuration for either systemd-networkd or NetworkManager backends. It provides a single, consistent way to configure networking across Ubuntu systems regardless of the underlying network management daemon, replacing the legacy /etc/network/interfaces approach.
Netplan configuration files reside in /etc/netplan/ with a .yaml extension and are processed in lexicographic order, allowing layered configuration. The tool supports ethernet, WiFi, bridges, bonds, VLANs, tunnels, and virtual devices. Netplan’s declarative YAML syntax is human-readable and version-control friendly, making it ideal for infrastructure-as-code workflows, cloud-init integration, and automated server provisioning.
Installation
# Netplan is pre-installed on Ubuntu 18.04+
# Verify installation
netplan --version
# Install if missing
sudo apt update
sudo apt install netplan.io
# Check available backends
dpkg -l | grep -E "systemd-networkd|network-manager"
# Install NetworkManager backend if needed
sudo apt install network-manager
Configuration Files
File Locations
| Path | Purpose |
|---|
/etc/netplan/*.yaml | System network configuration |
/run/netplan/*.yaml | Runtime overrides |
/lib/netplan/*.yaml | Library defaults |
Priority order: /run/netplan/ > /etc/netplan/ > /lib/netplan/
Basic Structure
# /etc/netplan/01-network-config.yaml
network:
version: 2
renderer: networkd # or NetworkManager
ethernets:
# interface configurations
wifis:
# wifi configurations
bridges:
# bridge configurations
bonds:
# bond configurations
vlans:
# vlan configurations
tunnels:
# tunnel configurations
Core Commands
| Command | Description |
|---|
sudo netplan generate | Generate backend config (dry run) |
sudo netplan apply | Apply configuration |
sudo netplan try | Apply with automatic rollback (120s) |
sudo netplan get | Show current merged configuration |
sudo netplan status | Show interface status (Ubuntu 23.04+) |
sudo netplan set | Modify config via CLI |
netplan info | Show netplan version and features |
Safe Configuration Changes
# Apply with auto-rollback (confirms or reverts in 120 seconds)
sudo netplan try
# Apply with custom timeout
sudo netplan try --timeout 60
# Generate without applying (check for errors)
sudo netplan generate
# Apply configuration
sudo netplan apply
Ethernet Configuration
Static IP
network:
version: 2
renderer: networkd
ethernets:
ens33:
addresses:
- 192.168.1.100/24
- 192.168.1.101/24 # Multiple IPs
routes:
- to: default
via: 192.168.1.1
nameservers:
addresses:
- 8.8.8.8
- 8.8.4.4
search:
- example.com
- corp.example.com
DHCP
network:
version: 2
ethernets:
ens33:
dhcp4: true
dhcp6: true
dhcp4-overrides:
use-dns: false
use-routes: true
route-metric: 100
dhcp-identifier: mac
Multiple Interfaces
network:
version: 2
ethernets:
ens33:
addresses:
- 10.0.0.10/24
routes:
- to: default
via: 10.0.0.1
ens34:
addresses:
- 192.168.100.10/24
routes:
- to: 172.16.0.0/12
via: 192.168.100.1
routing-policy:
- from: 192.168.100.0/24
table: 100
Interface Matching
network:
version: 2
ethernets:
id0:
match:
macaddress: "00:11:22:33:44:55"
set-name: lan0
addresses:
- 10.0.0.5/24
all-ethernets:
match:
name: "en*"
dhcp4: true
WiFi Configuration
network:
version: 2
renderer: NetworkManager
wifis:
wlan0:
dhcp4: true
access-points:
"HomeNetwork":
password: "supersecret123"
"OfficeWPA2":
password: "officepass"
band: 5GHz
"OpenCafe":
auth:
key-management: none
"EnterpriseWiFi":
auth:
key-management: eap
method: peap
identity: "user@corp.com"
password: "secret"
Bridges
network:
version: 2
ethernets:
ens33:
dhcp4: false
ens34:
dhcp4: false
bridges:
br0:
interfaces:
- ens33
- ens34
addresses:
- 10.0.0.1/24
routes:
- to: default
via: 10.0.0.254
parameters:
stp: true
forward-delay: 4
max-age: 20
priority: 32768
mtu: 1500
Bonding
network:
version: 2
ethernets:
ens33:
dhcp4: false
ens34:
dhcp4: false
bonds:
bond0:
interfaces:
- ens33
- ens34
addresses:
- 10.0.0.10/24
routes:
- to: default
via: 10.0.0.1
parameters:
mode: 802.3ad # LACP
lacp-rate: fast
mii-monitor-interval: 100
transmit-hash-policy: layer3+4
Bond Modes
| Mode | Description |
|---|
balance-rr | Round-robin |
active-backup | Active/standby failover |
balance-xor | XOR-based transmit balancing |
broadcast | Transmit on all interfaces |
802.3ad | LACP (requires switch support) |
balance-tlb | Adaptive transmit load balancing |
balance-alb | Adaptive load balancing |
VLANs
network:
version: 2
ethernets:
ens33:
dhcp4: false
vlans:
vlan10:
id: 10
link: ens33
addresses:
- 10.10.10.1/24
vlan20:
id: 20
link: ens33
addresses:
- 10.20.20.1/24
routes:
- to: 172.16.0.0/16
via: 10.20.20.254
Advanced Usage
Routing Tables and Policy Routing
network:
version: 2
ethernets:
ens33:
addresses:
- 10.0.0.10/24
routes:
- to: default
via: 10.0.0.1
- to: 172.16.0.0/12
via: 10.0.0.254
metric: 200
table: 101
routing-policy:
- from: 10.0.0.0/24
table: 101
priority: 100
MTU and Wake-on-LAN
network:
version: 2
ethernets:
ens33:
mtu: 9000
wakeonlan: true
dhcp4: true
Tunnels
network:
version: 2
tunnels:
gre-tunnel:
mode: gre
local: 10.0.0.1
remote: 10.0.0.2
addresses:
- 172.16.0.1/30
vxlan100:
mode: vxlan
id: 100
local: 10.0.0.1
remote: 10.0.0.2
port: 4789
WireGuard via Netplan (Ubuntu 24.04+)
network:
version: 2
tunnels:
wg0:
mode: wireguard
addresses:
- 10.100.0.1/24
key: <base64-private-key>
port: 51820
peers:
- keys:
public: <base64-public-key>
allowed-ips:
- 10.100.0.2/32
endpoint: 203.0.113.5:51820
CLI-Based Configuration
# Set interface config via CLI
sudo netplan set ethernets.ens33.addresses='[192.168.1.50/24]'
sudo netplan set ethernets.ens33.routes='[{"to": "default", "via": "192.168.1.1"}]'
sudo netplan apply
# Get current configuration
sudo netplan get
sudo netplan get ethernets.ens33
Configuration
Backend Selection
# Use systemd-networkd (servers)
network:
version: 2
renderer: networkd
# Use NetworkManager (desktops)
network:
version: 2
renderer: NetworkManager
Cloud-Init Integration
# /etc/netplan/50-cloud-init.yaml (auto-generated)
# To override, create /etc/netplan/99-custom.yaml with higher sort order
# Disable cloud-init network config:
# echo "network: {config: disabled}" > /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
Troubleshooting
| Issue | Solution |
|---|
| YAML syntax error | Validate with sudo netplan generate |
| Config not applying | Check file permissions (root:root, 600) |
| Interface not found | Verify name with ip link show |
| DNS not resolving | Check systemd-resolved: resolvectl status |
| WiFi not connecting | Use renderer: NetworkManager for WiFi |
| Routes not added | Verify gateway is reachable on the subnet |
| Netplan try hangs | Press Enter to confirm or wait for rollback |
| Multiple YAML conflicts | Check file ordering (lexicographic precedence) |
Validation and Debugging
# Validate YAML syntax
sudo netplan generate --debug
# Check what backend configs are generated
ls -la /run/systemd/network/
ls -la /run/NetworkManager/system-connections/
# View systemd-networkd status
networkctl status
networkctl list
# Check resolved status
resolvectl status
# View logs
journalctl -u systemd-networkd -f
journalctl -u NetworkManager -f
Reset to DHCP
# /etc/netplan/01-dhcp-all.yaml
network:
version: 2
renderer: networkd
ethernets:
all-en:
match:
name: "en*"
dhcp4: true
all-eth:
match:
name: "eth*"
dhcp4: true
sudo netplan apply
