| blob | 7e19ac9e2340bbab7b7498ba5d6b3cfcdd7c5a06 |
1 .\" $NetBSD: gif.4,v 1.28 2006/12/18 00:16:10 wiz Exp $
2 .\" $KAME: gif.4,v 1.24 2001/02/20 12:54:01 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 December 18, 2006
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
40 The
41 .Nm
42 interface is a generic tunneling pseudo device for IPv4 and IPv6.
43 It can tunnel IPv[46] traffic over IPv[46].
44 Therefore, there can be four possible configurations.
45 The behavior of
46 .Nm
47 is mainly based on RFC 2893 IPv6-over-IPv4 configured tunnel.
48 .Nm
49 can also tunnel ISO traffic over IPv[46] using EON encapsulation.
50 .Pp
51 To use
52 .Nm gif ,
53 the administrator must first create the interface
54 and then configure protocol and addresses used for the outer
55 header.
56 This can be done by using
57 .Xr ifconfig 8
58 .Cm create
59 and
60 .Cm tunnel
61 subcommands, or
62 .Dv SIOCIFCREATE
63 and
64 .Dv SIOCSIFPHYADDR
65 ioctls.
66 Also, administrator needs to configure protocol and addresses used for the
67 inner header, by using
68 .Xr ifconfig 8 .
69 Note that IPv6 link-local address
70 .Pq those start with Li fe80::
71 will be automatically configured whenever possible.
72 You may need to remove IPv6 link-local address manually using
73 .Xr ifconfig 8 ,
74 when you would like to disable the use of IPv6 as inner header
75 .Pq like when you need pure IPv4-over-IPv6 tunnel .
76 Finally, use routing table to route the packets toward
77 .Nm
78 interface.
79 .Pp
80 .Nm
81 can be configured to be ECN friendly.
82 This can be configured by
83 .Dv IFF_LINK1 .
84 .Ss ECN friendly behavior
85 .Nm
86 can be configured to be ECN friendly, as described in
87 .Dv draft-ietf-ipsec-ecn-02.txt .
88 This is turned off by default, and can be turned on by
89 .Dv IFF_LINK1
90 interface flag.
91 .Pp
92 Without
93 .Dv IFF_LINK1 ,
94 .Nm
95 will show a normal behavior, like described in RFC 2893.
96 This can be summarized as follows:
97 .Bl -tag -width "Ingress" -offset indent
98 .It Ingress
99 Set outer TOS bit to
100 .Dv 0 .
101 .It Egress
102 Drop outer TOS bit.
103 .El
104 .Pp
105 With
106 .Dv IFF_LINK1 ,
107 .Nm
108 will copy ECN bits
109 .Dv ( 0x02
110 and
111 .Dv 0x01
112 on IPv4 TOS byte or IPv6 traffic class byte)
113 on egress and ingress, as follows:
114 .Bl -tag -width "Ingress" -offset indent
115 .It Ingress
116 Copy TOS bits except for ECN CE
117 (masked with
118 .Dv 0xfe )
119 from
120 inner to outer.
121 set ECN CE bit to
122 .Dv 0 .
123 .It Egress
124 Use inner TOS bits with some change.
125 If outer ECN CE bit is
126 .Dv 1 ,
127 enable ECN CE bit on the inner.
128 .El
129 .Pp
130 Note that the ECN friendly behavior violates RFC 2893.
131 This should be used in mutual agreement with the peer.
132 .Ss Packet format
133 Every inner packet is encapsulated in an outer packet.
134 The inner packet may be IPv4, IPv6, or ISO CLNP.
135 The outer packet may be IPv4 or IPv6, and has all the
136 usual IP headers, including a protocol field that identifies the
137 type of inner packet.
138 .Pp
139 When the inner packet is IPv4, the protocol field of the outer packet
140 is 4
141 .Dv ( IPPROTO_IPV4 ) .
142 When the inner packet is IPv6, the protocol field of the outer packet
143 is 41
144 .Dv ( IPPROTO_IPV6 ) .
145 When the inner packet is ISO CNLP, the protocol field of the outer packet
146 is 80
147 .Dv ( IPPROTO_EON ) .
148 .Ss Security
149 Malicious party may try to circumvent security filters by using
150 tunneled packets.
151 For better protection,
152 .Nm
153 performs martian filter and ingress filter against outer source address,
154 on egress.
155 Note that martian/ingress filters are no way complete.
156 You may want to secure your node by using packet filters.
157 Ingress filter can be turned off by
158 .Dv IFF_LINK2
159 bit.
160 .\"
161 .Sh EXAMPLES
162 Configuration example:
163 .Bd -literal
164 Host X--NetBSD A ----------------tunnel---------- cisco D------Host E
165 \\ |
166 \\ /
167 +-----Router B--------Router C---------+
169 .Ed
170 On
171 .Nx
172 system A
173 .Ns ( Nx ) :
174 .Bd -literal
175 # route add default B
176 # ifconfig gifN create
177 # ifconfig gifN A netmask 0xffffffff tunnel A D up
178 # route add E 0
179 # route change E -ifp gif0
180 .Ed
181 .Pp
182 On Host D (Cisco):
183 .Bd -literal
184 Interface TunnelX
185 ip unnumbered D ! e.g. address from Ethernet interface
186 tunnel source D ! e.g. address from Ethernet interface
187 tunnel destination A
188 ip route C <some interface and mask>
189 ip route A mask C
190 ip route X mask tunnelX
191 .Ed
192 .Pp
193 or on Host D
194 .Ns ( Nx ) :
195 .Bd -literal
196 # route add default C
197 # ifconfig gifN D A
198 .Ed
199 .Pp
200 If all goes well, you should see packets flowing.
201 .Pp
202 If you want to reach Host A over the tunnel (from the Cisco D), then
203 you have to have an alias on Host A for e.g. the Ethernet interface like:
204 .Ic ifconfig Ar <etherif> alias Y
205 and on the cisco
206 .Ic ip Ar route Y mask tunnelX .
207 .Sh SEE ALSO
208 .Xr etherip 4 ,
209 .Xr inet 4 ,
210 .Xr inet6 4 ,
211 .Xr ifconfig 8
212 .Rs
213 .%A C. Perkins
214 .%B RFC 2003
215 .%T IP Encapsulation within IP
216 .%D October 1996
217 .%O ftp://ftp.isi.edu/in-notes/rfc2003.txt
218 .Re
219 .Rs
220 .%A R. Gilligan
221 .%A E. Nordmark
222 .%B RFC 2893
223 .%T Transition Mechanisms for IPv6 Hosts and Routers
224 .%D August 2000
225 .%O ftp://ftp.isi.edu/in-notes/rfc2893.txt
226 .Re
227 .Rs
228 .%A Sally Floyd
229 .%A David L. Black
230 .%A K. K. Ramakrishnan
231 .%T "IPsec Interactions with ECN"
232 .%D December 1999
233 .%O draft-ietf-ipsec-ecn-02.txt
234 .Re
235 .Rs
236 .%A F. Baker
237 .%A P. Savola
238 .%B RFC 3704
239 .%T Ingress Filtering for Multihomed Networks
240 .%D March 2004
241 .%O ftp://ftp.isi.edu/in-notes/rfc3704.txt
242 .Re
243 .\"
244 .Sh STANDARDS
245 IPv4 over IPv4 encapsulation is compatible with RFC 2003.
246 IPv6 over IPv4 encapsulation is compatible with RFC 2893.
247 .\"
248 .Sh HISTORY
249 The
250 .Nm
251 device first appeared in WIDE hydrangea IPv6 kit.
252 .\"
253 .Sh BUGS
254 There are many tunneling protocol specifications,
255 defined differently from each other.
256 .Nm
257 may not interoperate with peers which are based on different specifications,
258 and are picky about outer header fields.
259 For example, you cannot usually use
260 .Nm
261 to talk with IPsec devices that use IPsec tunnel mode.
262 .Pp
263 The current code does not check if the ingress address
264 .Pq outer source address
265 configured to
266 .Nm
267 makes sense.
268 Make sure to configure an address which belongs to your node.
269 Otherwise, your node will not be able to receive packets from the peer,
270 and your node will generate packets with a spoofed source address.
271 .Pp
272 If the outer protocol is IPv6, path MTU discovery for encapsulated packet
273 may affect communication over the interface.
274 .Pp
275 In the past,
276 .Nm
277 had a multi-destination behavior, configurable via
278 .Dv IFF_LINK0
279 flag.
280 The behavior was obsoleted and is no longer supported.