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