.\" $OpenBSD: erspan.4,v 1.3 2025/05/18 23:01:43 dlg Exp $ .\" $NetBSD: gre.4,v 1.10 1999/12/22 14:55:49 kleink Exp $ .\" .\" Copyright 1998 (c) The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Heiko W. Rupp .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: May 18 2025 $ .Dt ERSPAN 4 .Os .Sh NAME .Nm erspan .Nd ERSPAN Type II tunnel network device .Sh SYNOPSIS .Cd "pseudo-device gre" .Sh DESCRIPTION The .Nm interface provides tunnelling of Ethernet frames across IPv4 and IPv6 networks using the .\" Cisco Systems' Encapsulated Remote Switch Port Analyzer (ERSPAN) Type II protocol. .Pp ERSPAN is intended as a network based packet capture format rather than a tunnelling protocol. However, ERSPAN Type II is implemented as a network interface driver in .Ox to allow existing infrastructure such as .Xr bpf 4 and tools such as .Xr bpflogd 8 and .Xr tcpdump 8 to store and analyse the received packets. .Nm interfaces support packet transmission so they can be used as span ports on .Xr veb 4 and .Xr bridge 4 configurations. .Pp The protocol is based on the Generic Routing and Encapsulation (GRE) protocol. GRE datagrams (IP protocol number 47) consist of a GRE header and an outer IP header for encapsulating another protocol's datagram. The GRE header specifies a version and the type of the encapsulated datagram, allowing for the tunnelling of multiple protocols. ERSPAN Type II uses GRE version 0, sequence numbers, protocol identifier (0x88be), and a custom header before the Ethernet payload, making it distinct from the Ethernet over GRE encapsulation supported by .Xr egre 4 . However, it is implemented as part of the same driver providing .Xr egre 4 . .Pp Distinct tunnels between the same endpoints are distinguished by a 10-bit tunnel identifier field in the header. .Pp .Nm supports the capture of the encapsulated Ethernet packets via .Xr bpf 4 using the .Dv DLT_EN10MB data link type, and the encapsulating ERSPAN, GRE, and IP headers using the .Dv DLT_LOOP data link type. .Pp .Nm interfaces are configured in monitor mode by default, preventing the processing of received packets from entering the network stack. .Pp All GRE packet processing in the system is allowed or denied by setting the .Va net.inet.gre.allow .Xr sysctl 8 variable. To allow GRE packet processing, set .Va net.inet.gre.allow to 1. .Pp .Nm interfaces can be created at runtime using the .Ic ifconfig erspan Ns Ar N Ic create command or by setting up a .Xr hostname.if 5 configuration file for .Xr netstart 8 . .Pp For correct operation, encapsulated traffic must not be routed over the interface itself. This can be implemented 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. .Ss Programming Interface .Nm interfaces support the following .Xr ioctl 2 calls for configuring tunnel options: .Bl -tag -width indent -offset 3n .It Dv SIOCSLIFPHYADDR Fa "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. .It Dv SIOCGLIFPHYADDR Fa "struct if_laddrreq *" Get the addresses used for the encapsulating IP packets. .It Dv SIOCDIFPHYADDR Fa "struct ifreq *" Clear the addresses used for the encapsulating IP packets. The addresses may only be cleared while the interface is down. .It Dv SIOCSVNETID Fa "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. .It Dv SIOCGVNETID Fa "struct ifreq *" Get the virtual network identifier used as the Session ID in the ERSPAN Type II header. .It Dv SIOCDVNETID Fa "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. .It Dv SIOCSLIFPHYRTABLE Fa "struct ifreq *" Set the routing table the tunnel traffic operates in. The routing table may only be configured while the interface is down. .It Dv SIOCGLIFPHYRTABLE Fa "struct ifreq *" Get the routing table the tunnel traffic operates in. .It Dv SIOCSLIFPHYTTL Fa "struct ifreq *" Set the Time-To-Live field in IPv4 encapsulation headers, or the Hop Limit field in IPv6 encapsulation headers. .It Dv SIOCGLIFPHYTTL Fa "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. .It Dv SIOCSLIFPHYDF Fa "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. .It Dv SIOCGLIFPHYDF Fa "struct ifreq *" Get whether the tunnel traffic sent by the interface can be fragmented or not. .It Dv SIOCSTXHPRIO Fa "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 .Dv IF_HDRPRIO_PACKET to specify that the current priority of a packet should be used. .It Dv SIOCGTXHPRIO Fa "struct ifreq *" Get the priority value used in the Type of Service field in IPv4 headers, or the Traffic Class field in IPv6 headers. .El .Ss Security Considerations ERSPAN does not provide any integrated security features. 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. .Pp The Packet Filter .Xr pf 4 can be used to filter tunnel traffic with endpoint policies .Xr pf.conf 5 . .Pp 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: .Bd -literal -offset indent # ifconfig erspanN tunnelttl 1 .Ed .Sh SEE ALSO .Xr egre 4 , .Xr inet 4 , .Xr ip 4 , .Xr netintro 4 , .Xr options 4 , .Xr hostname.if 5 , .Xr protocols 5 , .Xr bpflogd 8 , .Xr ifconfig 8 , .Xr netstart 8 , .Xr sysctl 8 , .Xr tcpdump 8 .Sh STANDARDS .Rs .%A S. Hanks .%A "T. Li" .%A D. Farinacci .%A P. Traina .%D October 1994 .%R RFC 1701 .%T Generic Routing Encapsulation (GRE) .Re .Sh HISTORY The .Nm driver first appeared in .Ox 7.8 . .Sh AUTHORS .An David Gwynne Aq Mt dlg@openbsd.org