1.\" $OpenBSD: gre.4,v 1.37 2012/09/26 17:34:38 jmc Exp $ 2.\" $NetBSD: gre.4,v 1.10 1999/12/22 14:55:49 kleink Exp $ 3.\" 4.\" Copyright 1998 (c) The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Heiko W.Rupp <hwr@pilhuhn.de> 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: September 26 2012 $ 32.Dt GRE 4 33.Os 34.Sh NAME 35.Nm gre 36.Nd encapsulating network device 37.Sh SYNOPSIS 38.Cd "pseudo-device gre" 39.Sh DESCRIPTION 40The 41.Nm 42network interface allows tunnel construction using the Cisco GRE or 43the Mobile-IP (RFC 2004) encapsulation protocols. 44.Pp 45.Tn GRE , 46.Tn WCCPv1 , 47and 48.Tn MobileIP 49are enabled with the following 50.Xr sysctl 3 51variables respectively in 52.Pa /etc/sysctl.conf : 53.Bl -tag -width "net.inet.mobileip.allow" 54.It Va net.inet.gre.allow 55Allow GRE packets in and out of the system. 56.It Va net.inet.gre.wccp 57Allow WCCPv1-style GRE packets into the system (depends on the above). 58.It Va net.inet.mobileip.allow 59Allow MobileIP packets in and out of the system. 60.El 61.Pp 62A 63.Nm 64interface can be created at runtime using the 65.Ic ifconfig gre Ns Ar N Ic create 66command or by setting up a 67.Xr hostname.if 5 68configuration file for 69.Xr netstart 8 . 70.Pp 71This driver currently supports the following modes of operation: 72.Bl -tag -width abc 73.It GRE encapsulation (IP protocol number 47). 74Encapsulated datagrams are prepended by an outer datagram and a GRE header. 75The GRE header specifies the type of the encapsulated datagram 76and thus allows for tunneling other protocols than IP like 77e.g. AppleTalk. 78GRE mode is the default tunnel mode on Cisco routers. 79This is also the default mode of operation of the 80.Nm 81interfaces. 82.It MOBILE encapsulation (IP protocol number 55). 83Datagrams are encapsulated into IP, but with a much smaller 84encapsulation header. 85This protocol only supports IP in IP encapsulation, and is intended 86for use with mobile IP. 87.El 88.Pp 89The network interfaces are named 90.Li gre0 , 91.Li gre1 , 92etc. 93The number of interfaces is given by the corresponding 94.Ic pseudo-device 95line in the system configuration file. 96.Nm gre 97interfaces support the following 98.Xr ioctl 2 Ns s : 99.Bl -tag -width Ds 100.It Dv GRESADDRS Fa "struct ifreq *" 101Set the IP address of the local tunnel end. 102.It Dv GRESADDRD Fa "struct ifreq *" 103Set the IP address of the remote tunnel end. 104.It Dv GREGADDRS Fa "struct ifreq *" 105Query the IP address that is set for the local tunnel end. 106.It Dv GREGADDRD Fa "struct ifreq *" 107Query the IP address that is set for the remote tunnel end. 108.It Dv GRESPROTO Fa "struct ifreq *" 109Set the operation mode to the specified IP protocol value. 110The protocol is passed to the interface in the 111.Va ifr_flags 112field of the 113.Vt ifreq 114structure. 115The operation mode can also be set with the following modifiers to 116.Xr ifconfig 8 : 117.Pp 118.Bl -tag -width "-link0" -offset indent -compact 119.It Cm link0 120.Dv IPPROTO_GRE 121.It Cm -link0 122.Dv IPPROTO_MOBILE 123.El 124.It Dv GREGPROTO Fa "struct ifreq *" 125Query operation mode. 126.El 127.Pp 128Note that the IP addresses of the tunnel endpoints may be the same as the 129ones defined with 130.Xr ifconfig 8 131for the interface (as if IP is encapsulated), but need not be, as e.g. when 132encapsulating AppleTalk. 133.Sh EXAMPLES 134Configuration example: 135.Bd -literal 136Host X ---- Host A ------------ tunnel ------------ Cisco D ---- Host E 137 \e / 138 \e / 139 +------ Host B ------ Host C ------+ 140.Ed 141.Pp 142On Host A (OpenBSD): 143.Bd -literal -offset indent 144# route add default B 145# ifconfig greN create 146# ifconfig greN A D netmask 0xffffffff linkX up 147# ifconfig greN tunnel A D 148# route add E D 149.Ed 150.Pp 151On Host D (Cisco): 152.Bd -literal -offset indent 153Interface TunnelX 154 ip unnumbered D ! e.g. address from Ethernet interface 155 tunnel source D ! e.g. address from Ethernet interface 156 tunnel destination A 157ip route C <some interface and mask> 158ip route A mask C 159ip route X mask tunnelX 160.Ed 161.Pp 162OR 163.Pp 164On Host D (OpenBSD): 165.Bd -literal -offset indent 166# route add default C 167# ifconfig greN create 168# ifconfig greN D A 169# ifconfig greN tunnel D A 170.Ed 171.Pp 172To reach Host A over the tunnel (from Host D), there has to be an 173alias on Host A for the Ethernet interface: 174.Pp 175.Dl # ifconfig <etherif> alias Y 176.Pp 177and on the Cisco: 178.Pp 179.Dl ip route Y mask tunnelX 180.Pp 181Keepalive packets may optionally be sent to the remote endpoint, which 182decapsulates and returns them, allowing tunnel failure to be detected. 183Enable them like this: 184.Bd -literal -offset indent 185# ifconfig greN keepalive period count 186.Ed 187.Pp 188This will send a keepalive packet every 189.Ar period 190seconds. 191If no response is received in 192.Ar count 193* 194.Ar period 195seconds, the link is considered down. 196To return keepalives, the remote host must be configured to forward packets: 197.Bd -literal -offset indent 198# sysctl net.inet.ip.forwarding=1 199.Ed 200.Pp 201If 202.Xr pf 4 203is enabled then it is necessary to add a pass rule specific for the keepalive 204packets. 205The rule must use 206.Em no state 207because the keepalive packet is entering the network stack multiple times. 208In most cases the following should work: 209.Bd -literal -offset indent 210pass quick on gre proto gre no state 211.Ed 212.Sh NOTES 213The MTU of 214.Nm 215interfaces is set to 1476 by default to match the value used by Cisco routers. 216This may not be an optimal value, depending on the link between the two tunnel 217endpoints. 218It can be adjusted via 219.Xr ifconfig 8 . 220.Pp 221For correct operation, the 222.Nm 223device needs a route to the destination, that is less specific than the 224one over the tunnel. 225(There needs to be a route to the decapsulating host that 226does not run over the tunnel, as this would create a loop.) 227.Pp 228In order for 229.Xr ifconfig 8 230to actually mark the interface as up, the keyword 231.Cm up 232must be given last on its command line. 233.Pp 234The kernel must be set to forward datagrams by issuing the appropriate 235option to 236.Xr sysctl 8 . 237.Pp 238The GRE interface will accept WCCPv1-style GRE encapsulated packets 239from a Cisco router. 240Some magic with the packet filter configuration 241and a caching proxy like squid are needed to do anything useful with 242these packets. 243.Sh SEE ALSO 244.Xr inet 4 , 245.Xr ip 4 , 246.Xr netintro 4 , 247.Xr options 4 , 248.Xr hostname.if 5 , 249.Xr protocols 5 , 250.Xr ifconfig 8 , 251.Xr netstart 8 , 252.Xr sysctl 8 253.Sh STANDARDS 254.Rs 255.%A S. Hanks 256.%A "T. Li" 257.%A D. Farinacci 258.%A P. Traina 259.%D October 1994 260.%R RFC 1701 261.%T Generic Routing Encapsulation (GRE) 262.Re 263.Pp 264.Rs 265.%A S. Hanks 266.%A "T. Li" 267.%A D. Farinacci 268.%A P. Traina 269.%D October 1994 270.%R RFC 1702 271.%T Generic Routing Encapsulation over IPv4 networks 272.Re 273.Pp 274.Rs 275.%A C. Perkins 276.%D October 1996 277.%R RFC 2004 278.%T Minimal Encapsulation within IP 279.Re 280.Pp 281.Rs 282.%U http://www.wrec.org/Drafts/draft-ietf-wrec-web-pro-00.txt 283.%T Web Cache Coordination Protocol V1.0 284.Re 285.Pp 286.Rs 287.%U http://www.wrec.org/Drafts/draft-wilson-wrec-wccp-v2-00.txt 288.%T Web Cache Coordination Protocol V2.0 289.Re 290.Sh AUTHORS 291.An Heiko W.Rupp Aq hwr@pilhuhn.de 292.Sh BUGS 293GRE RFC not yet fully implemented (no GRE options). 294.Pp 295For the WCCP GRE encapsulated packets we can only reliably accept 296WCCPv1 format; WCCPv2 formatted packets add another header which will 297skew the decode, and results are not defined (i.e. don't do WCCPv2). 298