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

FreeBSD Manual Pages


home | help
VXLAN(4)		 BSD 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 de-
     signed to be better suited	for large, multiple tenant data	center envi-

     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 sup-
     ports the usual network ioctl(2)s and is thus can be used with
     ifconfig(8) like any other	Ethernet interface.  The vxlan interface en-
     capsulates	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	multi-
     cast mode,	the interface joins an IP multicast group, and receives	pack-
     ets sent to the group address, and	transmits packets to either the	multi-
     cast group	address, or directly the remote	host if	there is an appropri-
     ate 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 num-
     ber.  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 en-
     try 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 period-
     ically 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 encapsu-
     lated 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 ad-
     dress 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 <>.

BSD			       December	16, 2014			   BSD


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

home | help