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