1.\" $OpenBSD: gre.4,v 1.43 2015/07/16 15:46:41 sobrado 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: July 16 2015 $ 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 Mobile IP 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 57Set to 1 to allow WCCPv1-style GRE packets into the system; 58set to 2 to handle the packets as WCCPv2-style GRE, truncating 59the redirect header. 60This variable depends on 61.Va gre.allow 62being set. 63.It Va net.inet.mobileip.allow 64Allow Mobile IP packets in and out of the system. 65.El 66.Pp 67A 68.Nm 69interface can be created at runtime using the 70.Ic ifconfig gre Ns Ar N Ic create 71command or by setting up a 72.Xr hostname.if 5 73configuration file for 74.Xr netstart 8 . 75.Pp 76This driver currently supports the following modes of operation: 77.Bl -tag -width abc 78.It GRE encapsulation (IP protocol number 47) 79Encapsulated datagrams are prepended by an outer datagram and a GRE header. 80The GRE header specifies the type of the encapsulated datagram 81and thus allows for tunneling other protocols than IP like 82e.g. AppleTalk. 83GRE mode is the default tunnel mode on Cisco routers. 84This is also the default mode of operation of the 85.Nm 86interfaces. 87.It MOBILE encapsulation (IP protocol number 55) 88Datagrams are encapsulated into IP, but with a much smaller 89encapsulation header. 90This protocol only supports IP in IP encapsulation, and is intended 91for use with Mobile IP. 92.El 93.Pp 94The network interfaces are named 95.Li gre0 , 96.Li gre1 , 97etc. 98The number of interfaces is given by the corresponding 99.Ic pseudo-device 100line in the system configuration file. 101.Nm gre 102interfaces support the following 103.Xr ioctl 2 Ns s : 104.Bl -tag -width Ds 105.It Dv GRESADDRS Fa "struct ifreq *" 106Set the IP address of the local tunnel end. 107.It Dv GRESADDRD Fa "struct ifreq *" 108Set the IP address of the remote tunnel end. 109.It Dv GREGADDRS Fa "struct ifreq *" 110Query the IP address that is set for the local tunnel end. 111.It Dv GREGADDRD Fa "struct ifreq *" 112Query the IP address that is set for the remote tunnel end. 113.It Dv GRESPROTO Fa "struct ifreq *" 114Set the operation mode to the specified IP protocol value. 115The protocol is passed to the interface in the 116.Va ifr_flags 117field of the 118.Vt ifreq 119structure. 120The operation mode can also be set with the following modifiers to 121.Xr ifconfig 8 : 122.Pp 123.Bl -tag -width "-link0" -offset indent -compact 124.It Cm link0 125.Dv IPPROTO_GRE 126.It Cm -link0 127.Dv IPPROTO_MOBILE 128.El 129.It Dv GREGPROTO Fa "struct ifreq *" 130Query operation mode. 131.El 132.Pp 133Note that the IP addresses of the tunnel endpoints may be the same as the 134ones defined with 135.Xr ifconfig 8 136for the interface (as if IP is encapsulated), but need not be, as e.g. when 137encapsulating AppleTalk. 138.Sh EXAMPLES 139Configuration example: 140.Bd -literal 141Host X ---- Host A ------------ tunnel ------------ Cisco D ---- Host E 142 \e / 143 \e / 144 +------ Host B ------ Host C ------+ 145.Ed 146.Pp 147On Host A (OpenBSD): 148.Bd -literal -offset indent 149# route add default B 150# ifconfig greN create 151# ifconfig greN A D netmask 0xffffffff linkX up 152# ifconfig greN tunnel A D 153# route add E D 154.Ed 155.Pp 156On Host D (Cisco): 157.Bd -literal -offset indent 158Interface TunnelX 159 ip unnumbered D ! e.g. address from Ethernet interface 160 tunnel source D ! e.g. address from Ethernet interface 161 tunnel destination A 162ip route C <some interface and mask> 163ip route A mask C 164ip route X mask tunnelX 165.Ed 166.Pp 167OR 168.Pp 169On Host D (OpenBSD): 170.Bd -literal -offset indent 171# route add default C 172# ifconfig greN create 173# ifconfig greN D A 174# ifconfig greN tunnel D A 175.Ed 176.Pp 177To reach Host A over the tunnel (from Host D), there has to be an 178alias on Host A for the Ethernet interface: 179.Pp 180.Dl # ifconfig <etherif> alias Y 181.Pp 182and on the Cisco: 183.Pp 184.Dl ip route Y mask tunnelX 185.Pp 186Keepalive packets may optionally be sent to the remote endpoint, which 187decapsulates and returns them, allowing tunnel failure to be detected. 188Enable them like this: 189.Bd -literal -offset indent 190# ifconfig greN keepalive period count 191.Ed 192.Pp 193This will send a keepalive packet every 194.Ar period 195seconds. 196If no response is received in 197.Ar count 198* 199.Ar period 200seconds, the link is considered down. 201To return keepalives, the remote host must be configured to forward packets: 202.Bd -literal -offset indent 203# sysctl net.inet.ip.forwarding=1 204.Ed 205.Pp 206If 207.Xr pf 4 208is enabled then it is necessary to add a pass rule specific for the keepalive 209packets. 210The rule must use 211.Em no state 212because the keepalive packet is entering the network stack multiple times. 213In most cases the following should work: 214.Bd -literal -offset indent 215pass quick on gre proto gre no state 216.Ed 217.Sh NOTES 218The MTU of 219.Nm 220interfaces is set to 1476 by default to match the value used by Cisco routers. 221This may not be an optimal value, depending on the link between the two tunnel 222endpoints. 223It can be adjusted via 224.Xr ifconfig 8 . 225.Pp 226For correct operation, the 227.Nm 228device needs a route to the destination, that is less specific than the 229one over the tunnel. 230(There needs to be a route to the decapsulating host that 231does not run over the tunnel, as this would create a loop.) 232.Pp 233In order for 234.Xr ifconfig 8 235to actually mark the interface as up, the keyword 236.Cm up 237must be given last on its command line. 238.Pp 239The kernel must be set to forward datagrams by issuing the appropriate 240option to 241.Xr sysctl 8 . 242.Pp 243The GRE interface will accept WCCPv1-style or WWCPv2-style GRE 244encapsulated packets from a Cisco router. 245Some magic with the packet filter configuration 246and a caching proxy like squid are needed to do anything useful with 247these packets. 248.Sh SEE ALSO 249.Xr inet 4 , 250.Xr ip 4 , 251.Xr netintro 4 , 252.Xr options 4 , 253.Xr hostname.if 5 , 254.Xr protocols 5 , 255.Xr ifconfig 8 , 256.Xr netstart 8 , 257.Xr sysctl 8 258.Sh STANDARDS 259.Rs 260.%A S. Hanks 261.%A "T. Li" 262.%A D. Farinacci 263.%A P. Traina 264.%D October 1994 265.%R RFC 1701 266.%T Generic Routing Encapsulation (GRE) 267.Re 268.Pp 269.Rs 270.%A S. Hanks 271.%A "T. Li" 272.%A D. Farinacci 273.%A P. Traina 274.%D October 1994 275.%R RFC 1702 276.%T Generic Routing Encapsulation over IPv4 networks 277.Re 278.Pp 279.Rs 280.%A C. Perkins 281.%D October 1996 282.%R RFC 2004 283.%T Minimal Encapsulation within IP 284.Re 285.Pp 286.Rs 287.%U http://www.wrec.org/Drafts/draft-ietf-wrec-web-pro-00.txt 288.%T Web Cache Coordination Protocol V1.0 289.Re 290.Pp 291.Rs 292.%U http://www.wrec.org/Drafts/draft-wilson-wrec-wccp-v2-00.txt 293.%T Web Cache Coordination Protocol V2.0 294.Re 295.Sh AUTHORS 296.An Heiko W. Rupp Aq Mt hwr@pilhuhn.de 297.Sh BUGS 298GRE RFC not yet fully implemented (no GRE options). 299.Pp 300The redirect header for WCCPv2 GRE encapsulated packets is skipped. 301