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