1.\" $FreeBSD$ 2.\" $KAME: gif.4,v 1.17 2000/06/30 18:31:27 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 37.Tn Generic tunnel interface 38.Sh SYNOPSIS 39.Cd "pseudo-device gif" Op Ar count 40.Sh DESCRIPTION 41The 42.Nm 43interface is a generic tunnelling pseudo 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 RFC1933 IPv6-over-IPv4 configured tunnel. 49.Pp 50To use 51.Nm , 52administrator needs to configure protocol and addresses used for the outer 53header. 54This can be done by using 55.Xr gifconfig 8 , 56or 57.Dv SIOCSIFPHYADDR 58ioctl. 59Also, administrator needs to configure protocol and addresses used for the 60inner header, by using 61.Xr ifconfig 8 . 62Note that IPv6 link-local address 63.Pq those start with Li fe80:: 64will be automatically configured whenever possible. 65You may need to remove IPv6 link-local address manually using 66.Xr ifconfig 8 , 67when you would like to disable the use of IPv6 as inner header 68.Pq like when you need pure IPv4-over-IPv6 tunnel . 69Finally, use routing table to route the packets toward 70.Nm 71interface. 72.Pp 73.Nm 74interface can be configued to perform bidirectional tunnel, or 75multi-destination tunnel. 76This is controlled by 77.Dv IFF_LINK0 78interface flag. 79Also, 80.Nm 81can be configured to be ECN friendly. 82This can be configured by 83.Dv IFF_LINK1 . 84.\" 85.Ss Bidirectional and multi-destination mode 86Usually, 87.Nm 88implements bidirectional tunnel. 89.Xr gifconfig 8 90should configure a tunnel ingress point 91.Pq this node 92and an egress point 93.Pq tunnel endpoint , 94and 95one 96.Nm 97interface will tunnel to only a single tunnel endpoint, 98and accept from only a single tunnel endpoint. 99Source and destination address for outer IP header is always the 100ingress and the egress point configued by 101.Xr gifconfig 8 . 102.Pp 103With 104.Dv IFF_LINK0 105interface flag, 106.Nm 107can be configured to implement multi-destination tunnel. 108With 109.Dv IFF_LINK0 , 110it is able to configure egress point to IPv4 wildcard address 111.Pq Li 0.0.0.0 112or IPv6 unspecified address 113.Pq Li 0::0 . 114In this case, destination address for the outer IP header is 115determined based on the routing table setup. 116Therefore, one 117.Nm 118interface can tunnel to multiple destinations. 119Also, 120.Nm 121will accept tunneled traffic from any outer source address. 122.Pp 123When finding a 124.Nm 125interface from the inbound tunneled traffic, 126bidirectional mode interface is preferred than multi-destination mode interface. 127For example, if you have the following three 128.Nm 129interfaces on node A, tunneled traffic from C to A will match the second 130.Nm 131interface, not the third one. 132.Bl -bullet -compact -offset indent 133.It 134bidirectional, A to B 135.It 136bidirectional, A to C 137.It 138multi-destination, A to any 139.El 140.Pp 141Please note that multi-destination mode is far less secure 142than bidirectional mode. 143Multi-destination mode 144.Nm 145can accept tunneled packet from anybody, 146and can be attacked from a malicious node. 147.Pp 148.Ss ECN friendly behavior 149.Nm 150can be configured to be ECN friendly, as described in 151.Dv draft-ietf-ipsec-ecn-02.txt . 152This is turned off by default, and can be turned on by 153.Dv IFF_LINK1 154interface flag. 155.Pp 156Without 157.Dv IFF_LINK1 , 158.Nm 159will show a normal behavior, like described in RFC1933. 160This can be summarized as follows: 161.Bl -tag -width "Ingress" -offset indent 162.It Ingress 163Set outer TOS bit to 164.Dv 0 . 165.It Egress 166Drop outer TOS bit. 167.El 168.Pp 169With 170.Dv IFF_LINK1 , 171.Nm 172will copy ECN bits 173.Po 174.Dv 0x02 175and 176.Dv 0x01 177on IPv4 TOS byte or IPv6 traffic class byte 178.Pc 179on egress and ingress, as follows: 180.Bl -tag -width "Ingress" -offset indent 181.It Ingress 182Copy TOS bits except for ECN CE 183.Po 184masked with 185.Dv 0xfe 186.Pc 187from 188inner to outer. 189set ECN CE bit to 190.Dv 0 . 191.It Egress 192Use inner TOS bits with some change. 193If outer ECN CE bit is 194.Dv 1 , 195enable ECN CE bit on the inner. 196.El 197.Pp 198Note that the ECN friendly behavior violates RFC1933. 199This should be used in mutual agreement with the peer. 200.Pp 201.Ss Security 202Malicious party may try to circumvent security filters by using 203tunnelled packets. 204For better protection, 205.Nm 206performs martian filter and ingress filter against outer source address, 207on egress. 208Note that martian/ingress filters are no way complete. 209You may want to secure your node by using packet filters. 210.Pp 211As mentioned above, multi-destination mode 212.Pq Dv IFF_LINK0 213is far less secure than bidirectional mode. 214.\" 215.Sh SEE ALSO 216.Xr inet 4 , 217.Xr inet6 4 , 218.Xr gifconfig 8 219.Rs 220.%A R. Gilligan 221.%A E. Nordmark 222.%B RFC1933 223.%T Transition Mechanisms for IPv6 Hosts and Routers 224.%D April 1996 225.%O ftp://ftp.isi.edu/in-notes/rfc1933.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.%O draft-ietf-ipsec-ecn-02.txt 234.Re 235.\" 236.Sh HISTORY 237The 238.Nm 239device first appeared in WIDE hydrangea IPv6 kit. 240.\" 241.Sh BUGS 242There are many tunnelling protocol specifications, 243defined differently from each other. 244.Nm 245may not interoperate with peers which are based on different specifications, 246and are picky about outer header fields. 247For example, you cannot usually use 248.Nm 249to talk with IPsec devices that use IPsec tunnel mode. 250.Pp 251The current code does not check if the ingress address 252.Pq outer source address 253configured to 254.Nm 255makes sense. 256Make sure to configure an address which belongs to your node. 257Otherwise, your node will not be able to receive packets from the peer, 258and your node will generate packets with a spoofed source address. 259.Pp 260.Xr gif 4 261is an 262.Dv IFF_POINTOPOINT 263device, however, it supports NBMA behavior in multi-destination mode. 264