1.\" $OpenBSD: gre.4,v 1.21 2003/11/21 09:26:54 jmc Exp $ 2.\" $NetBSD: gre.4,v 1.10 1999/12/22 14:55:49 kleink Exp $ 3.\" 4.\" Copyright 1998 (c) The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Heiko W.Rupp <hwr@pilhuhn.de> 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of the The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd September 13, 1998 39.Dt GRE 4 40.Os 41.Sh NAME 42.Nm gre 43.Nd encapsulating network device 44.Sh SYNOPSIS 45.Cd pseudo-device gre Op Ar count 46.Sh NOTE 47.Tn GRE , 48.Tn WCCPv1 , 49and 50.Tn MobileIP 51are enabled with the following 52.Xr sysctl 3 53variables respectively in 54.Pa /etc/sysctl.conf : 55.Bl -tag -width "net.inet.mobileip.allow" 56.It net.inet.gre.allow 57Allow GRE packets in and out of the system. 58.It net.inet.gre.wccp 59Allow WCCPv1-style GRE packets into the system (depends on the above). 60.It net.inet.mobileip.allow 61Allow MobileIP packets in and out of the system. 62.El 63.Sh DESCRIPTION 64The 65.Nm 66network interface allows tunnel construction using the Cisco GRE or 67the Mobile-IP (RFC 2004) encapsulation protocols. 68.Pp 69This driver currently supports the following modes of operation: 70.Bl -tag -width abc 71.It GRE encapsulation (IP protocol number 47). 72Encapsulated datagrams are prepended by an outer datagram and a GRE header. 73The GRE header specifies the type of the encapsulated datagram 74and thus allows for tunneling other protocols than IP like 75e.g. AppleTalk. 76GRE mode is the default tunnel mode on Cisco routers. 77This is also the default mode of operation of the 78.Sy gre Ns Ar X 79interfaces. 80.It MOBILE encapsulation (IP protocol number 55). 81Datagrams are encapsulated into IP, but with a much smaller 82encapsulation header. 83This protocol only supports IP in IP encapsulation, and is intended 84for use with mobile IP. 85.El 86.Pp 87The network interfaces are named 88.Sy gre Ns Ar 0 , 89.Sy gre Ns Ar 1 , 90etc. 91The number of interfaces is given by the corresponding 92.Sy pseudo-device 93line in the system config file. 94.Nm gre 95interfaces support the following 96.Xr ioctl 2 Ns s : 97.Bl -tag -width aaa 98.It GRESADDRS: 99Set the IP address of the local tunnel end. 100.It GRESADDRD: 101Set the IP address of the remote tunnel end. 102.It GREGADDRS: 103Query the IP address that is set for the local tunnel end. 104.It GREGADDRD: 105Query the IP address that is set for the remote tunnel end. 106.It GRESPROTO: 107Set the operation mode to the specified IP protocol value. 108The protocol is passed to the interface in (struct ifreq)->ifr_flags. 109The operation mode can also be given as 110.Bl -tag -width bbb 111.It link0 112IPPROTO_GRE 113.It -link0 114IPPROTO_MOBILE 115.El 116.It GREGPROTO: 117Query operation mode. 118.El 119.Pp 120Note that the IP addresses of the tunnel endpoints may be the same as the 121ones defined with 122.Xr ifconfig 8 123for the interface (as if IP is encapsulated), but need not be, as e.g. when 124encapsulating AppleTalk. 125.Sh EXAMPLES 126Configuration example: 127.Bd -literal 128 129 130Host X-- Host A ----------------tunnel---------- Cisco D------Host E 131 \\ | 132 \\ / 133 +------Host B----------Host C----------+ 134 135.Ed 136On Host A (OpenBSD): 137.Bd -literal -offset indent 138# route add default B 139# ifconfig greN A D netmask 0xffffffff linkX up 140# ifconfig greN tunnel A D 141# route add E D 142.Ed 143.Pp 144On Host D (Cisco): 145.Bd -literal -offset indent 146Interface TunnelX 147 ip unnumbered D ! e.g. address from Ethernet interface 148 tunnel source D ! e.g. address from Ethernet interface 149 tunnel destination A 150ip route C <some interface and mask> 151ip route A mask C 152ip route X mask tunnelX 153.Ed 154.Pp 155OR 156.Pp 157On Host D (OpenBSD): 158.Bd -literal -offset indent 159# route add default C 160# ifconfig greN D A 161# ifconfig greN tunnel D A 162.Ed 163.Pp 164To reach Host A over the tunnel (from host D), there has to be an 165alias on Host A for the Ethernet interface: 166.Dl ifconfig <etherif> alias Y 167and on the Cisco 168.Dl ip route Y mask tunnelX 169.Sh NOTE 170For correct operation, the 171.Nm 172device needs a route to the destination, that is less specific than the 173one over the tunnel. 174(There needs to be a route to the decapsulating host that 175does not run over the tunnel, as this would create a loop.) 176.Pp 177In order for 178.Xr ifconfig 8 179to actually mark the interface as up, the keyword ``up'' must be given 180last on its command line. 181.Pp 182The kernel must be set to forward datagrams by including option 183``GATEWAY'' in the kernel config file and issuing the appropriate 184option to 185.Xr sysctl 8 . 186.Pp 187The GRE interface will accept WCCPv1-style GRE encapsulated packets 188from a Cisco router. 189Some magic with the packet filter configuration 190and a caching proxy like squid are needed to do anything useful with 191these packets. 192.Sh SEE ALSO 193.Xr atalk 4 , 194.Xr inet 4 , 195.Xr ip 4 , 196.Xr netintro 4 , 197.Xr options 4 , 198.Xr protocols 5 , 199.Xr ifconfig 8 , 200.Xr sysctl 8 201.Pp 202A description of GRE encapsulation can be found in RFC 1701, RFC 1702. 203.Pp 204A description of MOBILE encapsulation can be found in RFC 2004. 205.Pp 206A description of WCCPv1 can be found in draft-ietf-wrec-web-pro-00.txt, 207and WCCPv2 in draft-wilson-wrec-wccp-v2-00.txt. 208Both of these documents 209can be found at http://www.wrec.org/ (at the time of this writing). 210.Sh AUTHORS 211.An Heiko W.Rupp Aq hwr@pilhuhn.de 212.Sh BUGS 213The compute_route() code in 214.Pa net/if_gre.c 215toggles the last bit of the IP-address to provoke the search for a less 216specific route than the one directly over the tunnel to prevent loops. 217This is possibly not the best solution. 218.Pp 219To avoid the address munging described above, turn on the link1 flag 220on the ifconfig command line. 221This implies that the GRE packet destination and the remote host are not 222the same IP addresses, and that the GRE destination does not route over 223the 224.Sy gre Ns Ar X 225interface itself. 226.Pp 227GRE RFC not yet fully implemented (no GRE options). 228.Pp 229For the WCCP GRE encapsulated packets we can only reliably accept 230WCCPv1 format; WCCPv2 formatted packets add another header which will 231skew the decode, and results are not defined (i.e. don't do WCCPv2). 232