1.\" $NetBSD: gre.4,v 1.28 2002/06/10 02:49:35 itojun Exp $ 2.\" $FreeBSD: src/share/man/man4/gre.4,v 1.1.2.1 2002/12/01 14:03:11 sobomax Exp $ 3.\" $DragonFly: src/share/man/man4/gre.4,v 1.3 2007/07/29 17:27:45 swildner Exp $ 4.\" 5.\" Copyright 1998 (c) The NetBSD Foundation, Inc. 6.\" All rights reserved. 7.\" 8.\" This code is derived from software contributed to The NetBSD Foundation 9.\" by Heiko W.Rupp <hwr@pilhuhn.de> 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 3. All advertising materials mentioning features or use of this software 20.\" must display the following acknowledgement: 21.\" This product includes software developed by the NetBSD 22.\" Foundation, Inc. and its contributors. 23.\" 4. Neither the name of the The NetBSD Foundation nor the names of its 24.\" contributors may be used to endorse or promote products derived 25.\" from this software without specific prior written permission. 26.\" 27.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 28.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 29.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 30.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 31.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 32.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 33.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 34.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 35.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 36.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 37.\" POSSIBILITY OF SUCH DAMAGE. 38.\" 39.Dd June 9, 2002 40.Dt GRE 4 41.Os 42.Sh NAME 43.Nm gre 44.Nd encapsulating network device 45.Sh SYNOPSIS 46.Cd pseudo-device gre 47.Sh DESCRIPTION 48The 49.Nm 50network interface pseudo device encapsulates datagrams 51into IP. These encapsulated datagrams are routed to a destination host, 52where they are decapsulated and further routed to their final destination. 53The 54.Dq tunnel 55appears to the inner datagrams as one hop. 56.Pp 57.Nm 58interfaces are dynamically created and destroyed with the 59.Xr ifconfig 8 60.Cm create 61and 62.Cm destroy 63subcommands. 64.Pp 65This driver currently supports the following modes of operation: 66.Bl -tag -width abc 67.It GRE encapsulation (IP protocol number 47) 68Encapsulated datagrams are 69prepended an outer datagram and a GRE header. The GRE header specifies 70the type of the encapsulated datagram and thus allows for tunneling other 71protocols than IP like e.g. AppleTalk. GRE mode is also the default tunnel 72mode on Cisco routers. This is also the default mode of operation of the 73.Sy gre Ns Ar X 74interfaces. 75.It MOBILE encapsulation (IP protocol number 55) 76Datagrams are 77encapsulated into IP, but with a shorter encapsulation. The original 78IP header is modified and the modifications are inserted between the 79so modified header and the original payload. Like 80.Xr gif 4 , 81only for IP in IP encapsulation. 82.El 83.Pp 84The 85.Sy gre Ns Ar X 86interfaces support 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. This is the source address 92set by or displayed by ifconfig for the 93.Sy gre Ns Ar X 94interface. 95.It GRESADDRD : 96Set the IP address of the remote tunnel end. This is the destination address 97set by or displayed by ifconfig for the 98.Sy gre Ns Ar X 99interface. 100.It GREGADDRS : 101Query the IP address that is set for the local tunnel end. This is the 102address the encapsulation header carries as local address (i.e. the real 103address of the tunnel start point.) 104.It GREGADDRD : 105Query the IP address that is set for the remote tunnel end. This is the 106address the encapsulated packets are sent to (i.e. the real address of 107the remote tunnel endpoint.) 108.It GRESPROTO : 109Set the operation mode to the specified IP protocol value. The 110protocol is passed to the interface in (struct ifreq)-\*[Gt]ifr_flags. 111The operation mode can also be given as 112.Bl -tag -width link0xxx 113.It link0 114IPPROTO_GRE 115.It -link0 116IPPROTO_MOBILE 117.El 118.Pp 119to 120.Xr ifconfig 8 . 121.Pp 122The link1 flag is not used to choose encapsulation, but to modify the 123internal route search for the remote tunnel endpoint, see the 124.Sx BUGS 125section below. 126.It GREGPROTO : 127Query operation mode. 128.El 129.Pp 130Note that the IP addresses of the tunnel endpoints may be the same as the 131ones defined with 132.Xr ifconfig 8 133for the interface (as if IP is encapsulated), but need not be, as e.g. when 134encapsulating AppleTalk. 135.Sh EXAMPLES 136Configuration example: 137.Bd -literal 138Host X-- Host A ----------------tunnel---------- cisco D------Host E 139 \\ | 140 \\ / 141 +------Host B----------Host C----------+ 142.Ed 143On host A 144.Ns ( Nx ) : 145.Bd -literal 146 # route add default B 147 # ifconfig greN create 148 # ifconfig greN A D netmask 0xffffffff linkX up 149 # ifconfig greN tunnel A D 150 # route add E D 151.Ed 152On Host D (Cisco): 153.Bd -literal 154 Interface TunnelX 155 ip unnumbered D ! e.g. address from Ethernet interface 156 tunnel source D ! e.g. address from Ethernet interface 157 tunnel destination A 158 ip route C \*[Lt]some interface and mask\*[Gt] 159 ip route A mask C 160 ip route X mask tunnelX 161.Ed 162OR 163On Host D 164.Ns ( Nx ) : 165.Bd -literal 166 # route add default C 167 # ifconfig greN create 168 # ifconfig greN D A 169 # ifconfig tunnel greN D A 170.Ed 171.Pp 172If all goes well, you should see packets flowing ;-) 173.Pp 174If you want to reach Host A over the tunnel (from Host D (Cisco)), then 175you have to have an alias on Host A for e.g. the Ethernet interface like: 176.Bd -literal 177 ifconfig \*[Lt]etherif\*[Gt] alias Y 178.Ed 179and on the cisco 180.Bd -literal 181 ip route Y mask tunnelX 182.Ed 183.Pp 184A similar setup can be used to create a link between two private networks 185(for example in the 192.168 subnet) over the Internet: 186.Bd -literal 187192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* 188 \\ / 189 \\ / 190 +----- the Internet ------+ 191.Ed 192Assuming router A has the (external) IP address A and the internal address 193192.168.1.1, while router B has external address B and internal address 194192.168.2.1, the following commands will configure the tunnel: 195.Pp 196On router A: 197.Bd -literal 198 # ifconfig greN create 199 # ifconfig greN 192.168.1.1 192.168.2.1 link1 200 # ifconfig greN tunnel A B 201 # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 202.Ed 203.Pp 204On router B: 205.Bd -literal 206 # ifconfig greN create 207 # ifconfig greN 192.168.2.1 192.168.1.1 link1 208 # ifconfig greN tunnel B A 209 # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 210.Ed 211.Pp 212Note that this is a safe situation where the link1 flag (as discussed in the 213.Sx BUGS 214section below) may (and probably should) be set. 215.Sh NOTES 216The MTU of 217.Sy gre Ns Ar X 218interfaces is set to 1476 by default to match the value used by Cisco routers. 219This may not be an optimal value, depending on the link between the two tunnel 220endpoints. It can be adjusted via 221.Xr ifconfig 8 . 222.Pp 223For correct operation, the 224.Nm 225device needs a route to the destination that is less specific than the 226one over the tunnel. 227(Basically, there needs to be a route to the decapsulating host that 228does not run over the tunnel, as this would be a loop.) 229If the addresses are ambiguous, doing the 230.Xr ifconfig 8 231.Li tunnel 232step before the 233.Xr ifconfig 8 234call to set the 235.Sy gre Ns Ar X 236IP addresses will help to find a route outside the tunnel. 237.Pp 238In order to tell 239.Xr ifconfig 8 240to actually mark the interface as up, the keyword 241.Dq up 242must be given last on its command line. 243.Pp 244The kernel must be set to forward datagrams by either option 245.Em GATEWAY 246in the kernel config file or by issuing the appropriate option to 247.Xr sysctl 8 . 248.Sh SEE ALSO 249.Xr atalk 4 , 250.Xr gif 4 , 251.Xr inet 4 , 252.Xr ip 4 , 253.Xr netintro 4 , 254.Xr options 4 , 255.Xr protocols 5 , 256.Xr ifconfig 8 , 257.Xr sysctl 8 258.Pp 259A description of GRE encapsulation can be found in RFC 1701 and RFC 1702. 260.Pp 261A description of MOBILE encapsulation can be found in RFC 2004. 262.Sh AUTHORS 263.An Heiko W.Rupp Aq hwr@pilhuhn.de 264.Sh BUGS 265The compute_route() code in if_gre.c toggles the last bit of the 266IP-address to provoke the search for a less specific route than the 267one directly over the tunnel to prevent loops. This is possibly not 268the best solution. 269.Pp 270To avoid the address munging described above, turn on the link1 flag 271on the 272.Xr ifconfig 8 273command line. 274This implies that the GRE packet destination and the ifconfig remote host 275are not the same IP addresses, and that the GRE destination does not route 276over the 277.Sy gre Ns Ar X 278interface itself. 279.Pp 280The GRE RFCs are not yet fully implemented (no GRE options). 281