1.\" $NetBSD: gre.4,v 1.32 2006/08/31 17:46:16 dyoung 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 August 30, 2006 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 GRE in UDP encapsulation 76Encapsulated datagrams are prepended a GRE header, and then they 77are sent over a UDP socket. 78Userland may create the socket and 79.Dq delegate 80it to the kernel using the 81.Dv GRESSOCK 82.Xr ioctl 2 . 83If userland does not supply a socket, then the kernel will create 84one using the addresses and ports supplied by 85.Xr ioctl 2 Ns s 86.Dv SIOCSLIFPHYADDR , 87.Dv GRESADDRD , 88and/or 89.Dv GRESADDRS . 90.It MOBILE encapsulation (IP protocol number 55) 91Datagrams are 92encapsulated into IP, but with a shorter encapsulation. 93The original IP header is modified and the modifications are inserted 94between the so modified header and the original payload. 95Like 96.Xr gif 4 , 97only for IP in IP encapsulation. 98.El 99.Pp 100The 101.Sy gre Ns Ar X 102interfaces support a number of 103.Xr ioctl 2 Ns s , 104such as: 105.Bl -tag -width aaa 106.It GRESADDRS : 107Set the IP address of the local tunnel end. 108This is the source address set by or displayed by ifconfig for the 109.Sy gre Ns Ar X 110interface. 111.It GRESADDRD : 112Set the IP address of the remote tunnel end. 113This is the destination address set by or displayed by ifconfig for the 114.Sy gre Ns Ar X 115interface. 116.It GREGADDRS : 117Query the IP address that is set for the local tunnel end. 118This is the address the encapsulation header carries as local 119address (i.e. the real address of the tunnel start point.) 120.It GREGADDRD : 121Query the IP address that is set for the remote tunnel end. 122This is the address the encapsulated packets are sent to (i.e. the 123real address of the remote tunnel endpoint.) 124.It GRESPROTO : 125Set the operation mode to the specified IP protocol value. 126The protocol is passed to the interface in (struct ifreq)-\*[Gt]ifr_flags. 127The operation mode can also be given as 128.Bl -tag -width link0xxx 129.It link0 link2 130IPPROTO_UDP 131.It link0 -link2 132IPPROTO_GRE 133.It -link0 -link2 134IPPROTO_MOBILE 135.El 136.Pp 137to 138.Xr ifconfig 8 . 139.Pp 140The link1 flag is not used to choose encapsulation, but to modify the 141internal route search for the remote tunnel endpoint, see the 142.Sx BUGS 143section below. 144.It GREGPROTO : 145Query operation mode. 146.It GRESSOCK : 147Delegate a socket from userland to a tunnel interface in UDP 148encapsulation mode. 149The file descriptor for the socket is passed in 150(struct ifreq)-\*[Gt]ifr_value. 151.El 152.Pp 153Note that the IP addresses of the tunnel endpoints may be the same as the 154ones defined with 155.Xr ifconfig 8 156for the interface (as if IP is encapsulated), but need not be, as e.g. when 157encapsulating AppleTalk. 158.Sh EXAMPLES 159Configuration example: 160.Bd -literal 161Host X-- Host A ----------------tunnel---------- cisco D------Host E 162 \\ | 163 \\ / 164 +------Host B----------Host C----------+ 165.Ed 166On host A 167.Pq Nx : 168.Bd -literal 169 # route add default B 170 # ifconfig greN create 171 # ifconfig greN A D netmask 0xffffffff linkX up 172 # ifconfig greN tunnel A D 173 # route add E D 174.Ed 175On Host D (Cisco): 176.Bd -literal 177 Interface TunnelX 178 ip unnumbered D ! e.g. address from Ethernet interface 179 tunnel source D ! e.g. address from Ethernet interface 180 tunnel destination A 181 ip route C \*[Lt]some interface and mask\*[Gt] 182 ip route A mask C 183 ip route X mask tunnelX 184.Ed 185OR 186On Host D 187.Pq Nx : 188.Bd -literal 189 # route add default C 190 # ifconfig greN create 191 # ifconfig greN D A 192 # ifconfig tunnel greN D A 193.Ed 194.Pp 195If all goes well, you should see packets flowing ;-) 196.Pp 197If you want to reach Host A over the tunnel (from Host D (Cisco)), then 198you have to have an alias on Host A for e.g. the Ethernet interface like: 199.Bd -literal 200 ifconfig \*[Lt]etherif\*[Gt] alias Y 201.Ed 202and on the cisco 203.Bd -literal 204 ip route Y mask tunnelX 205.Ed 206.Pp 207A similar setup can be used to create a link between two private networks 208(for example in the 192.168 subnet) over the Internet: 209.Bd -literal 210192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* 211 \\ / 212 \\ / 213 +----- the Internet ------+ 214.Ed 215Assuming router A has the (external) IP address A and the internal address 216192.168.1.1, while router B has external address B and internal address 217192.168.2.1, the following commands will configure the tunnel: 218.Pp 219On router A: 220.Bd -literal 221 # ifconfig greN create 222 # ifconfig greN 192.168.1.1 192.168.2.1 link1 223 # ifconfig greN tunnel A B 224 # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 225.Ed 226.Pp 227On router B: 228.Bd -literal 229 # ifconfig greN create 230 # ifconfig greN 192.168.2.1 192.168.1.1 link1 231 # ifconfig greN tunnel B A 232 # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 233.Ed 234.Pp 235Note that this is a safe situation where the link1 flag (as discussed in the 236.Sx BUGS 237section below) may (and probably should) be set. 238.Pp 239To setup the same tunnel as above, but using GRE in UDP encapsulation 240instead of GRE encapsulation, set flags 241.Ar link0 242and 243.Ar link2 , 244and specify source and destination UDP ports. 245.Pp 246On router A: 247.Bd -literal 248 # ifconfig greN create 249 # ifconfig greN link0 link2 250 # ifconfig greN 192.168.1.1 192.168.2.1 251 # ifconfig greN tunnel A,port-A B,port-B 252 # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 253.Ed 254.Pp 255On router B: 256.Bd -literal 257 # ifconfig greN create 258 # ifconfig greN link0 link2 259 # ifconfig greN 192.168.2.1 192.168.1.1 260 # ifconfig greN tunnel B,port-B A,port-A 261 # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 262.Pp 263Along these lines, you can use GRE tunnels to interconnect two IPv6 264networks over an IPv4 infrastructure, or to hook up to the IPv6 internet 265via an IPv4 tunnel to a Cisco router. 266.Bd -literal 2672001:db8:1::/64 -- NetBSD A -----tunnel----- Cisco B --- IPv6 Internet 268 \\ / 269 \\ / 270 +----- the Internet ------+ 271 272.Ed 273The example will use the following addressing: 274.Nx 275A has the 276IPv4 address A and the IPv6 address 2001:db8:1::1 (connects to internal 277network 2001:db8:1::/64). 278Cisco B has external IPv4 address B. 279All the IPv6 internet world is behind B, so A wants to route 0::0/0 280(the IPv6 default route) into the tunnel. 281The GRE tunnel will use a transit network: 2001:db8:ffff::1/64 on 282the 283,Nx 284side, and ::2/64 on the Cisco side. 285Then the following commands will configure the tunnel: 286.Pp 287On router A 288.Pq Nx : 289.Bd -literal 290 # ifconfig greN create 291 # ifconfig greN inet6 2001:db8:ffff::1/64 292 # ifconfig greN tunnel A B 293 # route add -inet6 2001:db8:ffff::/64 2001:db8:ffff::2 -ifp greN 294 # route add -inet6 0::0/0 2001:db8:ffff::2 -ifp greN 295.Ed 296.Pp 297On router B (Cisco): 298.Bd -literal 299 Interface TunnelX 300 tunnel mode gre ip 301 ipv6 address 2001:db8:ffff::2/64 ! transfer network 302 tunnel source B ! e.g. address from LAN interface 303 tunnel destination A ! where the tunnel is connected to 304 ipv6 route 2001:db8::/64 TunnelX ! route this network through tunnel 305.Ed 306.Pp 307Note that this is a safe situation where the link1 flag (as discussed in the 308.Sx BUGS 309section below) may be set. 310.Ed 311.Sh NOTES 312The MTU of 313.Sy gre Ns Ar X 314interfaces is set to 1476 by default to match the value used by Cisco routers. 315This may not be an optimal value, depending on the link between the two tunnel 316endpoints. 317It can be adjusted via 318.Xr ifconfig 8 . 319.Pp 320For correct operation, the 321.Nm 322device needs a route to the destination that is less specific than the 323one over the tunnel. 324(Basically, there needs to be a route to the decapsulating host that 325does not run over the tunnel, as this would be a loop. 326This is not relevant for IPv6-over-IPv4 tunnels, of course.) 327If the addresses are ambiguous, doing the 328.Xr ifconfig 8 329.Li tunnel 330step before the 331.Xr ifconfig 8 332call to set the 333.Sy gre Ns Ar X 334IP addresses will help to find a route outside the tunnel. 335.Pp 336In order to tell 337.Xr ifconfig 8 338to actually mark the interface as up, the keyword 339.Dq up 340must be given last on its command line. 341.Pp 342The kernel must be set to forward datagrams by either option 343.Em GATEWAY 344in the kernel config file or by issuing the appropriate option to 345.Xr sysctl 8 . 346.Sh SEE ALSO 347.Xr atalk 4 , 348.Xr gif 4 , 349.Xr inet 4 , 350.Xr ip 4 , 351.Xr netintro 4 , 352.Xr options 4 , 353.Xr protocols 5 , 354.Xr ifconfig 8 , 355.Xr sysctl 8 356.Pp 357A description of GRE encapsulation can be found in RFC 1701 and RFC 1702. 358.Pp 359A description of MOBILE encapsulation can be found in RFC 2004. 360.Sh AUTHORS 361.An Heiko W.Rupp Aq hwr@pilhuhn.de 362.An David Young Aq dyoung@NetBSD.org 363.Pq GRE in UDP encapsulation, bug fixes 364.Sh BUGS 365The compute_route() code in if_gre.c toggles the last bit of the 366IP-address to provoke the search for a less specific route than the 367one directly over the tunnel to prevent loops. 368This is possibly not the best solution. 369.Pp 370To avoid the address munging described above, turn on the link1 flag 371on the 372.Xr ifconfig 8 373command line. 374This implies that the GRE packet destination and the ifconfig remote host 375are not the same IP addresses, and that the GRE destination does not route 376over the 377.Sy gre Ns Ar X 378interface itself. 379.Pp 380The GRE RFCs are not yet fully implemented (no GRE options). 381.Pp 382The MOBILE encapsulation appears to have been broken since 383it was first added to 384.Nx , 385until August 2006. 386It is known to interoperate with another 387.Xr gre 4 388in MOBILE mode, however, it has not been tested for interoperability 389with any other implementation of RFC 2004. 390.Pp 391The 392.Nx 393base system does not 394.Pq yet 395contain a daemon for automatically establishing a UDP tunnel between 396a host behind a NAT router and a host on the Internet. 397