1.\" $OpenBSD: vxlan.4,v 1.20 2023/11/23 03:36:42 dlg Exp $ 2.\" 3.\" Copyright (c) 2013 Reyk Floeter <reyk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 23 2023 $ 18.Dt VXLAN 4 19.Os 20.Sh NAME 21.Nm vxlan 22.Nd Virtual eXtensible Local Area Network tunnel interface 23.Sh SYNOPSIS 24.Cd "pseudo-device vxlan" 25.Sh DESCRIPTION 26The 27.Nm 28pseudo-device provides interfaces for tunnelling or overlaying 29Ethernet networks on top of IPv4 and IPv6 networks using the 30Virtual eXtensible Local Area Network (VXLAN) protocol. 31.Pp 32VXLAN datagrams consist of an Ethernet payload encapsulated by an 338-byte VXLAN header, which in turn is encapsulated by UDP and IP 34headers. 35Different VXLAN tunnels or overlays between the same VXLAN Tunnel 36Endpoints (VTEPs) can be distinguished by an optional 24-bit Virtual 37Network Identifier (VNI). 38.Pp 39A 40.Nm 41interface can be created using the 42.Ic ifconfig vxlan Ns Ar N Ic create 43command or by setting up a 44.Xr hostname.if 5 45configuration file for 46.Xr netstart 8 . 47.Pp 48For correct operation, encapsulated traffic must not be routed 49over the interface itself. 50This can be implemented by adding a distinct or a more specific 51route to the tunnel destination than the hosts or networks routed 52via the tunnel interface. 53Alternatively, the tunnel traffic may be configured in a separate 54routing table to the encapsulated traffic. 55.Pp 56The interface can operate in the following tunnel modes: 57.Bl -tag -width multicast 58.It Ic point-to-point mode 59When a unicast IP address is configured as the tunnel destination, 60all traffic is sent to a single tunnel endpoint. 61.It Ic learning mode 62When a multicast IP address is configured as the tunnel destination, 63.Nm 64operates as a learning bridge. 65Broadcast, multicast, and unknown unicast packets are sent to the 66specified multicast group. 67Packets received by the tunnel source address are used to dynamically 68learn the endpoint addresses for the encapsulated Ethernet source 69addresses. 70.It Ic endpoint mode 71When configured without a tunnel destination address, 72.Nm 73operates as a bridge, but with learning disabled. 74Endpoints for Ethernet addresses must be added explicitly before 75packets will be encapsulated for those addresses. 76All valid VXLAN packets sent to the local address will be accepted. 77.El 78.Pp 79.Nm 80supports the following 81.Xr ioctl 2 82calls for configuration: 83.Bl -tag -width indent -offset 3n 84.It Dv SIOCSLIFPHYADDR Fa "struct if_laddrreq *" 85Set the IPv4 or IPv6 addresses used for the exchange of encapsulated 86traffic. 87The interface will operate in point-to-point mode if the destination 88address is unicast, 89learning mode if the destination address is multicast, 90or endpoint mode if the destination address is unspecified. 91A non-standard UDP port for VXLAN packets can be specified by the 92port in the source address, otherwise use 0 to request the default. 93The addresses may only be configured while the interface is down. 94.It Dv SIOCGLIFPHYADDR Fa "struct if_laddrreq *" 95Get the addresses configured for the exchange of encapsulated packets. 96.It Dv SIOCDIFPHYADDR Fa "struct ifreq *" 97Clear the addresses used for the exchange of encapsulated packets. 98The addresses may only be cleared while the interface is down. 99.It Dv SIOCSVNETID Fa "struct ifreq *" 100Configure a virtual network identifier for use in the VXLAN header. 101The virtual network identifier may only be configured while the 102interface is down. 103.It Dv SIOCGVNETID Fa "struct ifreq *" 104Get the virtual network identifier used in the VXLAN header. 105.It Dv SIOCDVNETID Fa "struct ifreq *" 106Remove the virtual network identifier. 107The virtual network identifier may only be disabled while the 108interface is down. 109.It Dv SIOCSLIFPHYRTABLE Fa "struct ifreq *" 110Set the routing table the encapsulated traffic operates in. 111The routing table may only be configured while the interface is down. 112.It Dv SIOCGLIFPHYRTABLE Fa "struct ifreq *" 113Get the routing table the encapsulated traffic operates in. 114.It Dv SIOCSLIFPHYTTL Fa "struct ifreq *" 115Set the Time-To-Live field in IPv4 encapsulation headers, or the 116Hop Limit field in IPv6 encapsulation headers. 117.It Dv SIOCGLIFPHYTTL Fa "struct ifreq *" 118Get the value used in the Time-To-Live field in an IPv4 encapsulation 119header or the Hop Limit field in an IPv6 encapsulation header. 120.It Dv SIOCSLIFPHYDF Fa "struct ifreq *" 121Configure whether the encapsulated traffic sent by the interface 122can be fragmented or not. 123This sets the Don't Fragment (DF) bit on IPv4 packets, 124and disables fragmentation of IPv6 packets. 125.It Dv SIOCGLIFPHYDF Fa "struct ifreq *" 126Get whether the encapsulated traffic sent by the interface can be 127fragmented or not. 128.It Dv SIOCSRXHPRIO Fa "struct ifreq *" 129Set the priority value for received packets. 130Values may be from 0 to 7, 131.Dv IF_HDRPRIO_PACKET 132to specify that the current priority of a packet should be kept, 133or 134.Dv IF_HDRPRIO_OUTER 135to use the value in the Type of Service field in IPv4 136or the Traffic Class field in IPv6 encapsulation headers. 137.It Dv SIOCGRXHPRIO Fa "struct ifreq *" 138Get the priority value for received packets. 139.It Dv SIOCSTXHPRIO Fa "struct ifreq *" 140Set the priority value used in the Type of Service field in IPv4 141headers, or the Traffic Class field in IPv6 headers. 142Values may be from 0 to 7, or 143.Dv IF_HDRPRIO_PACKET 144to specify that the current priority of a packet should be used. 145.It Dv SIOCGTXHPRIO Fa "struct ifreq *" 146Get the priority value used in the Type of Service field in IPv4 147headers, or the Traffic Class field in IPv6 headers. 148.It Dv SIOCSIFPARENT Fa "struct if_parent *" 149Configure which interface will be joined to the multicast group 150specified by the tunnel destination address. 151The parent interface may only be configured for interfaces in 152learning mode, and while the interface is down. 153.It Dv SIOCGIFPARENT Fa "struct if_parent *" 154Get the name of the interface used for multicast communication. 155.It Dv SIOCDIFPARENT Fa "struct ifreq *" 156Remove the configuration of the interface used for multicast 157communication. 158.El 159.Sh EXAMPLES 160Create a point-to-point tunnel using Virtual Network Identifier 5: 161.Bd -literal -offset indent 162# ifconfig vxlan0 tunnel 192.168.1.100 192.168.1.200 vnetid 5 163# ifconfig vxlan0 10.1.1.100/24 164.Ed 165.Pp 166The following examples creates a learning overlay network: 167.Bd -literal -offset indent 168# ifconfig vxlan0 tunnel 192.168.1.100 239.1.1.100 169# ifconfig vxlan0 parent ix0 170# ifconfig vxlan0 vnetid 7395 171# ifconfig vxlan0 10.1.2.100/24 172.Ed 173.Pp 174Prior to the assignment of UDP port 4789 by IANA, some early VXLAN 175implementations used port 8472. 176A non-standard port can be specified with the tunnel source 177address: 178.Bd -literal -offset indent 179# ifconfig vxlan0 tunnel 192.168.1.100:8472 239.1.1.100 180.Ed 181.Sh SECURITY 182.Nm 183does not provide any integrated security features. 184It is designed to be a simple protocol that can be used in trusted 185data center environments, to carry VM traffic between virtual machine 186hypervisors, and provide virtualized layer 2 networks in Cloud 187infrastructures. 188.Pp 189To protect 190.Nm 191tunnels, the traffic can be protected with IPsec to add authentication 192and encryption for confidentiality. 193.Pp 194The Packet Filter (PF) can be used to filter tunnel traffic with 195endpoint policies in 196.Xr pf.conf 5 : 197.Bd -literal -offset indent 198table <vxlantep> { 192.168.1.200, 192.168.1.201 } 199block in on em0 200pass out on em0 201pass in on em0 proto udp from <vxlantep> to port vxlan 202.Ed 203.Pp 204The Time-to-Live (TTL) value of the tunnel can be set to 1 or a low 205value to restrict the traffic to the local network: 206.Bd -literal -offset indent 207# ifconfig vxlan0 tunnelttl 1 208.Ed 209.Sh SEE ALSO 210.Xr inet 4 , 211.Xr udp 4 , 212.Xr hostname.if 5 , 213.Xr ifconfig 8 , 214.Xr netstart 8 215.Sh STANDARDS 216.Rs 217.%A M. Mahalingam 218.%A D. Dutt 219.%A K. Duda 220.%A P. Agarwal 221.%A L. Kreeger 222.%A T. Sridhar 223.%A M. Bursell 224.%A C. Wright 225.%D August 2014 226.%R RFC 7348 227.%T Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks 228.Re 229.Sh HISTORY 230The 231.Nm 232device first appeared in 233.Ox 5.5 . 234.Sh CAVEATS 235The 236.Nm 237interface requires at least 50 bytes for the IP, UDP and VXLAN 238protocol overhead and optionally 4 bytes for the encapsulated VLAN tag. 239The default MTU is set to 1500 bytes but can be adjusted if the 240transport interfaces carrying the tunnel traffic do not support larger 241MTUs, the tunnel traffic is leaving the local network, or if 242interoperability with another implementation requires running a 243decreased MTU of 1450 bytes. 244In any other case, it is commonly recommended to set the MTU of the 245transport interfaces to at least 1600 bytes. 246