1.\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $ 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 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 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" $FreeBSD$ 38.\" 39.Dd June 9, 2002 40.Dt GRE 4 41.Os 42.Sh NAME 43.Nm gre 44.Nd encapsulating network device 45.Sh SYNOPSIS 46.Cd "device gre" 47.Sh DESCRIPTION 48The 49.Nm 50network interface pseudo device encapsulates datagrams 51into IP. 52These encapsulated datagrams are routed to a destination host, 53where they are decapsulated and further routed to their final destination. 54The 55.Dq tunnel 56appears to the inner datagrams as one hop. 57.Pp 58.Nm 59interfaces are dynamically created and destroyed with the 60.Xr ifconfig 8 61.Cm create 62and 63.Cm destroy 64subcommands. 65.Pp 66This driver currently supports the following modes of operation: 67.Bl -tag -width indent 68.It "GRE encapsulation (IP protocol number 47)" 69Encapsulated datagrams are 70prepended an outer datagram and a GRE header. 71The GRE header specifies 72the type of the encapsulated datagram and thus allows for tunneling other 73protocols than IP like e.g.\& AppleTalk. 74GRE mode is also the default tunnel mode on Cisco routers. 75This is also the default mode of operation of the 76.Nm 77interfaces. 78As part of the GRE mode, 79.Nm 80also supports Cisco WCCP protocol, both version 1 and version 2. 81Since there is no reliable way to distinguish between WCCP versions, it 82should be configured manually using the 83.Cm link2 84flag. 85If the 86.Cm link2 87flag is not set (default), then WCCP version 1 is selected. 88.It "MOBILE encapsulation (IP protocol number 55)" 89Datagrams are 90encapsulated into IP, but with a shorter encapsulation. 91The original 92IP header is modified and the modifications are inserted between the 93so modified header and the original payload. 94Like 95.Xr gif 4 , 96only for IP-in-IP encapsulation. 97.El 98.Pp 99The 100.Nm 101interfaces support a number of 102.Xr ioctl 2 Ns s , 103such as: 104.Bl -tag -width ".Dv GRESADDRS" 105.It Dv GRESADDRS 106Set the IP address of the local tunnel end. 107This is the source address 108set by or displayed by 109.Xr ifconfig 8 110for the 111.Nm 112interface. 113.It Dv GRESADDRD 114Set the IP address of the remote tunnel end. 115This is the destination address 116set by or displayed by 117.Xr ifconfig 8 118for the 119.Nm 120interface. 121.It Dv GREGADDRS 122Query the IP address that is set for the local tunnel end. 123This is the 124address the encapsulation header carries as local address (i.e., the real 125address of the tunnel start point). 126.It Dv GREGADDRD 127Query the IP address that is set for the remote tunnel end. 128This is the 129address the encapsulated packets are sent to (i.e., the real address of 130the remote tunnel endpoint). 131.It Dv GRESPROTO 132Set the operation mode to the specified IP protocol value. 133The 134protocol is passed to the interface in 135.Po Vt "struct ifreq" Pc Ns Li -> Ns Va ifr_flags . 136The operation mode can also be given as 137.Pp 138.Bl -tag -width ".Cm -link0" -compact 139.It Cm link0 140.Dv IPPROTO_GRE 141.It Cm -link0 142.Dv IPPROTO_MOBILE 143.El 144.Pp 145to 146.Xr ifconfig 8 . 147.Pp 148The 149.Cm link1 150flag is not used to choose encapsulation, but to modify the 151internal route search for the remote tunnel endpoint, see the 152.Sx BUGS 153section below. 154.It Dv GREGPROTO 155Query operation mode. 156.El 157.Pp 158Note that the IP addresses of the tunnel endpoints may be the same as the 159ones defined with 160.Xr ifconfig 8 161for the interface (as if IP is encapsulated), but need not be, as e.g.\& when 162encapsulating AppleTalk. 163.Sh EXAMPLES 164Configuration example: 165.Bd -literal 166Host X-- Host A ----------------tunnel---------- Cisco D------Host E 167 \\ | 168 \\ / 169 +------Host B----------Host C----------+ 170.Ed 171.Pp 172On host A 173.Pq Fx : 174.Bd -literal -offset indent 175route add default B 176ifconfig greN create 177ifconfig greN A D netmask 0xffffffff linkX up 178ifconfig greN tunnel A D 179route add E D 180.Ed 181.Pp 182On Host D (Cisco): 183.Bd -literal -offset indent 184Interface 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 188ip route C <some interface and mask> 189ip route A mask C 190ip route X mask tunnelX 191.Ed 192.Pp 193OR 194.Pp 195On Host D 196.Pq Fx : 197.Bd -literal -offset indent 198route add default C 199ifconfig greN create 200ifconfig greN D A 201ifconfig tunnel greN D A 202.Ed 203.Pp 204If all goes well, you should see packets flowing ;-) 205.Pp 206If you want to reach Host A over the tunnel (from Host D (Cisco)), then 207you have to have an alias on Host A for e.g.\& the Ethernet interface like: 208.Pp 209.Dl "ifconfig <etherif> alias Y" 210.Pp 211and on the Cisco: 212.Pp 213.Dl "ip route Y mask tunnelX" 214.Pp 215A similar setup can be used to create a link between two private networks 216(for example in the 192.168 subnet) over the Internet: 217.Bd -literal 218192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* 219 \\ / 220 \\ / 221 +------ the Internet ------+ 222.Ed 223.Pp 224Assuming router A has the (external) IP address A and the internal address 225192.168.1.1, while router B has external address B and internal address 226192.168.2.1, the following commands will configure the tunnel: 227.Pp 228On router A: 229.Bd -literal -offset indent 230ifconfig greN create 231ifconfig greN 192.168.1.1 192.168.2.1 link1 232ifconfig greN tunnel A B 233route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 234.Ed 235.Pp 236On router B: 237.Bd -literal -offset indent 238ifconfig greN create 239ifconfig greN 192.168.2.1 192.168.1.1 link1 240ifconfig greN tunnel B A 241route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 242.Ed 243.Pp 244Note that this is a safe situation where the 245.Cm link1 246flag (as discussed in the 247.Sx BUGS 248section below) may (and probably should) be set. 249.Sh NOTES 250The MTU of 251.Nm 252interfaces is set to 1476 by default, to match the value used by Cisco routers. 253This may not be an optimal value, depending on the link between the two tunnel 254endpoints. 255It can be adjusted via 256.Xr ifconfig 8 . 257.Pp 258For correct operation, the 259.Nm 260device needs a route to the destination that is less specific than the 261one over the tunnel. 262(Basically, there needs to be a route to the decapsulating host that 263does not run over the tunnel, as this would be a loop.) 264If the addresses are ambiguous, doing the 265.Nm ifconfig Cm tunnel 266step before the 267.Xr ifconfig 8 268call to set the 269.Nm 270IP addresses will help to find a route outside the tunnel. 271.Pp 272In order to tell 273.Xr ifconfig 8 274to actually mark the interface as 275.Dq up , 276the keyword 277.Cm up 278must be given last on its command line. 279.Pp 280The kernel must be set to forward datagrams by setting the 281.Va ip.forwarding 282.Xr sysctl 8 283variable to non-zero. 284.Sh SEE ALSO 285.\" Xr atalk 4 , 286.Xr gif 4 , 287.Xr inet 4 , 288.Xr ip 4 , 289.Xr netintro 4 , 290.\" Xr options 4 , 291.Xr protocols 5 , 292.Xr ifconfig 8 , 293.Xr sysctl 8 294.Pp 295A description of GRE encapsulation can be found in RFC 1701 and RFC 1702. 296.Pp 297A description of MOBILE encapsulation can be found in RFC 2004. 298.Sh AUTHORS 299.An Heiko W.Rupp Aq hwr@pilhuhn.de 300.Sh BUGS 301The 302.Fn compute_route 303code in 304.Pa if_gre.c 305toggles the last bit of the 306IP-address to provoke the search for a less specific route than the 307one directly over the tunnel to prevent loops. 308This is possibly not the best solution. 309.Pp 310To avoid the address munging described above, turn on the 311.Cm link1 312flag on the 313.Xr ifconfig 8 314command line. 315This implies that the GRE packet destination and the ifconfig remote host 316are not the same IP addresses, and that the GRE destination does not route 317over the 318.Nm 319interface itself. 320.Pp 321The GRE RFCs are not yet fully implemented (no GRE options). 322