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