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