1.\" $FreeBSD: src/share/man/man4/gif.4,v 1.3.2.9 2002/03/25 10:44:05 brooks 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 tunneling 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 RFC2893 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 done with the 57.Xr ifconfig 8 58.Cm create 59command. 60.Pp 61To use 62.Nm , 63administrator needs to configure protocol and addresses used for the outer 64header. 65This can be done by using the 66.Dv SIOCSIFPHYADDR 67ioctl. 68Also, administrator needs to configure protocol and addresses used for the 69inner header, by using 70.Xr ifconfig 8 . 71Note that IPv6 link-local address 72(those start with 73.Li fe80:: ) 74will be automatically configured whenever possible. 75You may need to remove IPv6 link-local address manually using 76.Xr ifconfig 8 , 77when you would like to disable the use of IPv6 as inner header 78(like when you need pure IPv4-over-IPv6 tunnel). 79Finally, use routing table to route the packets toward 80.Nm 81interface. 82.Pp 83.Nm 84can be configured to be ECN friendly. 85This can be configured by 86.Dv IFF_LINK1 . 87.Ss ECN friendly behavior 88.Nm 89can be configured to be ECN friendly, as described in 90.Dv draft-ietf-ipsec-ecn-02.txt . 91This is turned off by default, and can be turned on by 92.Dv IFF_LINK1 93interface flag. 94.Pp 95Without 96.Dv IFF_LINK1 , 97.Nm 98will show a normal behavior, like described in RFC2893. 99This can be summarized as follows: 100.Bl -tag -width "Ingress" -offset indent 101.It Ingress 102Set outer TOS bit to 103.Dv 0 . 104.It Egress 105Drop outer TOS bit. 106.El 107.Pp 108With 109.Dv IFF_LINK1 , 110.Nm 111will copy ECN bits 112.Dv ( 0x02 113and 114.Dv 0x01 115on IPv4 TOS byte or IPv6 traffic class byte) 116on egress and ingress, as follows: 117.Bl -tag -width "Ingress" -offset indent 118.It Ingress 119Copy TOS bits except for ECN CE 120(masked with 121.Dv 0xfe ) 122from 123inner to outer. 124Set ECN CE bit to 125.Dv 0 . 126.It Egress 127Use inner TOS bits with some change. 128If outer ECN CE bit is 129.Dv 1 , 130enable ECN CE bit on the inner. 131.El 132.Pp 133Note that the ECN friendly behavior violates RFC2893. 134This should be used in mutual agreement with the peer. 135.Ss Security 136Malicious party may try to circumvent security filters by using 137tunnelled packets. 138For better protection, 139.Nm 140performs martian filter and ingress filter against outer source address, 141on egress. 142Note that martian/ingress filters are no way complete. 143You may want to secure your node by using packet filters. 144Ingress filter can be turned off by 145.Dv IFF_LINK2 146bit. 147.\" 148.Ss Miscellaneous 149By default, 150.Nm 151tunnels may not be nested. 152This behavior may be modified at runtime by setting the 153.Xr sysctl 8 154variable 155.Va net.link.gif.max_nesting 156to the desired level of nesting. 157Additionally, 158.Nm 159tunnels are restricted to one per pair of end points. 160Parallel tunnels may be enabled by setting the 161.Xr sysctl 8 162variable 163.Va net.link.gif.parallel_tunnels 164to 1. 165.Sh SEE ALSO 166.Xr inet 4 , 167.Xr inet6 4 , 168.Rs 169.%A R. Gilligan 170.%A E. Nordmark 171.%B RFC2893 172.%T Transition Mechanisms for IPv6 Hosts and Routers 173.%D August 2000 174.%O ftp://ftp.isi.edu/in-notes/rfc2893.txt 175.Re 176.Rs 177.%A Sally Floyd 178.%A David L. Black 179.%A K. K. Ramakrishnan 180.%T "IPsec Interactions with ECN" 181.%D December 1999 182.%O draft-ietf-ipsec-ecn-02.txt 183.Re 184.\" 185.Sh HISTORY 186The 187.Nm 188device first appeared in WIDE hydrangea IPv6 kit. 189.\" 190.Sh BUGS 191There are many tunneling protocol specifications, 192defined differently from each other. 193.Nm 194may not interoperate with peers which are based on different specifications, 195and are picky about outer header fields. 196For example, you cannot usually use 197.Nm 198to talk with IPsec devices that use IPsec tunnel mode. 199.Pp 200The current code does not check if the ingress address 201(outer source address) 202configured to 203.Nm 204makes sense. 205Make sure to configure an address which belongs to your node. 206Otherwise, your node will not be able to receive packets from the peer, 207and your node will generate packets with a spoofed source address. 208.Pp 209If the outer protocol is IPv4, 210.Nm 211does not try to perform path MTU discovery for the encapsulated packet 212(DF bit is set to 0). 213.Pp 214If the outer protocol is IPv6, path MTU discovery for encapsulated packet 215may affect communication over the interface. 216The first bigger-than-pmtu packet may be lost. 217To avoid the problem, you may want to set the interface MTU for 218.Nm 219to 1240 or smaller, when outer header is IPv6 and inner header is IPv4. 220.Pp 221.Nm 222does not translate ICMP messages for outer header into inner header. 223.Pp 224In the past, 225.Nm 226had a multi-destination behavior, configurable via 227.Dv IFF_LINK0 228flag. 229The behavior was obsoleted and is no longer supported. 230.Pp 231It is thought that this is not actually a bug in gif, but rather lies 232somewhere around a manipulation of an IPv6 routing table. 233
