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 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 break tunnel operation in an asymmetrically 154routed network. 155It can be turned off by 156.Dv IFF_LINK2 157bit. 158.Ss Route caching 159Processing each packet requires two route lookups: first on the 160packet itself, and second on the tunnel destination. 161This second route can be cached, increasing tunnel performance. 162However, in a dynamically routed network, the tunnel will stick 163to the cached route, ignoring routing table updates. 164Route caching can be enabled with the 165.Dv IFF_LINK0 166flag. 167.\" 168.Ss Miscellaneous 169By default, 170.Nm 171tunnels may not be nested. 172This behavior may be modified at runtime by setting the 173.Xr sysctl 8 174variable 175.Va net.link.gif.max_nesting 176to the desired level of nesting. 177Additionally, 178.Nm 179tunnels are restricted to one per pair of end points. 180Parallel tunnels may be enabled by setting the 181.Xr sysctl 8 182variable 183.Va net.link.gif.parallel_tunnels 184to 1. 185.Sh SEE ALSO 186.Xr inet 4 , 187.Xr inet6 4 , 188.Xr ifconfig 8 189.Rs 190.%A R. Gilligan 191.%A E. Nordmark 192.%B RFC2893 193.%T Transition Mechanisms for IPv6 Hosts and Routers 194.%D August 2000 195.%O ftp://ftp.isi.edu/in-notes/rfc2893.txt 196.Re 197.Rs 198.%A Sally Floyd 199.%A David L. Black 200.%A K. K. Ramakrishnan 201.%T "IPsec Interactions with ECN" 202.%D December 1999 203.%O draft-ietf-ipsec-ecn-02.txt 204.Re 205.\" 206.Sh HISTORY 207The 208.Nm 209device first appeared in the WIDE hydrangea IPv6 kit. 210.\" 211.Sh BUGS 212There are many tunnelling protocol specifications, all 213defined differently from each other. 214The 215.Nm 216device may not interoperate with peers which are based on different specifications, 217and are picky about outer header fields. 218For example, you cannot usually use 219.Nm 220to talk with IPsec devices that use IPsec tunnel mode. 221.Pp 222The current code does not check if the ingress address 223(outer source address) 224configured in the 225.Nm 226interface makes sense. 227Make sure to specify an address which belongs to your node. 228Otherwise, your node will not be able to receive packets from the peer, 229and it will generate packets with a spoofed source address. 230.Pp 231If the outer protocol is IPv4, 232.Nm 233does not try to perform path MTU discovery for the encapsulated packet 234(DF bit is set to 0). 235.Pp 236If the outer protocol is IPv6, path MTU discovery for encapsulated packets 237may affect communication over the interface. 238The first bigger-than-pmtu packet may be lost. 239To avoid the problem, you may want to set the interface MTU for 240.Nm 241to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4. 242.Pp 243The 244.Nm 245device does not translate ICMP messages for the outer header into the inner header. 246.Pp 247In the past, 248.Nm 249had a multi-destination behavior, configurable via 250.Dv IFF_LINK0 251flag. 252The behavior is obsolete and is no longer supported. 253
