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