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