1.\" $OpenBSD: vxlan.4,v 1.3 2013/10/13 10:52:35 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: October 13 2013 $ 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 three different 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.El 66.Pp 67The configuration can be done at runtime or by setting up a 68.Xr hostname.if 5 69configuration file for 70.Xr netstart 8 . 71.Sh EXAMPLES 72Create a tunnel to a unicast tunnel endpoint, using the virtual tunnel 73identifier 5: 74.Bd -literal -offset indent 75# ifconfig vxlan0 tunnel 192.168.1.100 192.168.1.200 vnetid 5 76# ifconfig vxlan0 10.1.1.100/24 77.Ed 78.Pp 79The following examples creates a dynamic tunnel that is attached to a 80.Xr bridge 4 : 81.Bd -literal -offset indent 82# ifconfig vxlan0 tunnel 192.168.1.100 239.1.1.100 vnetid 7395 83# ifconfig vxlan0 10.1.2.100/24 84# ifconfig bridge0 add vxlan0 up 85.Ed 86.Pp 87Prior to the assignment of UDP port 4789 by IANA, some early VXLAN 88implementations used port 8472. 89A non-standard port can be specified with the tunnel destination 90address: 91.Bd -literal -offset indent 92# ifconfig vxlan0 tunnel 192.168.1.100 239.1.1.100:8472 93.Ed 94.Sh SECURITY 95.Nm 96does not provide any integrated security features. 97It is designed to be a simple protocol that can be used in trusted 98data center environments, to carry VM traffic between virtual machine 99hypervisors, and provide virtualized layer 2 networks in Cloud 100infrastructures. 101.Pp 102To protect 103.Nm 104tunnels, the traffic can be protected with IPsec to add authentication 105and encryption for confidentiality. 106.Pp 107The Packet Filter (PF) can be used to filter tunnel traffic with 108endpoint policies in 109.Xr pf.conf 5 : 110.Bd -literal -offset indent 111table <vxlantep> { 192.168.1.200 192.168.1.201 } 112block in on vmx0 113pass out on vmx0 114pass in on vmx0 proto udp from <vxlantep> to port 4789 115.Ed 116.Pp 117The Time-to-Live (TTL) value of the tunnel can be set to 1 or a low 118value to restrict the traffic to the local network: 119.Bd -literal -offset indent 120# ifconfig vxlan0 tunnelttl 1 121.Ed 122.Sh SEE ALSO 123.Xr bridge 4 , 124.Xr inet 4 , 125.Xr hostname.if 5 , 126.Xr ifconfig 8 , 127.Xr netstart 8 128.Sh STANDARDS 129.Rs 130.%A M. Mahalingam 131.%A D. Dutt 132.%A K. Duda 133.%A P. Agarwal 134.%A L. Kreeger 135.%A T. Sridhar 136.%A M. Bursell 137.%A C. Wright 138.%D May 2013 139.%R draft-mahalingam-dutt-dcops-vxlan-04 140.%T VXLAN: A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks 141.Re 142.Sh HISTORY 143The 144.Nm 145device first appeared in 146.Ox 5.5 . 147.Sh AUTHORS 148The 149.Nm 150driver was written by 151.An Reyk Floeter Aq Mt reyk@openbsd.org . 152.Sh CAVEATS 153The 154.Nm 155interface requires at least 50 bytes for the IP, UDP and VXLAN 156protocol overhead and optionally 4 bytes for the encapsulated VLAN tag. 157The default MTU is set to 1500 bytes but can be adjusted if the 158transport interfaces carrying the tunnel traffic do not support larger 159MTUs, the tunnel traffic is leaving the local network, or if 160interoperability with another implementation requires running a 161decreased MTU of 1450 bytes. 162In any other case, it is commonly recommended to set the MTU of the 163transport interfaces to at least 1600 bytes. 164.Pp 165The implementation does not support IPv6 tunnel endpoints at present. 166