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