1.\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun 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 June 9, 2002 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. 51The 52.Dq tunnel 53appears to the inner datagrams as one hop. 54.Pp 55.Nm 56interfaces are dynamically created and destroyed with the 57.Xr ifconfig 8 58.Cm create 59and 60.Cm destroy 61subcommands. 62.Pp 63This driver currently supports the following modes of operation: 64.Bl -tag -width abc 65.It GRE encapsulation (IP protocol number 47) 66Encapsulated datagrams are 67prepended an outer datagram and a GRE header. The GRE header specifies 68the type of the encapsulated datagram and thus allows for tunneling other 69protocols than IP like e.g. AppleTalk. GRE mode is also the default tunnel 70mode on Cisco routers. This is also the default mode 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 78.Xr gif 4 , 79only for IP in IP encapsulation. 80.El 81.Pp 82The 83.Sy gre Ns Ar X 84interfaces support a number of 85.Xr ioctl 2 Ns s , 86such as: 87.Bl -tag -width aaa 88.It GRESADDRS : 89Set the IP address of the local tunnel end. This is the source address 90set by or displayed by ifconfig for the 91.Sy gre Ns Ar X 92interface. 93.It GRESADDRD : 94Set the IP address of the remote tunnel end. This is the destination address 95set by or displayed by ifconfig for the 96.Sy gre Ns Ar X 97interface. 98.It GREGADDRS : 99Query the IP address that is set for the local tunnel end. This is the 100address the encapsulation header carries as local address (i.e. the real 101address of the tunnel start point.) 102.It GREGADDRD : 103Query the IP address that is set for the remote tunnel end. This is the 104address the encapsulated packets are sent to (i.e. the real address of 105the remote tunnel endpoint.) 106.It GRESPROTO : 107Set the operation mode to the specified IP protocol value. The 108protocol is passed to the interface in (struct ifreq)-\*[Gt]ifr_flags. 109The operation mode can also be given as 110.Bl -tag -width link0xxx 111.It link0 112IPPROTO_GRE 113.It -link0 114IPPROTO_MOBILE 115.El 116.Pp 117to 118.Xr ifconfig 8 . 119.Pp 120The link1 flag is not used to choose encapsulation, but to modify the 121internal route search for the remote tunnel endpoint, see the 122.Sx BUGS 123section below. 124.It GREGPROTO : 125Query operation mode. 126.El 127.Pp 128Note that the IP addresses of the tunnel endpoints may be the same as the 129ones defined with 130.Xr ifconfig 8 131for the interface (as if IP is encapsulated), but need not be, as e.g. when 132encapsulating AppleTalk. 133.Sh EXAMPLES 134Configuration example: 135.Bd -literal 136Host X-- Host A ----------------tunnel---------- cisco D------Host E 137 \\ | 138 \\ / 139 +------Host B----------Host C----------+ 140.Ed 141On host A 142.Ns ( Nx ) : 143.Bd -literal 144 # route add default B 145 # ifconfig greN create 146 # ifconfig greN A D netmask 0xffffffff linkX up 147 # ifconfig greN tunnel A D 148 # route add E D 149.Ed 150On Host D (Cisco): 151.Bd -literal 152 Interface TunnelX 153 ip unnumbered D ! e.g. address from Ethernet interface 154 tunnel source D ! e.g. address from Ethernet interface 155 tunnel destination A 156 ip route C \*[Lt]some interface and mask\*[Gt] 157 ip route A mask C 158 ip route X mask tunnelX 159.Ed 160OR 161On Host D 162.Ns ( Nx ) : 163.Bd -literal 164 # route add default C 165 # ifconfig greN create 166 # ifconfig greN D A 167 # ifconfig tunnel greN D A 168.Ed 169.Pp 170If all goes well, you should see packets flowing ;-) 171.Pp 172If you want to reach Host A over the tunnel (from Host D (Cisco)), then 173you have to have an alias on Host A for e.g. the Ethernet interface like: 174.Bd -literal 175 ifconfig \*[Lt]etherif\*[Gt] alias Y 176.Ed 177and on the cisco 178.Bd -literal 179 ip route Y mask tunnelX 180.Ed 181.Pp 182A similar setup can be used to create a link between two private networks 183(for example in the 192.168 subnet) over the Internet: 184.Bd -literal 185192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* 186 \\ / 187 \\ / 188 +----- the Internet ------+ 189.Ed 190Assuming router A has the (external) IP address A and the internal address 191192.168.1.1, while router B has external address B and internal address 192192.168.2.1, the following commands will configure the tunnel: 193.Pp 194On router A: 195.Bd -literal 196 # ifconfig greN create 197 # ifconfig greN 192.168.1.1 192.168.2.1 link1 198 # ifconfig greN tunnel A B 199 # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 200.Ed 201.Pp 202On router B: 203.Bd -literal 204 # ifconfig greN create 205 # ifconfig greN 192.168.2.1 192.168.1.1 link1 206 # ifconfig greN tunnel B A 207 # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 208.Ed 209.Pp 210Note that this is a safe situation where the link1 flag (as discussed in the 211.Sx BUGS 212section below) may (and probably should) be set. 213.Sh NOTES 214The MTU of 215.Sy gre Ns Ar X 216interfaces is set to 1476 by default to match the value used by Cisco routers. 217This may not be an optimal value, depending on the link between the two tunnel 218endpoints. It can be adjusted via 219.Xr ifconfig 8 . 220.Pp 221For correct operation, the 222.Nm 223device needs a route to the destination that is less specific than the 224one over the tunnel. 225(Basically, there needs to be a route to the decapsulating host that 226does not run over the tunnel, as this would be a loop.) 227If the addresses are ambiguous, doing the 228.Xr ifconfig 8 229.Li tunnel 230step before the 231.Xr ifconfig 8 232call to set the 233.Sy gre Ns Ar X 234IP addresses will help to find a route outside the tunnel. 235.Pp 236In order to tell 237.Xr ifconfig 8 238to actually mark the interface as up, the keyword 239.Dq up 240must be given last on its command line. 241.Pp 242The kernel must be set to forward datagrams by either option 243.Em GATEWAY 244in the kernel config file or by issuing the appropriate option to 245.Xr sysctl 8 . 246.Sh SEE ALSO 247.Xr atalk 4 , 248.Xr gif 4 , 249.Xr inet 4 , 250.Xr ip 4 , 251.Xr netintro 4 , 252.Xr options 4 , 253.Xr protocols 5 , 254.Xr ifconfig 8 , 255.Xr sysctl 8 256.Pp 257A description of GRE encapsulation can be found in RFC 1701 and RFC 1702. 258.Pp 259A description of MOBILE encapsulation can be found in RFC 2004. 260.Sh AUTHORS 261.An Heiko W.Rupp Aq hwr@pilhuhn.de 262.Sh BUGS 263The compute_route() code in if_gre.c toggles the last bit of the 264IP-address to provoke the search for a less specific route than the 265one directly over the tunnel to prevent loops. This is possibly not 266the best solution. 267.Pp 268To avoid the address munging described above, turn on the link1 flag 269on the 270.Xr ifconfig 8 271command line. 272This implies that the GRE packet destination and the ifconfig remote host 273are not the same IP addresses, and that the GRE destination does not route 274over the 275.Sy gre Ns Ar X 276interface itself. 277.Pp 278The GRE RFCs are not yet fully implemented (no GRE options). 279