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 August 1, 2011
  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 Note that
  54 .Nm
  55 does not perform GRE encapsulation; use
  56 .Xr gre 4
  57 for GRE encapsulation.
  58 .Pp
  59 Each
  60 .Nm
  61 interface is created at runtime using interface cloning.
  62 This is
  63 most easily done with the
  64 .Dq Nm ifconfig Cm create
  65 command or using the
  66 .Va ifconfig_ Ns Aq Ar interface
  67 variable in
  68 .Xr rc.conf 5 .
  69 .Pp
  70 To use
  71 .Nm ,
  72 the administrator needs to configure the protocol and addresses used for the outer
  73 header.
  74 This can be done by using
  75 .Xr ifconfig 8
  76 .Cm tunnel ,
  77 or
  78 .Dv SIOCSIFPHYADDR
  79 ioctl.
  80 The administrator also needs to configure the protocol and addresses for the
  81 inner header, with
  82 .Xr ifconfig 8 .
  83 Note that IPv6 link-local addresses
  84 (those that start with
  85 .Li fe80:: )
  86 will be automatically configured whenever possible.
  87 You may need to remove IPv6 link-local addresses manually using
  88 .Xr ifconfig 8 ,
  89 if you want to disable the use of IPv6 as the inner header
  90 (for example, if you need a pure IPv4-over-IPv6 tunnel).
  91 Finally, you must modify the routing table to route the packets through the
  92 .Nm
  93 interface.
  94 .Pp
  95 The
  96 .Nm
  97 device can be configured to be ECN friendly.
  98 This can be configured by
  99 .Dv IFF_LINK1 .
 100 .Ss ECN friendly behavior
 101 The
 102 .Nm
 103 device can be configured to be ECN friendly, as described in
 104 .Dv draft-ietf-ipsec-ecn-02.txt .
 105 This is turned off by default, and can be turned on by the
 106 .Dv IFF_LINK1
 107 interface flag.
 108 .Pp
 109 Without
 110 .Dv IFF_LINK1 ,
 111 .Nm
 112 will show normal behavior, as described in RFC2893.
 113 This can be summarized as follows:
 114 .Bl -tag -width "Ingress" -offset indent
 115 .It Ingress
 116 Set outer TOS bit to
 117 .Dv 0 .
 118 .It Egress
 119 Drop outer TOS bit.
 120 .El
 121 .Pp
 122 With
 123 .Dv IFF_LINK1 ,
 124 .Nm
 125 will copy ECN bits
 126 .Dv ( 0x02
 127 and
 128 .Dv 0x01
 129 on IPv4 TOS byte or IPv6 traffic class byte)
 130 on egress and ingress, as follows:
 131 .Bl -tag -width "Ingress" -offset indent
 132 .It Ingress
 133 Copy TOS bits except for ECN CE
 134 (masked with
 135 .Dv 0xfe )
 136 from
 137 inner to outer.
 138 Set ECN CE bit to
 139 .Dv 0 .
 140 .It Egress
 141 Use inner TOS bits with some change.
 142 If outer ECN CE bit is
 143 .Dv 1 ,
 144 enable ECN CE bit on the inner.
 145 .El
 146 .Pp
 147 Note that the ECN friendly behavior violates RFC2893.
 148 This should be used in mutual agreement with the peer.
 149 .Ss Security
 150 A malicious party may try to circumvent security filters by using
 151 tunnelled packets.
 152 For better protection,
 153 .Nm
 154 performs both martian and ingress filtering against the outer source address
 155 on egress.
 156 Note that martian/ingress filters are in no way complete.
 157 You may want to secure your node by using packet filters.
 158 Ingress filtering can break tunnel operation in an asymmetrically
 159 routed network.
 160 It can be turned off by
 161 .Dv IFF_LINK2
 162 bit.
 163 .Ss Route caching
 164 Processing each packet requires two route lookups: first on the
 165 packet itself, and second on the tunnel destination.
 166 This second route can be cached, increasing tunnel performance.
 167 However, in a dynamically routed network, the tunnel will stick
 168 to the cached route, ignoring routing table updates.
 169 Route caching can be enabled with the
 170 .Dv IFF_LINK0
 171 flag.
 172 .\"
 173 .Ss Miscellaneous
 174 By default,
 175 .Nm
 176 tunnels may not be nested.
 177 This behavior may be modified at runtime by setting the
 178 .Xr sysctl 8
 179 variable
 180 .Va net.link.gif.max_nesting
 181 to the desired level of nesting.
 182 Additionally,
 183 .Nm
 184 tunnels are restricted to one per pair of end points.
 185 Parallel tunnels may be enabled by setting the
 186 .Xr sysctl 8
 187 variable
 188 .Va net.link.gif.parallel_tunnels
 189 to 1.
 190 .Sh SEE ALSO
 191 .Xr gre 4 ,
 192 .Xr inet 4 ,
 193 .Xr inet6 4 ,
 194 .Xr ifconfig 8
 195 .Rs
 196 .%A R. Gilligan
 197 .%A E. Nordmark
 198 .%B RFC2893
 199 .%T Transition Mechanisms for IPv6 Hosts and Routers
 200 .%D August 2000
 201 .%U http://tools.ietf.org/html/rfc2893
 202 .Re
 203 .Rs
 204 .%A Sally Floyd
 205 .%A David L. Black
 206 .%A K. K. Ramakrishnan
 207 .%T "IPsec Interactions with ECN"
 208 .%D December 1999
 209 .%O draft-ietf-ipsec-ecn-02.txt
 210 .Re
 211 .\"
 212 .Sh HISTORY
 213 The
 214 .Nm
 215 device first appeared in the WIDE hydrangea IPv6 kit.
 216 .\"
 217 .Sh BUGS
 218 There are many tunnelling protocol specifications, all
 219 defined differently from each other.
 220 The
 221 .Nm
 222 device may not interoperate with peers which are based on different specifications,
 223 and are picky about outer header fields.
 224 For example, you cannot usually use
 225 .Nm
 226 to talk with IPsec devices that use IPsec tunnel mode.
 227 .Pp
 228 The current code does not check if the ingress address
 229 (outer source address)
 230 configured in the
 231 .Nm
 232 interface makes sense.
 233 Make sure to specify an address which belongs to your node.
 234 Otherwise, your node will not be able to receive packets from the peer,
 235 and it will generate packets with a spoofed source address.
 236 .Pp
 237 If the outer protocol is IPv4,
 238 .Nm
 239 does not try to perform path MTU discovery for the encapsulated packet
 240 (DF bit is set to 0).
 241 .Pp
 242 If the outer protocol is IPv6, path MTU discovery for encapsulated packets
 243 may affect communication over the interface.
 244 The first bigger-than-pmtu packet may be lost.
 245 To avoid the problem, you may want to set the interface MTU for
 246 .Nm
 247 to 1240 or smaller, when the outer header is IPv6 and the inner header is IPv4.
 248 .Pp
 249 The
 250 .Nm
 251 device does not translate ICMP messages for the outer header into the inner header.
 252 .Pp
 253 In the past,
 254 .Nm
 255 had a multi-destination behavior, configurable via
 256 .Dv IFF_LINK0
 257 flag.
 258 The behavior is obsolete and is no longer supported.
 259 .Pp
 260 On
 261 .Fx
 262 6.1, 6.2, 6.3, 7.0, 7.1, and 7.2
 263 the
 264 .Nm
 265 sends and receives incorrect EtherIP packets with reversed version
 266 field when
 267 .Xr if_bridge 4
 268 is used together.  As a workaround on this interoperability issue, the
 269 following two
 270 .Xr ifconfig 8
 271 flags can be used:
 272 .Bl -tag -width "accept_rev_ethip_ver" -offset indent
 273 .It accept_rev_ethip_ver
 274 accepts both correct EtherIP packets and ones with reversed version
 275 field, if enabled.  If disabled, the
 276 .Nm
 277 accepts the correct packets only.  This flag is enabled by default.
 278 .It send_rev_ethip_ver
 279 sends EtherIP packets with reversed version field intentionally, if
 280 enabled.  If disabled, the
 281 .Nm
 282 sends the correct packets only.  This flag is disabled by default.
 283 .El
 284 .Pp
 285 If interoperability with the older
 286 .Fx
 287 machines is needed, both of these two flags must be enabled.