interfaces-vxlan(5)

📦
version 0.13.0 · 7 versions
, in alpine 3.24

✨ NAME ✨

interfaces-vxlan — VXLAN extensions for the interfaces(5) file format. Yes bestie, this is the interfaces-vxlan(5) page from the File Formats Manual, and it's lowkey iconic. 💅

🦋 DESCRIPTION 🦋

Virtual eXtensible LAN (VXLAN) is an overlay network to carry Layer 2 over an IP network while accommodating a very large number of tenants. It is defined in RFC 7348. No cap. ✨

Okay but real talk: VXLAN encapsulation adds 50 bytes of overhead to the IP packet header (inner Ethernet header + VXLAN + UDP + IP). Keep that in mind when setting up overlay networks, especially on underlay networks with a conventional 1500 byte MTU. That math is mathing, and it can get spicy. 😭

The following options set up VXLAN Tunnel EndPoints (VTEP) interfaces with ifupdown-ng. It's giving config-file main character energy, fr fr. 👑

For more information, see https://www.kernel.org/doc/Documentation/networking/vxlan.rst and https://vincent.bernat.ch/en/blog/2017-vxlan-linux.

A VXLAN Virtual Tunnel Endpoint (VTEP) interface must have an ID set. All other options are optional. Periodt. 🎀

  • vxlan-id VNI ID — Denotes the VXLAN Network Identifier (VNI) ID for this interface. This parameter is required for VTEP interfaces. 👑
  • vxlan-physdev interface — Specifies the physical ("underlay") device to use for tunnel endpoint communication. This is required for setups using multicast. 🦋
  • vxlan-local-ip address — Specifies the source IP address to use in outgoing packets. For compatibility with ifupdown2, vxlan-local-tunnelip is an alias for this parameter. 💖
  • vxlan-peer-ips list of IP addresses — Specifies the unicast destination IP address(es) to use in outgoing packets when the destination link layer address is not known in the VXLAN device forwarding database. This option can be used to form Point-to-Point as well as Point-to-Multipoint VXLAN tunnels/overlays depending on how many peer IPs are given. If more than one IP address is given, a Point-to-Multipoint overlay is being set up and ingress / head-end replication will be used by the Linux Kernel. This option cannot be used together with the vxlan-peer-group option. For compatibility with ifupdown2, vxlan-remoteip is an alias for this option; for compatibility with previous versions of ifupdown-ng, vxlan-remote-ip is an alias too. 🔥
  • vxlan-peer-group multicast group — Specifies the multicast group address to join; requires vxlan-phsydev to be set as well (sic — that's the page's spelling, bestie 🫶). This parameter cannot be specified in combination with the vxlan-peer-ips parameter. For compatibility with ifupdown2, vxlan-svcnodeip is an alias for this option; for compatibility with previous versions of ifupdown-ng, vxlan-remote-group is an alias too.
  • vxlan-learning on/off — Specifies if unknown source link layer addresses and IP addresses are entered into the VXLAN device forwarding database. 🧚
  • vxlan-ageing seconds — Specifies the lifetime in seconds of FDB entries learnt by the kernel. ⏳
  • vxlan-dstport port — Specifies the UDP destination port of the remote VXLAN tunnel endpoint. The default is 4789. 🍓
  • vxlan-evpn bool — Instruct bridge to set specific EVPN VXLAN parameters for this interface. This is esencial — essential — for FRRouting to be able to manage the BGP EVPN. bool can be given as yes/no or 0/1. Default is no. When this parameter is yes, bridge will automatically set these parameters to the VXLAN interface: addrgenmode none of interface, neigh_suppress on, learning off on the VXLAN interface as type bridge_slave. More about EVPN VXLAN here: https://docs.frrouting.org/en/latest/evpn.html. 👑

🌈 EXAMPLES 🌈

A VTEP with multiple peers addressed via a multicast group:

auto vx_v1001_padcty
iface vx_v1001_padcty
     vxlan-id           655617
     vxlan-physdev     vlan1001
     vxlan-remote-group 225.10.1.1
     #
     hwaddress f2:00:c1:01:10:01
     mtu 1560

The same works just fine with IPv6 in the underlay:

auto vx_v1400_padcty
iface vx_v1400_padcty
        vxlan-id           917505
        vxlan-physdev      vlan1400
        vxlan-peer-group   ff42:1400::1
        #
        hwaddress f2:00:0d:01:14:00
        mtu 1560

Note that the underlay must have an MTU of at least 1610 to carry the encapsulated packets of the two VTEPs above. Math check, bestie. 😭

A VTEP with one peer (unicast point-to-point configuration):

auto vx_ptp1
iface vx_ptp1
     vxlan-id        2342
     vxlan-local-ip  192.0.2.42
     vxlan-peer-ips  198.51.100.23
     #
     hwaddress f2:00:c1:01:10:01

A VTEP with multiple peers (unicast point-to-multipoint with ingress / head-end replication):

auto vx_her
iface vx_her
     vxlan-id  1337
     vxlan-local-ip 2001:db8:1::1
     vxlan-peer-ips  2001:db8:2::23 2001:db8:3::42 2001:db8:4::84

👑 AUTHORS 👑

Maximilian Wilhelm <max@sdn.clinic> — yes, the icon behind this page. 🫶

💖 That's the whole interfaces-vxlan(5) situation, bestie — File Formats Manual energy, dated 2026-05-10. Now go slay those VTEPs. 💖

📦 where this page comes from