Netplan: advanced network configuration (tunnels, VLAN, bridges, bonding)

Introduction

Netplan is a utility for declarative network configuration in Linux (Ubuntu, Debian, and derivatives). It is usually used for simple cases like Ethernet or Wi-Fi, but it can do much more:

• tunnel interfaces (IPIP, GRE, VXLAN, WireGuard),
• VLAN,
• bridges,
• bonding (interface aggregation).

These features allow building complex network topologies — from home VPNs to data centers and cloud environments.

Tunnel interfaces

Tunnels encapsulate packets of one protocol into another. They are used for VPNs, inter-server connections, or network isolation.

IPIP (IP-in-IP)

The simplest IPv4-in-IPv4 tunnel.

network:
  version: 2
  renderer: networkd
  tunnels:
    tun0:
      mode: ipip
      local: 192.168.1.100
      remote: 203.0.113.1
      addresses: [10.0.0.1/30]
      routes:
        - to: 10.0.1.0/24
          via: 10.0.0.2

GRE (Generic Routing Encapsulation)

Supports more protocols than IPIP.

network:
  version: 2
  renderer: networkd
  tunnels:
    gre0:
      mode: gre
      local: 192.168.1.100
      remote: 203.0.113.1
      addresses: [10.0.0.1/30]
      routes:
        - to: 10.0.2.0/24
          via: 10.0.0.2

VXLAN (Virtual Extensible LAN)

Used in virtualization and cloud. Supports multicast and custom ports.

network:
  version: 2
  renderer: networkd
  tunnels:
    vxlan0:
      mode: vxlan
      id: 42
      link: enp0s3
      local: 192.168.1.100
      group: 239.1.1.1   # multicast group
      port: 4789         # default VXLAN port
      addresses: [10.0.0.1/24]

WireGuard

Modern VPN, supported in netplan.io >= 0.99.

network:
  version: 2
  renderer: networkd
  tunnels:
    wg0:
      mode: wireguard
      addresses: [10.0.0.2/24]
      private-key: /etc/wireguard/private.key
      peers:
        - public-key: <remote-public-key>
          endpoint: 203.0.113.1:51820
          allowed-ips: [0.0.0.0/0]
          persistent-keepalive: 25

VLAN (Virtual LAN)

Traffic segmentation by VLAN ID.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s3:
      dhcp4: no
  vlans:
    vlan10:
      id: 10
      link: enp0s3
      addresses: [192.168.10.100/24]
      routes:
        - to: default
          via: 192.168.10.1

Bridges

Combine multiple interfaces.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s3: { dhcp4: no }
    enp0s8: { dhcp4: no }
  bridges:
    br0:
      interfaces: [enp0s3, enp0s8]
      addresses: [192.168.1.100/24]
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]

Bonding (interface aggregation)

For high availability and/or increased bandwidth.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s3: { dhcp4: no }
    enp0s8: { dhcp4: no }
  bonds:
    bond0:
      interfaces: [enp0s3, enp0s8]
      addresses: [192.168.1.100/24]
      routes:
        - to: default
          via: 192.168.1.1
      parameters:
        mode: 802.3ad                # LACP (requires switch support)
        transmit-hash-policy: layer3+4
        mii-monitor-interval: 100

Additional parameters

• MTU:

  mtu: 9000
  

• MAC address:

  macaddress: 00:16:3e:12:34:56
  

• Route metrics:

  routes:
    - to: 192.168.2.0/24
      via: 192.168.1.1
      metric: 100
  

Applying configuration

1. Syntax check:

   sudo netplan generate
   

2. Test for 120 seconds:

   sudo netplan try
   

3. Apply:

   sudo netplan apply
   

Useful tips

• File permissions: configs in /etc/netplan/*.yaml should be 600 or 644, otherwise warnings appear.

  sudo chmod 600 /etc/netplan/*.yaml
  

• Check interfaces: ip a, ip r, nmcli (if using NetworkManager).

• Logs: journalctl -u systemd-networkd or /var/log/syslog.

• Backups: always save copies before experimenting.

Netplan feature compatibility by version

Practical notes

• For Ubuntu 18.04: Netplan is present, but tunnel support is limited. Better to upgrade or install netplan.io from backports.

• For Ubuntu 20.04: IPIP, GRE, VXLAN work; WireGuard — via PPA or backports.

• For Ubuntu 22.04 and newer: full support, including WireGuard.

• Check your package version:

  apt show netplan.io | grep Version
  

Frequently Asked Questions (FAQ)

❓ How to check if Netplan configuration works? Use:

sudo netplan try

— you’ll have 120 seconds to confirm. If everything is correct, then run:

sudo netplan apply

❓ How to configure VLAN via Netplan? Example:

vlans:
  vlan10:
    id: 10
    link: enp0s3
    addresses: [192.168.10.100/24]

❓ How to configure WireGuard in Netplan? Starting from netplan.io >= 0.104 you can use:

tunnels:
  wg0:
    mode: wireguard
    private-key: /etc/wireguard/private.key
    peers:
      - public-key: <remote-pubkey>
        endpoint: 203.0.113.1:51820
        allowed-ips: [0.0.0.0/0]

❓ Why does Netplan complain about file permissions? Configs in /etc/netplan/ must have permissions 600 or 644.

sudo chmod 600 /etc/netplan/*.yaml

❓ Does Netplan support bonding? Yes. Example for LACP (802.3ad):

bonds:
  bond0:
    interfaces: [enp0s3, enp0s8]
    parameters:
      mode: 802.3ad

Useful links

• Netplan Documentation
• Ubuntu Networking Guide
• WireGuard Project