1.\" $KAME: gif.4,v 1.28 2001/05/18 13:15:56 itojun Exp $ 2.\" 3.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the project nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd August 1, 2011 33.Dt GIF 4 34.Os 35.Sh NAME 36.Nm gif 37.Nd generic tunnel interface 38.Sh SYNOPSIS 39.Cd "device gif" 40.Sh DESCRIPTION 41The 42.Nm 43interface is a generic tunnelling device for IPv4 and IPv6. 44It can tunnel IPv[46] traffic over IPv[46]. 45Therefore, there can be four possible configurations. 46The behavior of 47.Nm 48is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel. 49On 50.Nx , 51.Nm 52can also tunnel ISO traffic over IPv[46] using EON encapsulation. 53Note that 54.Nm 55does not perform GRE encapsulation; use 56.Xr gre 4 57for GRE encapsulation. 58.Pp 59Each 60.Nm 61interface is created at runtime using interface cloning. 62This is 63most easily done with the 64.Dq Nm ifconfig Cm create 65command or using the 66.Va ifconfig_ Ns Aq Ar interface 67variable in 68.Xr rc.conf 5 . 69.Pp 70To use 71.Nm , 72the administrator needs to configure the protocol and addresses used for the outer 73header. 74This can be done by using 75.Xr ifconfig 8 76.Cm tunnel , 77or 78.Dv SIOCSIFPHYADDR 79ioctl. 80The administrator also needs to configure the protocol and addresses for the 81inner header, with 82.Xr ifconfig 8 . 83Note that IPv6 link-local addresses 84(those that start with 85.Li fe80:: ) 86will be automatically configured whenever possible. 87You may need to remove IPv6 link-local addresses manually using 88.Xr ifconfig 8 , 89if you want to disable the use of IPv6 as the inner header 90(for example, if you need a pure IPv4-over-IPv6 tunnel). 91Finally, you must modify the routing table to route the packets through the 92.Nm 93interface. 94.Pp 95The 96.Nm 97device can be configured to be ECN friendly. 98This can be configured by 99.Dv IFF_LINK1 . 100.Ss ECN friendly behavior 101The 102.Nm 103device can be configured to be ECN friendly, as described in 104.Dv draft-ietf-ipsec-ecn-02.txt . 105This is turned off by default, and can be turned on by the 106.Dv IFF_LINK1 107interface flag. 108.Pp 109Without 110.Dv IFF_LINK1 , 111.Nm 112will show normal behavior, as described in RFC2893. 113This can be summarized as follows: 114.Bl -tag -width "Ingress" -offset indent 115.It Ingress 116Set outer TOS bit to 117.Dv 0 . 118.It Egress 119Drop outer TOS bit. 120.El 121.Pp 122With 123.Dv IFF_LINK1 , 124.Nm 125will copy ECN bits 126.Dv ( 0x02 127and 128.Dv 0x01 129on IPv4 TOS byte or IPv6 traffic class byte) 130on egress and ingress, as follows: 131.Bl -tag -width "Ingress" -offset indent 132.It Ingress 133Copy TOS bits except for ECN CE 134(masked with 135.Dv 0xfe ) 136from 137inner to outer. 138Set ECN CE bit to 139.Dv 0 . 140.It Egress 141Use inner TOS bits with some change. 142If outer ECN CE bit is 143.Dv 1 , 144enable ECN CE bit on the inner. 145.El 146.Pp 147Note that the ECN friendly behavior violates RFC2893. 148This should be used in mutual agreement with the peer. 149.Ss Security 150A malicious party may try to circumvent security filters by using 151tunnelled packets. 152For better protection, 153.Nm 154performs both martian and ingress filtering against the outer source address 155on egress. 156Note that martian/ingress filters are in no way complete. 157You may want to secure your node by using packet filters. 158Ingress filtering can break tunnel operation in an asymmetrically 159routed network. 160It can be turned off by 161.Dv IFF_LINK2 162bit. 163.Ss Route caching 164Processing each packet requires two route lookups: first on the 165packet itself, and second on the tunnel destination. 166This second route can be cached, increasing tunnel performance. 167However, in a dynamically routed network, the tunnel will stick 168to the cached route, ignoring routing table updates. 169Route caching can be enabled with the 170.Dv IFF_LINK0 171flag. 172.\" 173.Ss Miscellaneous 174By default, 175.Nm 176tunnels may not be nested. 177This behavior may be modified at runtime by setting the 178.Xr sysctl 8 179variable 180.Va net.link.gif.max_nesting 181to the desired level of nesting. 182Additionally, 183.Nm 184tunnels are restricted to one per pair of end points. 185Parallel tunnels may be enabled by setting the 186.Xr sysctl 8 187variable 188.Va net.link.gif.parallel_tunnels 189to 1. 190.Sh SEE ALSO 191.Xr gre 4 , 192.Xr inet 4 , 193.Xr inet6 4 , 194.Xr ifconfig 8 195.Rs 196.%A R. Gilligan 197.%A E. Nordmark 198.%B RFC2893 199.%T Transition Mechanisms for IPv6 Hosts and Routers 200.%D August 2000 201.%U http://tools.ietf.org/html/rfc2893 202.Re 203.Rs 204.%A Sally Floyd 205.%A David L. Black 206.%A K. K. Ramakrishnan 207.%T "IPsec Interactions with ECN" 208.%D December 1999 209.%O draft-ietf-ipsec-ecn-02.txt 210.Re 211.\" 212.Sh HISTORY 213The 214.Nm 215device first appeared in the WIDE hydrangea IPv6 kit. 216.\" 217.Sh BUGS 218There are many tunnelling protocol specifications, all 219defined differently from each other. 220The 221.Nm 222device may not interoperate with peers which are based on different specifications, 223and are picky about outer header fields. 224For example, you cannot usually use 225.Nm 226to talk with IPsec devices that use IPsec tunnel mode. 227.Pp 228The current code does not check if the ingress address 229(outer source address) 230configured in the 231.Nm 232interface makes sense. 233Make sure to specify an address which belongs to your node. 234Otherwise, your node will not be able to receive packets from the peer, 235and it will generate packets with a spoofed source address. 236.Pp 237If the outer protocol is IPv4, 238.Nm 239does not try to perform path MTU discovery for the encapsulated packet 240(DF bit is set to 0). 241.Pp 242If the outer protocol is IPv6, path MTU discovery for encapsulated packets 243may affect communication over the interface. 244The first bigger-than-pmtu packet may be lost. 245To avoid the problem, you may want to set the interface MTU for 246.Nm 247to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. 248.Pp 249The 250.Nm 251device does not translate ICMP messages for the outer header into the inner header. 252.Pp 253In the past, 254.Nm 255had a multi-destination behavior, configurable via 256.Dv IFF_LINK0 257flag. 258The behavior is obsolete and is no longer supported. 259.Pp 260On 261.Fx 2626.1, 6.2, 6.3, 7.0, 7.1, and 7.2 263the 264.Nm 265sends and receives incorrect EtherIP packets with reversed version 266field when 267.Xr if_bridge 4 268is used together. As a workaround on this interoperability issue, the 269following two 270.Xr ifconfig 8 271flags can be used: 272.Bl -tag -width "accept_rev_ethip_ver" -offset indent 273.It accept_rev_ethip_ver 274accepts both correct EtherIP packets and ones with reversed version 275field, if enabled. If disabled, the 276.Nm 277accepts the correct packets only. This flag is enabled by default. 278.It send_rev_ethip_ver 279sends EtherIP packets with reversed version field intentionally, if 280enabled. If disabled, the 281.Nm 282sends the correct packets only. This flag is disabled by default. 283.El 284.Pp 285If interoperability with the older 286.Fx 287machines is needed, both of these two flags must be enabled. 288
