Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
VXLAN(4)               FreeBSD Kernel Interfaces Manual               VXLAN(4)

     vxlan - Virtual eXtensible LAN interface

     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):


     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

     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) command.

     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.

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

           ifconfig vxlan create vxlanid 108 vxlanlocal vxlanremote

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

           ifconfig vxlan create vxlanid 42 vxlanlocal vxlangroup vxlandev em0

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

     ifconfig(8), inet(4), inet(6), sysctl(8), vlan(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.

     The vxlan driver was written by Bryan Venteicher <>.

FreeBSD 11.0-PRERELEASE        December 16, 2014       FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help