1.\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $ 2.\" 3.\" Copyright 1998 (c) The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Heiko W.Rupp <hwr@pilhuhn.de> 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd August 21, 2020 31.Dt GRE 4 32.Os 33.Sh NAME 34.Nm gre 35.Nd encapsulating network device 36.Sh SYNOPSIS 37To compile the 38driver into the kernel, place the following line in the kernel 39configuration file: 40.Bd -ragged -offset indent 41.Cd "device gre" 42.Ed 43.Pp 44Alternatively, to load the 45driver as a module at boot time, place the following line in 46.Xr loader.conf 5 : 47.Bd -literal -offset indent 48if_gre_load="YES" 49.Ed 50.Sh DESCRIPTION 51The 52.Nm 53network interface pseudo device encapsulates datagrams 54into IP. 55These encapsulated datagrams are routed to a destination host, 56where they are decapsulated and further routed to their final destination. 57The 58.Dq tunnel 59appears to the inner datagrams as one hop. 60.Pp 61.Nm 62interfaces are dynamically created and destroyed with the 63.Xr ifconfig 8 64.Cm create 65and 66.Cm destroy 67subcommands. 68.Pp 69This driver corresponds to RFC 2784. 70Encapsulated datagrams are prepended an outer datagram and a GRE header. 71The GRE header specifies 72the type of the encapsulated datagram and thus allows for tunneling other 73protocols than IP. 74GRE mode is also the default tunnel mode on Cisco routers. 75.Nm 76also supports Cisco WCCP protocol, both version 1 and version 2. 77.Pp 78The 79.Nm 80interfaces support a number of additional parameters to the 81.Xr ifconfig 8 : 82.Bl -tag -width "enable_csum" 83.It Ar grekey 84Set the GRE key used for outgoing packets. 85A value of 0 disables the key option. 86.It Ar enable_csum 87Enables checksum calculation for outgoing packets. 88.It Ar enable_seq 89Enables use of sequence number field in the GRE header for outgoing packets. 90.It Ar udpencap 91Enables UDP-in-GRE encapsulation (see the 92.Sx GRE-IN-UDP ENCAPSULATION 93Section below for details). 94.It Ar udpport 95Set the source UDP port for outgoing packets. 96A value of 0 disables the persistence of source UDP port for outgoing packets. 97See the 98.Sx GRE-IN-UDP ENCAPSULATION 99Section below for details. 100.El 101.Sh GRE-IN-UDP ENCAPSULATION 102The 103.Nm 104supports GRE in UDP encapsulation as defined in RFC 8086. 105A GRE in UDP tunnel offers the possibility of better performance for 106load-balancing GRE traffic in transit networks. 107Encapsulating GRE in UDP enables use of the UDP source port to provide 108entropy to ECMP hashing. 109.Pp 110The GRE in UDP tunnel uses single value 4754 as UDP destination port. 111The UDP source port contains a 14-bit entropy value that is generated 112by the encapsulator to identify a flow for the encapsulated packet. 113The 114.Ar udpport 115option can be used to disable this behaviour and use single source UDP 116port value. 117The value of 118.Ar udpport 119should be within the ephemeral port range, i.e., 49152 to 65535 by default. 120.Pp 121Note that a GRE in UDP tunnel is unidirectional; the tunnel traffic is not 122expected to be returned back to the UDP source port values used to generate 123entropy. 124This may impact NAPT (Network Address Port Translator) middleboxes. 125If such tunnels are expected to be used on a path with a middlebox, 126the tunnel can be configured either to disable use of the UDP source port 127for entropy or to enable middleboxes to pass packets with UDP source port 128entropy. 129.Sh EXAMPLES 130.Bd -literal 131192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* 132 \\ / 133 \\ / 134 +------ the Internet ------+ 135.Ed 136.Pp 137Assuming router A has the (external) IP address A and the internal address 138192.168.1.1, while router B has external address B and internal address 139192.168.2.1, the following commands will configure the tunnel: 140.Pp 141On router A: 142.Bd -literal -offset indent 143ifconfig greN create 144ifconfig greN inet 192.168.1.1 192.168.2.1 145ifconfig greN inet tunnel A B 146route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 147.Ed 148.Pp 149On router B: 150.Bd -literal -offset indent 151ifconfig greN create 152ifconfig greN inet 192.168.2.1 192.168.1.1 153ifconfig greN inet tunnel B A 154route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 155.Ed 156.Pp 157In case when internal and external IP addresses are the same, 158different routing tables (FIB) should be used. 159The default FIB will be applied to IP packets before GRE encapsulation. 160After encapsulation GRE interface should set different FIB number to 161outgoing packet. 162Then different FIB will be applied to such encapsulated packets. 163According to this FIB packet should be routed to tunnel endpoint. 164.Bd -literal 165Host X -- Host A (198.51.100.1) ---tunnel--- Cisco D (203.0.113.1) -- Host E 166 \\ / 167 \\ / 168 +----- Host B ----- Host C -----+ 169 (198.51.100.254) 170.Ed 171.Pp 172On Host A (FreeBSD): 173.Pp 174First of multiple FIBs should be configured via loader.conf: 175.Bd -literal -offset indent 176net.fibs=2 177net.add_addr_allfibs=0 178.Ed 179.Pp 180Then routes to the gateway and remote tunnel endpoint via this gateway 181should be added to the second FIB: 182.Bd -literal -offset indent 183route add -net 198.51.100.0 -netmask 255.255.255.0 -fib 1 -iface em0 184route add -host 203.0.113.1 -fib 1 198.51.100.254 185.Ed 186.Pp 187And GRE tunnel should be configured to change FIB for encapsulated packets: 188.Bd -literal -offset indent 189ifconfig greN create 190ifconfig greN inet 198.51.100.1 203.0.113.1 191ifconfig greN inet tunnel 198.51.100.1 203.0.113.1 tunnelfib 1 192.Ed 193.Sh NOTES 194The MTU of 195.Nm 196interfaces is set to 1476 by default, to match the value used by Cisco routers. 197This may not be an optimal value, depending on the link between the two tunnel 198endpoints. 199It can be adjusted via 200.Xr ifconfig 8 . 201.Pp 202For correct operation, the 203.Nm 204device needs a route to the decapsulating host that does not run over the tunnel, 205as this would be a loop. 206.Pp 207The kernel must be set to forward datagrams by setting the 208.Va net.inet.ip.forwarding 209.Xr sysctl 8 210variable to non-zero. 211.Pp 212By default, 213.Nm 214tunnels may not be nested. 215This behavior may be modified at runtime by setting the 216.Xr sysctl 8 217variable 218.Va net.link.gre.max_nesting 219to the desired level of nesting. 220.Sh SEE ALSO 221.Xr gif 4 , 222.Xr inet 4 , 223.Xr ip 4 , 224.Xr me 4 , 225.Xr netintro 4 , 226.Xr protocols 5 , 227.Xr ifconfig 8 , 228.Xr sysctl 8 229.Sh STANDARDS 230.Rs 231.%A S. Hanks 232.%A "T. Li" 233.%A D. Farinacci 234.%A P. Traina 235.%D October 1994 236.%R RFC 1701 237.%T Generic Routing Encapsulation (GRE) 238.Re 239.Pp 240.Rs 241.%A S. Hanks 242.%A "T. Li" 243.%A D. Farinacci 244.%A P. Traina 245.%D October 1994 246.%R RFC 1702 247.%T Generic Routing Encapsulation over IPv4 networks 248.Re 249.Pp 250.Rs 251.%A D. Farinacci 252.%A "T. Li" 253.%A S. Hanks 254.%A D. Meyer 255.%A P. Traina 256.%D March 2000 257.%R RFC 2784 258.%T Generic Routing Encapsulation (GRE) 259.Re 260.Pp 261.Rs 262.%A G. Dommety 263.%D September 2000 264.%R RFC 2890 265.%T Key and Sequence Number Extensions to GRE 266.Re 267.Sh AUTHORS 268.An Andrey V. Elsukov Aq Mt ae@FreeBSD.org 269.An Heiko W.Rupp Aq Mt hwr@pilhuhn.de 270.Sh BUGS 271The current implementation uses the key only for outgoing packets. 272Incoming packets with a different key or without a key will be treated as if they 273would belong to this interface. 274.Pp 275The sequence number field also used only for outgoing packets. 276