share/man/man4/gre.4

   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
  39 To compile the
  40 driver into the kernel, place the following line in the kernel
  41 configuration file:
  42 .Bd -ragged -offset indent
  43 .Cd "device gre"
  44 .Ed
  45 .Pp
  46 Alternatively, to load the
  47 driver as a module at boot time, place the following line in
  48 .Xr loader.conf 5 :
  49 .Bd -literal -offset indent
  50 if_gre_load="YES"
  51 .Ed
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  55 network interface pseudo device encapsulates datagrams
  56 into IP.
  57 These encapsulated datagrams are routed to a destination host,
  58 where they are decapsulated and further routed to their final destination.
  59 The
  60 .Dq tunnel
  61 appears to the inner datagrams as one hop.
  62 .Pp
  63 .Nm
  64 interfaces are dynamically created and destroyed with the
  65 .Xr ifconfig 8
  66 .Cm create
  67 and
  68 .Cm destroy
  69 subcommands.
  70 .Pp
  71 This driver corresponds to RFC 2784.
  72 Encapsulated datagrams are prepended an outer datagram and a GRE header.
  73 The GRE header specifies
  74 the type of the encapsulated datagram and thus allows for tunneling other
  75 protocols than IP.
  76 GRE mode is also the default tunnel mode on Cisco routers.
  77 .Nm
  78 also supports Cisco WCCP protocol, both version 1 and version 2.
  79 .Pp
  80 The
  81 .Nm
  82 interfaces support a number of additional parameters to the
  83 .Xr ifconfig 8 :
  84 .Bl -tag -width "enable_csum"
  85 .It Ar grekey
  86 Set the GRE key used for outgoing packets.
  87 A value of 0 disables the key option.
  88 .It Ar enable_csum
  89 Enables checksum calculation for outgoing packets.
  90 .It Ar enable_seq
  91 Enables use of sequence number field in the GRE header for outgoing packets.
  92 .It Ar udpencap
  93 Enables UDP-in-GRE encapsulation (see the
  94 .Sx GRE-IN-UDP ENCAPSULATION
  95 Section below for details).
  96 .It Ar udpport
  97 Set the source UDP port for outgoing packets.
  98 A value of 0 disables the persistence of source UDP port for outgoing packets.
  99 See the
 100 .Sx GRE-IN-UDP ENCAPSULATION
 101 Section below for details.
 102 .El
 103 .Sh GRE-IN-UDP ENCAPSULATION
 104 The
 105 .Nm
 106 supports GRE in UDP encapsulation as defined in RFC 8086.
 107 A GRE in UDP tunnel offers the possibility of better performance for
 108 load-balancing GRE traffic in transit networks.
 109 Encapsulating GRE in UDP enables use of the UDP source port to provide
 110 entropy to ECMP hashing.
 111 .Pp
 112 The GRE in UDP tunnel uses single value 4754 as UDP destination port.
 113 The UDP source port contains a 14-bit entropy value that is generated
 114 by the encapsulator to identify a flow for the encapsulated packet.
 115 The
 116 .Ar udpport
 117 option can be used to disable this behaviour and use single source UDP
 118 port value.
 119 The value of
 120 .Ar udpport
 121 should be within the ephemeral port range, i.e., 49152 to 65535 by default.
 122 .Pp
 123 Note that a GRE in UDP tunnel is unidirectional; the tunnel traffic is not
 124 expected to be returned back to the UDP source port values used to generate
 125 entropy.
 126 This may impact NAPT (Network Address Port Translator) middleboxes.
 127 If such tunnels are expected to be used on a path with a middlebox,
 128 the tunnel can be configured either to disable use of the UDP source port
 129 for entropy or to enable middleboxes to pass packets with UDP source port
 130 entropy.
 131 .Sh EXAMPLES
 132 .Bd -literal
 133 192.168.1.* --- Router A  -------tunnel-------- Router B --- 192.168.2.*
 134                    \\                              /
 135                     \\                            /
 136                      +------ the Internet ------+
 137 .Ed
 138 .Pp
 139 Assuming router A has the (external) IP address A and the internal address
 140 192.168.1.1, while router B has external address B and internal address
 141 192.168.2.1, the following commands will configure the tunnel:
 142 .Pp
 143 On router A:
 144 .Bd -literal -offset indent
 145 ifconfig greN create
 146 ifconfig greN inet 192.168.1.1 192.168.2.1
 147 ifconfig greN inet tunnel A B
 148 route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1
 149 .Ed
 150 .Pp
 151 On router B:
 152 .Bd -literal -offset indent
 153 ifconfig greN create
 154 ifconfig greN inet 192.168.2.1 192.168.1.1
 155 ifconfig greN inet tunnel B A
 156 route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1
 157 .Ed
 158 .Pp
 159 In case when internal and external IP addresses are the same,
 160 different routing tables (FIB) should be used.
 161 The default FIB will be applied to IP packets before GRE encapsulation.
 162 After encapsulation GRE interface should set different FIB number to
 163 outgoing packet.
 164 Then different FIB will be applied to such encapsulated packets.
 165 According to this FIB packet should be routed to tunnel endpoint.
 166 .Bd -literal
 167 Host 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
 174 On Host A (FreeBSD):
 175 .Pp
 176 First of multiple FIBs should be configured via loader.conf:
 177 .Bd -literal -offset indent
 178 net.fibs=2
 179 net.add_addr_allfibs=0
 180 .Ed
 181 .Pp
 182 Then routes to the gateway and remote tunnel endpoint via this gateway
 183 should be added to the second FIB:
 184 .Bd -literal -offset indent
 185 route add -net 198.51.100.0 -netmask 255.255.255.0 -fib 1 -iface em0
 186 route add -host 203.0.113.1 -fib 1 198.51.100.254
 187 .Ed
 188 .Pp
 189 And GRE tunnel should be configured to change FIB for encapsulated packets:
 190 .Bd -literal -offset indent
 191 ifconfig greN create
 192 ifconfig greN inet 198.51.100.1 203.0.113.1
 193 ifconfig greN inet tunnel 198.51.100.1 203.0.113.1 tunnelfib 1
 194 .Ed
 195 .Sh NOTES
 196 The MTU of
 197 .Nm
 198 interfaces is set to 1476 by default, to match the value used by Cisco routers.
 199 This may not be an optimal value, depending on the link between the two tunnel
 200 endpoints.
 201 It can be adjusted via
 202 .Xr ifconfig 8 .
 203 .Pp
 204 For correct operation, the
 205 .Nm
 206 device needs a route to the decapsulating host that does not run over the tunnel,
 207 as this would be a loop.
 208 .Pp
 209 The kernel must be set to forward datagrams by setting the
 210 .Va net.inet.ip.forwarding
 211 .Xr sysctl 8
 212 variable to non-zero.
 213 .Pp
 214 By default,
 215 .Nm
 216 tunnels may not be nested.
 217 This behavior may be modified at runtime by setting the
 218 .Xr sysctl 8
 219 variable
 220 .Va net.link.gre.max_nesting
 221 to 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
 273 The current implementation uses the key only for outgoing packets.
 274 Incoming packets with a different key or without a key will be treated as if they
 275 would belong to this interface.
 276 .Pp
 277 The sequence number field also used only for outgoing packets.