bsd/man/man4/gif.4

   1 .\"     $FreeBSD: src/share/man/man4/gif.4,v 1.3.2.9 2002/03/25 10:44:05 brooks Exp $
   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 "pseudo-device gif"
  39 .Sh DESCRIPTION
  40 The
  41 .Nm
  42 interface is a generic tunnelling pseudo device for IPv4 and IPv6.
  43 It can tunnel IPv[46] traffic over IPv[46].
  44 Therefore, there can be four possible configurations.
  45 The behavior of
  46 .Nm
  47 is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel.
  48 On
  49 .Nx ,
  50 .Nm
  51 can also tunnel ISO traffic over IPv[46] using EON encapsulation.
  52 .Pp
  53 Each
  54 .Nm
  55 interface is created at runtime using interface cloning.
  56 This is
  57 most easily done with the
  58 .Xr ifconfig 8
  59 .Cm create
  60 command or using the
  61 .Va gifconfig_ Ns Aq Ar interface
  62 variable in
  63 .Xr rc.conf 5 .
  64 .Pp
  65 To use
  66 .Nm ,
  67 administrator needs to configure protocol and addresses used for the outer
  68 header.
  69 This can be done by using
  70 .Xr gifconfig 8 ,
  71 or
  72 .Dv SIOCSIFPHYADDR
  73 ioctl.
  74 Also, administrator needs to configure protocol and addresses used for the
  75 inner header, by using
  76 .Xr ifconfig 8 .
  77 Note that IPv6 link-local address
  78 (those start with
  79 .Li fe80:: )
  80 will be automatically configured whenever possible.
  81 You may need to remove IPv6 link-local address manually using
  82 .Xr ifconfig 8 ,
  83 when you would like to disable the use of IPv6 as inner header
  84 (like when you need pure IPv4-over-IPv6 tunnel).
  85 Finally, use routing table to route the packets toward
  86 .Nm
  87 interface.
  88 .Pp
  89 .Nm
  90 can be configured to be ECN friendly.
  91 This can be configured by
  92 .Dv IFF_LINK1 .
  93 .Ss ECN friendly behavior
  94 .Nm
  95 can be configured to be ECN friendly, as described in
  96 .Dv draft-ietf-ipsec-ecn-02.txt .
  97 This is turned off by default, and can be turned on by
  98 .Dv IFF_LINK1
  99 interface flag.
 100 .Pp
 101 Without
 102 .Dv IFF_LINK1 ,
 103 .Nm
 104 will show a normal behavior, like described in RFC2893.
 105 This can be summarized as follows:
 106 .Bl -tag -width "Ingress" -offset indent
 107 .It Ingress
 108 Set outer TOS bit to
 109 .Dv 0 .
 110 .It Egress
 111 Drop outer TOS bit.
 112 .El
 113 .Pp
 114 With
 115 .Dv IFF_LINK1 ,
 116 .Nm
 117 will copy ECN bits
 118 .Dv ( 0x02
 119 and
 120 .Dv 0x01
 121 on IPv4 TOS byte or IPv6 traffic class byte)
 122 on egress and ingress, as follows:
 123 .Bl -tag -width "Ingress" -offset indent
 124 .It Ingress
 125 Copy TOS bits except for ECN CE
 126 (masked with
 127 .Dv 0xfe )
 128 from
 129 inner to outer.
 130 Set ECN CE bit to
 131 .Dv 0 .
 132 .It Egress
 133 Use inner TOS bits with some change.
 134 If outer ECN CE bit is
 135 .Dv 1 ,
 136 enable ECN CE bit on the inner.
 137 .El
 138 .Pp
 139 Note that the ECN friendly behavior violates RFC2893.
 140 This should be used in mutual agreement with the peer.
 141 .Ss Security
 142 Malicious party may try to circumvent security filters by using
 143 tunnelled packets.
 144 For better protection,
 145 .Nm
 146 performs martian filter and ingress filter against outer source address,
 147 on egress.
 148 Note that martian/ingress filters are no way complete.
 149 You may want to secure your node by using packet filters.
 150 Ingress filter can be turned off by
 151 .Dv IFF_LINK2
 152 bit.
 153 .\"
 154 .Ss Miscellaneous
 155 By default,
 156 .Nm
 157 tunnels may not be nested.
 158 This behavior may be modified at runtime by setting the
 159 .Xr sysctl 8
 160 variable
 161 .Va net.link.gif.max_nesting
 162 to the desired level of nesting.
 163 Additionally,
 164 .Nm
 165 tunnels are restricted to one per pair of end points.
 166 Parallel tunnels may be enabled by setting the
 167 .Xr sysctl 8
 168 variable
 169 .Va net.link.gif.parallel_tunnels
 170 to 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
 193 The
 194 .Nm
 195 device first appeared in WIDE hydrangea IPv6 kit.
 196 .\"
 197 .Sh BUGS
 198 There are many tunnelling protocol specifications,
 199 defined differently from each other.
 200 .Nm
 201 may not interoperate with peers which are based on different specifications,
 202 and are picky about outer header fields.
 203 For example, you cannot usually use
 204 .Nm
 205 to talk with IPsec devices that use IPsec tunnel mode.
 206 .Pp
 207 The current code does not check if the ingress address
 208 (outer source address)
 209 configured to
 210 .Nm
 211 makes sense.
 212 Make sure to configure an address which belongs to your node.
 213 Otherwise, your node will not be able to receive packets from the peer,
 214 and your node will generate packets with a spoofed source address.
 215 .Pp
 216 If the outer protocol is IPv4,
 217 .Nm
 218 does not try to perform path MTU discovery for the encapsulated packet
 219 (DF bit is set to 0).
 220 .Pp
 221 If the outer protocol is IPv6, path MTU discovery for encapsulated packet
 222 may affect communication over the interface.
 223 The first bigger-than-pmtu packet may be lost.
 224 To avoid the problem, you may want to set the interface MTU for
 225 .Nm
 226 to 1240 or smaller, when outer header is IPv6 and inner header is IPv4.
 227 .Pp
 228 .Nm
 229 does not translate ICMP messages for outer header into inner header.
 230 .Pp
 231 In the past,
 232 .Nm
 233 had a multi-destination behavior, configurable via
 234 .Dv IFF_LINK0
 235 flag.
 236 The behavior was obsoleted and is no longer supported.
 237 .Pp
 238 It is thought that this is not actually a bug in gif, but rather lies
 239 somewhere around a manipulation of an IPv6 routing table.