share/man/man4/gif.4

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