1 .\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $
3 .\" Copyright 1998 (c) The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Heiko W.Rupp <hwr@pilhuhn.de>
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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.
37 .Nd encapsulating network device
40 driver into the kernel, place the following line in the kernel
42 .Bd -ragged -offset indent
46 Alternatively, to load the
47 driver as a module at boot time, place the following line in
49 .Bd -literal -offset indent
55 network interface pseudo device encapsulates datagrams
57 These encapsulated datagrams are routed to a destination host,
58 where they are decapsulated and further routed to their final destination.
61 appears to the inner datagrams as one hop.
64 interfaces are dynamically created and destroyed with the
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
76 GRE mode is also the default tunnel mode on Cisco routers.
78 also supports Cisco WCCP protocol, both version 1 and version 2.
82 interfaces support a number of additional parameters to the
84 .Bl -tag -width "enable_csum"
86 Set the GRE key used for outgoing packets.
87 A value of 0 disables the key option.
89 Enables checksum calculation for outgoing packets.
91 Enables use of sequence number field in the GRE header for outgoing packets.
93 Enables UDP-in-GRE encapsulation (see the
94 .Sx GRE-IN-UDP ENCAPSULATION
95 Section below for details).
97 Set the source UDP port for outgoing packets.
98 A value of 0 disables the persistence of source UDP port for outgoing packets.
100 .Sx GRE-IN-UDP ENCAPSULATION
101 Section below for details.
103 .Sh GRE-IN-UDP ENCAPSULATION
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.
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.
117 option can be used to disable this behaviour and use single source UDP
121 should be within the ephemeral port range, i.e., 49152 to 65535 by default.
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
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
133 192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.*
136 +------ the Internet ------+
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:
144 .Bd -literal -offset indent
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
152 .Bd -literal -offset indent
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
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
164 Then different FIB will be applied to such encapsulated packets.
165 According to this FIB packet should be routed to tunnel endpoint.
167 Host X -- Host A (198.51.100.1) ---tunnel--- Cisco D (203.0.113.1) -- Host E
170 +----- Host B ----- Host C -----+
176 First of multiple FIBs should be configured via loader.conf:
177 .Bd -literal -offset indent
179 net.add_addr_allfibs=0
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
189 And GRE tunnel should be configured to change FIB for encapsulated packets:
190 .Bd -literal -offset indent
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
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
201 It can be adjusted via
204 For correct operation, the
206 device needs a route to the decapsulating host that does not run over the tunnel,
207 as this would be a loop.
209 The kernel must be set to forward datagrams by setting the
210 .Va net.inet.ip.forwarding
212 variable to non-zero.
223 A description of GRE encapsulation can be found in RFC 2784 and RFC 2890.
225 .An Andrey V. Elsukov Aq Mt ae@FreeBSD.org
226 .An Heiko W.Rupp Aq Mt hwr@pilhuhn.de
228 The current implementation uses the key only for outgoing packets.
229 Incoming packets with a different key or without a key will be treated as if they
230 would belong to this interface.
232 The sequence number field also used only for outgoing packets.