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