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.Dd October 21, 2018 31.Dt GIF 4 32.Os 33.Sh NAME 34.Nm gif 35.Nd generic tunnel interface 36.Sh SYNOPSIS 37.Cd "device gif" 38.Sh DESCRIPTION 39The 40.Nm 41interface is a generic tunnelling device for IPv4 and IPv6. 42It can tunnel IPv[46] traffic over IPv[46]. 43Therefore, there can be four possible configurations. 44The behavior of 45.Nm 46is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel. 47On 48.Nx , 49.Nm 50can also tunnel ISO traffic over IPv[46] using EON encapsulation. 51Note that 52.Nm 53does not perform GRE encapsulation; use 54.Xr gre 4 55for GRE encapsulation. 56.Pp 57Each 58.Nm 59interface is created at runtime using interface cloning. 60This is 61most easily done with the 62.Dq Nm ifconfig Cm create 63command or using the 64.Va ifconfig_ Ns Aq Ar interface 65variable in 66.Xr rc.conf 5 . 67.Pp 68To use 69.Nm , 70the administrator needs to configure the protocol and addresses used for the outer 71header. 72This can be done by using 73.Xr ifconfig 8 74.Cm tunnel , 75or 76.Dv SIOCSIFPHYADDR 77ioctl. 78The administrator also needs to configure the protocol and addresses for the 79inner header, with 80.Xr ifconfig 8 . 81Note that IPv6 link-local addresses 82(those that start with 83.Li fe80:: ) 84will be automatically configured whenever possible. 85You may need to remove IPv6 link-local addresses manually using 86.Xr ifconfig 8 , 87if you want to disable the use of IPv6 as the inner header 88(for example, if you need a pure IPv4-over-IPv6 tunnel). 89Finally, you must modify the routing table to route the packets through the 90.Nm 91interface. 92.Pp 93The 94.Nm 95device can be configured to be ECN friendly. 96This can be configured by 97.Dv IFF_LINK1 . 98.Ss ECN friendly behavior 99The 100.Nm 101device can be configured to be ECN friendly, as described in 102.Dv draft-ietf-ipsec-ecn-02.txt . 103This is turned off by default, and can be turned on by the 104.Dv IFF_LINK1 105interface flag. 106.Pp 107Without 108.Dv IFF_LINK1 , 109.Nm 110will show normal behavior, as described in RFC2893. 111This can be summarized as follows: 112.Bl -tag -width "Ingress" -offset indent 113.It Ingress 114Set outer TOS bit to 115.Dv 0 . 116.It Egress 117Drop outer TOS bit. 118.El 119.Pp 120With 121.Dv IFF_LINK1 , 122.Nm 123will copy ECN bits 124.Dv ( 0x02 125and 126.Dv 0x01 127on IPv4 TOS byte or IPv6 traffic class byte) 128on egress and ingress, as follows: 129.Bl -tag -width "Ingress" -offset indent 130.It Ingress 131Copy TOS bits except for ECN CE 132(masked with 133.Dv 0xfe ) 134from 135inner to outer. 136Set ECN CE bit to 137.Dv 0 . 138.It Egress 139Use inner TOS bits with some change. 140If outer ECN CE bit is 141.Dv 1 , 142enable ECN CE bit on the inner. 143.El 144.Pp 145Note that the ECN friendly behavior violates RFC2893. 146This should be used in mutual agreement with the peer. 147.Ss Security 148A malicious party may try to circumvent security filters by using 149tunnelled packets. 150For better protection, 151.Nm 152performs both martian and ingress filtering against the outer source address 153on egress. 154Note that martian/ingress filters are in no way complete. 155You may want to secure your node by using packet filters. 156Ingress filtering can break tunnel operation in an asymmetrically 157routed network. 158It can be turned off by 159.Dv IFF_LINK2 160bit. 161.Ss Miscellaneous 162By default, 163.Nm 164tunnels may not be nested. 165This behavior may be modified at runtime by setting the 166.Xr sysctl 8 167variable 168.Va net.link.gif.max_nesting 169to the desired level of nesting. 170.Sh SEE ALSO 171.Xr gre 4 , 172.Xr inet 4 , 173.Xr inet6 4 , 174.Xr ifconfig 8 175.Rs 176.%A R. Gilligan 177.%A E. Nordmark 178.%B RFC2893 179.%T Transition Mechanisms for IPv6 Hosts and Routers 180.%D August 2000 181.%U http://tools.ietf.org/html/rfc2893 182.Re 183.Rs 184.%A Sally Floyd 185.%A David L. Black 186.%A K. K. Ramakrishnan 187.%T "IPsec Interactions with ECN" 188.%D December 1999 189.%O draft-ietf-ipsec-ecn-02.txt 190.Re 191.\" 192.Sh HISTORY 193The 194.Nm 195device first appeared in the WIDE hydrangea IPv6 kit. 196.\" 197.Sh BUGS 198There are many tunnelling protocol specifications, all 199defined differently from each other. 200The 201.Nm 202device may not interoperate with peers which are based on different specifications, 203and are picky about outer header fields. 204For example, you cannot usually use 205.Nm 206to talk with IPsec devices that use IPsec tunnel mode. 207.Pp 208If the outer protocol is IPv4, 209.Nm 210does not try to perform path MTU discovery for the encapsulated packet 211(DF bit is set to 0). 212.Pp 213If the outer protocol is IPv6, path MTU discovery for encapsulated packets 214may affect communication over the interface. 215The first bigger-than-pmtu packet may be lost. 216To avoid the problem, you may want to set the interface MTU for 217.Nm 218to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. 219.Pp 220The 221.Nm 222device does not translate ICMP messages for the outer header into the inner header. 223.Pp 224In the past, 225.Nm 226had a multi-destination behavior, configurable via 227.Dv IFF_LINK0 228flag. 229The behavior is obsolete and is no longer supported. 230
