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