share/man/man4/stf.4

   1 .\"     $FreeBSD: src/share/man/man4/stf.4,v 1.3.2.5 2002/08/28 04:46:25 brooks Exp $
   2 .\"     $DragonFly: src/share/man/man4/stf.4,v 1.2 2003/06/17 04:36:59 dillon Exp $
   3 .\"     $KAME: stf.4,v 1.35 2001/05/02 06:24:49 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 27, 2001
  33 .Dt STF 4
  34 .Os
  35 .Sh NAME
  36 .Nm stf
  37 .Nd
  38 .Tn 6to4
  39 tunnel interface
  40 .Sh SYNOPSIS
  41 .Cd "pseudo-device stf"
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 interface supports
  46 .Dq 6to4
  47 IPv6 in IPv4 encapsulation.
  48 It can tunnel IPv6 traffic over IPv4, as specified in
  49 .Li RFC3056 .
  50 .Pp
  51 For ordinary nodes in 6to4 site, you do not need
  52 .Nm
  53 interface.
  54 The
  55 .Nm
  56 interface is necessary for site border router
  57 (called
  58 .Dq 6to4 router
  59 in the specification).
  60 .Pp
  61 Each
  62 .Nm
  63 interface is created at runtime using interface cloning.
  64 This is
  65 most easily done with the
  66 .Xr ifconfig 8
  67 .Cm create
  68 command or using the
  69 .Va cloned_interfaces
  70 variable in
  71 .Xr rc.conf 5 .
  72 .Pp
  73 Due to the way 6to4 protocol is specified,
  74 .Nm
  75 interface requires certain configuration to work properly.
  76 Single
  77 (no more than 1)
  78 valid 6to4 address needs to be configured to the interface.
  79 .Dq A valid 6to4 address
  80 is an address which has the following properties.
  81 If any of the following properties are not satisfied,
  82 .Nm
  83 raises runtime error on packet transmission.
  84 Read the specification for more details.
  85 .Bl -bullet
  86 .It
  87 matches
  88 .Li 2002:xxyy:zzuu::/48
  89 where
  90 .Li xxyy:zzuu
  91 is a hexadecimal notation of an IPv4 address for the node.
  92 IPv4 address can be taken from any of interfaces your node has.
  93 Since the specification forbids the use of IPv4 private address,
  94 the address needs to be a global IPv4 address.
  95 .It
  96 Subnet identifier portion
  97 (48th to 63rd bit)
  98 and interface identifier portion
  99 (lower 64 bits)
 100 are properly filled to avoid address collisions.
 101 .El
 102 .Pp
 103 If you would like the node to behave as a relay router,
 104 the prefix length for the IPv6 interface address needs to be 16 so that
 105 the node would consider any 6to4 destination as
 106 .Dq on-link .
 107 If you would like to restrict 6to4 peers to be inside certain IPv4 prefix,
 108 you may want to configure IPv6 prefix length as
 109 .Dq 16 + IPv4 prefix length .
 110 .Nm
 111 interface will check the IPv4 source address on packets,
 112 if the IPv6 prefix length is larger than 16.
 113 .Pp
 114 .Nm
 115 can be configured to be ECN friendly.
 116 This can be configured by
 117 .Dv IFF_LINK1 .
 118 See
 119 .Xr gif 4
 120 for details.
 121 .Pp
 122 Please note that 6to4 specification is written as
 123 .Dq accept tunnelled packet from everyone
 124 tunnelling device.
 125 By enabling
 126 .Nm
 127 device, you are making it much easier for malicious parties to inject
 128 fabricated IPv6 packet to your node.
 129 Also, malicious party can inject an IPv6 packet with fabricated source address
 130 to make your node generate improper tunnelled packet.
 131 Administrators must take caution when enabling the interface.
 132 To prevent possible attacks,
 133 .Nm
 134 interface filters out the following packets.
 135 Note that the checks are no way complete:
 136 .Bl -bullet
 137 .It
 138 Packets with IPv4 unspecified address as outer IPv4 source/destination
 139 .Pq Li 0.0.0.0/8
 140 .It
 141 Packets with loopback address as outer IPv4 source/destination
 142 .Pq Li 127.0.0.0/8
 143 .It
 144 Packets with IPv4 multicast address as outer IPv4 source/destination
 145 .Pq Li 224.0.0.0/4
 146 .It
 147 Packets with limited broadcast address as outer IPv4 source/destination
 148 .Pq Li 255.0.0.0/8
 149 .It
 150 Packets with subnet broadcast address as outer IPv4 source/destination.
 151 The check is made against subnet broadcast addresses for
 152 all of the directly connected subnets.
 153 .It
 154 Packets that does not pass ingress filtering.
 155 Outer IPv4 source address must meet the IPv4 topology on the routing table.
 156 Ingress filter can be turned off by
 157 .Dv IFF_LINK2
 158 bit.
 159 .It
 160 The same set of rules are applied against the IPv4 address embedded into
 161 inner IPv6 address, if the IPv6 address matches 6to4 prefix.
 162 .El
 163 .Pp
 164 It is recommended to filter/audit
 165 incoming IPv4 packet with IP protocol number 41, as necessary.
 166 It is also recommended to filter/audit encapsulated IPv6 packets as well.
 167 You may also want to run normal ingress filter against inner IPv6 address
 168 to avoid spoofing.
 169 .Pp
 170 By setting the
 171 .Dv IFF_LINK0
 172 flag on the
 173 .Nm
 174 interface, it is possible to disable the input path,
 175 making the direct attacks from the outside impossible.
 176 Note, however, there are other security risks exist.
 177 If you wish to use the configuration,
 178 you must not advertise your 6to4 address to others.
 179 .\"
 180 .Sh EXAMPLES
 181 Note that
 182 .Li 8504:0506
 183 is equal to
 184 .Li 133.4.5.6 ,
 185 written in hexadecimals.
 186 .Bd -literal
 187 # ifconfig ne0 inet 133.4.5.6 netmask 0xffffff00
 188 # ifconfig stf0 inet6 2002:8504:0506:0000:a00:5aff:fe38:6f86 \\
 189         prefixlen 16 alias
 190 .Ed
 191 .Pp
 192 The following configuration accepts packets from IPv4 source
 193 .Li 9.1.0.0/16
 194 only.
 195 It emits 6to4 packet only for IPv6 destination 2002:0901::/32
 196 (IPv4 destination will match
 197 .Li 9.1.0.0/16 ) .
 198 .Bd -literal
 199 # ifconfig ne0 inet 9.1.2.3 netmask 0xffff0000
 200 # ifconfig stf0 inet6 2002:0901:0203:0000:a00:5aff:fe38:6f86 \\
 201         prefixlen 32 alias
 202 .Ed
 203 .Pp
 204 The following configuration uses the
 205 .Nm
 206 interface as an output-only device.
 207 You need to have alternative IPv6 connectivity
 208 (other than 6to4)
 209 to use this configuration.
 210 For outbound traffic, you can reach other 6to4 networks efficiently via
 211 .Nm stf .
 212 For inbound traffic, you will not receive any 6to4-tunneled packets
 213 (less security drawbacks).
 214 Be careful not to advertise your 6to4 prefix to others
 215 .Pq Li 2002:8504:0506::/48 ,
 216 and not to use your 6to4 prefix as a source.
 217 .Bd -literal
 218 # ifconfig ne0 inet 133.4.5.6 netmask 0xffffff00
 219 # ifconfig stf0 inet6 2002:8504:0506:0000:a00:5aff:fe38:6f86 \\
 220         prefixlen 16 alias deprecated link0
 221 # route add -inet6 2002:: -prefixlen 16 ::1
 222 # route change -inet6 2002:: -prefixlen 16 ::1 -ifp stf0
 223 .Ed
 224 .\"
 225 .Sh SEE ALSO
 226 .Xr gif 4 ,
 227 .Xr inet 4 ,
 228 .Xr inet6 4
 229 .Pp
 230 .Pa http://www.6bone.net/6bone_6to4.html
 231 .Rs
 232 .%A Brian Carpenter
 233 .%A Keith Moore
 234 .%T "Connection of IPv6 Domains via IPv4 Clouds"
 235 .%D February 2001
 236 .%R RFC
 237 .%N 3056
 238 .Re
 239 .Rs
 240 .%A Jun-ichiro itojun Hagino
 241 .%T "Possible abuse against IPv6 transition technologies"
 242 .%D July 2000
 243 .%N draft-itojun-ipv6-transition-abuse-01.txt
 244 .%O work in progress
 245 .Re
 246 .\"
 247 .Sh HISTORY
 248 The
 249 .Nm
 250 device first appeared in WIDE/KAME IPv6 stack.
 251 .\"
 252 .Sh BUGS
 253 No more than one
 254 .Nm
 255 interface is allowed for a node,
 256 and no more than one IPv6 interface address is allowed for an
 257 .Nm
 258 interface.
 259 It is to avoid source address selection conflicts
 260 between IPv6 layer and IPv4 layer,
 261 and to cope with ingress filtering rule on the other side.
 262 This is a feature to make
 263 .Nm
 264 work right for all occasions.