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.\" 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.\" $FreeBSD$ 31.\" 32.Dd November 7, 2014 33.Dt GRE 4 34.Os 35.Sh NAME 36.Nm gre 37.Nd encapsulating network device 38.Sh SYNOPSIS 39To compile the 40driver into the kernel, place the following line in the kernel 41configuration file: 42.Bd -ragged -offset indent 43.Cd "device gre" 44.Ed 45.Pp 46Alternatively, to load the 47driver as a module at boot time, place the following line in 48.Xr loader.conf 5 : 49.Bd -literal -offset indent 50if_gre_load="YES" 51.Ed 52.Sh DESCRIPTION 53The 54.Nm 55network interface pseudo device encapsulates datagrams 56into IP. 57These encapsulated datagrams are routed to a destination host, 58where they are decapsulated and further routed to their final destination. 59The 60.Dq tunnel 61appears to the inner datagrams as one hop. 62.Pp 63.Nm 64interfaces are dynamically created and destroyed with the 65.Xr ifconfig 8 66.Cm create 67and 68.Cm destroy 69subcommands. 70.Pp 71This driver corresponds to RFC 2784. 72Encapsulated datagrams are prepended an outer datagram and a GRE header. 73The GRE header specifies 74the type of the encapsulated datagram and thus allows for tunneling other 75protocols than IP. 76GRE mode is also the default tunnel mode on Cisco routers. 77.Nm 78also supports Cisco WCCP protocol, both version 1 and version 2. 79.Pp 80The 81.Nm 82interfaces support a number of additional parameters to the 83.Xr ifconfig 8 : 84.Bl -tag -width "enable_csum" 85.It Ar grekey 86Set the GRE key used for outgoing packets. 87A value of 0 disables the key option. 88.It Ar enable_csum 89Enables checksum calculation for outgoing packets. 90.It Ar enable_seq 91Enables use of sequence number field in the GRE header for outgoing packets. 92.El 93.Sh EXAMPLES 94.Pp 95.Bd -literal 96192.168.1.* --- Router A -------tunnel-------- Router B --- 192.168.2.* 97 \\ / 98 \\ / 99 +------ the Internet ------+ 100.Ed 101.Pp 102Assuming router A has the (external) IP address A and the internal address 103192.168.1.1, while router B has external address B and internal address 104192.168.2.1, the following commands will configure the tunnel: 105.Pp 106On router A: 107.Bd -literal -offset indent 108ifconfig greN create 109ifconfig greN inet 192.168.1.1 192.168.2.1 110ifconfig greN inet tunnel A B 111route add -net 192.168.2 -netmask 255.255.255.0 192.168.2.1 112.Ed 113.Pp 114On router B: 115.Bd -literal -offset indent 116ifconfig greN create 117ifconfig greN inet 192.168.2.1 192.168.1.1 118ifconfig greN inet tunnel B A 119route add -net 192.168.1 -netmask 255.255.255.0 192.168.1.1 120.Ed 121.Sh NOTES 122The MTU of 123.Nm 124interfaces is set to 1476 by default, to match the value used by Cisco routers. 125This may not be an optimal value, depending on the link between the two tunnel 126endpoints. 127It can be adjusted via 128.Xr ifconfig 8 . 129.Pp 130For correct operation, the 131.Nm 132device needs a route to the decapsulating host that does not run over the tunnel, 133as this would be a loop. 134.Pp 135The kernel must be set to forward datagrams by setting the 136.Va net.inet.ip.forwarding 137.Xr sysctl 8 138variable to non-zero. 139.Sh SEE ALSO 140.Xr gif 4 , 141.Xr inet 4 , 142.Xr ip 4 , 143.Xr me 4 , 144.Xr netintro 4 , 145.Xr protocols 5 , 146.Xr ifconfig 8 , 147.Xr sysctl 8 148.Pp 149A description of GRE encapsulation can be found in RFC 2784 and RFC 2890. 150.Sh AUTHORS 151.An Andrey V. Elsukov Aq Mt ae@FreeBSD.org 152.An Heiko W.Rupp Aq Mt hwr@pilhuhn.de 153.Sh BUGS 154.Pp 155The current implementation uses the key only for outgoing packets. 156Incoming packets with a different key or without a key will be treated as if they 157would belong to this interface. 158.Pp 159The sequence number field also used only for outgoing packets. 160