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