share/man/man4/gif.4

   1 .\"     $FreeBSD: src/share/man/man4/gif.4,v 1.3.2.11 2003/03/03 18:51:16 trhodes Exp $
   2 .\"     $DragonFly: src/share/man/man4/gif.4,v 1.2 2003/06/17 04:36:59 dillon Exp $
   3 .\"     $KAME: gif.4,v 1.28 2001/05/18 13:15:56 itojun Exp $
   4 .\"
   5 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the project nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd April 10, 1999
  33 .Dt GIF 4
  34 .Os
  35 .Sh NAME
  36 .Nm gif
  37 .Nd generic tunnel interface
  38 .Sh SYNOPSIS
  39 .Cd "pseudo-device gif"
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 interface is a generic tunnelling pseudo device for IPv4 and IPv6.
  44 It can tunnel IPv[46] traffic over IPv[46].
  45 Therefore, there can be four possible configurations.
  46 The behavior of
  47 .Nm
  48 is mainly based on RFC2893 IPv6-over-IPv4 configured tunnel.
  49 On
  50 .Nx ,
  51 .Nm
  52 can also tunnel ISO traffic over IPv[46] using EON encapsulation.
  53 .Pp
  54 Each
  55 .Nm
  56 interface is created at runtime using interface cloning.
  57 This is
  58 most easily done with the
  59 .Dq Nm ifconfig 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 the administrator needs to configure the 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 The administrator also needs to configure the protocol and addresses for the
  75 inner header, with
  76 .Xr ifconfig 8 .
  77 Note that IPv6 link-local addresses
  78 (those that start with
  79 .Li fe80:: )
  80 will be automatically be configured whenever possible.
  81 You may need to remove IPv6 link-local addresses manually using
  82 .Xr ifconfig 8 ,
  83 if you want to disable the use of IPv6 as the inner header
  84 (for example, if you need a pure IPv4-over-IPv6 tunnel).
  85 Finally, you must modify the routing table to route the packets through the
  86 .Nm
  87 interface.
  88 .Pp
  89 The
  90 .Nm
  91 pseudo-device can be configured to be ECN friendly.
  92 This can be configured by
  93 .Dv IFF_LINK1 .
  94 .Ss ECN friendly behavior
  95 The
  96 .Nm
  97 pseudo-device can be configured to be ECN friendly, as described in
  98 .Dv draft-ietf-ipsec-ecn-02.txt .
  99 This is turned off by default, and can be turned on by the
 100 .Dv IFF_LINK1
 101 interface flag.
 102 .Pp
 103 Without
 104 .Dv IFF_LINK1 ,
 105 .Nm
 106 will show normal behavior, as described in RFC2893.
 107 This can be summarized as follows:
 108 .Bl -tag -width "Ingress" -offset indent
 109 .It Ingress
 110 Set outer TOS bit to
 111 .Dv 0 .
 112 .It Egress
 113 Drop outer TOS bit.
 114 .El
 115 .Pp
 116 With
 117 .Dv IFF_LINK1 ,
 118 .Nm
 119 will copy ECN bits
 120 .Dv ( 0x02
 121 and
 122 .Dv 0x01
 123 on IPv4 TOS byte or IPv6 traffic class byte)
 124 on egress and ingress, as follows:
 125 .Bl -tag -width "Ingress" -offset indent
 126 .It Ingress
 127 Copy TOS bits except for ECN CE
 128 (masked with
 129 .Dv 0xfe )
 130 from
 131 inner to outer.
 132 Set ECN CE bit to
 133 .Dv 0 .
 134 .It Egress
 135 Use inner TOS bits with some change.
 136 If outer ECN CE bit is
 137 .Dv 1 ,
 138 enable ECN CE bit on the inner.
 139 .El
 140 .Pp
 141 Note that the ECN friendly behavior violates RFC2893.
 142 This should be used in mutual agreement with the peer.
 143 .Ss Security
 144 A malicious party may try to circumvent security filters by using
 145 tunnelled packets.
 146 For better protection,
 147 .Nm
 148 performs both martian and ingress filtering against the outer source address
 149 on egress.
 150 Note that martian/ingress filters are in no way complete.
 151 You may want to secure your node by using packet filters.
 152 Ingress filtering can be turned off by
 153 .Dv IFF_LINK2
 154 bit.
 155 .\"
 156 .Ss Miscellaneous
 157 By default,
 158 .Nm
 159 tunnels may not be nested.
 160 This behavior may be modified at runtime by setting the
 161 .Xr sysctl 8
 162 variable
 163 .Va net.link.gif.max_nesting
 164 to the desired level of nesting.
 165 Additionally,
 166 .Nm
 167 tunnels are restricted to one per pair of end points.
 168 Parallel tunnels may be enabled by setting the
 169 .Xr sysctl 8
 170 variable
 171 .Va net.link.gif.parallel_tunnels
 172 to 1.
 173 .Sh SEE ALSO
 174 .Xr inet 4 ,
 175 .Xr inet6 4 ,
 176 .Xr gifconfig 8
 177 .Rs
 178 .%A     R. Gilligan
 179 .%A     E. Nordmark
 180 .%B     RFC2893
 181 .%T     Transition Mechanisms for IPv6 Hosts and Routers
 182 .%D     August 2000
 183 .%O     ftp://ftp.isi.edu/in-notes/rfc2893.txt
 184 .Re
 185 .Rs
 186 .%A     Sally Floyd
 187 .%A     David L. Black
 188 .%A     K. K. Ramakrishnan
 189 .%T     "IPsec Interactions with ECN"
 190 .%D     December 1999
 191 .%O     draft-ietf-ipsec-ecn-02.txt
 192 .Re
 193 .\"
 194 .Sh HISTORY
 195 The
 196 .Nm
 197 device first appeared in the WIDE hydrangea IPv6 kit.
 198 .\"
 199 .Sh BUGS
 200 There are many tunnelling protocol specifications, all
 201 defined differently from each other. The
 202 .Nm
 203 pseudo-device may not interoperate with peers which are based on different specifications,
 204 and are picky about outer header fields.
 205 For example, you cannot usually use
 206 .Nm
 207 to talk with IPsec devices that use IPsec tunnel mode.
 208 .Pp
 209 The current code does not check if the ingress address
 210 (outer source address)
 211 configured in the
 212 .Nm
 213 interface makes sense.
 214 Make sure to specify an address which belongs to your node.
 215 Otherwise, your node will not be able to receive packets from the peer,
 216 and it will generate packets with a spoofed source address.
 217 .Pp
 218 If the outer protocol is IPv4,
 219 .Nm
 220 does not try to perform path MTU discovery for the encapsulated packet
 221 (DF bit is set to 0).
 222 .Pp
 223 If the outer protocol is IPv6, path MTU discovery for encapsulated packets
 224 may affect communication over the interface.
 225 The first bigger-than-pmtu packet may be lost.
 226 To avoid the problem, you may want to set the interface MTU for
 227 .Nm
 228 to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4.
 229 .Pp
 230 The
 231 .Nm
 232 pseudo-device does not translate ICMP messages for the outer header into the inner header.
 233 .Pp
 234 In the past,
 235 .Nm
 236 had a multi-destination behavior, configurable via
 237 .Dv IFF_LINK0
 238 flag.
 239 The behavior is obsolete and is no longer supported.
 240 .Pp
 241 It is thought that this is not actually a bug in gif, but rather lies
 242 somewhere around a manipulation of an IPv6 routing table.