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