EPAIR(4)

💖 EPAIR(4) 💖

okay so bestie, welcome to the kernel interfaces manual page for epair — and yes, we're doing the whole thing, every flag, every tunable, no skipping 🫶

---

✨ NAME ✨

epair — a pair of virtual back-to-back connected Ethernet interfaces. that's it. that's the vibe. two interfaces, holding hands, cross-over cable style 💅

---

🦋 SYNOPSIS 🦋

so if you wanna bake this driver straight into your kernel, drop this line into your kernel configuration file:

device epair

or, alternatively — if compiling-in isn't your era and you'd rather load it as a module at boot time — put this line in loader.conf(5):

if_epair_load="YES"

both valid. both slay. pick your fighter ✨

---

🎀 DESCRIPTION 🎀

epair is literally a pair of Ethernet-like software interfaces, and they're connected back-to-back with a virtual cross-over cable. besties with a wire between them, fr fr 🔥

each epair interface pair gets created at runtime using interface cloning — most easily done with the ifconfig(8) create command, or by using the cloned_interfaces variable in rc.conf(5). and here's the cute part: when you clone, you only give either epair or epair<n>, and the resulting pair gets named like epair<n>[ab]. so the names of the first epair interfaces will be epair0a and epair0b. adorable. iconic. 💖

like any other Ethernet interface, an epair needs a network address — no address, no address, y'know? now, the MAC situation:

• if the tunable net.link.epair.ether_gen_addr=0, each epair gets assigned a random locally administered address — and that one 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 👀. and if you wanna change the default addresses yourself, you can use the SIOCSIFADDR ioctl(2) or the ifconfig(8) utility.

the basic intent here — the whole reason this exists — is to provide connectivity between two virtual network stack instances. and when it's connected to an if_bridge(4), one end of the interface pair can also be part of another (virtual) LAN. just like any other Ethernet interface, epair can have a vlan(4) configured on top of it. layers on layers, bestie 🌈

🌸 the checksum tea 🌸

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

it also supports TXCSUM and TXCSUM6 for TCP and UDP — but only by forwarding the order to compute the checksum. so when you're using an epair interface, a TCP or UDP sender can offload checksum computation to a physical interface. and note this caveat, because it matters:

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. why? because in case one end is in a bridge and the bridge disabled TXCSUM or TXCSUM6, this avoids a sender sending packets with checksum offloading into the bridge by using the other end. teamwork, but make it networking 🫶

🧚 the VLAN_HWTAGGING of it all 🧚

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. sneaky? a little. effective? extremely ✨

and 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. same rules, same energy, both ends always matching 💅

---

🍓 SEE ALSO 🍓

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

go read them, they're all lowkey relevant, iykyk 👑

---

⭐ HISTORY ⭐

the epair interface first appeared in FreeBSD 8.0. a whole era. a whole legend. 🎀

---

👑 AUTHORS 👑

the epair interface was written by Bjoern A. Zeeb, CK Software GmbH, under sponsorship from the FreeBSD Foundation. absolute main character energy, no cap 💜

---

okay that's the whole page, you understood every word, i'm so proud of you 😭💖 this was the Debian build, dated January 30, 2026 — go forth and clone some interfaces, bestie 🌸🦋