| blob | 74c142c29d1baf4f5b7c560d9111e0861a3a7bd6 |
1 .\" $NetBSD: gre.4,v 1.41 2009/01/04 16:30:17 wiz Exp $
2 .\"
3 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Heiko W.Rupp <hwr@pilhuhn.de>
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd January 4, 2009
31 .Dt GRE 4
32 .Os
33 .Sh NAME
34 .Nm gre
35 .Nd encapsulating network device
36 .Sh SYNOPSIS
37 .Cd pseudo-device gre
38 .Sh DESCRIPTION
39 The
40 .Nm gre
41 network interface pseudo device encapsulates datagrams
42 into IP.
43 These encapsulated datagrams are routed to a destination host,
44 where they are decapsulated and further routed to their final destination.
45 The
46 .Dq tunnel
47 appears to the inner datagrams as one hop.
48 .Pp
49 .Nm
50 interfaces are dynamically created and destroyed with the
51 .Xr ifconfig 8
52 .Cm create
53 and
54 .Cm destroy
55 subcommands.
56 .Pp
57 This driver currently supports the following modes of operation:
58 .Bl -tag -width abc
59 .It GRE encapsulation (IP protocol number 47)
60 Encapsulated datagrams are
61 prepended an outer datagram and a GRE header.
62 The GRE header specifies the type of the encapsulated datagram and
63 thus allows for tunneling other protocols than IP like e.g. AppleTalk.
64 GRE mode is also the default tunnel mode on Cisco routers.
65 This is also the default mode of operation of the
66 .Sy gre Ns Ar X
67 interfaces.
68 .It GRE in UDP encapsulation
69 Encapsulated datagrams are prepended a GRE header, and then they
70 are sent over a UDP socket.
71 Userland may create the socket and
72 .Dq delegate
73 it to the kernel using the
74 .Dv GRESSOCK
75 .Xr ioctl 2 .
76 If userland does not supply a socket, then the kernel will create
77 one using the addresses and ports supplied by
78 .Xr ioctl 2 Ns s
79 .Dv SIOCSLIFPHYADDR ,
80 .Dv GRESADDRD ,
81 and/or
82 .Dv GRESADDRS .
83 .It MOBILE encapsulation (IP protocol number 55)
84 Datagrams are
85 encapsulated into IP, but with a shorter encapsulation.
86 The original IP header is modified and the modifications are inserted
87 between the so modified header and the original payload.
88 Like
89 .Xr gif 4 ,
90 only for IP in IP encapsulation.
91 .El
92 .Pp
93 The
94 .Sy gre Ns Ar X
95 interfaces support a number of
96 .Xr ioctl 2 Ns s ,
97 such as:
98 .Bl -tag -width aaa
99 .It GRESADDRS :
100 Set the IP address of the local tunnel end.
101 This is the source address set by or displayed by ifconfig for the
102 .Sy gre Ns Ar X
103 interface.
104 .It GRESADDRD :
105 Set the IP address of the remote tunnel end.
106 This is the destination address set by or displayed by ifconfig for the
107 .Sy gre Ns Ar X
108 interface.
109 .It GREGADDRS :
110 Query the IP address that is set for the local tunnel end.
111 This is the address the encapsulation header carries as local
112 address (i.e. the real address of the tunnel start point.)
113 .It GREGADDRD :
114 Query the IP address that is set for the remote tunnel end.
115 This is the address the encapsulated packets are sent to (i.e. the
116 real address of the remote tunnel endpoint.)
117 .It GRESPROTO :
118 Set the operation mode to the specified IP protocol value.
119 The protocol is passed to the interface in (struct ifreq)-\*[Gt]ifr_flags.
120 The operation mode can also be given as
121 .Bl -tag -width link0xxx
122 .It link0 link2
123 IPPROTO_UDP
124 .It link0 -link2
125 IPPROTO_GRE
126 .It -link0 -link2
127 IPPROTO_MOBILE
128 .El
129 .Pp
130 to
131 .Xr ifconfig 8 .
132 .It GREGPROTO :
133 Query operation mode.
134 .It GRESSOCK :
135 Delegate a socket from userland to a tunnel interface in UDP
136 encapsulation mode.
137 The file descriptor for the socket is passed in
138 (struct ifreq)-\*[Gt]ifr_value.
139 .El
140 .Pp
141 Note that the IP addresses of the tunnel endpoints may be the same as the
142 ones defined with
143 .Xr ifconfig 8
144 for the interface (as if IP is encapsulated), but need not be, as e.g. when
145 encapsulating AppleTalk.
146 .Sh EXAMPLES
147 .Ss Example 1: Basic GRE tunneling
148 Configuration example:
149 .Bd -literal
150 Host X-- Router A --------------tunnel---------- Router D ----Host E
151 | |
152 \\ /
153 +----- Router B ----- Router C --------+
154 .Ed
155 .Pp
156 On Router A
157 .Pq Nx :
158 .Bd -literal
159 # route add default B
160 # ifconfig greN create
161 # ifconfig greN A D netmask 0xffffffff linkX up
162 # ifconfig greN tunnel A D
163 # route add E D
164 .Ed
165 .Pp
166 On Router D (Cisco):
167 .Bd -literal
168 Interface TunnelX
169 ip unnumbered D ! e.g. address from Ethernet interface
170 tunnel source D ! e.g. address from Ethernet interface
171 tunnel destination A
172 ip route C \*[Lt]some interface and mask\*[Gt]
173 ip route A mask C
174 ip route X mask tunnelX
175 .Ed
176 .Pp
177 or on Router D
178 .Pq Nx :
179 .Bd -literal
180 # route add default C
181 # ifconfig greN create
182 # ifconfig greN D A
183 # ifconfig tunnel greN D A
184 .Ed
185 .Pp
186 If all goes well, you should see packets flowing ;-)
187 .Pp
188 If you want to reach Router A over the tunnel (from Router D (Cisco)), then
189 you have to have an alias on Router A for e.g. the Ethernet interface like:
190 .Bd -literal
191 ifconfig \*[Lt]etherif\*[Gt] alias Y
192 .Ed
193 .Pp
194 and on the Cisco
195 .Bd -literal
196 ip route Y mask tunnelX
197 .Ed
198 .Ss Example 2: Linking private subnets
199 A similar setup can be used to create a link between two private networks
200 (for example in the 192.168 subnet) over the Internet:
201 .Bd -literal
202 192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.*
203 \\ /
204 \\ /
205 +----- the Internet ------+
206 .Ed
207 .Pp
208 Assuming Router A has the (external) IP address A and the internal address
209 192.168.1.1, while Router B has external address B and internal address
210 192.168.2.1, the following commands will configure the tunnel:
211 .Pp
212 On Router A:
213 .Bd -literal
214 # ifconfig greN create
215 # ifconfig greN 192.168.1.1 192.168.2.1
216 # ifconfig greN tunnel A B
217 # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1
218 .Ed
219 .Pp
220 On Router B:
221 .Bd -literal
222 # ifconfig greN create
223 # ifconfig greN 192.168.2.1 192.168.1.1
224 # ifconfig greN tunnel B A
225 # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1
226 .Ed
227 .Ss Example 3: Encapsulating GRE in UDP
228 To setup the same tunnel as above, but using GRE in UDP encapsulation
229 instead of GRE encapsulation, set flags
230 .Ar link0
231 and
232 .Ar link2 ,
233 and specify source and destination UDP ports.
234 .Pp
235 On Router A:
236 .Bd -literal
237 # ifconfig greN create
238 # ifconfig greN link0 link2
239 # ifconfig greN 192.168.1.1 192.168.2.1
240 # ifconfig greN tunnel A,port-A B,port-B
241 # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1
242 .Ed
243 .Pp
244 On Router B:
245 .Bd -literal
246 # ifconfig greN create
247 # ifconfig greN link0 link2
248 # ifconfig greN 192.168.2.1 192.168.1.1
249 # ifconfig greN tunnel B,port-B A,port-A
250 # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1
251 .Ed
252 .Ss Example 4: Realizing IPv6 connectivity
253 Along these lines, you can use GRE tunnels to interconnect two IPv6
254 networks over an IPv4 infrastructure, or to hook up to the IPv6 internet
255 via an IPv4 tunnel to a Cisco router.
256 .Bd -literal
257 2001:db8:1::/64 -- NetBSD A ---- Tunnel ---- Cisco B --- IPv6 Internet
258 \\ /
259 \\ /
260 +------ the Internet ------+
261 .Ed
262 .Pp
263 The example will use the following addressing:
264 .Bl -hang
265 .It Nx
266 A has the IPv4 address A and the IPv6 address 2001:db8:1::1 (connects
267 to internal network 2001:db8:1::/64).
268 .It Cisco B
269 has external IPv4 address B.
270 .It All the IPv6 internet world
271 is behind B, so A wants to route 0::0/0
272 (the IPv6 default route) into the tunnel.
273 .It The GRE tunnel
274 will use a transit network: 2001:db8:ffff::1/64 on
275 the
276 .Nx
277 side, and ::2/64 on the Cisco side.
278 .El
279 .Pp
280 Then the following commands will configure the tunnel:
281 .Pp
282 On Router A
283 .Pq Nx :
284 .Bd -literal
285 # ifconfig greN create
286 # ifconfig greN inet6 2001:db8:ffff::1/64
287 # ifconfig greN tunnel A B
288 # route add -inet6 2001:db8:ffff::/64 2001:db8:ffff::2 -ifp greN
289 # route add -inet6 0::0/0 2001:db8:ffff::2 -ifp greN
290 .Ed
291 .Pp
292 On Router B (Cisco):
293 .Bd -literal
294 Interface TunnelX
295 tunnel mode gre ip
296 ipv6 address 2001:db8:ffff::2/64 ! transfer network
297 tunnel source B ! e.g. address from LAN interface
298 tunnel destination A ! where the tunnel is connected to
299 ipv6 route 2001:db8::/64 TunnelX ! route this network through tunnel
300 .Ed
301 .Sh NOTES
302 The MTU of
303 .Sy gre Ns Ar X
304 interfaces is set to 1476 by default to match the value used by Cisco routers.
305 This may not be an optimal value, depending on the link between the two tunnel
306 endpoints.
307 It can be adjusted via
308 .Xr ifconfig 8 .
309 .Pp
310 There needs to be a route to the decapsulating host that does not
311 run over the tunnel, as this would be a loop.
312 (This is not relevant for IPv6-over-IPv4 tunnels, of course.)
313 .Pp
314 In order to tell
315 .Xr ifconfig 8
316 to actually mark the interface as up, the keyword
317 .Dq up
318 must be given last on its command line.
319 .Pp
320 The kernel must be set to forward datagrams by either option
321 .Em GATEWAY
322 in the kernel config file or by issuing the appropriate option to
323 .Xr sysctl 8 .
324 .Sh SEE ALSO
325 .Xr atalk 4 ,
326 .Xr gif 4 ,
327 .Xr inet 4 ,
328 .Xr ip 4 ,
329 .Xr netintro 4 ,
330 .Xr options 4 ,
331 .Xr protocols 5 ,
332 .Xr ifconfig 8 ,
333 .Xr sysctl 8
334 .Pp
335 A description of GRE encapsulation can be found in RFC 1701 and RFC 1702.
336 .Pp
337 A description of MOBILE encapsulation can be found in RFC 2004.
338 .Sh AUTHORS
339 .An Heiko W.Rupp Aq hwr@pilhuhn.de
340 .An David Young Aq dyoung@NetBSD.org
341 .Pq GRE in UDP encapsulation, bug fixes
342 .Sh BUGS
343 The GRE RFCs are not yet fully implemented (no GRE options).
344 .Pp
345 The MOBILE encapsulation appears to have been broken since
346 it was first added to
347 .Nx ,
348 until August 2006.
349 It is known to interoperate with another
350 .Nm
351 in MOBILE mode, however, it has not been tested for interoperability
352 with any other implementation of RFC 2004.
353 .Pp
354 The
355 .Nx
356 base system does not
357 .Pq yet
358 contain a daemon for automatically establishing a UDP tunnel between
359 a host behind a NAT router and a host on the Internet.