1.\" $OpenBSD: vxlan.4,v 1.6 2016/09/03 15:27:54 jmc 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: September 3 2016 $ 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 28interface is a tunnelling pseudo-device for overlaying virtualized 29layer 2 networks over layer 3 networks. 30.Pp 31A 32.Nm 33interface can be created using the 34.Ic ifconfig vxlan Ns Ar N Ic create 35command. 36Once configured, the interface encapsulates and decapsulates Ethernet 37frames in UDP datagrams that are exchanged with tunnel endpoints. 38The default UDP port for VXLAN traffic is 4789. 39.Pp 40Each 41.Nm 42interface uses a 24-bit 43.Ic vnetid 44(virtual networks identifier) 45that distinguishes multiple virtualized layer 2 networks and 46their tunnels between identical tunnel endpoints. 47.Pp 48The interface can operate in the following tunnel modes: 49.Bl -tag -width multicast 50.It Ic unicast mode 51When a unicast IP address is configured as the tunnel destination, 52all traffic is sent to a single tunnel endpoint. 53.It Ic multicast mode 54When a multicast IP address is configured as the tunnel destination, 55all traffic is sent to all the tunnel endpoints that subscribed for the 56specified multicast group. 57.It Ic dynamic mode 58When 59.Nm 60is configured for multicast mode and added to a 61.Xr bridge 4 , 62all broadcast and multicast traffic is sent to the multicast group, 63but directed traffic is sent to unicast IP addresses of individual tunnel 64endpoints as they are learned by the bridge. 65.It Ic multipoint mode 66When 67.Nm 68is configured with 69.Ic vnetid any 70and added to a 71.Xr bridge 4 , 72all return traffic is sent to the known tunnel endpoints 73as they are learned by the bridge. 74In this mode, 75.Nm 76does not use a specific virtual network identifier but learns the ones 77of the individual tunnel endpoints. 78It is used to dynamically bridge many virtual networks together. 79.El 80.Pp 81The configuration can be done at runtime or by setting up a 82.Xr hostname.if 5 83configuration file for 84.Xr netstart 8 . 85.Sh EXAMPLES 86Create a tunnel to a unicast tunnel endpoint, using the virtual tunnel 87identifier 5: 88.Bd -literal -offset indent 89# ifconfig vxlan0 tunnel 192.168.1.100 192.168.1.200 vnetid 5 90# ifconfig vxlan0 10.1.1.100/24 91.Ed 92.Pp 93The following examples creates a dynamic tunnel that is attached to a 94.Xr bridge 4 : 95.Bd -literal -offset indent 96# ifconfig vxlan0 tunnel 192.168.1.100 239.1.1.100 vnetid 7395 97# ifconfig vxlan0 10.1.2.100/24 98# ifconfig bridge0 add vxlan0 up 99.Ed 100.Pp 101Prior to the assignment of UDP port 4789 by IANA, some early VXLAN 102implementations used port 8472. 103A non-standard port can be specified with the tunnel destination 104address: 105.Bd -literal -offset indent 106# ifconfig vxlan0 tunnel 192.168.1.100 239.1.1.100:8472 107.Ed 108.Sh SECURITY 109.Nm 110does not provide any integrated security features. 111It is designed to be a simple protocol that can be used in trusted 112data center environments, to carry VM traffic between virtual machine 113hypervisors, and provide virtualized layer 2 networks in Cloud 114infrastructures. 115.Pp 116To protect 117.Nm 118tunnels, the traffic can be protected with IPsec to add authentication 119and encryption for confidentiality. 120.Pp 121The Packet Filter (PF) can be used to filter tunnel traffic with 122endpoint policies in 123.Xr pf.conf 5 : 124.Bd -literal -offset indent 125table <vxlantep> { 192.168.1.200, 192.168.1.201 } 126block in on vmx0 127pass out on vmx0 128pass in on vmx0 proto udp from <vxlantep> to port vxlan 129.Ed 130.Pp 131The Time-to-Live (TTL) value of the tunnel can be set to 1 or a low 132value to restrict the traffic to the local network: 133.Bd -literal -offset indent 134# ifconfig vxlan0 tunnelttl 1 135.Ed 136.Sh SEE ALSO 137.Xr bridge 4 , 138.Xr inet 4 , 139.Xr hostname.if 5 , 140.Xr ifconfig 8 , 141.Xr netstart 8 142.Sh STANDARDS 143.Rs 144.%A M. Mahalingam 145.%A D. Dutt 146.%A K. Duda 147.%A P. Agarwal 148.%A L. Kreeger 149.%A T. Sridhar 150.%A M. Bursell 151.%A C. Wright 152.%D May 2013 153.%R draft-mahalingam-dutt-dcops-vxlan-04 154.%T VXLAN: A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks 155.Re 156.Sh HISTORY 157The 158.Nm 159device first appeared in 160.Ox 5.5 . 161.Sh AUTHORS 162The 163.Nm 164driver was written by 165.An Reyk Floeter Aq Mt reyk@openbsd.org . 166.Sh CAVEATS 167The 168.Nm 169interface requires at least 50 bytes for the IP, UDP and VXLAN 170protocol overhead and optionally 4 bytes for the encapsulated VLAN tag. 171The default MTU is set to 1500 bytes but can be adjusted if the 172transport interfaces carrying the tunnel traffic do not support larger 173MTUs, the tunnel traffic is leaving the local network, or if 174interoperability with another implementation requires running a 175decreased MTU of 1450 bytes. 176In any other case, it is commonly recommended to set the MTU of the 177transport interfaces to at least 1600 bytes. 178.Pp 179The implementation does not support IPv6 tunnel endpoints at present. 180