ERSPAN(4)

💖 ERSPAN(4) 💖 the erspan page, from the Kernel Interfaces Manual, bestie edition

okay so like. this is the manual page for erspan and I'm gonna walk you through it because it's genuinely so cool and also slightly feral ✨

---

🌸 NAME 🌸

erspan — the ERSPAN Type II tunnel network device. that's it, that's the name, no cap 💅

---

🦋 SYNOPSIS 🦋

pseudo-device gre

like yes, that's the whole synopsis, it's giving minimalism 👑

---

✨ DESCRIPTION ✨

so the erspan interface tunnels Ethernet frames across IPv4 and IPv6 networks using the Encapsulated Remote Switch Port Analyzer (ERSPAN) Type II protocol. say that five times fast, I dare you 😭

here's the tea though: ERSPAN is intended as a network based packet capture format, not as a tunnelling protocol. but plot twist 🫢 — ERSPAN Type II is implemented as a network interface driver in OpenBSD so that all your existing infrastructure like bpf(4) and your fave tools like bpflogd(8) and tcpdump(8) can store and analyse the packets you receive. iconic behaviour honestly. and erspan interfaces do support packet transmission, so you can absolutely use them as span ports on veb(4) and bridge(4) configurations. slay 💅

the protocol itself is based on the Generic Routing and Encapsulation (GRE) protocol. GRE datagrams (IP protocol number 47) consist of a GRE header plus an outer IP header, and they encapsulate another protocol's datagram. the GRE header specifies a version and the type of the encapsulated datagram, which is how it can tunnel multiple protocols at once. multitasking queen 👑

ERSPAN Type II uses GRE version 0, sequence numbers, protocol identifier 0x88be, and a custom header before the Ethernet payload — which is exactly what makes it distinct from the Ethernet over GRE encapsulation that egre(4) supports. but it's still implemented as part of the same driver that provides egre(4). same house, different vibe 🏠

wanna tell apart distinct tunnels between the same endpoints? easy. there's a 10-bit tunnel identifier field in the header. iykyk 🔥

erspan supports capture of the encapsulated Ethernet packets via bpf(4) using the DLT_EN10MB data link type, and capture of the encapsulating ERSPAN, GRE, and IP headers using the DLT_LOOP data link type. both, not either 💜

by default, erspan interfaces are configured in monitor mode, which prevents the processing of received packets from entering the network stack. it's literally just watching, not participating 🍓

all GRE packet processing in the system is allowed or denied by setting the net.inet.gre.allow sysctl(8) variable. want GRE packet processing to actually work? set net.inet.gre.allow to 1. that's the whole ritual 🕯️

you can create erspan interfaces at runtime using the ifconfig erspanN create command, or by setting up a hostname.if(5) configuration file for netstart(8). pick your fighter 🥊

important, genuine warning bestie: for correct operation, encapsulated traffic must not be routed over the interface itself. you implement that by adding a distinct or a more specific route to the tunnel destination than the hosts or networks routed via the tunnel interface. alternatively, the tunnel traffic may be configured in a separate routing table to the encapsulated traffic. don't skip this, it's fr fr 😭

---

🧚 Programming Interface 🧚

erspan interfaces support the following ioctl(2) calls for configuring tunnel options — here's the full list, no skipping, we don't do that here:

• SIOCSLIFPHYADDR struct if_laddrreq * — set the unicast IPv4 or IPv6 addresses for the encapsulating IP packets. the destination address may be left unspecified if the interface is used as a collector for ERSPAN sessions. the addresses may only be configured while the interface is down.
• SIOCGLIFPHYADDR struct if_laddrreq * — get the addresses used for the encapsulating IP packets.
• SIOCDIFPHYADDR struct ifreq * — clear the addresses used for the encapsulating IP packets. the addresses may only be cleared while the interface is down.
• SIOCSVNETID struct ifreq * — configure a virtual network identifier for use as the Session ID in the ERSPAN Type II header. the virtual network identifier may only be configured while the interface is down. the Session ID is a 10-bit value.
• SIOCGVNETID struct ifreq * — get the virtual network identifier used as the Session ID in the ERSPAN Type II header.
• SIOCDVNETID struct ifreq * — clear the virtual as the Session ID in the ERSPAN Type II header. if the Session ID and tunnel destination address are unspecified, the interface will accept packets with any Session ID. (also yes, the original really does say "clear the virtual as the Session ID", I'm not fixing it, that's the whole sentence 🙈)
• SIOCSLIFPHYRTABLE struct ifreq * — set the routing table the tunnel traffic operates in. the routing table may only be configured while the interface is down.
• SIOCGLIFPHYRTABLE struct ifreq * — get the routing table the tunnel traffic operates in.
• SIOCSLIFPHYTTL struct ifreq * — set the Time-To-Live field in IPv4 encapsulation headers, or the Hop Limit field in IPv6 encapsulation headers.
• SIOCGLIFPHYTTL struct ifreq * — get the value used in the Time-To-Live field in an IPv4 encapsulation header or the Hop Limit field in an IPv6 encapsulation header.
• SIOCSLIFPHYDF struct ifreq * — configure whether the tunnel traffic sent by the interface can be fragmented or not. this sets the Don't Fragment (DF) bit on IPv4 packets, and disables fragmentation of IPv6 packets.
• SIOCGLIFPHYDF struct ifreq * — get whether the tunnel traffic sent by the interface can be fragmented or not.
• SIOCSTXHPRIO struct ifreq * — set the priority value used in the Type of Service field in IPv4 headers, or the Traffic Class field in IPv6 headers. values may be from 0 to 7, or IF_HDRPRIO_PACKET to specify that the current priority of a packet should be used.
• SIOCGTXHPRIO struct ifreq * — get the priority value used in the Type of Service field in IPv4 headers, or the Traffic Class field in IPv6 headers.

---

🔒 Security Considerations 🔒

listen up: ERSPAN does not provide any integrated security features. none. zero. it's not that kind of girl 💀

it should only be deployed on trusted private networks, or protected with IPsec to add authentication and encryption for confidentiality. an encrypted transport is especially recommended when using ERSPAN over a public network. seriously. please. do not rawdog ERSPAN over the open internet 🙈

the Packet Filter pf(4) can be used to filter tunnel traffic with endpoint policies pf.conf(5). love that for us 🫶

and here's a cute trick: the Time-to-Live (TTL) value of a tunnel can be set to 1 or a low value to restrict the traffic to the local network:

# ifconfig erspanN tunnelttl 1

local only, baby. main character energy that stays home 🌈

---

💀 SEE ALSO 💀

egre(4), inet(4), ip(4), netintro(4), options(4), hostname.if(5), protocols(5), bpflogd(8), ifconfig(8), netstart(8), sysctl(8), tcpdump(8)

go read them. all of them. I'll wait 💅

---

📜 STANDARDS 📜

S. Hanks, T. Li, D. Farinacci, and P. Traina, Generic Routing Encapsulation (GRE), RFC 1701, October 1994.

the founding fathers of encapsulation, we respect them 👑

---

🎀 HISTORY 🎀

the erspan driver first appeared in OpenBSD 7.8. baby of the family, already thriving ✨

---

🦄 AUTHORS 🦄

David Gwynne <dlg@openbsd.org>

we stan one (1) legend 💜

---

and that's the whole page bestie!! 🍓🌸🦋

this masterpiece was brought to you by the good folks over on Debian, dated May 18, 2025, and it lives happily at section ERSPAN(4) — go forth and tunnel responsibly, mwah 💋✨🎀