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.\" $FreeBSD$ 26.\" 27.Dd December 31, 2017 28.Dt VXLAN 4 29.Os 30.Sh NAME 31.Nm vxlan 32.Nd "Virtual eXtensible LAN interface" 33.Sh SYNOPSIS 34To compile this driver into the kernel, 35place the following line in your 36kernel configuration file: 37.Bd -ragged -offset indent 38.Cd "device vxlan" 39.Ed 40.Pp 41Alternatively, to load the driver as a 42module at boot time, place the following line in 43.Xr loader.conf 5 : 44.Bd -literal -offset indent 45if_vxlan_load="YES" 46.Ed 47.Sh DESCRIPTION 48The 49.Nm 50driver creates a virtual tunnel endpoint in a 51.Nm 52segment. 53A 54.Nm 55segment is a virtual Layer 2 (Ethernet) network that is overlaid 56in a Layer 3 (IP/UDP) network. 57.Nm 58is analogous to 59.Xr vlan 4 60but is designed to be better suited for large, multiple tenant 61data center environments. 62.Pp 63Each 64.Nm 65interface is created at runtime using interface cloning. 66This is most easily done with the 67.Xr ifconfig 8 68.Cm create 69command or using the 70.Va cloned_interfaces 71variable in 72.Xr rc.conf 5 . 73The interface may be removed with the 74.Xr ifconfig 8 75.Cm destroy 76command. 77.Pp 78The 79.Nm 80driver creates a pseudo Ethernet network interface 81that supports the usual network 82.Xr ioctl 2 Ns s 83and is thus can be used with 84.Xr ifconfig 8 85like any other Ethernet interface. 86The 87.Nm 88interface encapsulates the Ethernet frame 89by prepending IP/UDP and 90.Nm 91headers. 92Thus, the encapsulated (inner) frame is able to transmitted 93over a routed, Layer 3 network to the remote host. 94.Pp 95The 96.Nm 97interface may be configured in either unicast or multicast mode. 98When in unicast mode, 99the interface creates a tunnel to a single remote host, 100and all traffic is transmitted to that host. 101When in multicast mode, 102the interface joins an IP multicast group, 103and receives packets sent to the group address, 104and transmits packets to either the multicast group address, 105or directly the remote host if there is an appropriate 106forwarding table entry. 107.Pp 108When the 109.Nm 110interface is brought up, a 111.Xr udp 4 112.Xr socket 9 113is created based on the configuration, 114such as the local address for unicast mode or 115the group address for multicast mode, 116and the listening (local) port number. 117Since multiple 118.Nm 119interfaces may be created that either 120use the same local address 121or join the same group address, 122and use the same port, 123the driver may share a socket among multiple interfaces. 124However, each interface within a socket must belong to 125a unique 126.Nm 127segment. 128The analogous 129.Xr vlan 4 130configuration would be a physical interface configured as 131the parent device for multiple VLAN interfaces, each with 132a unique VLAN tag. 133Each 134.Nm 135segment is identified by a 24-bit value in the 136.Nm 137header called the 138.Dq VXLAN Network Identifier , 139or VNI. 140.Pp 141When configured with the 142.Xr ifconfig 8 143.Cm vxlanlearn 144parameter, the interface dynamically creates forwarding table entries 145from received packets. 146An entry in the forwarding table maps the inner source MAC address 147to the outer remote IP address. 148During transmit, the interface attempts to lookup an entry for 149the encapsulated destination MAC address. 150If an entry is found, the IP address in the entry is used to directly 151transmit the encapsulated frame to the destination. 152Otherwise, when configured in multicast mode, 153the interface must flood the frame to all hosts in the group. 154The maximum number of entries in the table is configurable with the 155.Xr ifconfig 8 156.Cm vxlanmaxaddr 157command. 158Stale entries in the table periodically pruned. 159The timeout is configurable with the 160.Xr ifconfig 8 161.Cm vxlantimeout 162command. 163The table may be viewed with the 164.Xr sysctl 8 165.Cm net.link.vxlan.N.ftable.dump 166command. 167.Sh MTU 168Since the 169.Nm 170interface encapsulates the Ethernet frame with an IP, UDP, and 171.Nm 172header, the resulting frame may be larger than the MTU of the 173physical network. 174The 175.Nm 176specification recommends the physical network MTU be configured 177to use jumbo frames to accommodate the encapsulated frame size. 178Alternatively, the 179.Xr ifconfig 8 180.Cm mtu 181command may be used to reduce the MTU size on the 182.Nm 183interface to allow the encapsulated frame to fit in the 184current MTU of the physical network. 185.Sh EXAMPLES 186Create a 187.Nm 188interface in unicast mode 189with the 190.Cm vxlanlocal 191tunnel address of 192.168.100.1, 192and the 193.Cm vxlanremote 194tunnel address of 192.168.100.2. 195.Bd -literal -offset indent 196ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2 197.Ed 198.Pp 199Create a 200.Nm 201interface in multicast mode, 202with the 203.Cm local 204address of 192.168.10.95, 205and the 206.Cm group 207address of 224.0.2.6. 208The em0 interface will be used to transmit multicast packets. 209.Bd -literal -offset indent 210ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0 211.Ed 212.Pp 213Once created, the 214.Nm 215interface can be configured with 216.Xr ifconfig 8 . 217.Pp 218The following when placed in the file 219.Pa /etc/rc.conf 220will cause a vxlan interface called 221.Dq Li vxlan0 222to be created, and will configure the interface in unicast mode. 223.Bd -literal -offset indent 224cloned_interfaces="vxlan0" 225create_args_vxlan0="vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2" 226.Ed 227.Sh SEE ALSO 228.Xr inet 4 , 229.Xr inet6 4 , 230.Xr vlan 4 , 231.Xr rc.conf 5 , 232.Xr ifconfig 8 , 233.Xr sysctl 8 234.Rs 235.%A "M. Mahalingam" 236.%A "et al" 237.%T "Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks" 238.%D August 2014 239.%O "RFC 7348" 240.Re 241.Sh AUTHORS 242.An -nosplit 243The 244.Nm 245driver was written by 246.An Bryan Venteicher Aq bryanv@freebsd.org . 247