share/man/man4/vxlan.4

   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
  34 To compile this driver into the kernel,
  35 place the following line in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device vxlan"
  39 .Ed
  40 .Pp
  41 Alternatively, to load the driver as a
  42 module at boot time, place the following line in
  43 .Xr loader.conf 5 :
  44 .Bd -literal -offset indent
  45 if_vxlan_load="YES"
  46 .Ed
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 driver creates a virtual tunnel endpoint in a
  51 .Nm
  52 segment.
  53 A
  54 .Nm
  55 segment is a virtual Layer 2 (Ethernet) network that is overlaid
  56 in a Layer 3 (IP/UDP) network.
  57 .Nm
  58 is analogous to
  59 .Xr vlan 4
  60 but is designed to be better suited for large, multiple tenant
  61 data center environments.
  62 .Pp
  63 Each
  64 .Nm
  65 interface is created at runtime using interface cloning.
  66 This is most easily done with the
  67 .Xr ifconfig 8
  68 .Cm create
  69 command or using the
  70 .Va cloned_interfaces
  71 variable in
  72 .Xr rc.conf 5 .
  73 The interface may be removed with the
  74 .Xr ifconfig 8
  75 .Cm destroy
  76 command.
  77 .Pp
  78 The
  79 .Nm
  80 driver creates a pseudo Ethernet network interface
  81 that supports the usual network
  82 .Xr ioctl 2 Ns s
  83 and thus can be used with
  84 .Xr ifconfig 8
  85 like any other Ethernet interface.
  86 The
  87 .Nm
  88 interface encapsulates the Ethernet frame
  89 by prepending IP/UDP and
  90 .Nm
  91 headers.
  92 Thus, the encapsulated (inner) frame is able to be transmitted
  93 over a routed, Layer 3 network to the remote host.
  94 .Pp
  95 The
  96 .Nm
  97 interface may be configured in either unicast or multicast mode.
  98 When in unicast mode,
  99 the interface creates a tunnel to a single remote host,
 100 and all traffic is transmitted to that host.
 101 When in multicast mode,
 102 the interface joins an IP multicast group,
 103 and receives packets sent to the group address,
 104 and transmits packets to either the multicast group address,
 105 or directly to the remote host if there is an appropriate
 106 forwarding table entry.
 107 .Pp
 108 When the
 109 .Nm
 110 interface is brought up, a
 111 .Xr udp 4
 112 .Xr socket 9
 113 is created based on the configuration,
 114 such as the local address for unicast mode or
 115 the group address for multicast mode,
 116 and the listening (local) port number.
 117 Since multiple
 118 .Nm
 119 interfaces may be created that either
 120 use the same local address
 121 or join the same group address,
 122 and use the same port,
 123 the driver may share a socket among multiple interfaces.
 124 However, each interface within a socket must belong to
 125 a unique
 126 .Nm
 127 segment.
 128 The analogous
 129 .Xr vlan 4
 130 configuration would be a physical interface configured as
 131 the parent device for multiple VLAN interfaces, each with
 132 a unique VLAN tag.
 133 Each
 134 .Nm
 135 segment is identified by a 24-bit value in the
 136 .Nm
 137 header called the
 138 .Dq VXLAN Network Identifier ,
 139 or VNI.
 140 .Pp
 141 When configured with the
 142 .Xr ifconfig 8
 143 .Cm vxlanlearn
 144 parameter, the interface dynamically creates forwarding table entries
 145 from received packets.
 146 An entry in the forwarding table maps the inner source MAC address
 147 to the outer remote IP address.
 148 During transmit, the interface attempts to lookup an entry for
 149 the encapsulated destination MAC address.
 150 If an entry is found, the IP address in the entry is used to directly
 151 transmit the encapsulated frame to the destination.
 152 Otherwise, when configured in multicast mode,
 153 the interface must flood the frame to all hosts in the group.
 154 The maximum number of entries in the table is configurable with the
 155 .Xr ifconfig 8
 156 .Cm vxlanmaxaddr
 157 command.
 158 Stale entries in the table are periodically pruned.
 159 The timeout is configurable with the
 160 .Xr ifconfig 8
 161 .Cm vxlantimeout
 162 command.
 163 The table may be viewed with the
 164 .Xr sysctl 8
 165 .Cm net.link.vxlan.N.ftable.dump
 166 command.
 167 .Sh MTU
 168 Since the
 169 .Nm
 170 interface encapsulates the Ethernet frame with an IP, UDP, and
 171 .Nm
 172 header, the resulting frame may be larger than the MTU of the
 173 physical network.
 174 The
 175 .Nm
 176 specification recommends the physical network MTU be configured
 177 to use jumbo frames to accommodate the encapsulated frame size.
 178 .Pp
 179 By default, the
 180 .Nm
 181 driver sets its MTU to usual ethernet MTU of 1500 bytes, reduced by
 182 the size of vxlan headers prepended to the encapsulated packets.
 183 .Pp
 184 Alternatively, the
 185 .Xr ifconfig 8
 186 .Cm mtu
 187 command may be used to set the fixed MTU size on the
 188 .Nm
 189 interface to allow the encapsulated frame to fit in the
 190 current MTU of the physical network.
 191 If the
 192 .Cm mtu
 193 command was used, system no longer adjust the
 194 .Nm
 195 interface MTU on routing or address changes.
 196 .Sh HARDWARE
 197 The
 198 .Nm
 199 driver supports hardware checksum offload (receive and transmit) and TSO on the
 200 encapsulated traffic over physical interfaces that support these features.
 201 The
 202 .Nm
 203 interface examines the
 204 .Cm vxlandev
 205 interface, if one is specified, or the interface hosting the
 206 .Cm vxlanlocal
 207 address, and configures its capabilities based on the hardware offload
 208 capabilities of that physical interface.
 209 If multiple physical interfaces will transmit or receive traffic for the
 210 .Nm
 211 then they all must have the same hardware capabilities.
 212 The transmit routine of a
 213 .Nm
 214 interface may fail with
 215 .Er ENXIO
 216 if an outbound physical interface does not support
 217 an offload that the
 218 .Nm
 219 interface is requesting.
 220 This can happen if there are multiple physical interfaces involved, with
 221 different hardware capabilities, or an interface capability was disabled after
 222 the
 223 .Nm
 224 interface had already started.
 225 .Pp
 226 At present, these devices are capable of generating checksums and performing TSO
 227 on the inner frames in hardware:
 228 .Xr cxgbe 4 .
 229 .Sh EXAMPLES
 230 Create a
 231 .Nm
 232 interface in unicast mode
 233 with the
 234 .Cm vxlanlocal
 235 tunnel address of 192.168.100.1,
 236 and the
 237 .Cm vxlanremote
 238 tunnel address of 192.168.100.2.
 239 .Bd -literal -offset indent
 240 ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2
 241 .Ed
 242 .Pp
 243 Create a
 244 .Nm
 245 interface in multicast mode,
 246 with the
 247 .Cm local
 248 address of 192.168.10.95,
 249 and the
 250 .Cm group
 251 address of 224.0.2.6.
 252 The em0 interface will be used to transmit multicast packets.
 253 .Bd -literal -offset indent
 254 ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0
 255 .Ed
 256 .Pp
 257 Once created, the
 258 .Nm
 259 interface can be configured with
 260 .Xr ifconfig 8 .
 261 .Pp
 262 The following when placed in the file
 263 .Pa /etc/rc.conf
 264 will cause a vxlan interface called
 265 .Dq Li vxlan0
 266 to be created, and will configure the interface in unicast mode.
 267 .Bd -literal -offset indent
 268 cloned_interfaces="vxlan0"
 269 create_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
 287 The
 288 .Nm
 289 driver was written by
 290 .An Bryan Venteicher Aq bryanv@freebsd.org .
 291 Support for stateless hardware offloads was added by
 292 .An Navdeep Parhar Aq np@freebsd.org
 293 in
 294 .Fx 13.0 .