1.\" $NetBSD: gre.4,v 1.10 1999/12/22 14:55:49 kleink 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 119 120 121Host X-- Host A ----------------tunnel---------- cisco D------Host E 122 \\ | 123 \\ / 124 +------Host B----------Host C----------+ 125 126.Ed 127 On host A (NetBSD): 128 129 # route add default B 130 # ifconfig greN A D netmask 0xffffffff linkX up 131 # greconfig -i greN -s A -d D 132 # route add E D 133 134 On Host D (Cisco): 135 136 Interface TunnelX 137 ip unnumbered D ! e.g. address from Ethernet interface 138 tunnel source D ! e.g. address from Ethernet interface 139 tunnel destination A 140 ip route C <some interface and mask> 141 ip route A mask C 142 ip route X mask tunnelX 143 144 OR 145 146 On Host D (NetBSD): 147 148 # route add default C 149 # ifconfig greN D A 150.Pp 151If all goes well, you should see packets flowing ;-) 152.Pp 153If you want to reach Host A over the tunnel (from the Cisco D), then 154you have to have an alias on Host A for e.g. the Ethernet interface like: 155 ifconfig <etherif> alias Y 156 and on the cisco 157 ip route Y mask tunnelX 158.Sh NOTE 159For correct operation, the 160.Nm 161device needs a route to the destination, that is less specific than the 162one over the tunnel. 163(Basically, there needs to be a route to the decapsulating host that 164does not run over the tunnel, as this would be a loop ..) 165.Pp 166In order to 167.Xr ifconfig 168to actually mark the interface as up, the keyword ``up'' must be given 169last on its command line. 170.Pp 171The kernel must be set to forward datagrams by either option 172``GATEWAY'' in the kernel config file or by issuing the appropriate 173option to 174.Xr sysctl . 175.Sh SEE ALSO 176.Xr netintro 4 , 177.Xr ip 4 , 178.Xr atalk 4 , 179.Xr inet 4 , 180.Xr ifconfig 8 , 181.Xr greconfig 8 , 182.Xr options 4 , 183.Xr protocols 5 , 184.Xr sysctl 8 185.Pp 186A description of GRE encapsulation can be found in RFC 1701, RFC 1702. 187.Pp 188A description of MOBILE encapsulation can be found in RFC 2004. 189 190.Sh BUGS 191The compute_route() code in if_gre.c toggles the last bit of the 192IP-address to provoke the search for a less specific route than the 193one directly over the tunnel to prevent loops. This is possibly not 194the best solution. 195.Pp 196To avoid the address munging described above, turn on the link1 flag 197on the ifconfig command line. This implies that the GRE packet 198destination (set via greconfig -d) and the ifconfig remote host are 199not the same IP addresses, and that the GRE destination does not route 200over the greX interface itself. 201.Pp 202GRE RFC not yet fully implemented (no GRE options), no other protocols 203yet than IP over IP. 204.Pp 205Traceroute does not work yet over the tunnel :( 206.Pp 207BPF does probably not yet work (it might, but last time I looked, 208it bombed, so I #if 0'd it out). 209.Pp 210.Sh AUTHOR 211Heiko W.Rupp <hwr@pilhuhn.de> 212