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
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
<table class="head">
<tr>
<td class="head-ltitle">GIF(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">GIF(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">gif</code> — <span class="Nd">generic
tunnel interface</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">device gif</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">gif</code> interface is a generic tunnelling
device for IPv4 and IPv6. It can tunnel IPv[46] traffic over IPv[46].
Therefore, there can be four possible configurations. The behavior of
<code class="Nm">gif</code> is mainly based on RFC2893 IPv6-over-IPv4
configured tunnel. On <span class="Ux">NetBSD</span>,
<code class="Nm">gif</code> can also tunnel ISO traffic over IPv[46] using
EON encapsulation. Note that <code class="Nm">gif</code> does not perform
GRE encapsulation; use <a class="Xr">gre(4)</a> for GRE encapsulation.</p>
<p class="Pp">The <code class="Nm">gif</code> interface can also tunnel Ethernet
traffic over IPv4 or IPv6 when combined with a
<a class="Xr">if_bridge(4)</a> interface using EtherIP protocol. See
<a class="Xr">if_bridge(4)</a> for detailed setup.</p>
<p class="Pp">Each <code class="Nm">gif</code> interface is created at runtime
using interface cloning. This is most easily done with the
“<code class="Nm">ifconfig</code>
<code class="Cm">create</code>” command or using the
<var class="Va">ifconfig_</var>⟨<var class="Ar">interface</var>⟩
variable in <a class="Xr">rc.conf(5)</a>.</p>
<p class="Pp">To use <code class="Nm">gif</code>, the administrator needs to
configure the protocol and addresses used for the outer header. This can be
done by using <a class="Xr">ifconfig(8)</a> <code class="Cm">tunnel</code>,
or <code class="Dv">SIOCSIFPHYADDR</code> ioctl. The administrator also
needs to configure the protocol and addresses for the inner header, with
<a class="Xr">ifconfig(8)</a>. Note that IPv6 link-local addresses (those
that start with <code class="Li">fe80::</code>) will be automatically
configured whenever possible. You may need to remove IPv6 link-local
addresses manually using <a class="Xr">ifconfig(8)</a>, if you want to
disable the use of IPv6 as the inner header (for example, if you need a pure
IPv4-over-IPv6 tunnel). Finally, you must modify the routing table to route
the packets through the <code class="Nm">gif</code> interface.</p>
<section class="Ss">
<h2 class="Ss" id="MTU_Configuration_and_Path_MTU_Discovery"><a class="permalink" href="#MTU_Configuration_and_Path_MTU_Discovery">MTU
Configuration and Path MTU Discovery</a></h2>
<p class="Pp">The <code class="Nm">gif</code> interface uses the fixed length,
<code class="Li">1280</code>, to determine whether the outgoing IPv6 packets
are split. This means the MTU value configured on the interface will be
ignored when the outer protocol is IPv6. When the
<code class="Dv">NOCLAMP</code> interface flag is set,
<code class="Nm">gif</code> uses the same configured value as IPv4
communications. This behavior prevents potential issues when the path MTU is
smaller than the interface MTU. This section describes the reason why the
default behavior is different. The <code class="Dv">NOCLAMP</code> interface
flag can be set using the following command:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">ifconfig <var class="Ar">gif0</var>
<code class="Cm">noclamp</code></code></div>
<p class="Pp">and clear the flag using the following:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">ifconfig <var class="Ar">gif0</var>
<code class="Cm">-noclamp</code></code></div>
<p class="Pp">where <var class="Ar">gif0</var> is the actual interface name.</p>
<p class="Pp">A tunnel interface always has an implicit smaller MTU for the
inner protocol than the outer protocol because of the additional header.
Note that the interface MTU on a <code class="Nm">gif</code> interface, the
default value is <code class="Li">1280</code>, is used as MTU for the outer
protocol. This means that the MTU for the inner protocol varies depending on
the outer protocol header length. If an outgoing packet bigger than the
inner protocol MTU arrives at a <code class="Nm">gif</code> interface for
encapsulation, it will be split into fragments. Specifically, if IPv4 is
used as the outer protocol, the inner is 20 octets smaller than the
interface MTU. In the case of the default interface MTU,
<code class="Li">1280</code>, inner packets bigger than
<code class="Li">1260</code> will be fragmented. In the case of IPv6, the
inner is 40 octets smaller than the outer.</p>
<p class="Pp">This fragmentation is not harmful though it can degrade the
performance. Note that while an increased MTU on <code class="Nm">gif</code>
interface helps to mitigate this reduced performance issue, it can also
cause packet losses on the intermediate narrowest path between the two
communication endpoints in IPv6. IPv6 allows fragmentation only on the
sender, not on the routers in the communication path. A big outgoing packet
will be dropped on a router with a smaller MTU.</p>
<p class="Pp">In normal IPv6 communication, an ICMPv6 Packet Too Big error will
be sent back to the sender, who can adjust the packet length and re-send it.
This process is performed in the upper protocols than L3, such as TCP, and
makes the packet length shorter so that packets go through the path without
fragmentation. This behavior is known as path MTU discovery.</p>
<p class="Pp">When using a <code class="Nm">gif</code> interface, the Packet Too
Big message is generated for the outer protocol. Since the
<code class="Nm">gif</code> interface does not translate this error to the
inner protocol, the inner protocol sees it just as a packet loss with no
useful information to adjust the length of the next packets. In this
situation, path MTU discovery does not work, and communications of the inner
protocol become stalled.</p>
<p class="Pp">In order to avoid this, a <code class="Nm">gif</code> interface
silently splits a packet of over 1240 octets into fragments to make the
outer protocol packets equal or shorter than 1280 octets, even when the
interface MTU is configured as larger than 1280. Note that this occurs only
when the outer protocol is IPv6. <code class="Li">1280</code> is the
smallest MTU in IPv6 and guarantees no packet loss occurs on intermediate
routers.</p>
<p class="Pp">As mentioned earlier, the performance is sub-optimal if the actual
path MTU is larger than <code class="Li">1280</code>. A typical confusing
scenario is as follows. The <code class="Nm">gif</code> interface can have
Ethernet, whose MTU is usually 1500, as the inner protocol. It is called an
EtherIP tunnel, and can be configured by adding the
<code class="Nm">gif</code> interface as a member of
<a class="Xr">if_bridge(4)</a> interface. The <a class="Xr">if_bridge(4)</a>
interface forcibly changes the MTU of the <code class="Nm">gif</code>
interface with those for the other member interfaces, which are likely 1500.
In this case, a situation in which the MTU of the
<code class="Nm">gif</code> interface is 1500 but fragmentation in 1280
octets always occurs.</p>
<p class="Pp">The default behavior is most conservative to prevent confusing
packet loss. Depending on the network configuration, enabling the
<code class="Dv">NOCLAMP</code> interface flag might be helpful for better
performance. It is crucial to ensure that the path MTU is equal to or larger
than the interface MTU when enabling this flag.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="ECN_friendly_behavior"><a class="permalink" href="#ECN_friendly_behavior">ECN
friendly behavior</a></h2>
<p class="Pp">The <code class="Nm">gif</code> device can be configured to be ECN
friendly, as described in
<code class="Dv">draft-ietf-ipsec-ecn-02.txt</code>. This is turned off by
default, and can be turned on by the <code class="Dv">IFF_LINK1</code>
interface flag.</p>
<p class="Pp">Without <code class="Dv">IFF_LINK1</code>,
<code class="Nm">gif</code> will show normal behavior, as described in
RFC2893. This can be summarized as follows:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt>Ingress</dt>
<dd>Set outer TOS bit to <code class="Dv">0</code>.</dd>
<dt>Egress</dt>
<dd>Drop outer TOS bit.</dd>
</dl>
</div>
<p class="Pp">With <code class="Dv">IFF_LINK1</code>,
<code class="Nm">gif</code> will copy ECN bits (<code class="Dv">0x02</code>
and <code class="Dv">0x01</code> on IPv4 TOS byte or IPv6 traffic class
byte) on egress and ingress, as follows:</p>
<div class="Bd-indent">
<dl class="Bl-tag">
<dt>Ingress</dt>
<dd>Copy TOS bits except for ECN CE (masked with <code class="Dv">0xfe</code>)
from inner to outer. Set ECN CE bit to <code class="Dv">0</code>.</dd>
<dt>Egress</dt>
<dd>Use inner TOS bits with some change. If outer ECN CE bit is
<code class="Dv">1</code>, enable ECN CE bit on the inner.</dd>
</dl>
</div>
<p class="Pp">Note that the ECN friendly behavior violates RFC2893. This should
be used in mutual agreement with the peer.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Security"><a class="permalink" href="#Security">Security</a></h2>
<p class="Pp">A malicious party may try to circumvent security filters by using
tunnelled packets. For better protection, <code class="Nm">gif</code>
performs both martian and ingress filtering against the outer source address
on egress. Note that martian/ingress filters are in no way complete. You may
want to secure your node by using packet filters. Ingress filtering can
break tunnel operation in an asymmetrically routed network. It can be turned
off by <code class="Dv">IFF_LINK2</code> bit.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Miscellaneous"><a class="permalink" href="#Miscellaneous">Miscellaneous</a></h2>
<p class="Pp">By default, <code class="Nm">gif</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.gif.max_nesting</var> to the desired level of
nesting.</p>
</section>
</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">gre(4)</a>, <a class="Xr">if_bridge(4)</a>,
<a class="Xr">inet(4)</a>, <a class="Xr">inet6(4)</a>,
<a class="Xr">ifconfig(8)</a></p>
<p class="Pp"><cite class="Rs"><span class="RsA">R. Gilligan</span> and
<span class="RsA">E. Nordmark</span>, <span class="RsT">Transition
Mechanisms for IPv6 Hosts and Routers</span>, <i class="RsB">RFC2893</i>,
<a class="RsU" href="http://tools.ietf.org/html/rfc2893">http://tools.ietf.org/html/rfc2893</a>,
<span class="RsD">August 2000</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Sally Floyd</span>,
<span class="RsA">David L. Black</span>, and <span class="RsA">K. K.
Ramakrishnan</span>, <span class="RsT">IPsec Interactions with ECN</span>,
<span class="RsD">December 1999</span>,
<span class="RsO">draft-ietf-ipsec-ecn-02.txt</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">R. Housley</span> and
<span class="RsA">S. Hollenbeck</span>, <span class="RsT">EtherIP: Tunneling
Ethernet Frames in IP Datagrams</span>, <span class="RsR">RFC 3378</span>,
<span class="RsD">September 2002</span>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">gif</code> device first appeared in the WIDE
hydrangea IPv6 kit.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">There are many tunnelling protocol specifications, all defined
differently from each other. The <code class="Nm">gif</code> device may not
interoperate with peers which are based on different specifications, and are
picky about outer header fields. For example, you cannot usually use
<code class="Nm">gif</code> to talk with IPsec devices that use IPsec tunnel
mode.</p>
<p class="Pp">If the outer protocol is IPv4, <code class="Nm">gif</code> does
not try to perform path MTU discovery for the encapsulated packet (DF bit is
set to 0).</p>
<p class="Pp">If the outer protocol is IPv6, path MTU discovery for encapsulated
packets may affect communication over the interface. The first
bigger-than-pmtu packet may be lost. To avoid the problem, you may want to
set the interface MTU for <code class="Nm">gif</code> to 1240 or smaller,
when the outer header is IPv6 and the inner header is IPv4.</p>
<p class="Pp">The <code class="Nm">gif</code> device does not translate ICMP
messages for the outer header into the inner header.</p>
<p class="Pp">In the past, <code class="Nm">gif</code> had a multi-destination
behavior, configurable via <code class="Dv">NOCLAMP</code> flag. The
behavior is obsolete and is no longer supported. This flag is now used to
determine whether performing fragmentation when the outer protocol is
IPv6.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">August 27, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
