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

Introduction

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

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

These capabilities 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 environments. VXLAN support appeared in netplan 0.105.

network:
  version: 2
  renderer: networkd
  ethernets:
    enp0s3:
      addresses: [192.168.1.100/24]
  tunnels:
    vxlan0:
      mode: vxlan
      id: 42               # VXLAN network identifier (VNI), 1–16777215
      link: enp0s3
      local: 192.168.1.100
      remote: 203.0.113.1  # address of the other side or multicast group, e.g. 239.1.1.1
      port: 4789           # standard VXLAN port
      addresses: [10.0.0.1/24]

There is no separate key for a multicast group in netplan: the group address is specified in remote. The interface specified in link must be described in the same configuration (the ethernets block), otherwise netplan generate will fail.

WireGuard

A modern VPN; support appeared in netplan 0.100.

network:
  version: 2
  renderer: networkd
  tunnels:
    wg0:
      mode: wireguard
      port: 51820
      addresses: [10.0.0.2/24]
      key: /etc/wireguard/private.key   # private key (base64) or path to a file
      peers:
        - keys:
            public: <remote-public-key>
          endpoint: 203.0.113.1:51820
          allowed-ips: [0.0.0.0/0]
          keepalive: 25

The private key is set with key (or keys: private:), the peer’s public key — keys: public:, and the keepalive interval — keepalive. The keys private-key, public-key and persistent-keepalive, familiar from wg-quick, do not exist in netplan — using them will make netplan generate fail. Using a file path instead of the key itself is supported starting with systemd-networkd version 242. Replace <remote-public-key> with the remote side’s public key in base64 — netplan will not accept the configuration with a placeholder.

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 bundling)

For redundancy and/or increased throughput.

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

Why bonding doesn’t speed up a single connection and how to choose a mode are covered in the article “Link redundancy: inside a building”.

Additional parameters

• MTU:
  yaml Copy

  mtu: 9000

• MAC address:
  yaml Copy

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

• Route metrics:
  yaml Copy

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

Applying the configuration

1. Syntax check:
   bash Copy

   sudo netplan generate

2. Test for 120 seconds:
   bash Copy

   sudo netplan try

3. Apply:
   bash Copy

   sudo netplan apply

Useful tips

• Permissions: configs in /etc/netplan/*.yaml should be 600 or 644, otherwise there will be warnings.
  bash Copy

  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 versions

Practical tips

• For Ubuntu 18.04: Netplan is already present, but tunnel support is limited. It’s better to upgrade or install netplan.io from backports.
• For Ubuntu 20.04 and newer: availability of WireGuard and VXLAN depends on the installed version of netplan.io (WireGuard — from 0.100, VXLAN — from 0.105); check it before configuring.
• Check your package version:
  bash Copy

  apt show netplan.io | grep Version

Frequently Asked Questions (FAQ)

❓ How can I check if a Netplan configuration works?
Use:

sudo netplan try

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

sudo netplan apply

❓ How to configure a VLAN via Netplan?
Example:

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

❓ How to set up WireGuard in Netplan?
Since netplan.io 0.100:

tunnels:
  wg0:
    mode: wireguard
    key: /etc/wireguard/private.key
    peers:
      - keys:
          public: <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/ may contain keys and passwords, so netplan warns if the file is accessible to other users. Set permissions to 600:

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