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.\" Copyright (C) 2024 Hiroki Sato <hrs@FreeBSD.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd July 14, 2025 32.Dt GIF 4 33.Os 34.Sh NAME 35.Nm gif 36.Nd generic tunnel interface 37.Sh SYNOPSIS 38.Cd "device gif" 39.Sh DESCRIPTION 40The 41.Nm 42interface is a generic tunnelling device for IPv4 and IPv6. 43It can tunnel IPv[46] traffic over IPv[46]. 44Therefore, there can be four possible configurations. 45The behavior of 46.Nm 47is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel. 48On 49.Nx , 50.Nm 51can also tunnel ISO traffic over IPv[46] using EON encapsulation. 52Note that 53.Nm 54does not perform GRE encapsulation; use 55.Xr gre 4 56for GRE encapsulation. 57.Pp 58Each 59.Nm 60interface is created at runtime using interface cloning. 61This is 62most easily done with the 63.Dq Nm ifconfig Cm create 64command or using the 65.Va ifconfig_ Ns Aq Ar interface 66variable in 67.Xr rc.conf 5 . 68.Pp 69To use 70.Nm , 71the administrator needs to configure the protocol and addresses used for 72the outer header. 73This can be done by using 74.Xr ifconfig 8 75.Cm tunnel , 76or 77.Dv SIOCSIFPHYADDR 78ioctl. 79The administrator also needs to configure the protocol and addresses for the 80inner header, with 81.Xr ifconfig 8 . 82Note that IPv6 link-local addresses 83.Pq those that start with 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.Ss MTU Configuration and Path MTU Discovery 93The 94.Nm 95interface uses the fixed length, 96.Li 1280 , 97to determine whether the outgoing IPv6 packets are split. 98This means the MTU value configured on the interface will be ignored 99when the outer protocol is IPv6. 100When the 101.Dv NOCLAMP 102interface flag is set, 103.Nm 104uses the same configured value as IPv4 communications. 105This behavior prevents potential issues when the path MTU is 106smaller than the interface MTU. 107This section describes the reason why the default behavior is different. 108The 109.Dv NOCLAMP 110interface flag can be set using the following command: 111.Pp 112.Dl ifconfig Ar gif0 Cm noclamp 113.Pp 114and clear the flag using the following: 115.Pp 116.Dl ifconfig Ar gif0 Cm -noclamp 117.Pp 118where 119.Ar gif0 120is the actual interface name. 121.Pp 122A tunnel interface always has an implicit smaller MTU for the inner protocol 123than the outer protocol because of the additional header. 124Note that the interface MTU on a 125.Nm 126interface, 127the default value is 128.Li 1280 , 129is used as MTU for the outer protocol. 130This means that the MTU for the inner protocol varies depending on the 131outer protocol header length. 132If an outgoing packet bigger than the inner protocol MTU arrives at a 133.Nm 134interface for encapsulation, 135it will be split into fragments. 136Specifically, 137if IPv4 is used as the outer protocol, 138the inner is 20 octets smaller than the interface MTU. 139In the case of the default interface MTU, 140.Li 1280 , 141inner packets bigger than 142.Li 1260 143will be fragmented. 144In the case of IPv6, 145the inner is 40 octets smaller than the outer. 146.Pp 147This fragmentation is not harmful though it can degrade the 148performance. 149Note that while an increased MTU on 150.Nm 151interface helps to mitigate this reduced performance issue, 152it can also cause packet losses on the intermediate narrowest path 153between the two communication endpoints in IPv6. 154IPv6 allows fragmentation only on the sender, 155not on the routers in the communication path. 156A big outgoing packet will be dropped on a router with a smaller MTU. 157.Pp 158In normal IPv6 communication, 159an ICMPv6 Packet Too Big error will be sent back to the sender, 160who can adjust the packet length and re-send it. 161This process is performed in the upper protocols than L3, 162such as TCP, 163and makes the packet length shorter so that packets go through 164the path without fragmentation. 165This behavior is known as path MTU discovery. 166.Pp 167When using a 168.Nm 169interface, 170the Packet Too Big message is generated for the outer protocol. 171Since the 172.Nm 173interface does not translate this error to the inner protocol, 174the inner protocol sees it just as a packet loss with no useful 175information to adjust the length of the next packets. 176In this situation, 177path MTU discovery does not work, 178and communications of the inner protocol 179become stalled. 180.Pp 181In order to avoid this, 182a 183.Nm 184interface silently splits a packet of over 1240 octets into fragments to make 185the outer protocol packets equal or shorter than 1280 octets, 186even when the interface MTU is configured as larger than 1280. 187Note that this occurs only when the outer protocol is IPv6. 188.Li 1280 189is the smallest MTU in IPv6 and guarantees no packet loss occurs 190on intermediate routers. 191.Pp 192As mentioned earlier, 193the performance is sub-optimal if the actual path MTU is larger than 194.Li 1280 . 195A typical confusing scenario is as follows. 196The 197.Nm 198interface can have Ethernet, 199whose MTU is usually 1500, 200as the inner protocol. 201It is called an EtherIP tunnel, 202and can be configured by adding the 203.Nm 204interface as a member of 205.Xr if_bridge 4 206interface. 207The 208.Xr if_bridge 4 209interface forcibly changes the MTU of the 210.Nm 211interface with those for the other member interfaces, 212which are likely 1500. 213In this case, 214a situation in which the MTU of the 215.Nm 216interface is 1500 but fragmentation in 1280 octets always occurs. 217.Pp 218The default behavior is most conservative to prevent confusing packet loss. 219Depending on the network configuration, 220enabling the 221.Dv NOCLAMP 222interface flag might be helpful for better performance. 223It is crucial to ensure that the path MTU is equal to or larger than 224the interface MTU when enabling this flag. 225.Ss ECN friendly behavior 226The 227.Nm 228device can be configured to be ECN friendly, as described in 229.Dv draft-ietf-ipsec-ecn-02.txt . 230This is turned off by default, and can be turned on by the 231.Dv IFF_LINK1 232interface flag. 233.Pp 234Without 235.Dv IFF_LINK1 , 236.Nm 237will show normal behavior, as described in RFC2893. 238This can be summarized as follows: 239.Bl -tag -width "Ingress" -offset indent 240.It Ingress 241Set outer TOS bit to 242.Dv 0 . 243.It Egress 244Drop outer TOS bit. 245.El 246.Pp 247With 248.Dv IFF_LINK1 , 249.Nm 250will copy ECN bits 251.Dv ( 0x02 252and 253.Dv 0x01 254on IPv4 TOS byte or IPv6 traffic class byte) 255on egress and ingress, as follows: 256.Bl -tag -width "Ingress" -offset indent 257.It Ingress 258Copy TOS bits except for ECN CE 259(masked with 260.Dv 0xfe ) 261from 262inner to outer. 263Set ECN CE bit to 264.Dv 0 . 265.It Egress 266Use inner TOS bits with some change. 267If outer ECN CE bit is 268.Dv 1 , 269enable ECN CE bit on the inner. 270.El 271.Pp 272Note that the ECN friendly behavior violates RFC2893. 273This should be used in mutual agreement with the peer. 274.Ss Security 275A malicious party may try to circumvent security filters by using 276tunnelled packets. 277For better protection, 278.Nm 279performs both martian and ingress filtering against the outer source address 280on egress. 281Note that martian/ingress filters are in no way complete. 282You may want to secure your node by using packet filters. 283Ingress filtering can break tunnel operation in an asymmetrically 284routed network. 285It can be turned off by 286.Dv IFF_LINK2 287bit. 288.Ss Miscellaneous 289By default, 290.Nm 291tunnels may not be nested. 292This behavior may be modified at runtime by setting the 293.Xr sysctl 8 294variable 295.Va net.link.gif.max_nesting 296to the desired level of nesting. 297.Sh SEE ALSO 298.Xr gre 4 , 299.Xr if_bridge 4 , 300.Xr inet 4 , 301.Xr inet6 4 , 302.Xr ifconfig 8 303.Rs 304.%A R. Gilligan 305.%A E. Nordmark 306.%B RFC2893 307.%T Transition Mechanisms for IPv6 Hosts and Routers 308.%D August 2000 309.%U http://tools.ietf.org/html/rfc2893 310.Re 311.Rs 312.%A Sally Floyd 313.%A David L. Black 314.%A K. K. Ramakrishnan 315.%T "IPsec Interactions with ECN" 316.%D December 1999 317.%O draft-ietf-ipsec-ecn-02.txt 318.Re 319.\" 320.Sh HISTORY 321The 322.Nm 323device first appeared in the WIDE hydrangea IPv6 kit. 324.\" 325.Sh BUGS 326There are many tunnelling protocol specifications, all 327defined differently from each other. 328The 329.Nm 330device may not interoperate with peers which are based on different 331specifications, 332and are picky about outer header fields. 333For example, you cannot usually use 334.Nm 335to talk with IPsec devices that use IPsec tunnel mode. 336.Pp 337If the outer protocol is IPv4, 338.Nm 339does not try to perform path MTU discovery for the encapsulated packet 340(DF bit is set to 0). 341.Pp 342If the outer protocol is IPv6, path MTU discovery for encapsulated packets 343may affect communication over the interface. 344The first bigger-than-pmtu packet may be lost. 345To avoid the problem, you may want to set the interface MTU for 346.Nm 347to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. 348.Pp 349The 350.Nm 351device does not translate ICMP messages for the outer header into the inner 352header. 353.Pp 354In the past, 355.Nm 356had a multi-destination behavior, configurable via 357.Dv NOCLAMP 358flag. 359The behavior is obsolete and is no longer supported. 360This flag is now used to determine whether performing fragmentation when 361the outer protocol is IPv6. 362
