xref: /freebsd/share/man/man4/gif.4 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1.\"	$KAME: gif.4,v 1.28 2001/05/18 13:15:56 itojun Exp $
2.\"
3.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the project nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" $FreeBSD$
31.\"
32.Dd April 10, 1999
33.Dt GIF 4
34.Os
35.Sh NAME
36.Nm gif
37.Nd generic tunnel interface
38.Sh SYNOPSIS
39.Cd "device gif"
40.Sh DESCRIPTION
41The
42.Nm
43interface is a generic tunnelling device for IPv4 and IPv6.
44It can tunnel IPv[46] traffic over IPv[46].
45Therefore, there can be four possible configurations.
46The behavior of
47.Nm
48is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel.
49On
50.Nx ,
51.Nm
52can also tunnel ISO traffic over IPv[46] using EON encapsulation.
53Note that
54.Nm
55does not perform GRE encapsulation; use
56.Xr gre 4
57for GRE encapsulation.
58.Pp
59Each
60.Nm
61interface is created at runtime using interface cloning.
62This is
63most easily done with the
64.Dq Nm ifconfig Cm create
65command or using the
66.Va ifconfig_ Ns Aq Ar interface
67variable in
68.Xr rc.conf 5 .
69.Pp
70To use
71.Nm ,
72the administrator needs to configure the protocol and addresses used for the outer
73header.
74This can be done by using
75.Xr ifconfig 8
76.Cm tunnel ,
77or
78.Dv SIOCSIFPHYADDR
79ioctl.
80The administrator also needs to configure the protocol and addresses for the
81inner header, with
82.Xr ifconfig 8 .
83Note that IPv6 link-local addresses
84(those that start with
85.Li fe80:: )
86will be automatically configured whenever possible.
87You may need to remove IPv6 link-local addresses manually using
88.Xr ifconfig 8 ,
89if you want to disable the use of IPv6 as the inner header
90(for example, if you need a pure IPv4-over-IPv6 tunnel).
91Finally, you must modify the routing table to route the packets through the
92.Nm
93interface.
94.Pp
95The
96.Nm
97device can be configured to be ECN friendly.
98This can be configured by
99.Dv IFF_LINK1 .
100.Ss ECN friendly behavior
101The
102.Nm
103device can be configured to be ECN friendly, as described in
104.Dv draft-ietf-ipsec-ecn-02.txt .
105This is turned off by default, and can be turned on by the
106.Dv IFF_LINK1
107interface flag.
108.Pp
109Without
110.Dv IFF_LINK1 ,
111.Nm
112will show normal behavior, as described in RFC2893.
113This can be summarized as follows:
114.Bl -tag -width "Ingress" -offset indent
115.It Ingress
116Set outer TOS bit to
117.Dv 0 .
118.It Egress
119Drop outer TOS bit.
120.El
121.Pp
122With
123.Dv IFF_LINK1 ,
124.Nm
125will copy ECN bits
126.Dv ( 0x02
127and
128.Dv 0x01
129on IPv4 TOS byte or IPv6 traffic class byte)
130on egress and ingress, as follows:
131.Bl -tag -width "Ingress" -offset indent
132.It Ingress
133Copy TOS bits except for ECN CE
134(masked with
135.Dv 0xfe )
136from
137inner to outer.
138Set ECN CE bit to
139.Dv 0 .
140.It Egress
141Use inner TOS bits with some change.
142If outer ECN CE bit is
143.Dv 1 ,
144enable ECN CE bit on the inner.
145.El
146.Pp
147Note that the ECN friendly behavior violates RFC2893.
148This should be used in mutual agreement with the peer.
149.Ss Security
150A malicious party may try to circumvent security filters by using
151tunnelled packets.
152For better protection,
153.Nm
154performs both martian and ingress filtering against the outer source address
155on egress.
156Note that martian/ingress filters are in no way complete.
157You may want to secure your node by using packet filters.
158Ingress filtering can break tunnel operation in an asymmetrically
159routed network.
160It can be turned off by
161.Dv IFF_LINK2
162bit.
163.Ss Route caching
164Processing each packet requires two route lookups: first on the
165packet itself, and second on the tunnel destination.
166This second route can be cached, increasing tunnel performance.
167However, in a dynamically routed network, the tunnel will stick
168to the cached route, ignoring routing table updates.
169Route caching can be enabled with the
170.Dv IFF_LINK0
171flag.
172.\"
173.Ss Miscellaneous
174By default,
175.Nm
176tunnels may not be nested.
177This behavior may be modified at runtime by setting the
178.Xr sysctl 8
179variable
180.Va net.link.gif.max_nesting
181to the desired level of nesting.
182Additionally,
183.Nm
184tunnels are restricted to one per pair of end points.
185Parallel tunnels may be enabled by setting the
186.Xr sysctl 8
187variable
188.Va net.link.gif.parallel_tunnels
189to 1.
190.Sh SEE ALSO
191.Xr gre 4 ,
192.Xr inet 4 ,
193.Xr inet6 4 ,
194.Xr ifconfig 8
195.Rs
196.%A R. Gilligan
197.%A E. Nordmark
198.%B RFC2893
199.%T Transition Mechanisms for IPv6 Hosts and Routers
200.%D August 2000
201.%O ftp://ftp.isi.edu/in-notes/rfc2893.txt
202.Re
203.Rs
204.%A Sally Floyd
205.%A David L. Black
206.%A K. K. Ramakrishnan
207.%T "IPsec Interactions with ECN"
208.%D December 1999
209.%O draft-ietf-ipsec-ecn-02.txt
210.Re
211.\"
212.Sh HISTORY
213The
214.Nm
215device first appeared in the WIDE hydrangea IPv6 kit.
216.\"
217.Sh BUGS
218There are many tunnelling protocol specifications, all
219defined differently from each other.
220The
221.Nm
222device may not interoperate with peers which are based on different specifications,
223and are picky about outer header fields.
224For example, you cannot usually use
225.Nm
226to talk with IPsec devices that use IPsec tunnel mode.
227.Pp
228The current code does not check if the ingress address
229(outer source address)
230configured in the
231.Nm
232interface makes sense.
233Make sure to specify an address which belongs to your node.
234Otherwise, your node will not be able to receive packets from the peer,
235and it will generate packets with a spoofed source address.
236.Pp
237If the outer protocol is IPv4,
238.Nm
239does not try to perform path MTU discovery for the encapsulated packet
240(DF bit is set to 0).
241.Pp
242If the outer protocol is IPv6, path MTU discovery for encapsulated packets
243may affect communication over the interface.
244The first bigger-than-pmtu packet may be lost.
245To avoid the problem, you may want to set the interface MTU for
246.Nm
247to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4.
248.Pp
249The
250.Nm
251device does not translate ICMP messages for the outer header into the inner header.
252.Pp
253In the past,
254.Nm
255had a multi-destination behavior, configurable via
256.Dv IFF_LINK0
257flag.
258The behavior is obsolete and is no longer supported.
259