1.\" Copyright (c) 2014 Bryan Venteicher 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd March 30, 2021 26.Dt VXLAN 4 27.Os 28.Sh NAME 29.Nm vxlan 30.Nd "Virtual eXtensible LAN interface" 31.Sh SYNOPSIS 32To compile this driver into the kernel, 33place the following line in your 34kernel configuration file: 35.Bd -ragged -offset indent 36.Cd "device vxlan" 37.Ed 38.Pp 39Alternatively, to load the driver as a 40module at boot time, place the following line in 41.Xr loader.conf 5 : 42.Bd -literal -offset indent 43if_vxlan_load="YES" 44.Ed 45.Sh DESCRIPTION 46The 47.Nm 48driver creates a virtual tunnel endpoint in a 49.Nm 50segment. 51A 52.Nm 53segment is a virtual Layer 2 (Ethernet) network that is overlaid 54in a Layer 3 (IP/UDP) network. 55.Nm 56is analogous to 57.Xr vlan 4 58but is designed to be better suited for large, multiple tenant 59data center environments. 60.Pp 61Each 62.Nm 63interface is created at runtime using interface cloning. 64This is most easily done with the 65.Xr ifconfig 8 66.Cm create 67command or using the 68.Va cloned_interfaces 69variable in 70.Xr rc.conf 5 . 71The interface may be removed with the 72.Xr ifconfig 8 73.Cm destroy 74command. 75.Pp 76The 77.Nm 78driver creates a pseudo Ethernet network interface 79that supports the usual network 80.Xr ioctl 2 Ns s 81and thus can be used with 82.Xr ifconfig 8 83like any other Ethernet interface. 84The 85.Nm 86interface encapsulates the Ethernet frame 87by prepending IP/UDP and 88.Nm 89headers. 90Thus, the encapsulated (inner) frame is able to be transmitted 91over a routed, Layer 3 network to the remote host. 92.Pp 93The 94.Nm 95interface may be configured in either unicast or multicast mode. 96When in unicast mode, 97the interface creates a tunnel to a single remote host, 98and all traffic is transmitted to that host. 99When in multicast mode, 100the interface joins an IP multicast group, 101and receives packets sent to the group address, 102and transmits packets to either the multicast group address, 103or directly to the remote host if there is an appropriate 104forwarding table entry. 105.Pp 106When the 107.Nm 108interface is brought up, a 109.Xr udp 4 110.Xr socket 9 111is created based on the configuration, 112such as the local address for unicast mode or 113the group address for multicast mode, 114and the listening (local) port number. 115Since multiple 116.Nm 117interfaces may be created that either 118use the same local address 119or join the same group address, 120and use the same port, 121the driver may share a socket among multiple interfaces. 122However, each interface within a socket must belong to 123a unique 124.Nm 125segment. 126The analogous 127.Xr vlan 4 128configuration would be a physical interface configured as 129the parent device for multiple VLAN interfaces, each with 130a unique VLAN tag. 131Each 132.Nm 133segment is identified by a 24-bit value in the 134.Nm 135header called the 136.Dq VXLAN Network Identifier , 137or VNI. 138.Pp 139When configured with the 140.Xr ifconfig 8 141.Cm vxlanlearn 142parameter, the interface dynamically creates forwarding table entries 143from received packets. 144An entry in the forwarding table maps the inner source MAC address 145to the outer remote IP address. 146During transmit, the interface attempts to lookup an entry for 147the encapsulated destination MAC address. 148If an entry is found, the IP address in the entry is used to directly 149transmit the encapsulated frame to the destination. 150Otherwise, when configured in multicast mode, 151the interface must flood the frame to all hosts in the group. 152The maximum number of entries in the table is configurable with the 153.Xr ifconfig 8 154.Cm vxlanmaxaddr 155command. 156Stale entries in the table are periodically pruned. 157The timeout is configurable with the 158.Xr ifconfig 8 159.Cm vxlantimeout 160command. 161The table may be viewed with the 162.Xr sysctl 8 163.Cm net.link.vxlan.N.ftable.dump 164command. 165.Sh MTU 166Since the 167.Nm 168interface encapsulates the Ethernet frame with an IP, UDP, and 169.Nm 170header, the resulting frame may be larger than the MTU of the 171physical network. 172The 173.Nm 174specification recommends the physical network MTU be configured 175to use jumbo frames to accommodate the encapsulated frame size. 176.Pp 177By default, the 178.Nm 179driver sets its MTU to usual ethernet MTU of 1500 bytes, reduced by 180the size of vxlan headers prepended to the encapsulated packets. 181.Pp 182Alternatively, the 183.Xr ifconfig 8 184.Cm mtu 185command may be used to set the fixed MTU size on the 186.Nm 187interface to allow the encapsulated frame to fit in the 188current MTU of the physical network. 189If the 190.Cm mtu 191command was used, system no longer adjust the 192.Nm 193interface MTU on routing or address changes. 194.Sh HARDWARE 195The 196.Nm 197driver supports hardware checksum offload (receive and transmit) and TSO on the 198encapsulated traffic over physical interfaces that support these features. 199The 200.Nm 201interface examines the 202.Cm vxlandev 203interface, if one is specified, or the interface hosting the 204.Cm vxlanlocal 205address, and configures its capabilities based on the hardware offload 206capabilities of that physical interface. 207If multiple physical interfaces will transmit or receive traffic for the 208.Nm 209then they all must have the same hardware capabilities. 210The transmit routine of a 211.Nm 212interface may fail with 213.Er ENXIO 214if an outbound physical interface does not support 215an offload that the 216.Nm 217interface is requesting. 218This can happen if there are multiple physical interfaces involved, with 219different hardware capabilities, or an interface capability was disabled after 220the 221.Nm 222interface had already started. 223.Pp 224At present, these devices are capable of generating checksums and performing TSO 225on the inner frames in hardware: 226.Xr cxgbe 4 . 227.Sh EXAMPLES 228Create a 229.Nm 230interface in unicast mode 231with the 232.Cm vxlanlocal 233tunnel address of 192.168.100.1, 234and the 235.Cm vxlanremote 236tunnel address of 192.168.100.2. 237.Bd -literal -offset indent 238ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2 239.Ed 240.Pp 241Create a 242.Nm 243interface in multicast mode, 244with the 245.Cm local 246address of 192.168.10.95, 247and the 248.Cm group 249address of 224.0.2.6. 250The em0 interface will be used to transmit multicast packets. 251.Bd -literal -offset indent 252ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0 253.Ed 254.Pp 255Once created, the 256.Nm 257interface can be configured with 258.Xr ifconfig 8 . 259.Pp 260The following when placed in the file 261.Pa /etc/rc.conf 262will cause a vxlan interface called 263.Dq Li vxlan0 264to be created, and will configure the interface in unicast mode. 265.Bd -literal -offset indent 266cloned_interfaces="vxlan0" 267create_args_vxlan0="vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2" 268.Ed 269.Sh SEE ALSO 270.Xr inet 4 , 271.Xr inet6 4 , 272.Xr vlan 4 , 273.Xr rc.conf 5 , 274.Xr ifconfig 8 , 275.Xr sysctl 8 276.Rs 277.%A "M. Mahalingam" 278.%A "et al" 279.%T "Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks" 280.%D August 2014 281.%O "RFC 7348" 282.Re 283.Sh AUTHORS 284.An -nosplit 285The 286.Nm 287driver was written by 288.An Bryan Venteicher Aq bryanv@freebsd.org . 289Support for stateless hardware offloads was added by 290.An Navdeep Parhar Aq np@freebsd.org 291in 292.Fx 13.0 . 293