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