EPAIR(4)               FreeBSD Kernel Interfaces Manual               EPAIR(4)

NAME

     epair - A pair of virtual back-to-back connected Ethernet interfaces

SYNOPSIS

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

           device epair

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

           if_epair_load="YES"

DESCRIPTION

     The epair is a pair of Ethernet-like software interfaces, which are
     connected back-to-back with a virtual cross-over cable.

     Each epair interface pair 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).  While for cloning you only
     give either epair or epair<n> the epair pair will be named like
     epair<n>[ab].  This means the names of the first epair interfaces will be
     epair0a and epair0b.

     Like any other Ethernet interface, an epair needs to have a network
     address.  If the tunable net.link.epair.ether_gen_addr=0, each epair will
     be assigned a random locally administered address, that is only
     guaranteed to be unique within one network stack.  The tunable
     net.link.epair.ether_gen_addr=1 will generate a stable MAC address with
     FreeBSD OUI using ether_gen_addr(9).  This tunable defaults to 1 in
     FreeBSD 15.0 and might be removed in FreeBSD 16.0.  To change the default
     addresses one may use the SIOCSIFADDR ioctl(2) or ifconfig(8) utility.

     The basic intent is to provide connectivity between two virtual network
     stack instances.  When connected to an if_bridge(4), one end of the
     interface pair can also be part of another (virtual) LAN.  As with any
     other Ethernet interface, epair can have a vlan(4) configured on top of
     it.

     The epair has RXCSUM and RXCSUM6 enabled because it may receive a packet
     where the checksum has already been validated by a physical interface.

     The epair supports TXCSUM and TXCSUM6 for TCP and UDP, but only by
     forwarding the order to compute the checksum.  Thus, when using an epair
     interface, a TCP or UDP sender can offload checksum computation to a
     physical interface.  Note that, in case the packet does not leave the
     host, the checksum is unnecessary and will be ignored if offloaded.  Such
     packets contain an incorrect checksum, since it is not computed yet.
     TXCSUM and TXCSUM6 are synchronized between the epair interface pair
     (i.e., enabling/disabling the capability on one end enables/disables it
     on the other end).  In case one end is in a bridge and the bridge
     disabled TXCSUM or TXCSUM6, this avoids a sender to send packets with
     checksum offloading into the bridge by using the other end.

     The epair supports VLAN_HWTAGGING without actually adding a VLAN tag.
     The sending epair end just forwards the offloading information to the
     other end.  The receiving epair end leaves the offloading information set
     to pretend that there was a VLAN tag in the Ethernet header, which has
     been removed already.  To avoid a situation where the receiving epair end
     has VLAN_HWTAGGING disabled, this capability is synchronized between the
     epair interface pair (i.e., enabling/disabling the capability on one end
     enables/disables it on the other end).

SEE ALSO

     ioctl(2), altq(4), bpf(4), if_bridge(4), vlan(4), loader.conf(5),
     rc.conf(5), ifconfig(8)

HISTORY

     The epair interface first appeared in FreeBSD 8.0.

AUTHORS

     The epair interface was written by Bjoern A. Zeeb, CK Software GmbH,
     under sponsorship from the FreeBSD Foundation.

FreeBSD 15.1-STABLE-HBSD       January 30, 2026                       EPAIR(4)