xref: /freebsd/share/man/man4/vxlan.4 (revision ae7e8a02e6e93455e026036132c4d053b2c12ad9)
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 March 30, 2021
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 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 be 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 to 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 are 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.
178.Pp
179By default, the
180.Nm
181driver sets its MTU to usual ethernet MTU of 1500 bytes, reduced by
182the size of vxlan headers prepended to the encapsulated packets.
183.Pp
184Alternatively, the
185.Xr ifconfig 8
186.Cm mtu
187command may be used to set the fixed MTU size on the
188.Nm
189interface to allow the encapsulated frame to fit in the
190current MTU of the physical network.
191If the
192.Cm mtu
193command was used, system no longer adjust the
194.Nm
195interface MTU on routing or address changes.
196.Sh HARDWARE
197The
198.Nm
199driver supports hardware checksum offload (receive and transmit) and TSO on the
200encapsulated traffic over physical interfaces that support these features.
201The
202.Nm
203interface examines the
204.Cm vxlandev
205interface, if one is specified, or the interface hosting the
206.Cm vxlanlocal
207address, and configures its capabilities based on the hardware offload
208capabilities of that physical interface.
209If multiple physical interfaces will transmit or receive traffic for the
210.Nm
211then they all must have the same hardware capabilities.
212The transmit routine of a
213.Nm
214interface may fail with
215.Er ENXIO
216if an outbound physical interface does not support
217an offload that the
218.Nm
219interface is requesting.
220This can happen if there are multiple physical interfaces involved, with
221different hardware capabilities, or an interface capability was disabled after
222the
223.Nm
224interface had already started.
225.Pp
226At present, these devices are capable of generating checksums and performing TSO
227on the inner frames in hardware:
228.Xr cxgbe 4 .
229.Sh EXAMPLES
230Create a
231.Nm
232interface in unicast mode
233with the
234.Cm vxlanlocal
235tunnel address of 192.168.100.1,
236and the
237.Cm vxlanremote
238tunnel address of 192.168.100.2.
239.Bd -literal -offset indent
240ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2
241.Ed
242.Pp
243Create a
244.Nm
245interface in multicast mode,
246with the
247.Cm local
248address of 192.168.10.95,
249and the
250.Cm group
251address of 224.0.2.6.
252The em0 interface will be used to transmit multicast packets.
253.Bd -literal -offset indent
254ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0
255.Ed
256.Pp
257Once created, the
258.Nm
259interface can be configured with
260.Xr ifconfig 8 .
261.Pp
262The following when placed in the file
263.Pa /etc/rc.conf
264will cause a vxlan interface called
265.Dq Li vxlan0
266to be created, and will configure the interface in unicast mode.
267.Bd -literal -offset indent
268cloned_interfaces="vxlan0"
269create_args_vxlan0="vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2"
270.Ed
271.Sh SEE ALSO
272.Xr inet 4 ,
273.Xr inet6 4 ,
274.Xr vlan 4 ,
275.Xr rc.conf 5 ,
276.Xr ifconfig 8 ,
277.Xr sysctl 8
278.Rs
279.%A "M. Mahalingam"
280.%A "et al"
281.%T "Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks"
282.%D August 2014
283.%O "RFC 7348"
284.Re
285.Sh AUTHORS
286.An -nosplit
287The
288.Nm
289driver was written by
290.An Bryan Venteicher Aq bryanv@freebsd.org .
291Support for stateless hardware offloads was added by
292.An Navdeep Parhar Aq np@freebsd.org
293in
294.Fx 13.0 .
295