OpenBSD manual page server

Manual Page Search Parameters

VXLAN(4) Device Drivers Manual VXLAN(4)

vxlanVirtual eXtensible Local Area Network tunnel interface

pseudo-device vxlan

The vxlan interface is a tunnelling pseudo-device for overlaying virtualized layer 2 networks over layer 3 networks.

A vxlan interface can be created using the ifconfig vxlanN create command. Once configured, the interface encapsulates and decapsulates Ethernet frames in UDP datagrams that are exchanged with tunnel endpoints. The default UDP port for VXLAN traffic is 4789.

Each vxlan interface uses a 24-bit vnetid (virtual networks identifier) that distinguishes multiple virtualized layer 2 networks and their tunnels between identical tunnel endpoints.

The interface can operate in the following tunnel modes:

When a unicast IP address is configured as the tunnel destination, all traffic is sent to a single tunnel endpoint.
When a multicast IP address is configured as the tunnel destination, all traffic is sent to all the tunnel endpoints that subscribed for the specified multicast group.
When vxlan is configured for multicast mode and added to a bridge(4), all broadcast and multicast traffic is sent to the multicast group, but directed traffic is sent to unicast IP addresses of individual tunnel endpoints as they are learned by the bridge.
When vxlan is configured with vnetid any and added to a bridge(4), all return traffic is sent to the known tunnel endpoints as they are learned by the bridge. In this mode, vxlan does not use a specific virtual network identifier but learns the ones of the individual tunnel endpoints. It is used to dynamically bridge many virtual networks together.

The configuration can be done at runtime or by setting up a hostname.if(5) configuration file for netstart(8).

Create a tunnel to a unicast tunnel endpoint, using the virtual tunnel identifier 5:

# ifconfig vxlan0 tunnel vnetid 5
# ifconfig vxlan0

The following examples creates a dynamic tunnel that is attached to a bridge(4):

# ifconfig vxlan0 tunnel vnetid 7395
# ifconfig vxlan0
# ifconfig bridge0 add vxlan0 up

Prior to the assignment of UDP port 4789 by IANA, some early VXLAN implementations used port 8472. A non-standard port can be specified with the tunnel destination address:

# ifconfig vxlan0 tunnel

vxlan does not provide any integrated security features. It is designed to be a simple protocol that can be used in trusted data center environments, to carry VM traffic between virtual machine hypervisors, and provide virtualized layer 2 networks in Cloud infrastructures.

To protect vxlan tunnels, the traffic can be protected with IPsec to add authentication and encryption for confidentiality.

The Packet Filter (PF) can be used to filter tunnel traffic with endpoint policies in pf.conf(5):

table <vxlantep> {, }
block in on vmx0
pass out on vmx0
pass in on vmx0 proto udp from <vxlantep> to port vxlan

The Time-to-Live (TTL) value of the tunnel can be set to 1 or a low value to restrict the traffic to the local network:

# ifconfig vxlan0 tunnelttl 1

bridge(4), inet(4), hostname.if(5), ifconfig(8), netstart(8)

M. Mahalingam, D. Dutt, K. Duda, P. Agarwal, L. Kreeger, T. Sridhar, M. Bursell, and C. Wright, VXLAN: A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks, draft-mahalingam-dutt-dcops-vxlan-04, May 2013.

The vxlan device first appeared in OpenBSD 5.5.

The vxlan driver was written by Reyk Floeter <>.

The vxlan interface requires at least 50 bytes for the IP, UDP and VXLAN protocol overhead and optionally 4 bytes for the encapsulated VLAN tag. The default MTU is set to 1500 bytes but can be adjusted if the transport interfaces carrying the tunnel traffic do not support larger MTUs, the tunnel traffic is leaving the local network, or if interoperability with another implementation requires running a decreased MTU of 1450 bytes. In any other case, it is commonly recommended to set the MTU of the transport interfaces to at least 1600 bytes.

The implementation does not support IPv6 tunnel endpoints at present.

February 22, 2018 OpenBSD-6.3