1.\" $FreeBSD: src/share/man/man4/gif.4,v 1.3.2.11 2003/03/03 18:51:16 trhodes Exp $ 2.\" $KAME: gif.4,v 1.28 2001/05/18 13:15:56 itojun Exp $ 3.\" 4.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 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 April 10, 1999 32.Dt GIF 4 33.Os 34.Sh NAME 35.Nm gif 36.Nd generic tunnel interface 37.Sh SYNOPSIS 38.Cd "pseudo-device gif" 39.Sh DESCRIPTION 40The 41.Nm 42interface is a generic tunnelling pseudo 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 RFC 2893 IPv6-over-IPv4 configured tunnel. 48On 49.Nx , 50.Nm 51can also tunnel ISO traffic over IPv[46] using EON encapsulation. 52.Pp 53Each 54.Nm 55interface is created at runtime using interface cloning. 56This is 57most easily done with the 58.Dq Nm ifconfig Cm create 59command or using the 60.Va gifconfig_ Ns Aq Ar interface 61variable in 62.Xr rc.conf 5 . 63.Pp 64To use 65.Nm , 66the administrator needs to configure the protocol and addresses used for the outer 67header. 68This can be done by using 69.Xr gifconfig 8 , 70or 71.Dv SIOCSIFPHYADDR 72ioctl. 73The administrator also needs to configure the protocol and addresses for the 74inner header, with 75.Xr ifconfig 8 . 76Note that IPv6 link-local addresses 77(those that start with 78.Li fe80:: ) 79will be automatically configured whenever possible. 80You may need to remove IPv6 link-local addresses manually using 81.Xr ifconfig 8 , 82if you want to disable the use of IPv6 as the inner header 83(for example, if you need a pure IPv4-over-IPv6 tunnel). 84Finally, you must modify the routing table to route the packets through the 85.Nm 86interface. 87.Pp 88The 89.Nm 90pseudo-device can be configured to be ECN friendly. 91This can be configured by 92.Dv IFF_LINK1 . 93.Ss ECN friendly behavior 94The 95.Nm 96pseudo-device can be configured to be ECN friendly, as described in 97.Dv draft-ietf-ipsec-ecn-02.txt . 98This is turned off by default, and can be turned on by the 99.Dv IFF_LINK1 100interface flag. 101.Pp 102Without 103.Dv IFF_LINK1 , 104.Nm 105will show normal behavior, as described in RFC 2893. 106This can be summarized as follows: 107.Bl -tag -width "Ingress" -offset indent 108.It Ingress 109Set outer TOS bit to 110.Dv 0 . 111.It Egress 112Drop outer TOS bit. 113.El 114.Pp 115With 116.Dv IFF_LINK1 , 117.Nm 118will copy ECN bits 119.Dv ( 0x02 120and 121.Dv 0x01 122on IPv4 TOS byte or IPv6 traffic class byte) 123on egress and ingress, as follows: 124.Bl -tag -width "Ingress" -offset indent 125.It Ingress 126Copy TOS bits except for ECN CE 127(masked with 128.Dv 0xfe ) 129from 130inner to outer. 131Set ECN CE bit to 132.Dv 0 . 133.It Egress 134Use inner TOS bits with some change. 135If outer ECN CE bit is 136.Dv 1 , 137enable ECN CE bit on the inner. 138.El 139.Pp 140Note that the ECN friendly behavior violates RFC 2893. 141This should be used in mutual agreement with the peer. 142.Ss Security 143A malicious party may try to circumvent security filters by using 144tunnelled packets. 145For better protection, 146.Nm 147performs both martian and ingress filtering against the outer source address 148on egress. 149Note that martian/ingress filters are in no way complete. 150You may want to secure your node by using packet filters. 151Ingress filtering can be turned off by 152.Dv IFF_LINK2 153bit. 154.\" 155.Ss Miscellaneous 156By default, 157.Nm 158tunnels may not be nested. 159This behavior may be modified at runtime by setting the 160.Xr sysctl 8 161variable 162.Va net.link.gif.max_nesting 163to the desired level of nesting. 164Additionally, 165.Nm 166tunnels are restricted to one per pair of end points. 167Parallel tunnels may be enabled by setting the 168.Xr sysctl 8 169variable 170.Va net.link.gif.parallel_tunnels 171to 1. 172.Sh SEE ALSO 173.Xr inet 4 , 174.Xr inet6 4 , 175.Xr gifconfig 8 176.Rs 177.%A R. Gilligan 178.%A E. Nordmark 179.%B RFC 2893 180.%T Transition Mechanisms for IPv6 Hosts and Routers 181.%D August 2000 182.%U ftp://ftp.isi.edu/in-notes/rfc2893.txt 183.Re 184.Rs 185.%A Sally Floyd 186.%A David L. Black 187.%A K. K. Ramakrishnan 188.%T "IPsec Interactions with ECN" 189.%D December 1999 190.%O draft-ietf-ipsec-ecn-02.txt 191.Re 192.\" 193.Sh HISTORY 194The 195.Nm 196device first appeared in the WIDE hydrangea IPv6 kit. 197.\" 198.Sh BUGS 199There are many tunnelling protocol specifications, all 200defined differently from each other. The 201.Nm 202pseudo-device 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 208The current code does not check if the ingress address 209(outer source address) 210configured in the 211.Nm 212interface makes sense. 213Make sure to specify an address which belongs to your node. 214Otherwise, your node will not be able to receive packets from the peer, 215and it will generate packets with a spoofed source address. 216.Pp 217If the outer protocol is IPv4, 218.Nm 219does not try to perform path MTU discovery for the encapsulated packet 220(DF bit is set to 0). 221.Pp 222If the outer protocol is IPv6, path MTU discovery for encapsulated packets 223may affect communication over the interface. 224The first bigger-than-pmtu packet may be lost. 225To avoid the problem, you may want to set the interface MTU for 226.Nm 227to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. 228.Pp 229The 230.Nm 231pseudo-device does not translate ICMP messages for the outer header into the inner header. 232.Pp 233In the past, 234.Nm 235had a multi-destination behavior, configurable via 236.Dv IFF_LINK0 237flag. 238The behavior is obsolete and is no longer supported. 239.Pp 240It is thought that this is not actually a bug in gif, but rather lies 241somewhere around a manipulation of an IPv6 routing table. 242
