1.\" $NetBSD: gre.4,v 1.45 2017/07/03 21:30:58 wiz Exp $ 2.\" 3.\" Copyright (c) 1998 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 4, 2009 31.Dt GRE 4 32.Os 33.Sh NAME 34.Nm gre 35.Nd encapsulating network device 36.Sh SYNOPSIS 37.Cd pseudo-device gre 38.Sh DESCRIPTION 39The 40.Nm gre 41network interface pseudo device encapsulates datagrams 42into IP. 43These encapsulated datagrams are routed to a destination host, 44where they are decapsulated and further routed to their final destination. 45The 46.Dq tunnel 47appears to the inner datagrams as one hop. 48.Pp 49.Nm 50interfaces are dynamically created and destroyed with the 51.Xr ifconfig 8 52.Cm create 53and 54.Cm destroy 55subcommands. 56.Pp 57This driver currently supports the following modes of operation: 58.Bl -tag -width abc 59.It GRE encapsulation (IP protocol number 47) 60Encapsulated datagrams are 61prepended an outer datagram and a GRE header. 62The GRE header specifies the type of the encapsulated datagram and 63thus allows for tunneling other protocols than IP like e.g. AppleTalk. 64GRE mode is also the default tunnel mode on Cisco routers. 65This is also the default mode of operation of the 66.Sy gre Ns Ar X 67interfaces. 68.It GRE in UDP encapsulation 69Encapsulated datagrams are prepended a GRE header, and then they 70are sent over a UDP socket. 71Userland may create the socket and 72.Dq delegate 73it to the kernel using the 74.Dv GRESSOCK 75.Xr ioctl 2 . 76If userland does not supply a socket, then the kernel will create 77one using the addresses and ports supplied by 78.Xr ioctl 2 Ns s 79.Dv SIOCSLIFPHYADDR , 80.Dv GRESADDRD , 81and/or 82.Dv GRESADDRS . 83.It MOBILE encapsulation (IP protocol number 55) 84Datagrams are 85encapsulated into IP, but with a shorter encapsulation. 86The original IP header is modified and the modifications are inserted 87between the so modified header and the original payload. 88Like 89.Xr gif 4 , 90only for IP in IP encapsulation. 91.El 92.Pp 93The 94.Sy gre Ns Ar X 95interfaces support a number of 96.Xr ioctl 2 Ns s , 97such as: 98.Bl -tag -width aaa 99.It GRESADDRS : 100Set the IP address of the local tunnel end. 101This is the source address set by or displayed by ifconfig for the 102.Sy gre Ns Ar X 103interface. 104.It GRESADDRD : 105Set the IP address of the remote tunnel end. 106This is the destination address set by or displayed by ifconfig for the 107.Sy gre Ns Ar X 108interface. 109.It GREGADDRS : 110Query the IP address that is set for the local tunnel end. 111This is the address the encapsulation header carries as local 112address (i.e. the real address of the tunnel start point.) 113.It GREGADDRD : 114Query the IP address that is set for the remote tunnel end. 115This is the address the encapsulated packets are sent to (i.e. the 116real address of the remote tunnel endpoint.) 117.It GRESPROTO : 118Set the operation mode to the specified IP protocol value. 119The protocol is passed to the interface in (struct ifreq)->ifr_flags. 120The operation mode can also be given as 121.Bl -tag -width link0xxx 122.It link0 link2 123IPPROTO_UDP 124.It link0 -link2 125IPPROTO_GRE 126.It -link0 -link2 127IPPROTO_MOBILE 128.El 129.Pp 130to 131.Xr ifconfig 8 . 132.It GREGPROTO : 133Query operation mode. 134.It GRESSOCK : 135Delegate a socket from userland to a tunnel interface in UDP 136encapsulation mode. 137The file descriptor for the socket is passed in 138(struct ifreq)->ifr_value. 139.El 140.Pp 141Note that the IP addresses of the tunnel endpoints may be the same as the 142ones defined with 143.Xr ifconfig 8 144for the interface (as if IP is encapsulated), but need not be, as e.g. when 145encapsulating AppleTalk. 146.Sh EXAMPLES 147.Ss Example 1: Basic GRE tunneling 148Configuration example: 149.Bd -literal 150Host X-- Router A --------------tunnel---------- Router D ----Host E 151 | | 152 \\ / 153 +----- Router B ----- Router C --------+ 154.Ed 155.Pp 156On Router A 157.Pq Nx : 158.Bd -literal 159 # route add default B 160 # ifconfig greN create 161 # ifconfig greN A D netmask 0xffffffff linkX up 162 # ifconfig greN tunnel A D 163 # route add E D 164.Ed 165.Pp 166On Router D (Cisco): 167.Bd -literal 168 Interface TunnelX 169 ip unnumbered D ! e.g. address from Ethernet interface 170 tunnel source D ! e.g. address from Ethernet interface 171 tunnel destination A 172 ip route C <some interface and mask> 173 ip route A mask C 174 ip route X mask tunnelX 175.Ed 176.Pp 177or on Router D 178.Pq Nx : 179.Bd -literal 180 # route add default C 181 # ifconfig greN create 182 # ifconfig greN D A 183 # ifconfig tunnel greN D A 184.Ed 185.Pp 186If all goes well, you should see packets flowing ;-) 187.Pp 188If you want to reach Router A over the tunnel (from Router D (Cisco)), then 189you have to have an alias on Router A for e.g. the Ethernet interface like: 190.Bd -literal 191 ifconfig <etherif> alias Y 192.Ed 193.Pp 194and on the Cisco 195.Bd -literal 196 ip route Y mask tunnelX 197.Ed 198.Ss Example 2: Linking private subnets 199A similar setup can be used to create a link between two private networks 200(for example in the 192.168 subnet) over the Internet: 201.Bd -literal 202192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* 203 \\ / 204 \\ / 205 +----- the Internet ------+ 206.Ed 207.Pp 208Assuming Router A has the (external) IP address A and the internal address 209192.168.1.1, while Router B has external address B and internal address 210192.168.2.1, the following commands will configure the tunnel: 211.Pp 212On Router A: 213.Bd -literal 214 # ifconfig greN create 215 # ifconfig greN 192.168.1.1 192.168.2.1 216 # ifconfig greN tunnel A B 217 # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 218.Ed 219.Pp 220On Router B: 221.Bd -literal 222 # ifconfig greN create 223 # ifconfig greN 192.168.2.1 192.168.1.1 224 # ifconfig greN tunnel B A 225 # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 226.Ed 227.Ss Example 3: Encapsulating GRE in UDP 228To setup the same tunnel as above, but using GRE in UDP encapsulation 229instead of GRE encapsulation, set flags 230.Ar link0 231and 232.Ar link2 , 233and specify source and destination UDP ports. 234.Pp 235On Router A: 236.Bd -literal 237 # ifconfig greN create 238 # ifconfig greN link0 link2 239 # ifconfig greN 192.168.1.1 192.168.2.1 240 # ifconfig greN tunnel A,port-A B,port-B 241 # route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 242.Ed 243.Pp 244On Router B: 245.Bd -literal 246 # ifconfig greN create 247 # ifconfig greN link0 link2 248 # ifconfig greN 192.168.2.1 192.168.1.1 249 # ifconfig greN tunnel B,port-B A,port-A 250 # route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 251.Ed 252.Ss Example 4: Realizing IPv6 connectivity 253Along these lines, you can use GRE tunnels to interconnect two IPv6 254networks over an IPv4 infrastructure, or to hook up to the IPv6 internet 255via an IPv4 tunnel to a Cisco router. 256.Bd -literal 2572001:db8:1::/64 -- NetBSD A ---- Tunnel ---- Cisco B --- IPv6 Internet 258 \\ / 259 \\ / 260 +------ the Internet ------+ 261.Ed 262.Pp 263The example will use the following addressing: 264.Bl -hang 265.It Nx 266A has the IPv4 address A and the IPv6 address 2001:db8:1::1 (connects 267to internal network 2001:db8:1::/64). 268.It Cisco B 269has external IPv4 address B. 270.It All the IPv6 internet world 271is behind B, so A wants to route 0::0/0 272(the IPv6 default route) into the tunnel. 273.It The GRE tunnel 274will use a transit network: 2001:db8:ffff::1/64 on 275the 276.Nx 277side, and ::2/64 on the Cisco side. 278.El 279.Pp 280Then the following commands will configure the tunnel: 281.Pp 282On Router A 283.Pq Nx : 284.Bd -literal 285 # ifconfig greN create 286 # ifconfig greN inet6 2001:db8:ffff::1/64 287 # ifconfig greN tunnel A B 288 # route add -inet6 2001:db8:ffff::/64 2001:db8:ffff::2 -ifp greN 289 # route add -inet6 0::0/0 2001:db8:ffff::2 -ifp greN 290.Ed 291.Pp 292On Router B (Cisco): 293.Bd -literal 294 Interface TunnelX 295 tunnel mode gre ip 296 ipv6 address 2001:db8:ffff::2/64 ! transfer network 297 tunnel source B ! e.g. address from LAN interface 298 tunnel destination A ! where the tunnel is connected to 299 ipv6 route 2001:db8::/64 TunnelX ! route this network through tunnel 300.Ed 301.Sh NOTES 302The MTU of 303.Sy gre Ns Ar X 304interfaces is set to 1476 by default to match the value used by Cisco routers. 305This may not be an optimal value, depending on the link between the two tunnel 306endpoints. 307It can be adjusted via 308.Xr ifconfig 8 . 309.Pp 310There needs to be a route to the decapsulating host that does not 311run over the tunnel, as this would be a loop. 312(This is not relevant for IPv6-over-IPv4 tunnels, of course.) 313.Pp 314In order to tell 315.Xr ifconfig 8 316to actually mark the interface as up, the keyword 317.Dq up 318must be given last on its command line. 319.Pp 320The kernel must be set to forward datagrams by either option 321.Em GATEWAY 322in the kernel config file or by issuing the appropriate option to 323.Xr sysctl 8 . 324.Sh SEE ALSO 325.Xr atalk 4 , 326.Xr gif 4 , 327.Xr inet 4 , 328.Xr ip 4 , 329.Xr netintro 4 , 330.Xr options 4 , 331.Xr protocols 5 , 332.Xr ifconfig 8 , 333.Xr sysctl 8 334.Pp 335A description of GRE encapsulation can be found in RFC 1701 and RFC 1702. 336.Pp 337A description of MOBILE encapsulation can be found in RFC 2004. 338.Sh AUTHORS 339.An Heiko W.Rupp Aq Mt hwr@pilhuhn.de 340.An David Young Aq Mt dyoung@NetBSD.org 341.Pq GRE in UDP encapsulation, bug fixes 342.Sh BUGS 343The GRE RFCs are not yet fully implemented (no GRE options). 344.Pp 345The MOBILE encapsulation appears to have been broken since 346it was first added to 347.Nx , 348until August 2006. 349It is known to interoperate with another 350.Nm 351in MOBILE mode, however, it has not been tested for interoperability 352with any other implementation of RFC 2004. 353.Pp 354The 355.Nx 356base system does not 357.Pq yet 358contain a daemon for automatically establishing a UDP tunnel between 359a host behind a NAT router and a host on the Internet. 360