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