1.\" $NetBSD: gre.4,v 1.11 2000/05/13 15:22:17 mycroft 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.Dd 13 September 1998 38.Dt GRE 4 39.Os 40.Sh NAME 41.Nm gre 42.Nd encapsulating network device 43.Sh SYNOPSIS 44.Cd pseudo-device gre Op Ar count 45.Sh DESCRIPTION 46The 47.Nm gre 48network interface is a pseudo device that allows to encapsulate datagrams 49into IP. These encapsulated datagrams are routed to a destination host, 50where they are decapsulated and further routed to their final destination. 51The so called ``tunnel'' appears to the inner datagrams like one hop. 52.Pp 53This driver currently supports the following modes of operation: 54.Bl -tag -width abc 55.It GRE encapsulation (IP protocol number 47). 56Encapsulated datagrams are 57prepended by a outer datagram and a GRE header. The GRE header specifies 58the type of the encapsulated datagram and thus allows for tunneling other 59protocols than IP like e.g. AppleTalk (not yet supported). GRE mode is 60also the default tunnel mode on Cisco routers. This is also the default 61mode of operation of the 62.Sy gre Ns Ar X 63interfaces. 64.It MOBILE encapsulation (IP protocol number 55). 65Datagrams are 66encapsulated into IP, but with a shorter encapsulation. The original 67IP header is modified and the modifications are inserted between the 68so modified header and the original payload. Like IPIP only for IP in IP 69encapsulation. 70.El 71.Pp 72The network interfaces are named 73.Sy gre Ns Ar 0 , 74.Sy gre Ns Ar 1 75and so on, as many as have given on the 76.Sy pseudo-device 77line in the system config file. Each interface supports a number of 78.Xr ioctl 2 Ns s, 79such as: 80.Bl -tag -width aaa 81.It GRESADDRS: 82Set the IP address of the local tunnel end. 83.It GRESADDRD: 84Set the IP address of the remote tunnel end. 85.It GREGADDRS: 86Query the IP address that is set for the local tunnel end. 87.It GREGADDRD: 88Query the IP address that is set for the remote tunnel end. 89.It GRESPROTO: 90Set the operation mode to the specified IP protocol value. The 91protocol is passed to the interface in (struct ifreq)->ifr_flags. 92The operation mode can also 93be given as 94.Bl -tag -width bbb 95.It link0 96IPPROTO_GRE 97.It link2 98IPPROTO_MOBILE 99.El 100to 101.Xr ifconfig . 102As the linkN flags are not mutually exclusive, modes must be set by applying 103positive and negative flags as e.g. 104.Xr ifconfig 105link0 -link1 -link2 106.It GREGPROTO: 107Query operation mode. 108.El 109.Pp 110Note that the IP addresses of the tunnel endpoints may be the same as the 111ones defined with 112.Xr ifconfig 113for the interface (as if IP is encapsulated), but need not be, as e.g. when 114encapsulating AppleTalk. 115.Pp 116.Sh EXAMPLE 117Configuration example: 118.Bd -literal 119Host X-- Host A ----------------tunnel---------- cisco D------Host E 120 \\ | 121 \\ / 122 +------Host B----------Host C----------+ 123 124.Ed 125 On host A (NetBSD): 126 127 # route add default B 128 # ifconfig greN A D netmask 0xffffffff linkX up 129 # greconfig -i greN -s A -d D 130 # route add E D 131 132 On Host D (Cisco): 133 134 Interface TunnelX 135 ip unnumbered D ! e.g. address from Ethernet interface 136 tunnel source D ! e.g. address from Ethernet interface 137 tunnel destination A 138 ip route C <some interface and mask> 139 ip route A mask C 140 ip route X mask tunnelX 141 142 OR 143 144 On Host D (NetBSD): 145 146 # route add default C 147 # ifconfig greN D A 148.Pp 149If all goes well, you should see packets flowing ;-) 150.Pp 151If you want to reach Host A over the tunnel (from the Cisco D), then 152you have to have an alias on Host A for e.g. the Ethernet interface like: 153 ifconfig <etherif> alias Y 154 and on the cisco 155 ip route Y mask tunnelX 156.Sh NOTE 157For correct operation, the 158.Nm 159device needs a route to the destination, that is less specific than the 160one over the tunnel. 161(Basically, there needs to be a route to the decapsulating host that 162does not run over the tunnel, as this would be a loop ..) 163.Pp 164In order to 165.Xr ifconfig 166to actually mark the interface as up, the keyword ``up'' must be given 167last on its command line. 168.Pp 169The kernel must be set to forward datagrams by either option 170``GATEWAY'' in the kernel config file or by issuing the appropriate 171option to 172.Xr sysctl . 173.Sh SEE ALSO 174.Xr netintro 4 , 175.Xr ip 4 , 176.Xr atalk 4 , 177.Xr inet 4 , 178.Xr ifconfig 8 , 179.Xr greconfig 8 , 180.Xr options 4 , 181.Xr protocols 5 , 182.Xr sysctl 8 183.Pp 184A description of GRE encapsulation can be found in RFC 1701, RFC 1702. 185.Pp 186A description of MOBILE encapsulation can be found in RFC 2004. 187.Sh BUGS 188The compute_route() code in if_gre.c toggles the last bit of the 189IP-address to provoke the search for a less specific route than the 190one directly over the tunnel to prevent loops. This is possibly not 191the best solution. 192.Pp 193To avoid the address munging described above, turn on the link1 flag 194on the ifconfig command line. This implies that the GRE packet 195destination (set via greconfig -d) and the ifconfig remote host are 196not the same IP addresses, and that the GRE destination does not route 197over the greX interface itself. 198.Pp 199GRE RFC not yet fully implemented (no GRE options), no other protocols 200yet than IP over IP. 201.Pp 202Traceroute does not work yet over the tunnel :( 203.Pp 204BPF does probably not yet work (it might, but last time I looked, 205it bombed, so I #if 0'd it out). 206.Pp 207.Sh AUTHOR 208Heiko W.Rupp <hwr@pilhuhn.de> 209