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.\" $FreeBSD: src/share/man/man4/gre.4,v 1.7 2006/10/19 07:41:47 danger Exp $ 38.\" 39.Dd November 11, 2007 40.Dt GRE 4 41.Os 42.Sh NAME 43.Nm gre 44.Nd encapsulating network device 45.Sh SYNOPSIS 46To compile the 47.Ns Nm 48device into the kernel, place the following line in the kernel 49configuration file: 50.Bd -ragged -offset indent 51.Cd "pseudo-device gre" 52.Ed 53.Pp 54Alternatively, to load the 55.Ns Nm 56device as a module at boot time, place the following line in 57.Xr loader.conf 5 : 58.Bd -literal -offset indent 59if_gre_load="YES" 60.Ed 61.Sh DESCRIPTION 62The 63.Nm 64network interface pseudo device encapsulates datagrams 65into IP. 66These encapsulated datagrams are routed to a destination host, 67where they are decapsulated and further routed to their final destination. 68The 69.Dq tunnel 70appears to the inner datagrams as one hop. 71.Pp 72.Nm 73interfaces are dynamically created and destroyed with the 74.Xr ifconfig 8 75.Cm create 76and 77.Cm destroy 78subcommands. 79.Pp 80This driver currently supports the following modes of operation: 81.Bl -tag -width indent 82.It "GRE encapsulation (IP protocol number 47)" 83Encapsulated datagrams are 84prepended an outer datagram and a GRE header. 85The GRE header specifies 86the type of the encapsulated datagram and thus allows for tunneling other 87protocols than IP. 88GRE mode is also the default tunnel mode on Cisco routers. 89This is also the default mode of operation of the 90.Nm 91interfaces. 92.\"As part of the GRE mode, 93.\".Nm 94.\"also supports Cisco WCCP protocol, both version 1 and version 2. 95.\"Since there is no reliable way to distinguish between WCCP versions, it 96.\"should be configured manually using the 97.\".Cm link2 98.\"flag. 99.\"If the 100.\".Cm link2 101.\"flag is not set (default), then WCCP version 1 is selected. 102.It "MOBILE encapsulation (IP protocol number 55)" 103Datagrams are 104encapsulated into IP, but with a shorter encapsulation. 105The original 106IP header is modified and the modifications are inserted between the 107so modified header and the original payload. 108Like 109.Xr gif 4 , 110only for IP-in-IP encapsulation. 111.El 112.Pp 113The 114.Nm 115interfaces support a number of 116.Xr ioctl 2 Ns s , 117such as: 118.Bl -tag -width ".Dv GRESADDRS" 119.It Dv GRESADDRS 120Set the IP address of the local tunnel end. 121This is the source address 122set by or displayed by 123.Xr ifconfig 8 124for the 125.Nm 126interface. 127.It Dv GRESADDRD 128Set the IP address of the remote tunnel end. 129This is the destination address 130set by or displayed by 131.Xr ifconfig 8 132for the 133.Nm 134interface. 135.It Dv GREGADDRS 136Query the IP address that is set for the local tunnel end. 137This is the 138address the encapsulation header carries as local address (i.e., the real 139address of the tunnel start point). 140.It Dv GREGADDRD 141Query the IP address that is set for the remote tunnel end. 142This is the 143address the encapsulated packets are sent to (i.e., the real address of 144the remote tunnel endpoint). 145.It Dv GRESPROTO 146Set the operation mode to the specified IP protocol value. 147The 148protocol is passed to the interface in 149.Po Vt "struct ifreq" Pc Ns Li -> Ns Va ifr_flags . 150The operation mode can also be given as 151.Pp 152.Bl -tag -width ".Cm -link0" -compact 153.It Cm link0 154.Dv IPPROTO_GRE 155.It Cm -link0 156.Dv IPPROTO_MOBILE 157.El 158.Pp 159to 160.Xr ifconfig 8 . 161.Pp 162The 163.Cm link1 164flag is not used to choose encapsulation, but to modify the 165internal route search for the remote tunnel endpoint, see the 166.Sx BUGS 167section below. 168.It Dv GREGPROTO 169Query operation mode. 170.El 171.Pp 172Note that the IP addresses of the tunnel endpoints may be the same as the 173ones defined with 174.Xr ifconfig 8 175for the interface (as if IP is encapsulated), but need not be. 176.Sh EXAMPLES 177Configuration example: 178.Bd -literal 179Host X-- Host A ----------------tunnel---------- Cisco D------Host E 180 \\ | 181 \\ / 182 +------Host B----------Host C----------+ 183.Ed 184.Pp 185On host A 186.Pq Dx : 187.Bd -literal -offset indent 188route add default B 189ifconfig greN create 190ifconfig greN A D netmask 0xffffffff linkX up 191ifconfig greN tunnel A D 192route add E D 193.Ed 194.Pp 195On Host D (Cisco): 196.Bd -literal -offset indent 197Interface TunnelX 198 ip unnumbered D ! e.g. address from Ethernet interface 199 tunnel source D ! e.g. address from Ethernet interface 200 tunnel destination A 201ip route C <some interface and mask> 202ip route A mask C 203ip route X mask tunnelX 204.Ed 205.Pp 206OR 207.Pp 208On Host D 209.Pq Dx : 210.Bd -literal -offset indent 211route add default C 212ifconfig greN create 213ifconfig greN D A 214ifconfig greN tunnel D A 215.Ed 216.Pp 217If all goes well, you should see packets flowing ;-) 218.Pp 219If you want to reach Host A over the tunnel (from Host D (Cisco)), then 220you have to have an alias on Host A for e.g.\& the Ethernet interface like: 221.Pp 222.Dl "ifconfig <etherif> alias Y" 223.Pp 224and on the Cisco: 225.Pp 226.Dl "ip route Y mask tunnelX" 227.Pp 228A similar setup can be used to create a link between two private networks 229(for example in the 192.168 subnet) over the Internet: 230.Bd -literal 231192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* 232 \\ / 233 \\ / 234 +------ the Internet ------+ 235.Ed 236.Pp 237Assuming router A has the (external) IP address A and the internal address 238192.168.1.1, while router B has external address B and internal address 239192.168.2.1, the following commands will configure the tunnel: 240.Pp 241On router A: 242.Bd -literal -offset indent 243ifconfig greN create 244ifconfig greN 192.168.1.1 192.168.2.1 link1 245ifconfig greN tunnel A B 246route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 247.Ed 248.Pp 249On router B: 250.Bd -literal -offset indent 251ifconfig greN create 252ifconfig greN 192.168.2.1 192.168.1.1 link1 253ifconfig greN tunnel B A 254route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 255.Ed 256.Pp 257Note that this is a safe situation where the 258.Cm link1 259flag (as discussed in the 260.Sx BUGS 261section below) may (and probably should) be set. 262.Sh NOTES 263The MTU of 264.Nm 265interfaces is set to 1476 by default, to match the value used by Cisco routers. 266This may not be an optimal value, depending on the link between the two tunnel 267endpoints. 268It can be adjusted via 269.Xr ifconfig 8 . 270.Pp 271For correct operation, the 272.Nm 273device needs a route to the destination that is less specific than the 274one over the tunnel. 275(Basically, there needs to be a route to the decapsulating host that 276does not run over the tunnel, as this would be a loop.) 277If the addresses are ambiguous, doing the 278.Nm ifconfig Cm tunnel 279step before the 280.Xr ifconfig 8 281call to set the 282.Nm 283IP addresses will help to find a route outside the tunnel. 284.Pp 285In order to tell 286.Xr ifconfig 8 287to actually mark the interface as 288.Dq up , 289the keyword 290.Cm up 291must be given last on its command line. 292.Pp 293The kernel must be set to forward datagrams by setting the 294.Va net.inet.ip.forwarding 295.Xr sysctl 8 296variable to non-zero. 297.Sh SEE ALSO 298.Xr gif 4 , 299.Xr inet 4 , 300.Xr ip 4 , 301.Xr netintro 4 , 302.Xr protocols 5 , 303.Xr ifconfig 8 , 304.Xr sysctl 8 305.Pp 306A description of GRE encapsulation can be found in RFC 1701 and RFC 1702. 307.Pp 308A description of MOBILE encapsulation can be found in RFC 2004. 309.Sh AUTHORS 310.An Heiko W.Rupp Aq hwr@pilhuhn.de 311.Sh BUGS 312The 313.Fn gre_compute_route 314code in 315.Pa if_gre.c 316toggles 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 322.Cm link1 323flag on the 324.Xr ifconfig 8 325command line. 326This implies that the GRE packet destination and the ifconfig remote host 327are not the same IP addresses, and that the GRE destination does not route 328over the 329.Nm 330interface itself. 331.Pp 332The GRE RFCs are not yet fully implemented (no GRE options). 333