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