Mastering Netplan: Simplify Linux Networking with Declarative YAML

Netplan is a modern network configuration utility for Linux that replaces legacy tools like ifupdown (used in older Debian/Ubuntu systems) with a declarative YAML syntax. It unifies network setup across different renderers (e.g., systemd-networkd for servers, NetworkManager for desktops) and simplifies managing complex configurations like bridges, bonds, and VLANs.

Whether you’re a sysadmin configuring a server or a desktop user setting up WiFi, Netplan’s intuitive structure and wide compatibility make it the go-to tool for Linux networking in 2026.

Table of Contents#

1. Introduction
2. Core Concepts & Architecture
   • YAML Configuration
   • Renderers: NetworkManager vs. systemd-networkd
3. Installation & Initial Setup
4. Basic Configuration Syntax
5. Common Network Configurations
   • Static IP Address
   • DHCP Configuration
   • Wireless (WiFi) Setup
   • Bridge Configuration (for VMs/Containers)
   • Bonding (Link Aggregation)
6. Advanced Netplan Features
   • VLANs
   • IPv6 Configuration
   • Static Routing
   • DNS Management
7. Applying & Troubleshooting Changes
   • Applying Configs Safely
   • Debugging Workflow
   • Rolling Back Changes
8. Best Practices for Netplan
9. Migrating from Legacy Tools (ifupdown)
10. Conclusion
11. References

2. Core Concepts & Architecture#

To use Netplan effectively, you need to understand two foundational ideas: YAML syntax and renderers.

YAML Configuration#

Netplan uses YAML files stored in /etc/netplan/ (e.g., 01-ethernet.yaml, 02-wifi.yaml). YAML relies on indentation (2 spaces per level—no tabs!) and key-value pairs to define network settings.

A minimal Netplan config looks like this:

# /etc/netplan/01-ethernet.yaml
network:
  version: 2  # Current Netplan schema version
  renderer: systemd-networkd  # Use systemd-networkd (server) or NetworkManager (desktop)
  ethernets:
    eth0:  # Name of your Ethernet interface (use `ip a` to find)
      dhcp4: true  # Enable IPv4 DHCP

Renderers: NetworkManager vs. systemd-networkd#

Netplan doesn’t manage networks directly—it generates configs for a backend renderer. The two most common renderers are:

Rule of Thumb:

• Use systemd-networkd for servers (no GUI).
• Use NetworkManager for desktops/laptops (needs WiFi/VPN).

To check your current renderer:

netplan get network.renderer

3. Installation & Initial Setup#

Netplan is pre-installed on Ubuntu 17.10+. To install it on Debian 10+ (which uses ifupdown by default), Linux Mint, or other distros:

Step 1: Check if Netplan is Installed#

netplan --version
# Output: netplan 1.2.1 (or similar)

Step 2: Install Netplan (if missing)#

For Debian/Ubuntu:

sudo apt update && sudo apt install netplan.io

For Fedora (not officially supported): Fedora does not include Netplan in its official repositories and does not use it by default. For special use cases, you may find community-built packages in COPR (Fedora's Community Projects) or build from source. Note that these solutions may not receive official support.

Step 3: Verify Interface Names#

Use ip a or nmcli device status to list your network interfaces (e.g., eth0, wlan0, enp0s3).

4. Basic Configuration Syntax#

Netplan configs are structured around top-level keys (e.g., ethernets, wifis, bridges). Below are the most common keys:

Top-Level Keys#

Interface-Level Keys#

For each interface (e.g., eth0, wlan0), you can define:

• dhcp4: Enable/disable IPv4 DHCP (true/false).
• dhcp6: Enable/disable IPv6 DHCP.
• addresses: Static IP addresses (list of CIDR notation, e.g., ["192.168.1.10/24"]).
• gateway4: IPv4 default gateway (deprecated—use routes instead).
• gateway6: IPv6 default gateway (deprecated—use routes instead).
• nameservers: DNS settings for the interface.

5. Common Network Configurations#

Let’s walk through real-world examples for the most frequent use cases.

Static IP Address#

Use this for servers that need a fixed IP (e.g., web servers, databases).

Config:

# /etc/netplan/01-static-ip.yaml
network:
  version: 2
  renderer: systemd-networkd
  ethernets:
    eth0:
      dhcp4: false  # Disable DHCP
      addresses:  # Static IP (CIDR notation)
        - 192.168.1.10/24  # IPv4
      routes:  # Default gateway (replaces deprecated `gateway4`)
        - to: default
          via: 192.168.1.1  # Your router's IP
      nameservers:  # DNS servers
        addresses: ["8.8.8.8", "8.8.4.4"]  # Google DNS
        search: ["example.com"]  # Domain search suffix (optional)

DHCP Configuration#

Use this for devices that get IPs automatically (e.g., laptops, desktops).

Config:

# /etc/netplan/02-dhcp.yaml
network:
  version: 2
  renderer: NetworkManager  # Use NetworkManager for desktops
  ethernets:
    eth0:
      dhcp4: true  # Enable IPv4 DHCP
      dhcp6: true  # Enable IPv6 DHCP (if your ISP supports it)

Wireless (WiFi) Setup#

WiFi requires NetworkManager (for WPA3/WPA2 support) or wpa_supplicant (for systemd-networkd).

Config (NetworkManager):

# /etc/netplan/03-wifi.yaml
network:
  version: 2
  renderer: NetworkManager
  wifis:
    wlan0:  # Your WiFi interface (use `ip a` to find)
      dhcp4: true
      access-points:
        "MyHomeWiFi":  # SSID of your WiFi network
          password: "MySuperSecurePassword"  # Plain text (see Best Practices for security)

Security Note: Avoid storing plain-text passwords in YAML. The netplan set command can be used for command-line configuration, but always ensure proper config file permissions:

sudo chmod 600 /etc/netplan/*.yaml

Bridge Configuration (for VMs/Containers)#

Bridges let VMs/containers share your host’s network (e.g., KVM/QEMU, LXC). A bridge acts as a "virtual switch" for your interfaces.

Config:

# /etc/netplan/04-bridge.yaml
network:
  version: 2
  renderer: systemd-networkd
  ethernets:
    eth0:  # Slave interface (connected to the bridge)
      dhcp4: false  # Disable DHCP on the slave
  bridges:
    br0:  # Name of the bridge (use in VMs)
      interfaces: [eth0]  # Slave interface(s)
      dhcp4: true  # Bridge uses DHCP (or set static IP)

Verify: Use ip a show br0 to confirm the bridge is up.

Bonding (Link Aggregation)#

Bonding combines multiple Ethernet interfaces into one (link aggregation) for redundancy or speed. Common modes:

• active-backup: Failover (one interface active, others standby).
• 802.3ad: LACP (Link Aggregation Control Protocol—requires switch support).

Config (Active-Backup):

# /etc/netplan/05-bond.yaml
network:
  version: 2
  renderer: systemd-networkd
  ethernets:
    eth0:
      dhcp4: false
    eth1:
      dhcp4: false
  bonds:
    bond0:  # Name of the bond
      interfaces: [eth0, eth1]  # Slave interfaces
      dhcp4: true
      parameters:
        mode: active-backup  # Failover mode
        mii-monitor-interval: 100  # Check link status every 100ms

Verify: Use cat /proc/net/bonding/bond0 to check bond status.

6. Advanced Netplan Features#

Netplan excels at complex setups like VLANs, IPv6, and static routing.

VLANs#

VLANs (Virtual Local Area Networks) segment networks for security or performance. Netplan uses the vlans key to define VLAN interfaces.

Config:

# /etc/netplan/06-vlan.yaml
network:
  version: 2
  renderer: systemd-networkd
  ethernets:
    eth0:
      dhcp4: false
  vlans:
    eth0.10:  # VLAN 10 on eth0 (naming convention: interface.vlan-id)
      id: 10  # VLAN ID
      link: eth0  # Parent interface
      addresses: ["192.168.10.10/24"]  # Static IP for VLAN 10
    eth0.20:  # VLAN 20 on eth0
      id: 20
      link: eth0
      addresses: ["192.168.20.10/24"]

IPv6 Configuration#

Netplan supports dual-stack (IPv4 + IPv6) or IPv6-only setups. Use addresses to define IPv6 addresses and routes for the default gateway.

Config (Dual-Stack):

# /etc/netplan/07-ipv6.yaml
network:
  version: 2
  renderer: systemd-networkd
  ethernets:
    eth0:
      dhcp4: false
      dhcp6: false
      addresses:
        - 192.168.1.10/24  # IPv4
        - 2001:db8::10/64  # IPv6 (example documentation prefix, RFC 3849)
      routes:
        - to: default
          via: 192.168.1.1  # IPv4 gateway
        - to: default
          via: 2001:db8::1  # IPv6 gateway
      nameservers:
        addresses: ["8.8.8.8", "2001:4860:4860::8888"]  # Google DNS (IPv4 + IPv6)

Static Routing#

Static routes direct traffic to specific networks (e.g., a VPN or internal subnet).

Config:

# /etc/netplan/08-static-route.yaml
network:
  version: 2
  renderer: systemd-networkd
  ethernets:
    eth0:
      addresses: ["192.168.1.10/24"]
      routes:
        - to: 10.0.0.0/8  # Target network (internal subnet)
          via: 192.168.1.254  # Gateway for the subnet
        - to: default
          via: 192.168.1.1  # Default gateway

DNS Management#

Netplan lets you set DNS servers per interface.

Per-Interface DNS:

# /etc/netplan/09-dns.yaml
network:
  version: 2
  renderer: systemd-networkd
  ethernets:
    eth0:
      addresses: ["192.168.1.10/24"]
      nameservers:  # DNS settings for eth0
        addresses: ["1.1.1.1", "1.0.0.1"]  # Cloudflare DNS
        search: ["example.com"]

7. Applying & Troubleshooting Changes#

Once you write a Netplan config, you need to apply it and debug any issues.

Applying Configs Safely#

Netplan provides two commands to apply changes:

1. netplan try (Safe for Remote Servers)#

Tests the config and reverts after 120 seconds if you lose connection (critical for remote servers):

sudo netplan try
# Output: Press ENTER to keep the configuration or wait 120 seconds to revert.

2. netplan apply (Immediate Apply)#

Applies the config immediately (use for local machines):

sudo netplan apply

3. netplan generate (Dry Run)#

Generates renderer configs without applying them (use to debug):

sudo netplan generate
# Check output in /run/systemd/network/ (systemd-networkd) or /run/NetworkManager/system-connections/ (NetworkManager)

Debugging Workflow#

If your config fails:

1. Validate YAML Syntax:

   sudo netplan generate
   # Fix any indentation/grammar errors.

2. Check Renderer Logs: For systemd-networkd:

   journalctl -xeu systemd-networkd

   For NetworkManager:

   journalctl -xeu NetworkManager

3. Verify Interface Status:

   ip a show eth0  # Check IP address
   ip route show  # Check routes
   resolvectl status  # Check DNS

Rolling Back Changes#

If netplan try times out, it reverts automatically. For netplan apply, restore the previous config from a backup (always backup /etc/netplan/ before changes!).

8. Best Practices for Netplan#

Follow these rules to avoid common pitfalls:

1. Use Descriptive Filenames#

Name configs by function (e.g., 01-ethernet.yaml, 02-wifi.yaml) so they’re applied in order (lexicographical order).

2. Avoid Tabs in YAML#

YAML requires 2 spaces per indentation level. Tabs will break your config.

3. Version Control Your Configs#

Commit /etc/netplan/ to Git (or another VCS) to track changes and roll back easily:

cd /etc/netplan/
git init
git add .
git commit -m "Initial Netplan config"

4. Don’t Store Plain-Text WiFi Passwords#

Never store plain-text passwords in YAML files; always ensure secure config file permissions:

sudo chmod 600 /etc/netplan/*.yaml

5. Use routes Instead of gateway4/gateway6#

The gateway4 and gateway6 keys are deprecated. Use routes for better control:

# Bad (deprecated)
gateway4: 192.168.1.1
 
# Good (recommended)
routes:
  - to: default
    via: 192.168.1.1

9. Migrating from Legacy Tools (ifupdown)#

If you’re coming from ifupdown (/etc/network/interfaces), follow this step-by-step migration guide.

Step 1: Backup Old Config#

sudo cp /etc/network/interfaces /etc/network/interfaces.bak

Step 2: Convert interfaces to Netplan#

Example old interfaces config:

# /etc/network/interfaces
auto eth0
iface eth0 inet static
  address 192.168.1.10/24
  gateway 192.168.1.1
  dns-nameservers 8.8.8.8 8.8.4.4

Equivalent Netplan config:

# /etc/netplan/01-ethernet.yaml
network:
  version: 2
  renderer: systemd-networkd
  ethernets:
    eth0:
      dhcp4: false
      addresses: ["192.168.1.10/24"]
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: ["8.8.8.8", "8.8.4.4"]

Step 3: Disable ifupdown#

sudo systemctl mask networking.service  # Prevent ifupdown from starting
sudo systemctl stop networking.service

Step 4: Apply Netplan Config#

sudo netplan apply

Step 5: Test Connectivity#

ping 8.8.8.8  # Test internet
resolvectl query example.com  # Test DNS

10. Conclusion#

Netplan is a game-changer for Linux networking. Its declarative YAML syntax simplifies complex setups, and its renderer agnosticism lets you use the right tool for the job (systemd-networkd for servers, NetworkManager for desktops).

By following best practices (version control, no plain-text passwords) and mastering common configurations (static IP, bridges, bonding), you’ll be able to manage Linux networks with confidence.

11. References#

• Netplan Official Documentation
• Netplan Tutorial
• Netplan GitHub Releases
• systemd-networkd Man Page
• NetworkManager Documentation
• YAML Syntax Reference
• Ubuntu Server Networking Guide

Let me know in the comments if you have questions about specific Netplan setups! 🚀