.\" $OpenBSD: gre.4,v 1.75 2018/11/16 01:21:12 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: November 16 2018 $ .Dt GRE 4 .Os .Sh NAME .Nm gre , .Nm mgre , .Nm egre , .Nm nvgre .Nd Generic Routing Encapsulation network device .Sh SYNOPSIS .Cd "pseudo-device gre" .Sh DESCRIPTION The .Nm gre pseudo-device provides interfaces for tunnelling protocols across IPv4 and IPv6 networks using the Generic Routing Encapsulation (GRE) encapsulation protocol. .Pp 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 the type of the encapsulated datagram, allowing for the tunnelling of multiple protocols. .Pp Different tunnels between the same endpoints may be distinguished by an optional Key field in the GRE header. The Key field may be partitioned to carry flow information about the encapsulated traffic to allow better use of multipath links. .Pp This pseudo driver provides the clonable network interfaces: .Bl -tag -width nvgreX .It Nm gre Point-to-point Layer 3 tunnel interfaces. .It Nm mgre Point-to-multipoint Layer 3 tunnel interfaces. .It Nm egre Point-to-point Ethernet tunnel interfaces. .It Nm nvgre Network Virtualization using Generic Routing Encapsulation (NVGRE) overlay Ethernet network interfaces. .It Nm eoip MikroTik Ethernet over IP tunnel interfaces. .El .Pp See .Xr eoip 4 for information regarding MikroTik Ethernet over IP interfaces. .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 gre , .Nm mgre , .Nm egre , and .Nm nvgre interfaces can be created at runtime using the .Ic ifconfig iface 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 Point-to-Point Layer 3 GRE tunnel interfaces (gre) A .Nm gre tunnel can encapsulate IPv4, IPv6, and MPLS packets. The MTU is set to 1476 by default to match the value used by Cisco routers. .Pp .Nm gre supports sending keepalive packets to the remote endpoint which allows tunnel failure to be detected. To return keepalives, the remote host must be configured to forward IP packets received from inside the tunnel back to the address of the local tunnel endpoint. .Pp .Nm gre interfaces may be configured to receive IPv4 packets in Web Cache Communication Protocol (WCCP) encapsulation by setting the .Cm link0 flag on the interface. WCCP reception may be enabled globally by setting the .Va net.inet.gre.wccp sysctl value to 1. Some magic with the packet filter configuration and a caching proxy like squid are needed to do anything useful with these packets. This sysctl requires .Va net.inet.gre.allow to also be set. .Ss Point-to-Multipoint Layer 3 GRE tunnel interfaces (mgre) .Nm mgre interfaces can encapsulate IPv4, IPv6, and MPLS packets. Unlike a point-to-point interface, .Nm mgre interfaces are configured with an address on an IP subnet. Peers on that subnet are mapped to the addresses of multiple tunnel endpoints. .Pp The MTU is set to 1476 by default to match the value used by Cisco routers. .Ss Point-to-Point Ethernet over GRE tunnel interfaces (egre) A .Nm egre tunnel interface carries Ethernet over GRE (EoGRE). Ethernet traffic is encapsulated using Transparent Ethernet (0x6558) as the protocol identifier in the GRE header, as per RFC 1701. The MTU is set to 1500 by default. .Ss Network Virtualization using GRE interfaces (nvgre) .Nm nvgre interfaces allow construction of virtual overlay Ethernet networks on top of an IPv4 or IPv6 underlay network as per RFC 7367. Ethernet traffic is encapsulated using Transparent Ethernet (0x6558) as the protocol identifier in the GRE header, a 24-bit Virtual Subnet ID (VSID), and an 8-bit FlowID. .Pp By default the MTU of an .Nm nvgre interface is set to 1500, and the Don't Fragment flag is set. The MTU on the network interfaces carrying underlay network traffic must be raised to accommodate this and the overhead of the NVGRE encapsulation, or the .Nm nvgre interface must be reconfigured for less capable underlays. .Pp The underlay network parameters on a .Nm nvgre interface are a unicast tunnel source address, a multicast tunnel destination address, and a parent network interface. The unicast source address is used as the NVE Provider Address (PA) on the underlay network. The parent interface is used to identify which interface the multicast group should be joined to. .Pp The multicast group is used to transport broadcast and multicast traffic from the overlay to other participating NVGRE endpoints. It is also used to flood unicast traffic to Ethernet addresses in the overlay with an unknown association to a NVGRE endpoint. Traffic received from other NVGRE endpoints, either to the Provider Address or via the multicast group, is used to learn associations between Ethernet addresses in the overlay network and the Provider Addresses of NVGRE endpoints in the underlay. .Ss Programming Interface .Nm gre , .Nm mgre , .Nm egre , and .Nm nvgre 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 IPv4 or IPv6 addresses for the encapsulating IP packets. The addresses may only be configured while the interface is down. .Pp .Nm gre and .Nm egre interfaces support configuration of unicast IP addresses as the tunnel endpoints. .Pp .Nm mgre interfaces support configuration of a unicast local IP address, and require an .Dv AF_UNSPEC destination address. .Pp .Nm nvgre interfaces support configuration of a unicast IP address as the local endpoint and a multicast group address as the destination address. .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 in the GRE Key header. The virtual network identifier may only be configured while the interface is down. .Pp .Nm gre , .Nm mgre , and .Nm egre interfaces configured with a virtual network identifier will enable the use of the GRE Key header. The Key is a 32-bit value by default, or a 24-bit value when the virtual network flow identifier is enabled. .Pp .Nm nvgre interfaces use the virtual network identifier in the 24-bit Virtual Subnet Identifer (VSID) aka Tenant Network Identifier (TNI) field in of the GRE Key header. .It Dv SIOCGVNETID Fa "struct ifreq *" Get the virtual network identifer used in the GRE Key header. .It Dv SIOCDVNETID Fa "struct ifreq *" Disable the use of the virtual network identifier. The virtual network identifer may only be disabled while the interface is down. .Pp When the virtual network identifier is disabled on .Nm gre , .Nm mgre , and .Nm egre interfaces, it disables the use of the GRE Key header. .Pp .Nm nvgre interfaces do not support this ioctl as a Virtual Subnet Identifier is required by the protocol. .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. .Pp .Nm gre and .Nm mgre interfaces configured with a TTL of -1 will copy the TTL in and out of the encapsulated protocol headers. .It Dv SIOCGLIFPHYTTL Fa "struct ifreq *" Get the value used in the Time-To-Live field in a IPv4 encapsulation header or the Hop Limit field in a 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. .Pp .Nm gre and .Nm mgre interfaces configured with a value of .Dv IF_HDRPRIO_PAYLOAD will copy the priority from encapsulated protocol headers. .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 .Pp .Nm gre , .Nm mgre , and .Nm egre interfaces support the following .Xr ioctl 2 calls: .Bl -tag -width indent -offset 3n .It Dv SIOCSVNETFLOWID Fa "struct ifreq *" Enable or disable the partitioning of the optional GRE Key header into a 24-bit virtual network identifier and an 8-bit flow identifier. .Pp The interface must already be configured with a virtual network identifer before enabling flow identifiers in the GRE Key header. The configured virtual network identify must also fit into 24 bits. .It Dv SIOCDVNETFLOWID Fa "struct ifreq *" Get the status of the partitioning of the GRE key. .El .Pp .Nm gre interfaces support the following .Xr ioctl 2 calls: .Bl -tag -width indent -offset 3n .It Dv SIOCSETKALIVE Fa "struct ifkalivereq *" Enable the transmission of keepalive packets to detect tunnel failure. .\" Keepalives may only be configured while the interace is down. .Pp Setting the keepalive period or count to 0 disables keepalives on the tunnel. .It Dv SIOCGETKALIVE Fa "struct ifkalivereq *" Get the configuration of keepalive packets. .El .Pp .Nm nvgre interfaces support the following .Xr ioctl 2 calls: .Bl -tag -width indent -offset 3n .It Dv SIOCSIFPARENT Fa "struct if_parent *" Configure which interface will be joined to the multicast group specified by the tunnel destination address. The parent interface may only be configured while the interface is down. .It Dv SIOCGIFPARENT Fa "struct if_parent *" Get the name of the interface used for multicast communication. .It Dv SIOCGIFPARENT Fa "struct ireq *" Remove the configuration of the interface used for multicast communication. .\" bridge(4) ioctls should go here too. .El .Ss Security Considerations The GRE protocol in all its flavours does not provide any integrated security features. GRE should only be deployed on trusted private networks, or protected with IPsec to add authentication and encryption for confidentiality. IPsec is especially recommended when transporting GRE over the public internet. .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 gre0 tunnelttl 1 .Ed .Sh EXAMPLES .Ss Point-to-Point Layer 3 GRE tunnel interfaces (gre) example .Bd -literal Host X ---- Host A ------------ tunnel ------------ Cisco D ---- Host E \e / \e / +------ Host B ------ Host C ------+ .Ed .Pp On Host A .Pq Ox : .Bd -literal -offset indent # route add default B # ifconfig greN create # ifconfig greN A D netmask 0xffffffff up # ifconfig greN tunnel A D # route add E D .Ed .Pp On Host D (Cisco): .Bd -literal -offset indent Interface TunnelX ip unnumbered D ! e.g. address from Ethernet interface tunnel source D ! e.g. address from Ethernet interface tunnel destination A ip route C ip route A mask C ip route X mask tunnelX .Ed .Pp OR .Pp On Host D .Pq Ox : .Bd -literal -offset indent # route add default C # ifconfig greN create # ifconfig greN D A # ifconfig greN tunnel D A .Ed .Pp To reach Host A over the tunnel (from Host D), there has to be an alias on Host A for the Ethernet interface: .Pp .Dl # ifconfig alias Y .Pp and on the Cisco: .Pp .Dl ip route Y mask tunnelX .Pp .Nm gre keepalive packets may be enabled with .Xr ifconfig 8 like this: .Bd -literal -offset indent # ifconfig greN keepalive period count .Ed .Pp This will send a keepalive packet every .Ar period seconds. If no response is received in .Ar count * .Ar period seconds, the link is considered down. To return keepalives, the remote host must be configured to forward packets: .Bd -literal -offset indent # sysctl net.inet.ip.forwarding=1 .Ed .Pp If .Xr pf 4 is enabled then it is necessary to add a pass rule specific for the keepalive packets. The rule must use .Cm no state because the keepalive packet is entering the network stack multiple times. In most cases the following should work: .Bd -literal -offset indent pass quick on gre proto gre no state .Ed .Ss Point-to-Point Ethernet over GRE tunnel interfaces (egre) example .Nm egre can be used to carry Ethernet traffic between two endpoints over an IP network, including the public internet. This can also be achieved using .Xr etherip 4 , but .Nm egre offers the ability to carry different Ethernet networks between the same endpoints by using virtual network identifiers to distinguish between them. .Pp For example, a pair of routers separated by the internet could bridge several Ethernet networks using .Nm egre and .Xr bridge 4 . .Pp In this example the first router has a public IP of 192.0.2.1, and the second router has 203.0.113.2. They are connecting the Ethernet networks on two .Xr vlan 4 interfaces over the internet. A separate .Nm egre tunnel is created for each VLAN and given different virtual network identifiers so the routers can tell which network the encapsulated traffic is for. The .Nm egre interfaces are explicitley configured to provide the same MTU as the .Xr vlan 4 interfaces (1500 bytes) with fragmentation enabled so they can be carried over the internet, which has the same or lower MTU. .Pp At the first site: .Bd -literal -offset indent # ifconfig vlan0 vnetid 100 # ifconfig egre0 create # ifconfig egre0 tunnel 192.0.2.1 203.0.113.2 # ifconfig egre0 vnetid 100 # ifconfig egre0 mtu 1500 -tunneldf # ifconfig egre0 up # ifconfig bridge0 add vlan0 add egre0 up # ifconfig vlan1 vnetid 200 # ifconfig egre1 create # ifconfig egre1 tunnel 192.0.2.1 203.0.113.2 # ifconfig egre1 vnetid 200 # ifconfig egre1 mtu 1500 -tunneldf # ifconfig egre1 up # ifconfig bridge1 add vlan1 add egre1 up .Ed .Pp At the second site: .Bd -literal -offset indent # ifconfig vlan0 vnetid 100 # ifconfig egre0 create # ifconfig egre0 tunnel 203.0.113.2 192.0.2.1 # ifconfig egre0 vnetid 100 # ifconfig egre0 mtu 1500 -tunneldf # ifconfig egre0 up # ifconfig bridge0 add vlan0 add egre0 up # ifconfig vlan1 vnetid 200 # ifconfig egre1 create # ifconfig egre1 tunnel 203.0.113.2 192.0.2.1 # ifconfig egre1 vnetid 200 # ifconfig egre1 mtu 1500 -tunneldf # ifconfig egre1 up # ifconfig bridge1 add vlan1 add egre1 up .Ed .Ss Network Virtualization using GRE interfaces (nvgre) example NVGRE can be used to build a distinct logical Ethernet network on top of another network. .Nm nvgre is therefore like a .Xr vlan 4 interface configured on top of a physical Ethernet interface, except it can sit on any IP network capable of multicast. .Pp The following shows a basic .Nm nvgre configuration and an equivalent .Xr vlan 4 configuration. In the examples, 192.168.0.1/24 will be the network configured on the relevent virtual interfaces. The NVGRE underlay network will be configured on 100.64.10.0/24, and will use 239.1.1.100 as the multicast group address. .Pp The .Xr vlan 4 interface only relies on Ethernet, it does not rely on IP configuration on the parent interface: .Bd -literal -offset indent # ifconfig em0 up # ifconfig vlan0 create # ifconfig vlan0 parent em0 # ifconfig vlan0 vnetid 10 # ifconfig vlan0 inet 192.168.0.1/24 # ifconfig vlan0 up .Ed .Pp .Nm nvgre relies on IP configuration on the parent interface, and an MTU large enough to carry the encapsulated traffic: .Bd -literal -offset indent # ifconfig em0 mtu 1600 # ifconfig em0 inet 100.64.10.1/24 # ifconfig em0 up # ifconfig nvgre0 create # ifconfig nvgre0 parent em0 tunnel 100.64.10.1 239.1.1.100 # ifconfig nvgre0 vnetid 10010 # ifconfig nvgre0 inet 192.168.0.1/24 # ifconfig nvgre0 up .Ed .Pp NVGRE is intended for use in a multitenant datacentre environment to provide each customer with distinct Ethernet networks as needed, but without running into the limit on the number of VLAN tags, and without requiring reconfiguration of the underlying Ethernet infrastructure. Another way to look at it is NVGRE can be used to construct multipoint Ethernet VPNs across an IP core. .Pp For example, if a customer has multiple virtual machines running in .Xr vmm 4 on distinct physical hosts, .Nm nvgre and .Xr bridge 4 can be used to provide network connectivity between the .Xr tap 4 interfaces connected to the virtual machines. If there are 3 virtual machines, all using tap0 on each hosts, and those hosts are connected to the same network described above, .Nm nvgre with a distinct virtual network identifier and multicast group can be created for them. The following assumes nvgre1 and bridge1 have already been created on each host, and em0 has had the MTU raised: .Pp On physical host 1: .Bd -literal -offset indent # ifconfig em0 inet 100.64.10.10/24 # ifconfig nvgre1 parent em0 tunnel 100.64.10.10 239.1.1.111 # ifconfig nvgre1 vnetid 10011 # ifconfig bridge1 add nvgre1 add tap0 up .Ed .Pp On physical host 2: .Bd -literal -offset indent # ifconfig em0 inet 100.64.10.11/24 # ifconfig nvgre1 parent em0 tunnel 100.64.10.11 239.1.1.111 # ifconfig nvgre1 vnetid 10011 # ifconfig bridge1 add nvgre1 add tap0 up .Ed .Pp On physical host 3: .Bd -literal -offset indent # ifconfig em0 inet 100.64.10.12/24 # ifconfig nvgre1 parent em0 tunnel 100.64.10.12 239.1.1.111 # ifconfig nvgre1 vnetid 10011 # ifconfig bridge1 add nvgre1 add tap0 up .Ed .Pp Being able to carry working multicast and jumbo frames over the public internet is unlikely, which makes it difficult to use NVGRE to extended Ethernet VPNs between different sites. .Nm nvgre and .Nm egre can be bridged together to provide such connectivity. See the .Nm egre section for an example. .Sh SEE ALSO .Xr eoip 4 , .Xr inet 4 , .Xr ip 4 , .Xr netintro 4 , .Xr options 4 , .Xr hostname.if 5 , .Xr protocols 5 , .Xr ifconfig 8 , .Xr netstart 8 , .Xr sysctl 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 .Pp .Rs .%A S. Hanks .%A "T. Li" .%A D. Farinacci .%A P. Traina .%D October 1994 .%R RFC 1702 .%T Generic Routing Encapsulation over IPv4 networks .Re .Pp .Rs .%A D. Farinacci .%A "T. Li" .%A S. Hanks .%A D. Meyer .%A P. Traina .%D March 2000 .%R RFC 2784 .%T Generic Routing Encapsulation (GRE) .Re .Pp .Rs .%A G. Dommety .%D September 2000 .%R RFC 2890 .%T Key and Sequence Number Extensions to GRE .Re .Pp .Rs .%A T. Worster .%A Y. Rekhter .%A E. Rosen .%D March 2005 .%R RFC 4023 .%T Encapsulating MPLS in IP or Generic Routing Encapsulation (GRE) .Re .Pp .Rs .%A P. Garg .%A Y. Wang .%D September 2015 .%R RFC 7637 .%T NVGRE: Network Virtualization Using Generic Routing Encapsulation .Re .Pp .Rs .%U https://tools.ietf.org/html/draft-ietf-wrec-web-pro-00.txt .%T Web Cache Coordination Protocol V1.0 .Re .Pp .Rs .%U https://tools.ietf.org/html/draft-wilson-wrec-wccp-v2-00.txt .%T Web Cache Coordination Protocol V2.0 .Re .Sh AUTHORS .An Heiko W. Rupp Aq Mt hwr@pilhuhn.de .Sh CAVEATS RFC 1701 and RFC 2890 describe a variety of optional GRE header fields in the protocol that are not implemented in the .Nm gre and .Nm egre interface drivers. The only optional field the drivers implement support for is the Key header. .Pp .Nm gre interfaces skip the redirect header in WCCPv2 GRE encapsulated packets. .Pp The NVGRE RFC specifies VSIDs 0 (0x0) to 4095 (0xfff) as reserved for future use, and VSID 16777215 (0xffffff) for use for vendor-specific endpoint communication. The NVGRE RFC also explicitly states encapsulated Ethernet packets must not contain IEEE 802.1Q (VLAN) tags. The .Nm nvgre driver does not restrict the use of these VSIDs, and does not prevent the configuration of child .Xr vlan 4 interfaces or the bridging of VLAN tagged traffic across the tunnel. These non-restrictions allow non-compliant tunnels to be configured which may not interoperate with other vendors.