diff options
Diffstat (limited to 'static/freebsd/man4/gif.4')
| -rw-r--r-- | static/freebsd/man4/gif.4 | 378 |
1 files changed, 378 insertions, 0 deletions
diff --git a/static/freebsd/man4/gif.4 b/static/freebsd/man4/gif.4 new file mode 100644 index 00000000..cc12d91b --- /dev/null +++ b/static/freebsd/man4/gif.4 @@ -0,0 +1,378 @@ +.\" $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. |