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