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 June 5, 2018 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 Miscellaneous 164By default, 165.Nm 166tunnels may not be nested. 167This behavior may be modified at runtime by setting the 168.Xr sysctl 8 169variable 170.Va net.link.gif.max_nesting 171to the desired level of nesting. 172.Sh SEE ALSO 173.Xr gre 4 , 174.Xr inet 4 , 175.Xr inet6 4 , 176.Xr ifconfig 8 177.Rs 178.%A R. Gilligan 179.%A E. Nordmark 180.%B RFC2893 181.%T Transition Mechanisms for IPv6 Hosts and Routers 182.%D August 2000 183.%U http://tools.ietf.org/html/rfc2893 184.Re 185.Rs 186.%A Sally Floyd 187.%A David L. Black 188.%A K. K. Ramakrishnan 189.%T "IPsec Interactions with ECN" 190.%D December 1999 191.%O draft-ietf-ipsec-ecn-02.txt 192.Re 193.\" 194.Sh HISTORY 195The 196.Nm 197device first appeared in the WIDE hydrangea IPv6 kit. 198.\" 199.Sh BUGS 200There are many tunnelling protocol specifications, all 201defined differently from each other. 202The 203.Nm 204device may not interoperate with peers which are based on different specifications, 205and are picky about outer header fields. 206For example, you cannot usually use 207.Nm 208to talk with IPsec devices that use IPsec tunnel mode. 209.Pp 210The current code does not check if the ingress address 211(outer source address) 212configured in the 213.Nm 214interface makes sense. 215Make sure to specify an address which belongs to your node. 216Otherwise, your node will not be able to receive packets from the peer, 217and it will generate packets with a spoofed source address. 218.Pp 219If the outer protocol is IPv4, 220.Nm 221does not try to perform path MTU discovery for the encapsulated packet 222(DF bit is set to 0). 223.Pp 224If the outer protocol is IPv6, path MTU discovery for encapsulated packets 225may affect communication over the interface. 226The first bigger-than-pmtu packet may be lost. 227To avoid the problem, you may want to set the interface MTU for 228.Nm 229to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. 230.Pp 231The 232.Nm 233device does not translate ICMP messages for the outer header into the inner header. 234.Pp 235In the past, 236.Nm 237had a multi-destination behavior, configurable via 238.Dv IFF_LINK0 239flag. 240The behavior is obsolete and is no longer supported. 241
