1.\" $KAME: gif.4,v 1.28 2001/05/18 13:15:56 itojun Exp $ 2.\" 3.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the project nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd April 10, 1999 33.Dt GIF 4 34.Os 35.Sh NAME 36.Nm gif 37.Nd generic tunnel interface 38.Sh SYNOPSIS 39.Cd "device gif" 40.Sh DESCRIPTION 41The 42.Nm 43interface is a generic tunnelling device for IPv4 and IPv6. 44It can tunnel IPv[46] traffic over IPv[46]. 45Therefore, there can be four possible configurations. 46The behavior of 47.Nm 48is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel. 49On 50.Nx , 51.Nm 52can also tunnel ISO traffic over IPv[46] using EON encapsulation. 53.Pp 54Each 55.Nm 56interface is created at runtime using interface cloning. 57This is 58most easily done with the 59.Dq Nm ifconfig 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 ifconfig 8 71.Cm tunnel , 72or 73.Dv SIOCSIFPHYADDR 74ioctl. 75The administrator also needs to configure the protocol and addresses for the 76inner header, with 77.Xr ifconfig 8 . 78Note that IPv6 link-local addresses 79(those that start with 80.Li fe80:: ) 81will be automatically be configured whenever possible. 82You may need to remove IPv6 link-local addresses manually using 83.Xr ifconfig 8 , 84if you want to disable the use of IPv6 as the inner header 85(for example, if you need a pure IPv4-over-IPv6 tunnel). 86Finally, you must modify the routing table to route the packets through the 87.Nm 88interface. 89.Pp 90The 91.Nm 92device can be configured to be ECN friendly. 93This can be configured by 94.Dv IFF_LINK1 . 95.Ss ECN friendly behavior 96The 97.Nm 98device can be configured to be ECN friendly, as described in 99.Dv draft-ietf-ipsec-ecn-02.txt . 100This is turned off by default, and can be turned on by the 101.Dv IFF_LINK1 102interface flag. 103.Pp 104Without 105.Dv IFF_LINK1 , 106.Nm 107will show normal behavior, as described in RFC2893. 108This can be summarized as follows: 109.Bl -tag -width "Ingress" -offset indent 110.It Ingress 111Set outer TOS bit to 112.Dv 0 . 113.It Egress 114Drop outer TOS bit. 115.El 116.Pp 117With 118.Dv IFF_LINK1 , 119.Nm 120will copy ECN bits 121.Dv ( 0x02 122and 123.Dv 0x01 124on IPv4 TOS byte or IPv6 traffic class byte) 125on egress and ingress, as follows: 126.Bl -tag -width "Ingress" -offset indent 127.It Ingress 128Copy TOS bits except for ECN CE 129(masked with 130.Dv 0xfe ) 131from 132inner to outer. 133Set ECN CE bit to 134.Dv 0 . 135.It Egress 136Use inner TOS bits with some change. 137If outer ECN CE bit is 138.Dv 1 , 139enable ECN CE bit on the inner. 140.El 141.Pp 142Note that the ECN friendly behavior violates RFC2893. 143This should be used in mutual agreement with the peer. 144.Ss Security 145A malicious party may try to circumvent security filters by using 146tunnelled packets. 147For better protection, 148.Nm 149performs both martian and ingress filtering against the outer source address 150on egress. 151Note that martian/ingress filters are in no way complete. 152You may want to secure your node by using packet filters. 153Ingress filtering can be turned off by 154.Dv IFF_LINK2 155bit. 156.\" 157.Ss Miscellaneous 158By default, 159.Nm 160tunnels may not be nested. 161This behavior may be modified at runtime by setting the 162.Xr sysctl 8 163variable 164.Va net.link.gif.max_nesting 165to the desired level of nesting. 166Additionally, 167.Nm 168tunnels are restricted to one per pair of end points. 169Parallel tunnels may be enabled by setting the 170.Xr sysctl 8 171variable 172.Va net.link.gif.parallel_tunnels 173to 1. 174.Sh SEE ALSO 175.Xr inet 4 , 176.Xr inet6 4 , 177.Xr ifconfig 8 178.Rs 179.%A R. Gilligan 180.%A E. Nordmark 181.%B RFC2893 182.%T Transition Mechanisms for IPv6 Hosts and Routers 183.%D August 2000 184.%O ftp://ftp.isi.edu/in-notes/rfc2893.txt 185.Re 186.Rs 187.%A Sally Floyd 188.%A David L. Black 189.%A K. K. Ramakrishnan 190.%T "IPsec Interactions with ECN" 191.%D December 1999 192.%O draft-ietf-ipsec-ecn-02.txt 193.Re 194.\" 195.Sh HISTORY 196The 197.Nm 198device first appeared in the WIDE hydrangea IPv6 kit. 199.\" 200.Sh BUGS 201There are many tunnelling protocol specifications, all 202defined differently from each other. 203The 204.Nm 205device may not interoperate with peers which are based on different specifications, 206and are picky about outer header fields. 207For example, you cannot usually use 208.Nm 209to talk with IPsec devices that use IPsec tunnel mode. 210.Pp 211The current code does not check if the ingress address 212(outer source address) 213configured in the 214.Nm 215interface makes sense. 216Make sure to specify an address which belongs to your node. 217Otherwise, your node will not be able to receive packets from the peer, 218and it will generate packets with a spoofed source address. 219.Pp 220If the outer protocol is IPv4, 221.Nm 222does not try to perform path MTU discovery for the encapsulated packet 223(DF bit is set to 0). 224.Pp 225If the outer protocol is IPv6, path MTU discovery for encapsulated packets 226may affect communication over the interface. 227The first bigger-than-pmtu packet may be lost. 228To avoid the problem, you may want to set the interface MTU for 229.Nm 230to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. 231.Pp 232The 233.Nm 234device does not translate ICMP messages for the outer header into the inner header. 235.Pp 236In the past, 237.Nm 238had a multi-destination behavior, configurable via 239.Dv IFF_LINK0 240flag. 241The behavior is obsolete and is no longer supported. 242
