1.\" $OpenBSD: gre.4,v 1.18 2003/06/06 10:29:41 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 xxxxxxxxxxxxxxxxxxxxx 56.It net.inet.gre.allow 57Allow GRE packets in and out of the system. 58.It net.inet.gre.wccp 59Allow WCCPv2-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.Xr gre 4 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.Pp 159.Bd -literal -offset indent 160# route add default C 161# ifconfig greN D A 162# ifconfig greN tunnel D A 163.Ed 164.Pp 165To reach Host A over the tunnel (from host D), there has to be an 166alias on Host A for the Ethernet interface: 167.Dl ifconfig <etherif> alias Y 168and on the Cisco 169.Dl ip route Y mask tunnelX 170.Sh NOTE 171For correct operation, the 172.Nm 173device needs a route to the destination, that is less specific than the 174one over the tunnel. 175(There needs to be a route to the decapsulating host that 176does not run over the tunnel, as this would create a loop.) 177.Pp 178In order for 179.Xr ifconfig 8 180to actually mark the interface as up, the keyword ``up'' must be given 181last on its command line. 182.Pp 183The kernel must be set to forward datagrams by including option 184``GATEWAY'' in the kernel config file and issuing the appropriate 185option to 186.Xr sysctl 8 . 187.Pp 188The GRE interface will accept WCCPv1-style GRE encapsulated packets 189from a Cisco router. 190Some magic with the packet filter configuration 191and a caching proxy like squid are needed to do anything useful with 192these packets. 193.Sh SEE ALSO 194.Xr atalk 4 , 195.Xr inet 4 , 196.Xr ip 4 , 197.Xr netintro 4 , 198.Xr options 4 , 199.Xr protocols 5 , 200.Xr ifconfig 8 , 201.Xr sysctl 8 202.Pp 203A description of GRE encapsulation can be found in RFC 1701, RFC 1702. 204.Pp 205A description of MOBILE encapsulation can be found in RFC 2004. 206.Pp 207A description of WCCPv1 can be found in draft-ietf-wrec-web-pro-00.txt, 208and WCCPv2 in draft-wilson-wrec-wccp-v2-00.txt. 209Both of these documents 210can be found at http://www.wrec.org/ (at the time of this writing). 211.Sh AUTHORS 212.An Heiko W.Rupp Aq hwr@pilhuhn.de 213.Sh BUGS 214The compute_route() code in 215.Pa net/if_gre.c 216toggles the last bit of the IP-address to provoke the search for a less 217specific route than the one directly over the tunnel to prevent loops. 218This is possibly not the best solution. 219.Pp 220To avoid the address munging described above, turn on the link1 flag 221on the ifconfig command line. 222This implies that the GRE packet destination and the remote host are not 223the same IP addresses, and that the GRE destination does not route over 224the 225.Sy gre Ns Ar X 226interface itself. 227.Pp 228GRE RFC not yet fully implemented (no GRE options). 229.Pp 230For the WCCP GRE encapsulated packets we can only reliably accept 231WCCPv1 format; WCCPv2 formatted packets add another header which will 232skew the decode, and results are not defined (i.e. don't do WCCPv2). 233