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 August 27, 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 58The 59.Nm 60interface can also tunnel Ethernet traffic over IPv4 or IPv6 61when combined with a 62.Xr if_bridge 4 63interface using EtherIP protocol. 64See 65.Xr if_bridge 4 66for detailed setup. 67.Pp 68Each 69.Nm 70interface is created at runtime using interface cloning. 71This is 72most easily done with the 73.Dq Nm ifconfig Cm create 74command or using the 75.Va ifconfig_ Ns Aq Ar interface 76variable in 77.Xr rc.conf 5 . 78.Pp 79To use 80.Nm , 81the administrator needs to configure the protocol and addresses used for 82the outer header. 83This can be done by using 84.Xr ifconfig 8 85.Cm tunnel , 86or 87.Dv SIOCSIFPHYADDR 88ioctl. 89The administrator also needs to configure the protocol and addresses for the 90inner header, with 91.Xr ifconfig 8 . 92Note that IPv6 link-local addresses 93.Pq those that start with Li fe80\&:\&: 94will be automatically configured whenever possible. 95You may need to remove IPv6 link-local addresses manually using 96.Xr ifconfig 8 , 97if you want to disable the use of IPv6 as the inner header 98(for example, if you need a pure IPv4-over-IPv6 tunnel). 99Finally, you must modify the routing table to route the packets through the 100.Nm 101interface. 102.Ss MTU Configuration and Path MTU Discovery 103The 104.Nm 105interface uses the fixed length, 106.Li 1280 , 107to determine whether the outgoing IPv6 packets are split. 108This means the MTU value configured on the interface will be ignored 109when the outer protocol is IPv6. 110When the 111.Dv NOCLAMP 112interface flag is set, 113.Nm 114uses the same configured value as IPv4 communications. 115This behavior prevents potential issues when the path MTU is 116smaller than the interface MTU. 117This section describes the reason why the default behavior is different. 118The 119.Dv NOCLAMP 120interface flag can be set using the following command: 121.Pp 122.Dl ifconfig Ar gif0 Cm noclamp 123.Pp 124and clear the flag using the following: 125.Pp 126.Dl ifconfig Ar gif0 Cm -noclamp 127.Pp 128where 129.Ar gif0 130is the actual interface name. 131.Pp 132A tunnel interface always has an implicit smaller MTU for the inner protocol 133than the outer protocol because of the additional header. 134Note that the interface MTU on a 135.Nm 136interface, 137the default value is 138.Li 1280 , 139is used as MTU for the outer protocol. 140This means that the MTU for the inner protocol varies depending on the 141outer protocol header length. 142If an outgoing packet bigger than the inner protocol MTU arrives at a 143.Nm 144interface for encapsulation, 145it will be split into fragments. 146Specifically, 147if IPv4 is used as the outer protocol, 148the inner is 20 octets smaller than the interface MTU. 149In the case of the default interface MTU, 150.Li 1280 , 151inner packets bigger than 152.Li 1260 153will be fragmented. 154In the case of IPv6, 155the inner is 40 octets smaller than the outer. 156.Pp 157This fragmentation is not harmful though it can degrade the 158performance. 159Note that while an increased MTU on 160.Nm 161interface helps to mitigate this reduced performance issue, 162it can also cause packet losses on the intermediate narrowest path 163between the two communication endpoints in IPv6. 164IPv6 allows fragmentation only on the sender, 165not on the routers in the communication path. 166A big outgoing packet will be dropped on a router with a smaller MTU. 167.Pp 168In normal IPv6 communication, 169an ICMPv6 Packet Too Big error will be sent back to the sender, 170who can adjust the packet length and re-send it. 171This process is performed in the upper protocols than L3, 172such as TCP, 173and makes the packet length shorter so that packets go through 174the path without fragmentation. 175This behavior is known as path MTU discovery. 176.Pp 177When using a 178.Nm 179interface, 180the Packet Too Big message is generated for the outer protocol. 181Since the 182.Nm 183interface does not translate this error to the inner protocol, 184the inner protocol sees it just as a packet loss with no useful 185information to adjust the length of the next packets. 186In this situation, 187path MTU discovery does not work, 188and communications of the inner protocol 189become stalled. 190.Pp 191In order to avoid this, 192a 193.Nm 194interface silently splits a packet of over 1240 octets into fragments to make 195the outer protocol packets equal or shorter than 1280 octets, 196even when the interface MTU is configured as larger than 1280. 197Note that this occurs only when the outer protocol is IPv6. 198.Li 1280 199is the smallest MTU in IPv6 and guarantees no packet loss occurs 200on intermediate routers. 201.Pp 202As mentioned earlier, 203the performance is sub-optimal if the actual path MTU is larger than 204.Li 1280 . 205A typical confusing scenario is as follows. 206The 207.Nm 208interface can have Ethernet, 209whose MTU is usually 1500, 210as the inner protocol. 211It is called an EtherIP tunnel, 212and can be configured by adding the 213.Nm 214interface as a member of 215.Xr if_bridge 4 216interface. 217The 218.Xr if_bridge 4 219interface forcibly changes the MTU of the 220.Nm 221interface with those for the other member interfaces, 222which are likely 1500. 223In this case, 224a situation in which the MTU of the 225.Nm 226interface is 1500 but fragmentation in 1280 octets always occurs. 227.Pp 228The default behavior is most conservative to prevent confusing packet loss. 229Depending on the network configuration, 230enabling the 231.Dv NOCLAMP 232interface flag might be helpful for better performance. 233It is crucial to ensure that the path MTU is equal to or larger than 234the interface MTU when enabling this flag. 235.Ss ECN friendly behavior 236The 237.Nm 238device can be configured to be ECN friendly, as described in 239.Dv draft-ietf-ipsec-ecn-02.txt . 240This is turned off by default, and can be turned on by the 241.Dv IFF_LINK1 242interface flag. 243.Pp 244Without 245.Dv IFF_LINK1 , 246.Nm 247will show normal behavior, as described in RFC2893. 248This can be summarized as follows: 249.Bl -tag -width "Ingress" -offset indent 250.It Ingress 251Set outer TOS bit to 252.Dv 0 . 253.It Egress 254Drop outer TOS bit. 255.El 256.Pp 257With 258.Dv IFF_LINK1 , 259.Nm 260will copy ECN bits 261.Dv ( 0x02 262and 263.Dv 0x01 264on IPv4 TOS byte or IPv6 traffic class byte) 265on egress and ingress, as follows: 266.Bl -tag -width "Ingress" -offset indent 267.It Ingress 268Copy TOS bits except for ECN CE 269(masked with 270.Dv 0xfe ) 271from 272inner to outer. 273Set ECN CE bit to 274.Dv 0 . 275.It Egress 276Use inner TOS bits with some change. 277If outer ECN CE bit is 278.Dv 1 , 279enable ECN CE bit on the inner. 280.El 281.Pp 282Note that the ECN friendly behavior violates RFC2893. 283This should be used in mutual agreement with the peer. 284.Ss Security 285A malicious party may try to circumvent security filters by using 286tunnelled packets. 287For better protection, 288.Nm 289performs both martian and ingress filtering against the outer source address 290on egress. 291Note that martian/ingress filters are in no way complete. 292You may want to secure your node by using packet filters. 293Ingress filtering can break tunnel operation in an asymmetrically 294routed network. 295It can be turned off by 296.Dv IFF_LINK2 297bit. 298.Ss Miscellaneous 299By default, 300.Nm 301tunnels may not be nested. 302This behavior may be modified at runtime by setting the 303.Xr sysctl 8 304variable 305.Va net.link.gif.max_nesting 306to the desired level of nesting. 307.Sh SEE ALSO 308.Xr gre 4 , 309.Xr if_bridge 4 , 310.Xr inet 4 , 311.Xr inet6 4 , 312.Xr ifconfig 8 313.Rs 314.%A R. Gilligan 315.%A E. Nordmark 316.%B RFC2893 317.%T Transition Mechanisms for IPv6 Hosts and Routers 318.%D August 2000 319.%U http://tools.ietf.org/html/rfc2893 320.Re 321.Rs 322.%A Sally Floyd 323.%A David L. Black 324.%A K. K. Ramakrishnan 325.%T "IPsec Interactions with ECN" 326.%D December 1999 327.%O draft-ietf-ipsec-ecn-02.txt 328.Re 329.Rs 330.%A R. Housley 331.%A S. Hollenbeck 332.%T EtherIP: Tunneling Ethernet Frames in IP Datagrams 333.%R RFC 3378 334.%D September 2002 335.Re 336.\" 337.Sh HISTORY 338The 339.Nm 340device first appeared in the WIDE hydrangea IPv6 kit. 341.\" 342.Sh BUGS 343There are many tunnelling protocol specifications, all 344defined differently from each other. 345The 346.Nm 347device may not interoperate with peers which are based on different 348specifications, 349and are picky about outer header fields. 350For example, you cannot usually use 351.Nm 352to talk with IPsec devices that use IPsec tunnel mode. 353.Pp 354If the outer protocol is IPv4, 355.Nm 356does not try to perform path MTU discovery for the encapsulated packet 357(DF bit is set to 0). 358.Pp 359If the outer protocol is IPv6, path MTU discovery for encapsulated packets 360may affect communication over the interface. 361The first bigger-than-pmtu packet may be lost. 362To avoid the problem, you may want to set the interface MTU for 363.Nm 364to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. 365.Pp 366The 367.Nm 368device does not translate ICMP messages for the outer header into the inner 369header. 370.Pp 371In the past, 372.Nm 373had a multi-destination behavior, configurable via 374.Dv NOCLAMP 375flag. 376The behavior is obsolete and is no longer supported. 377This flag is now used to determine whether performing fragmentation when 378the outer protocol is IPv6. 379
