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