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