NAME

     vxlan — Virtual eXtensible LAN interface

SYNOPSIS

     To compile this driver into the kernel, place the following line in your kernel
     configuration file:

           device vxlan

     Alternatively, to load the driver as a module at boot time, place the following line in
     loader.conf(5):

           if_vxlan_load="YES"

DESCRIPTION

     The vxlan driver creates a virtual tunnel endpoint in a vxlan segment.  A vxlan segment is a
     virtual Layer 2 (Ethernet) network that is overlaid in a Layer 3 (IP/UDP) network.  vxlan is
     analogous to vlan(4) but is designed to be better suited for large, multiple tenant data
     center environments.

     Each vxlan interface is created at runtime using interface cloning.  This is most easily
     done with the ifconfig(8) create command or using the cloned_interfaces variable in
     rc.conf(5).  The interface may be removed with the ifconfig(8) destroy command.

     The vxlan driver creates a pseudo Ethernet network interface that supports the usual network
     ioctl(2)s and is thus can be used with ifconfig(8) like any other Ethernet interface.  The
     vxlan interface encapsulates the Ethernet frame by prepending IP/UDP and vxlan headers.
     Thus, the encapsulated (inner) frame is able to transmitted over a routed, Layer 3 network
     to the remote host.

     The vxlan interface may be configured in either unicast or multicast mode.  When in unicast
     mode, the interface creates a tunnel to a single remote host, and all traffic is transmitted
     to that host.  When in multicast mode, the interface joins an IP multicast group, and
     receives packets sent to the group address, and transmits packets to either the multicast
     group address, or directly the remote host if there is an appropriate forwarding table
     entry.

     When the vxlan interface is brought up, a UDP(4) socket(9) is created based on the
     configuration, such as the local address for unicast mode or the group address for multicast
     mode, and the listening (local) port number.  Since multiple vxlan interfaces may be created
     that either use the same local address or join the same group address, and use the same
     port, the driver may share a socket among multiple interfaces.  However, each interface
     within a socket must belong to a unique vxlan segment.  The analogous vlan(4) configuration
     would be a physical interface configured as the parent device for multiple VLAN interfaces,
     each with a unique VLAN tag.  Each vxlan segment is identified by a 24-bit value in the
     vxlan header called the “VXLAN Network Identifier”, or VNI.

     When configured with the ifconfig(8) vxlanlearn parameter, the interface dynamically creates
     forwarding table entries from received packets.  An entry in the forwarding table maps the
     inner source MAC address to the outer remote IP address.  During transmit, the interface
     attempts to lookup an entry for the encapsulated destination MAC address.  If an entry is
     found, the IP address in the entry is used to directly transmit the encapsulated frame to
     the destination.  Otherwise, when configured in multicast mode, the interface must flood the
     frame to all hosts in the group.  The maximum number of entries in the table is configurable
     with the ifconfig(8) vxlanmaxaddr command.  Stale entries in the table periodically pruned.
     The timeout is configurable with the ifconfig(8) vxlantimeout command.  The table may be
     viewed with the sysctl(8) net.link.vxlan.N.ftable.dump command.

MTU

     Since the vxlan interface encapsulates the Ethernet frame with an IP, UDP, and vxlan header,
     the resulting frame may be larger than the MTU of the physical network.  The vxlan
     specification recommends the physical network MTU be configured to use jumbo frames to
     accommodate the encapsulated frame size.  Alternatively, the ifconfig(8) mtu command may be
     used to reduce the MTU size on the vxlan interface to allow the encapsulated frame to fit in
     the current MTU of the physical network.

EXAMPLES

     Create a vxlan interface in unicast mode with the vxlanlocal tunnel address of
     192.168.100.1, and the vxlanremote tunnel address of 192.168.100.2.

           ifconfig vxlan create vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2

     Create a vxlan interface in multicast mode, with the local address of 192.168.10.95, and the
     group address of 224.0.2.6.  The em0 interface will be used to transmit multicast packets.

           ifconfig vxlan create vxlanid 42 vxlanlocal 192.168.10.95 vxlangroup 224.0.2.6 vxlandev em0

     Once created, the vxlan interface can be configured with ifconfig(8).

     The following when placed in the file /etc/rc.conf will cause a vxlan interface called
     “vxlan0” to be created, and will configure the interface in unicast mode.

           cloned_interfaces="vxlan0"
           create_args_vxlan0="vxlanid 108 vxlanlocal 192.168.100.1 vxlanremote 192.168.100.2"

SEE ALSO

     inet(4), inet6(4), vlan(4), rc.conf(5), ifconfig(8), sysctl(8)

     M. Mahalingam and et al, Virtual eXtensible Local Area Network (VXLAN): A Framework for
     Overlaying Virtualized Layer 2 Networks over Layer 3 Networks, August 2014, RFC 7348.

AUTHOR

     The vxlan driver was written by Bryan Venteicher <bryanv@freebsd.org>.