Remove some AppleTalk remains.
[dragonfly.git] / share / man / man4 / gre.4
CommitLineData
984263bc 1.\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $
984263bc
MD
2.\"
3.\" Copyright 1998 (c) 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.\" 3. All advertising materials mentioning features or use of this software
18.\" must display the following acknowledgement:
19.\" This product includes software developed by the NetBSD
20.\" Foundation, Inc. and its contributors.
21.\" 4. Neither the name of the The NetBSD Foundation nor the names of its
22.\" contributors may be used to endorse or promote products derived
23.\" from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
61f4f7c0
SW
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
984263bc
MD
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
61f4f7c0 37.\" $FreeBSD: src/share/man/man4/gre.4,v 1.7 2006/10/19 07:41:47 danger Exp $
61f4f7c0
SW
38.\"
39.Dd November 11, 2007
984263bc
MD
40.Dt GRE 4
41.Os
42.Sh NAME
43.Nm gre
44.Nd encapsulating network device
45.Sh SYNOPSIS
61f4f7c0
SW
46To compile the
47.Ns Nm
48device into the kernel, place the following line in the kernel
49configuration file:
50.Bd -ragged -offset indent
51.Cd "pseudo-device gre"
52.Ed
53.Pp
54Alternatively, to load the
55.Ns Nm
56device as a module at boot time, place the following line in
57.Xr loader.conf 5 :
58.Bd -literal -offset indent
59if_gre_load="YES"
60.Ed
984263bc
MD
61.Sh DESCRIPTION
62The
9b5a9965 63.Nm
984263bc 64network interface pseudo device encapsulates datagrams
61f4f7c0
SW
65into IP.
66These encapsulated datagrams are routed to a destination host,
984263bc
MD
67where they are decapsulated and further routed to their final destination.
68The
69.Dq tunnel
70appears to the inner datagrams as one hop.
71.Pp
72.Nm
73interfaces are dynamically created and destroyed with the
74.Xr ifconfig 8
75.Cm create
76and
77.Cm destroy
78subcommands.
79.Pp
80This driver currently supports the following modes of operation:
61f4f7c0
SW
81.Bl -tag -width indent
82.It "GRE encapsulation (IP protocol number 47)"
984263bc 83Encapsulated datagrams are
61f4f7c0
SW
84prepended an outer datagram and a GRE header.
85The GRE header specifies
984263bc 86the type of the encapsulated datagram and thus allows for tunneling other
b911de4f 87protocols than IP.
61f4f7c0
SW
88GRE mode is also the default tunnel mode on Cisco routers.
89This is also the default mode of operation of the
90.Nm
984263bc 91interfaces.
61f4f7c0
SW
92.\"As part of the GRE mode,
93.\".Nm
94.\"also supports Cisco WCCP protocol, both version 1 and version 2.
95.\"Since there is no reliable way to distinguish between WCCP versions, it
96.\"should be configured manually using the
97.\".Cm link2
98.\"flag.
99.\"If the
100.\".Cm link2
101.\"flag is not set (default), then WCCP version 1 is selected.
102.It "MOBILE encapsulation (IP protocol number 55)"
984263bc 103Datagrams are
61f4f7c0
SW
104encapsulated into IP, but with a shorter encapsulation.
105The original
984263bc 106IP header is modified and the modifications are inserted between the
61f4f7c0
SW
107so modified header and the original payload.
108Like
984263bc 109.Xr gif 4 ,
61f4f7c0 110only for IP-in-IP encapsulation.
984263bc
MD
111.El
112.Pp
113The
61f4f7c0 114.Nm
984263bc
MD
115interfaces support a number of
116.Xr ioctl 2 Ns s ,
117such as:
61f4f7c0
SW
118.Bl -tag -width ".Dv GRESADDRS"
119.It Dv GRESADDRS
120Set the IP address of the local tunnel end.
121This is the source address
122set by or displayed by
123.Xr ifconfig 8
124for the
125.Nm
984263bc 126interface.
61f4f7c0
SW
127.It Dv GRESADDRD
128Set the IP address of the remote tunnel end.
129This is the destination address
130set by or displayed by
131.Xr ifconfig 8
132for the
133.Nm
984263bc 134interface.
61f4f7c0
SW
135.It Dv GREGADDRS
136Query the IP address that is set for the local tunnel end.
137This is the
138address the encapsulation header carries as local address (i.e., the real
139address of the tunnel start point).
140.It Dv GREGADDRD
141Query the IP address that is set for the remote tunnel end.
142This is the
143address the encapsulated packets are sent to (i.e., the real address of
144the remote tunnel endpoint).
145.It Dv GRESPROTO
146Set the operation mode to the specified IP protocol value.
147The
148protocol is passed to the interface in
149.Po Vt "struct ifreq" Pc Ns Li -> Ns Va ifr_flags .
984263bc 150The operation mode can also be given as
61f4f7c0
SW
151.Pp
152.Bl -tag -width ".Cm -link0" -compact
153.It Cm link0
154.Dv IPPROTO_GRE
155.It Cm -link0
156.Dv IPPROTO_MOBILE
984263bc
MD
157.El
158.Pp
159to
160.Xr ifconfig 8 .
161.Pp
61f4f7c0
SW
162The
163.Cm link1
164flag is not used to choose encapsulation, but to modify the
984263bc
MD
165internal route search for the remote tunnel endpoint, see the
166.Sx BUGS
167section below.
61f4f7c0 168.It Dv GREGPROTO
984263bc
MD
169Query operation mode.
170.El
171.Pp
172Note that the IP addresses of the tunnel endpoints may be the same as the
173ones defined with
174.Xr ifconfig 8
b911de4f 175for the interface (as if IP is encapsulated), but need not be.
984263bc
MD
176.Sh EXAMPLES
177Configuration example:
178.Bd -literal
61f4f7c0 179Host X-- Host A ----------------tunnel---------- Cisco D------Host E
984263bc
MD
180 \\ |
181 \\ /
61f4f7c0 182 +------Host B----------Host C----------+
984263bc 183.Ed
61f4f7c0 184.Pp
984263bc 185On host A
61f4f7c0
SW
186.Pq Dx :
187.Bd -literal -offset indent
188route add default B
189ifconfig greN create
190ifconfig greN A D netmask 0xffffffff linkX up
191ifconfig greN tunnel A D
192route add E D
984263bc 193.Ed
61f4f7c0 194.Pp
984263bc 195On Host D (Cisco):
61f4f7c0
SW
196.Bd -literal -offset indent
197Interface TunnelX
198 ip unnumbered D ! e.g. address from Ethernet interface
199 tunnel source D ! e.g. address from Ethernet interface
200 tunnel destination A
201ip route C <some interface and mask>
202ip route A mask C
203ip route X mask tunnelX
984263bc 204.Ed
61f4f7c0 205.Pp
984263bc 206OR
61f4f7c0 207.Pp
984263bc 208On Host D
61f4f7c0
SW
209.Pq Dx :
210.Bd -literal -offset indent
211route add default C
212ifconfig greN create
213ifconfig greN D A
214ifconfig greN tunnel D A
984263bc
MD
215.Ed
216.Pp
217If all goes well, you should see packets flowing ;-)
218.Pp
219If you want to reach Host A over the tunnel (from Host D (Cisco)), then
61f4f7c0
SW
220you have to have an alias on Host A for e.g.\& the Ethernet interface like:
221.Pp
222.Dl "ifconfig <etherif> alias Y"
223.Pp
224and on the Cisco:
225.Pp
226.Dl "ip route Y mask tunnelX"
984263bc
MD
227.Pp
228A similar setup can be used to create a link between two private networks
229(for example in the 192.168 subnet) over the Internet:
230.Bd -literal
231192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.*
232 \\ /
233 \\ /
61f4f7c0 234 +------ the Internet ------+
984263bc 235.Ed
61f4f7c0 236.Pp
984263bc
MD
237Assuming router A has the (external) IP address A and the internal address
238192.168.1.1, while router B has external address B and internal address
239192.168.2.1, the following commands will configure the tunnel:
240.Pp
241On router A:
61f4f7c0
SW
242.Bd -literal -offset indent
243ifconfig greN create
244ifconfig greN 192.168.1.1 192.168.2.1 link1
245ifconfig greN tunnel A B
246route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1
984263bc
MD
247.Ed
248.Pp
249On router B:
61f4f7c0
SW
250.Bd -literal -offset indent
251ifconfig greN create
252ifconfig greN 192.168.2.1 192.168.1.1 link1
253ifconfig greN tunnel B A
254route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1
984263bc
MD
255.Ed
256.Pp
61f4f7c0
SW
257Note that this is a safe situation where the
258.Cm link1
259flag (as discussed in the
984263bc
MD
260.Sx BUGS
261section below) may (and probably should) be set.
262.Sh NOTES
263The MTU of
61f4f7c0
SW
264.Nm
265interfaces is set to 1476 by default, to match the value used by Cisco routers.
984263bc 266This may not be an optimal value, depending on the link between the two tunnel
61f4f7c0
SW
267endpoints.
268It can be adjusted via
984263bc
MD
269.Xr ifconfig 8 .
270.Pp
271For correct operation, the
272.Nm
273device needs a route to the destination that is less specific than the
274one over the tunnel.
275(Basically, there needs to be a route to the decapsulating host that
276does not run over the tunnel, as this would be a loop.)
277If the addresses are ambiguous, doing the
61f4f7c0 278.Nm ifconfig Cm tunnel
984263bc
MD
279step before the
280.Xr ifconfig 8
281call to set the
61f4f7c0 282.Nm
984263bc
MD
283IP addresses will help to find a route outside the tunnel.
284.Pp
285In order to tell
286.Xr ifconfig 8
61f4f7c0
SW
287to actually mark the interface as
288.Dq up ,
289the keyword
290.Cm up
984263bc
MD
291must be given last on its command line.
292.Pp
61f4f7c0
SW
293The kernel must be set to forward datagrams by setting the
294.Va net.inet.ip.forwarding
295.Xr sysctl 8
296variable to non-zero.
984263bc 297.Sh SEE ALSO
984263bc
MD
298.Xr gif 4 ,
299.Xr inet 4 ,
300.Xr ip 4 ,
301.Xr netintro 4 ,
984263bc
MD
302.Xr protocols 5 ,
303.Xr ifconfig 8 ,
304.Xr sysctl 8
305.Pp
306A description of GRE encapsulation can be found in RFC 1701 and RFC 1702.
307.Pp
308A description of MOBILE encapsulation can be found in RFC 2004.
309.Sh AUTHORS
310.An Heiko W.Rupp Aq hwr@pilhuhn.de
311.Sh BUGS
61f4f7c0 312The
a1a3b19e 313.Fn gre_compute_route
61f4f7c0
SW
314code in
315.Pa if_gre.c
316toggles the last bit of the
984263bc 317IP-address to provoke the search for a less specific route than the
61f4f7c0
SW
318one directly over the tunnel to prevent loops.
319This is possibly not the best solution.
984263bc 320.Pp
61f4f7c0
SW
321To avoid the address munging described above, turn on the
322.Cm link1
323flag on the
984263bc
MD
324.Xr ifconfig 8
325command line.
326This implies that the GRE packet destination and the ifconfig remote host
327are not the same IP addresses, and that the GRE destination does not route
328over the
61f4f7c0 329.Nm
984263bc
MD
330interface itself.
331.Pp
332The GRE RFCs are not yet fully implemented (no GRE options).