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 December 16, 2014
  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 is 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 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 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 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 EXAMPLES
 186 Create a
 187 .Nm
 188 interface in unicast mode
 189 with the
 190 .Cm vxlanlocal
 191 tunnel address of 192.168.100.1,
 192 and the
 193 .Cm vxlanremote
 194 tunnel address of 192.168.100.2.
 195 .Bd -literal -offset indent
 196 ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2
 197 .Ed
 198 .Pp
 199 Create a
 200 .Nm
 201 interface in multicast mode,
 202 with the
 203 .Cm local
 204 address of 192.168.10.95,
 205 and the
 206 .Cm group
 207 address of 224.0.2.6.
 208 The em0 interface will be used to transmit multicast packets.
 209 .Bd -literal -offset indent
 210 ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0
 211 .Ed
 212 .Pp
 213 Once created, the
 214 .Nm
 215 interface can be configured with
 216 .Xr ifconfig 8 .
 217 .Sh SEE ALSO
 218 .Xr ifconfig 8 ,
 219 .Xr inet 4 ,
 220 .Xr inet 6 ,
 221 .Xr sysctl 8 ,
 222 .Xr vlan 8
 223 .Rs
 224 .%A "M. Mahalingam"
 225 .%A "et al"
 226 .%T "Virtual eXtensible Local Area Network (VXLAN): A Framework for Overlaying Virtualized Layer 2 Networks over Layer 3 Networks"
 227 .%D August 2014
 228 .%O "RFC 7348"
 229 .Re
 230 .Sh AUTHOR
 231 .An -nosplit
 232 The
 233 .Nm
 234 driver was written by
 235 .An Bryan Venteicher Aq bryanv@freebsd.org .