1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
<table class="head">
<tr>
<td class="head-ltitle">GRE(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">GRE(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">gre</code> —
<span class="Nd">encapsulating network device</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp">To compile the driver into the kernel, place the following line in
the kernel configuration file:</p>
<div class="Bd Pp Bd-indent"><code class="Cd">device gre</code></div>
<p class="Pp">Alternatively, to load the driver as a module at boot time, place
the following line in <a class="Xr">loader.conf(5)</a>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>if_gre_load="YES"</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">gre</code> network interface pseudo device
encapsulates datagrams into IP. These encapsulated datagrams are routed to a
destination host, where they are decapsulated and further routed to their
final destination. The “tunnel” appears to the inner datagrams
as one hop.</p>
<p class="Pp"><code class="Nm">gre</code> interfaces are dynamically created and
destroyed with the <a class="Xr">ifconfig(8)</a>
<code class="Cm">create</code> and <code class="Cm">destroy</code>
subcommands.</p>
<p class="Pp">This driver corresponds to RFC 2784. Encapsulated datagrams are
prepended an outer datagram and a GRE header. The GRE header specifies the
type of the encapsulated datagram and thus allows for tunneling other
protocols than IP. GRE mode is also the default tunnel mode on Cisco
routers. <code class="Nm">gre</code> also supports Cisco WCCP protocol, both
version 1 and version 2.</p>
<p class="Pp">The <code class="Nm">gre</code> interfaces support a number of
additional parameters to the <a class="Xr">ifconfig(8)</a>:</p>
<dl class="Bl-tag">
<dt><var class="Ar">grekey</var></dt>
<dd>Set the GRE key used for outgoing packets. A value of 0 disables the key
option.</dd>
<dt><var class="Ar">enable_csum</var></dt>
<dd>Enables checksum calculation for outgoing packets.</dd>
<dt><var class="Ar">enable_seq</var></dt>
<dd>Enables use of sequence number field in the GRE header for outgoing
packets.</dd>
<dt><var class="Ar">udpencap</var></dt>
<dd>Enables UDP-in-GRE encapsulation (see the
<a class="Sx" href="#GRE_IN_UDP_ENCAPSULATION">GRE-IN-UDP
ENCAPSULATION</a> Section below for details).</dd>
<dt><var class="Ar">udpport</var></dt>
<dd>Set the source UDP port for outgoing packets. A value of 0 disables the
persistence of source UDP port for outgoing packets. See the
<a class="Sx" href="#GRE_IN_UDP_ENCAPSULATION">GRE-IN-UDP
ENCAPSULATION</a> Section below for details.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="GRE-IN-UDP_ENCAPSULATION"><a class="permalink" href="#GRE-IN-UDP_ENCAPSULATION">GRE-IN-UDP
ENCAPSULATION</a></h1>
<p class="Pp">The <code class="Nm">gre</code> supports GRE in UDP encapsulation
as defined in RFC 8086. A GRE in UDP tunnel offers the possibility of better
performance for load-balancing GRE traffic in transit networks.
Encapsulating GRE in UDP enables use of the UDP source port to provide
entropy to ECMP hashing.</p>
<p class="Pp">The GRE in UDP tunnel uses single value 4754 as UDP destination
port. The UDP source port contains a 14-bit entropy value that is generated
by the encapsulator to identify a flow for the encapsulated packet. The
<var class="Ar">udpport</var> option can be used to disable this behaviour
and use single source UDP port value. The value of
<var class="Ar">udpport</var> should be within the ephemeral port range,
i.e., 49152 to 65535 by default.</p>
<p class="Pp">Note that a GRE in UDP tunnel is unidirectional; the tunnel
traffic is not expected to be returned back to the UDP source port values
used to generate entropy. This may impact NAPT (Network Address Port
Translator) middleboxes. If such tunnels are expected to be used on a path
with a middlebox, the tunnel can be configured either to disable use of the
UDP source port for entropy or to enable middleboxes to pass packets with
UDP source port entropy.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<div class="Bd Li">
<pre>192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.*
\ /
\ /
+------ the Internet ------+</pre>
</div>
<p class="Pp">Assuming router A has the (external) IP address A and the internal
address 192.168.1.1, while router B has external address B and internal
address 192.168.2.1, the following commands will configure the tunnel:</p>
<p class="Pp">On router A:</p>
<div class="Bd Pp Bd-indent Li">
<pre>ifconfig greN create
ifconfig greN inet 192.168.1.1 192.168.2.1
ifconfig greN inet tunnel A B
route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1</pre>
</div>
<p class="Pp">On router B:</p>
<div class="Bd Pp Bd-indent Li">
<pre>ifconfig greN create
ifconfig greN inet 192.168.2.1 192.168.1.1
ifconfig greN inet tunnel B A
route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1</pre>
</div>
<p class="Pp">In case when internal and external IP addresses are the same,
different routing tables (FIB) should be used. The default FIB will be
applied to IP packets before GRE encapsulation. After encapsulation GRE
interface should set different FIB number to outgoing packet. Then different
FIB will be applied to such encapsulated packets. According to this FIB
packet should be routed to tunnel endpoint.</p>
<div class="Bd Pp Li">
<pre>Host X -- Host A (198.51.100.1) ---tunnel--- Cisco D (203.0.113.1) -- Host E
\ /
\ /
+----- Host B ----- Host C -----+
(198.51.100.254)</pre>
</div>
<p class="Pp">On Host A (FreeBSD):</p>
<p class="Pp">First of multiple FIBs should be configured via loader.conf:</p>
<div class="Bd Pp Bd-indent Li">
<pre>net.fibs=2
net.add_addr_allfibs=0</pre>
</div>
<p class="Pp">Then routes to the gateway and remote tunnel endpoint via this
gateway should be added to the second FIB:</p>
<div class="Bd Pp Bd-indent Li">
<pre>route add -net 198.51.100.0 -netmask 255.255.255.0 -fib 1 -iface em0
route add -host 203.0.113.1 -fib 1 198.51.100.254</pre>
</div>
<p class="Pp">And GRE tunnel should be configured to change FIB for encapsulated
packets:</p>
<div class="Bd Pp Bd-indent Li">
<pre>ifconfig greN create
ifconfig greN inet 198.51.100.1 203.0.113.1
ifconfig greN inet tunnel 198.51.100.1 203.0.113.1 tunnelfib 1</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1>
<p class="Pp">The MTU of <code class="Nm">gre</code> interfaces is set to 1476
by default, to match the value used by Cisco routers. This may not be an
optimal value, depending on the link between the two tunnel endpoints. It
can be adjusted via <a class="Xr">ifconfig(8)</a>.</p>
<p class="Pp">For correct operation, the <code class="Nm">gre</code> device
needs a route to the decapsulating host that does not run over the tunnel,
as this would be a loop.</p>
<p class="Pp">The kernel must be set to forward datagrams by setting the
<var class="Va">net.inet.ip.forwarding</var> <a class="Xr">sysctl(8)</a>
variable to non-zero.</p>
<p class="Pp">By default, <code class="Nm">gre</code> tunnels may not be nested.
This behavior may be modified at runtime by setting the
<a class="Xr">sysctl(8)</a> variable
<var class="Va">net.link.gre.max_nesting</var> to the desired level of
nesting.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">gif(4)</a>, <a class="Xr">inet(4)</a>,
<a class="Xr">ip(4)</a>, <a class="Xr">me(4)</a>,
<a class="Xr">netintro(4)</a>, <a class="Xr">protocols(5)</a>,
<a class="Xr">ifconfig(8)</a>, <a class="Xr">sysctl(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1>
<p class="Pp"><cite class="Rs"><span class="RsA">S. Hanks</span>,
<span class="RsA">T. Li</span>, <span class="RsA">D. Farinacci</span>, and
<span class="RsA">P. Traina</span>, <span class="RsT">Generic Routing
Encapsulation (GRE)</span>, <span class="RsR">RFC 1701</span>,
<span class="RsD">October 1994</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">S. Hanks</span>,
<span class="RsA">T. Li</span>, <span class="RsA">D. Farinacci</span>, and
<span class="RsA">P. Traina</span>, <span class="RsT">Generic Routing
Encapsulation over IPv4 networks</span>, <span class="RsR">RFC 1702</span>,
<span class="RsD">October 1994</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">D. Farinacci</span>,
<span class="RsA">T. Li</span>, <span class="RsA">S. Hanks</span>,
<span class="RsA">D. Meyer</span>, and <span class="RsA">P. Traina</span>,
<span class="RsT">Generic Routing Encapsulation (GRE)</span>,
<span class="RsR">RFC 2784</span>, <span class="RsD">March
2000</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">G. Dommety</span>,
<span class="RsT">Key and Sequence Number Extensions to GRE</span>,
<span class="RsR">RFC 2890</span>, <span class="RsD">September
2000</span>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><span class="An">Andrey V. Elsukov</span>
<<a class="Mt" href="mailto:ae@FreeBSD.org">ae@FreeBSD.org</a>>
<br/>
<span class="An">Heiko W.Rupp</span>
<<a class="Mt" href="mailto:hwr@pilhuhn.de">hwr@pilhuhn.de</a>></p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">The current implementation uses the key only for outgoing packets.
Incoming packets with a different key or without a key will be treated as if
they would belong to this interface.</p>
<p class="Pp">The sequence number field also used only for outgoing packets.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">August 21, 2020</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
