path: root/static/freebsd/man4/gif.4

.\"	$KAME: gif.4,v 1.28 2001/05/18 13:15:56 itojun Exp $
.\"
.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
.\" Copyright (C) 2024 Hiroki Sato <hrs@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the project nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd August 27, 2025
.Dt GIF 4
.Os
.Sh NAME
.Nm gif
.Nd generic tunnel interface
.Sh SYNOPSIS
.Cd "device gif"
.Sh DESCRIPTION
The
.Nm
interface is a generic tunnelling device for IPv4 and IPv6.
It can tunnel IPv[46] traffic over IPv[46].
Therefore, there can be four possible configurations.
The behavior of
.Nm
is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel.
On
.Nx ,
.Nm
can also tunnel ISO traffic over IPv[46] using EON encapsulation.
Note that
.Nm
does not perform GRE encapsulation; use
.Xr gre 4
for GRE encapsulation.
.Pp
The
.Nm
interface can also tunnel Ethernet traffic over IPv4 or IPv6
when combined with a
.Xr if_bridge 4
interface using EtherIP protocol.
See
.Xr if_bridge 4
for detailed setup.
.Pp
Each
.Nm
interface is created at runtime using interface cloning.
This is
most easily done with the
.Dq Nm ifconfig Cm create
command or using the
.Va ifconfig_ Ns Aq Ar interface
variable in
.Xr rc.conf 5 .
.Pp
To use
.Nm ,
the administrator needs to configure the protocol and addresses used for
the outer header.
This can be done by using
.Xr ifconfig 8
.Cm tunnel ,
or
.Dv SIOCSIFPHYADDR
ioctl.
The administrator also needs to configure the protocol and addresses for the
inner header, with
.Xr ifconfig 8 .
Note that IPv6 link-local addresses
.Pq those that start with Li fe80\&:\&:
will be automatically configured whenever possible.
You may need to remove IPv6 link-local addresses manually using
.Xr ifconfig 8 ,
if you want to disable the use of IPv6 as the inner header
(for example, if you need a pure IPv4-over-IPv6 tunnel).
Finally, you must modify the routing table to route the packets through the
.Nm
interface.
.Ss MTU Configuration and Path MTU Discovery
The
.Nm
interface uses the fixed length,
.Li 1280 ,
to determine whether the outgoing IPv6 packets are split.
This means the MTU value configured on the interface will be ignored
when the outer protocol is IPv6.
When the
.Dv NOCLAMP
interface flag is set,
.Nm
uses the same configured value as IPv4 communications.
This behavior prevents potential issues when the path MTU is
smaller than the interface MTU.
This section describes the reason why the default behavior is different.
The
.Dv NOCLAMP
interface flag can be set using the following command:
.Pp
.Dl ifconfig Ar gif0 Cm noclamp
.Pp
and clear the flag using the following:
.Pp
.Dl ifconfig Ar gif0 Cm -noclamp
.Pp
where
.Ar gif0
is the actual interface name.
.Pp
A tunnel interface always has an implicit smaller MTU for the inner protocol
than the outer protocol because of the additional header.
Note that the interface MTU on a
.Nm
interface,
the default value is
.Li 1280 ,
is used as MTU for the outer protocol.
This means that the MTU for the inner protocol varies depending on the
outer protocol header length.
If an outgoing packet bigger than the inner protocol MTU arrives at a
.Nm
interface for encapsulation,
it will be split into fragments.
Specifically,
if IPv4 is used as the outer protocol,
the inner is 20 octets smaller than the interface MTU.
In the case of the default interface MTU,
.Li 1280 ,
inner packets bigger than
.Li 1260
will be fragmented.
In the case of IPv6,
the inner is 40 octets smaller than the outer.
.Pp
This fragmentation is not harmful though it can degrade the
performance.
Note that while an increased MTU on
.Nm
interface helps to mitigate this reduced performance issue,
it can also cause packet losses on the intermediate narrowest path
between the two communication endpoints in IPv6.
IPv6 allows fragmentation only on the sender,
not on the routers in the communication path.
A big outgoing packet will be dropped on a router with a smaller MTU.
.Pp
In normal IPv6 communication,
an ICMPv6 Packet Too Big error will be sent back to the sender,
who can adjust the packet length and re-send it.
This process is performed in the upper protocols than L3,
such as TCP,
and makes the packet length shorter so that packets go through
the path without fragmentation.
This behavior is known as path MTU discovery.
.Pp
When using a
.Nm
interface,
the Packet Too Big message is generated for the outer protocol.
Since the
.Nm
interface does not translate this error to the inner protocol,
the inner protocol sees it just as a packet loss with no useful
information to adjust the length of the next packets.
In this situation,
path MTU discovery does not work,
and communications of the inner protocol
become stalled.
.Pp
In order to avoid this,
a
.Nm
interface silently splits a packet of over 1240 octets into fragments to make
the outer protocol packets equal or shorter than 1280 octets,
even when the interface MTU is configured as larger than 1280.
Note that this occurs only when the outer protocol is IPv6.
.Li 1280
is the smallest MTU in IPv6 and guarantees no packet loss occurs
on intermediate routers.
.Pp
As mentioned earlier,
the performance is sub-optimal if the actual path MTU is larger than
.Li 1280 .
A typical confusing scenario is as follows.
The
.Nm
interface can have Ethernet,
whose MTU is usually 1500,
as the inner protocol.
It is called an EtherIP tunnel,
and can be configured by adding the
.Nm
interface as a member of
.Xr if_bridge 4
interface.
The
.Xr if_bridge 4
interface forcibly changes the MTU of the
.Nm
interface with those for the other member interfaces,
which are likely 1500.
In this case,
a situation in which the MTU of the
.Nm
interface is 1500 but fragmentation in 1280 octets always occurs.
.Pp
The default behavior is most conservative to prevent confusing packet loss.
Depending on the network configuration,
enabling the
.Dv NOCLAMP
interface flag might be helpful for better performance.
It is crucial to ensure that the path MTU is equal to or larger than
the interface MTU when enabling this flag.
.Ss ECN friendly behavior
The
.Nm
device can be configured to be ECN friendly, as described in
.Dv draft-ietf-ipsec-ecn-02.txt .
This is turned off by default, and can be turned on by the
.Dv IFF_LINK1
interface flag.
.Pp
Without
.Dv IFF_LINK1 ,
.Nm
will show normal behavior, as described in RFC2893.
This can be summarized as follows:
.Bl -tag -width "Ingress" -offset indent
.It Ingress
Set outer TOS bit to
.Dv 0 .
.It Egress
Drop outer TOS bit.
.El
.Pp
With
.Dv IFF_LINK1 ,
.Nm
will copy ECN bits
.Dv ( 0x02
and
.Dv 0x01
on IPv4 TOS byte or IPv6 traffic class byte)
on egress and ingress, as follows:
.Bl -tag -width "Ingress" -offset indent
.It Ingress
Copy TOS bits except for ECN CE
(masked with
.Dv 0xfe )
from
inner to outer.
Set ECN CE bit to
.Dv 0 .
.It Egress
Use inner TOS bits with some change.
If outer ECN CE bit is
.Dv 1 ,
enable ECN CE bit on the inner.
.El
.Pp
Note that the ECN friendly behavior violates RFC2893.
This should be used in mutual agreement with the peer.
.Ss Security
A malicious party may try to circumvent security filters by using
tunnelled packets.
For better protection,
.Nm
performs both martian and ingress filtering against the outer source address
on egress.
Note that martian/ingress filters are in no way complete.
You may want to secure your node by using packet filters.
Ingress filtering can break tunnel operation in an asymmetrically
routed network.
It can be turned off by
.Dv IFF_LINK2
bit.
.Ss Miscellaneous
By default,
.Nm
tunnels may not be nested.
This behavior may be modified at runtime by setting the
.Xr sysctl 8
variable
.Va net.link.gif.max_nesting
to the desired level of nesting.
.Sh SEE ALSO
.Xr gre 4 ,
.Xr if_bridge 4 ,
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr ifconfig 8
.Rs
.%A R. Gilligan
.%A E. Nordmark
.%B RFC2893
.%T Transition Mechanisms for IPv6 Hosts and Routers
.%D August 2000
.%U http://tools.ietf.org/html/rfc2893
.Re
.Rs
.%A Sally Floyd
.%A David L. Black
.%A K. K. Ramakrishnan
.%T "IPsec Interactions with ECN"
.%D December 1999
.%O draft-ietf-ipsec-ecn-02.txt
.Re
.Rs
.%A R. Housley
.%A S. Hollenbeck
.%T EtherIP: Tunneling Ethernet Frames in IP Datagrams
.%R RFC 3378
.%D September 2002
.Re
.\"
.Sh HISTORY
The
.Nm
device first appeared in the WIDE hydrangea IPv6 kit.
.\"
.Sh BUGS
There are many tunnelling protocol specifications, all
defined differently from each other.
The
.Nm
device may not interoperate with peers which are based on different
specifications,
and are picky about outer header fields.
For example, you cannot usually use
.Nm
to talk with IPsec devices that use IPsec tunnel mode.
.Pp
If the outer protocol is IPv4,
.Nm
does not try to perform path MTU discovery for the encapsulated packet
(DF bit is set to 0).
.Pp
If the outer protocol is IPv6, path MTU discovery for encapsulated packets
may affect communication over the interface.
The first bigger-than-pmtu packet may be lost.
To avoid the problem, you may want to set the interface MTU for
.Nm
to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4.
.Pp
The
.Nm
device does not translate ICMP messages for the outer header into the inner
header.
.Pp
In the past,
.Nm
had a multi-destination behavior, configurable via
.Dv NOCLAMP
flag.
The behavior is obsolete and is no longer supported.
This flag is now used to determine whether performing fragmentation when
the outer protocol is IPv6.