1.\" $NetBSD: gif.4,v 1.30 2010/01/15 19:23:38 joerg 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 January 15, 2009 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 tunneling 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 RFC 2893 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.Cm create 59and 60.Cm 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 RFC 2893. 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.Dv ( 0x02 110and 111.Dv 0x01 112on IPv4 TOS byte or IPv6 traffic class byte) 113on egress and ingress, as follows: 114.Bl -tag -width "Ingress" -offset indent 115.It Ingress 116Copy TOS bits except for ECN CE 117(masked with 118.Dv 0xfe ) 119from 120inner to outer. 121set ECN CE bit to 122.Dv 0 . 123.It Egress 124Use inner TOS bits with some change. 125If outer ECN CE bit is 126.Dv 1 , 127enable ECN CE bit on the inner. 128.El 129.Pp 130Note that the ECN friendly behavior violates RFC 2893. 131This should be used in mutual agreement with the peer. 132.Ss Packet format 133Every inner packet is encapsulated in an outer packet. 134The inner packet may be IPv4, IPv6, or ISO CLNP. 135The outer packet may be IPv4 or IPv6, and has all the 136usual IP headers, including a protocol field that identifies the 137type of inner packet. 138.Pp 139When the inner packet is IPv4, the protocol field of the outer packet 140is 4 141.Dv ( IPPROTO_IPV4 ) . 142When the inner packet is IPv6, the protocol field of the outer packet 143is 41 144.Dv ( IPPROTO_IPV6 ) . 145When the inner packet is ISO CNLP, the protocol field of the outer packet 146is 80 147.Dv ( IPPROTO_EON ) . 148.Ss Security 149Malicious party may try to circumvent security filters by using 150tunneled packets. 151For better protection, 152.Nm 153performs martian filter and ingress filter against outer source address, 154on egress. 155Note that martian/ingress filters are no way complete. 156You may want to secure your node by using packet filters. 157Ingress filter can be turned off by 158.Dv IFF_LINK2 159bit. 160.\" 161.Sh EXAMPLES 162Configuration example: 163.Bd -literal 164Host X--NetBSD A ----------------tunnel---------- cisco D------Host E 165 \\ | 166 \\ / 167 +-----Router B--------Router C---------+ 168 169.Ed 170On 171.Nx 172system A 173.Ns ( Nx ) : 174.Bd -literal 175 # route add default B 176 # ifconfig gifN create 177 # ifconfig gifN A netmask 0xffffffff tunnel A D up 178 # route add E 0 179 # route change E -ifp gif0 180.Ed 181.Pp 182On Host D (Cisco): 183.Bd -literal 184 Interface TunnelX 185 ip unnumbered D ! e.g. address from Ethernet interface 186 tunnel source D ! e.g. address from Ethernet interface 187 tunnel destination A 188 ip route C <some interface and mask> 189 ip route A mask C 190 ip route X mask tunnelX 191.Ed 192.Pp 193or on Host D 194.Ns ( Nx ) : 195.Bd -literal 196 # route add default C 197 # ifconfig gifN D A 198.Ed 199.Pp 200If all goes well, you should see packets flowing. 201.Pp 202If you want to reach Host A over the tunnel (from the Cisco D), then 203you have to have an alias on Host A for e.g. the Ethernet interface like: 204.Ic ifconfig Ar <etherif> alias Y 205and on the cisco 206.Ic ip Ar route Y mask tunnelX . 207.Sh SEE ALSO 208.Xr etherip 4 , 209.Xr inet 4 , 210.Xr inet6 4 , 211.Xr ifconfig 8 212.Rs 213.%A C. Perkins 214.%B RFC 2003 215.%T IP Encapsulation within IP 216.%D October 1996 217.%U ftp://ftp.isi.edu/in-notes/rfc2003.txt 218.Re 219.Rs 220.%A R. Gilligan 221.%A E. Nordmark 222.%B RFC 2893 223.%T Transition Mechanisms for IPv6 Hosts and Routers 224.%D August 2000 225.%U ftp://ftp.isi.edu/in-notes/rfc2893.txt 226.Re 227.Rs 228.%A Sally Floyd 229.%A David L. Black 230.%A K. K. Ramakrishnan 231.%T "IPsec Interactions with ECN" 232.%D December 1999 233.%U http://datatracker.ietf.org/internet-drafts/draft-ietf-ipsec-ecn/ 234.Re 235.Rs 236.%A F. Baker 237.%A P. Savola 238.%B RFC 3704 239.%T Ingress Filtering for Multihomed Networks 240.%D March 2004 241.%U ftp://ftp.isi.edu/in-notes/rfc3704.txt 242.Re 243.\" 244.Sh STANDARDS 245IPv4 over IPv4 encapsulation is compatible with RFC 2003. 246IPv6 over IPv4 encapsulation is compatible with RFC 2893. 247.\" 248.Sh HISTORY 249The 250.Nm 251device first appeared in WIDE hydrangea IPv6 kit. 252.\" 253.Sh BUGS 254There are many tunneling protocol specifications, 255defined differently from each other. 256.Nm 257may not interoperate with peers which are based on different specifications, 258and are picky about outer header fields. 259For example, you cannot usually use 260.Nm 261to talk with IPsec devices that use IPsec tunnel mode. 262.Pp 263The current code does not check if the ingress address 264.Pq outer source address 265configured to 266.Nm 267makes sense. 268Make sure to configure an address which belongs to your node. 269Otherwise, your node will not be able to receive packets from the peer, 270and your node will generate packets with a spoofed source address. 271.Pp 272If the outer protocol is IPv6, path MTU discovery for encapsulated packet 273may affect communication over the interface. 274.Pp 275In the past, 276.Nm 277had a multi-destination behavior, configurable via 278.Dv IFF_LINK0 279flag. 280The behavior was obsoleted and is no longer supported. 281