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

FreeBSD Manual Pages


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 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 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 encap-
     sulated (inner) frame is able to be 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 to	the remote host	if there is an appro-
     priate 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 are pe-
     riodically	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.

     By	default, the vxlan driver sets its MTU to usual	ethernet MTU of	1500
     bytes, reduced by the size	of vxlan headers prepended to the encapsulated

     Alternatively, the	ifconfig(8) mtu	command	may be used to set the fixed
     MTU size on the vxlan interface to	allow the encapsulated frame to	fit in
     the current MTU of	the physical network.  If the mtu command was used,
     system no longer adjust the vxlan interface MTU on	routing	or address

     The vxlan driver supports hardware	checksum offload (receive and trans-
     mit) and TSO on the encapsulated traffic over physical interfaces that
     support these features.  The vxlan	interface examines the vxlandev	inter-
     face, if one is specified,	or the interface hosting the vxlanlocal	ad-
     dress, and	configures its capabilities based on the hardware offload ca-
     pabilities	of that	physical interface.  If	multiple physical interfaces
     will transmit or receive traffic for the vxlan then they all must have
     the same hardware capabilities.  The transmit routine of a	vxlan inter-
     face may fail with	ENXIO if an outbound physical interface	does not sup-
     port an offload that the vxlan interface is requesting.  This can happen
     if	there are multiple physical interfaces involved, with different	hard-
     ware capabilities,	or an interface	capability was disabled	after the
     vxlan interface had already started.

     At	present, these devices are capable of generating checksums and per-
     forming TSO on the	inner frames in	hardware: cxgbe(4).

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

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

	   create_args_vxlan0="vxlanid 108 vxlanlocal vxlanremote"

     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.

     The vxlan driver was written by Bryan Venteicher <>.
     Support for stateless hardware offloads was added by Navdeep Parhar
     <> in FreeBSD 13.0.

FreeBSD	13.0			March 30, 2021			  FreeBSD 13.0


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

home | help