---
name: "epair"
section: "4"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/epair"
---

# epair(4)

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

## 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)](/loader.conf/5.md):

```
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)](/ifconfig/8.md) **create** command or using the *cloned\_interfaces* variable in [rc.conf(5)](/rc.conf/5.md). 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)](/ether_gen_addr/9.md). This tunable defaults to 1 in FreeBSD 15.0 FreeBSD 16.0. To change the default addresses one may use the SIOCSIFADDR [ioctl(2)](/ioctl/2.md) or [ifconfig(8)](/ifconfig/8.md) utility.

The basic intent is to provide connectivity between two virtual network stack instances. When connected to an [if\_bridge(4)](/if_bridge/4.md), 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)](/vlan/4.md) configured on top of it.

The **epair** supports RXCSUM and RXCSUM6 but does not validate a checksum. In case an interface previously validated the checksum, **epair** leaves the flags set that indicate a valid checksum if RXCSUM and RXCSUM6 are enabled or unsets these flags if RXCSUM and RXCSUM6 are disabled. Note that RXCSUM and RXCSUM6 can only be enabled or disabled as a pair.

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)](/ioctl/2.md), [altq(4)](/altq/4.md), [bpf(4)](/bpf/4.md), [if\_bridge(4)](/if_bridge/4.md), [vlan(4)](/vlan/4.md), [loader.conf(5)](/loader.conf/5.md), [rc.conf(5)](/rc.conf/5.md), [ifconfig(8)](/ifconfig/8.md)

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