share/man/man4/stf.4

   1 .\"     $KAME: stf.4,v 1.35 2001/05/02 06:24:49 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 November 16, 2021
  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 "device stf"
  42 .Sh DESCRIPTION
  43 The
  44 .Nm
  45 interface supports
  46 .Dq 6to4
  47 and
  48 .Dq 6rd
  49 IPv6 in IPv4 encapsulation.
  50 It can tunnel IPv6 traffic over IPv4, as specified in
  51 .Li RFC3056
  52 or
  53 .Li RFC5969 .
  54 .Pp
  55 For ordinary nodes in a 6to4 or 6RD site, you do not need
  56 .Nm
  57 interface.
  58 The
  59 .Nm
  60 interface is necessary for site border routers
  61 (called
  62 .Dq 6to4 routers
  63 or
  64 .Dq 6rd Customer Edge (CE)
  65 in the specification).
  66 .Pp
  67 Each
  68 .Nm
  69 interface is created at runtime using interface cloning.
  70 This is
  71 most easily done with the
  72 .Xr ifconfig 8
  73 .Cm create
  74 command or using the
  75 .Va cloned_interfaces
  76 variable in
  77 .Xr rc.conf 5 .
  78 .Sh 6to4
  79 .Pp
  80 Due to the way 6to4 protocol is specified,
  81 .Nm
  82 interface requires certain configuration to work properly.
  83 Single
  84 (no more than 1)
  85 valid 6to4 address needs to be configured to the interface.
  86 .Dq A valid 6to4 address
  87 is an address which has the following properties.
  88 If any of the following properties are not satisfied,
  89 .Nm
  90 raises runtime error on packet transmission.
  91 Read the specification for more details.
  92 .Bl -bullet
  93 .It
  94 matches
  95 .Li 2002:xxyy:zzuu::/48
  96 where
  97 .Li xxyy:zzuu
  98 is a hexadecimal notation of an IPv4 address for the node.
  99 IPv4 address can be taken from any of interfaces your node has.
 100 Since the specification forbids the use of IPv4 private address,
 101 the address needs to be a global IPv4 address.
 102 .It
 103 Subnet identifier portion
 104 (48th to 63rd bit)
 105 and interface identifier portion
 106 (lower 64 bits)
 107 are properly filled to avoid address collisions.
 108 .El
 109 .Pp
 110 If you would like the node to behave as a relay router,
 111 the prefix length for the IPv6 interface address needs to be 16 so that
 112 the node would consider any 6to4 destination as
 113 .Dq on-link .
 114 If you would like to restrict 6to4 peers to be inside certain IPv4 prefix,
 115 you may want to configure IPv6 prefix length as
 116 .Dq 16 + IPv4 prefix length .
 117 .Nm
 118 interface will check the IPv4 source address on packets,
 119 if the IPv6 prefix length is larger than 16.
 120 .Pp
 121 .Nm
 122 can be configured to be ECN friendly.
 123 This can be configured by
 124 .Dv IFF_LINK1 .
 125 See
 126 .Xr gif 4
 127 for details.
 128 .Pp
 129 Please note that 6to4 specification is written as
 130 .Dq accept tunnelled packet from everyone
 131 tunnelling device.
 132 By enabling
 133 .Nm
 134 device, you are making it much easier for malicious parties to inject
 135 fabricated IPv6 packet to your node.
 136 Also, malicious party can inject an IPv6 packet with fabricated source address
 137 to make your node generate improper tunnelled packet.
 138 Administrators must take caution when enabling the interface.
 139 To prevent possible attacks,
 140 .Nm
 141 interface filters out the following packets.
 142 Note that the checks are no way complete:
 143 .Bl -bullet
 144 .It
 145 Packets with IPv4 unspecified address as outer IPv4 source/destination
 146 .Pq Li 0.0.0.0/8
 147 .It
 148 Packets with loopback address as outer IPv4 source/destination
 149 .Pq Li 127.0.0.0/8
 150 .It
 151 Packets with IPv4 multicast address as outer IPv4 source/destination
 152 .Pq Li 224.0.0.0/4
 153 .It
 154 Packets with limited broadcast address as outer IPv4 source/destination
 155 .Pq Li 255.0.0.0/8
 156 .It
 157 Packets with private address as outer IPv4 source/destination
 158 .Pq Li 10.0.0.0/8 , 172.16.0.0/12 , 192.168.0.0/16
 159 .It
 160 Packets with subnet broadcast address as outer IPv4 source/destination.
 161 The check is made against subnet broadcast addresses for
 162 all of the directly connected subnets.
 163 .It
 164 Packets that does not pass ingress filtering.
 165 Outer IPv4 source address must meet the IPv4 topology on the routing table.
 166 Ingress filter can be turned off by
 167 .Dv IFF_LINK2
 168 bit.
 169 .It
 170 The same set of rules are applied against the IPv4 address embedded into
 171 inner IPv6 address, if the IPv6 address matches 6to4 prefix.
 172 .El
 173 .Pp
 174 It is recommended to filter/audit
 175 incoming IPv4 packet with IP protocol number 41, as necessary.
 176 It is also recommended to filter/audit encapsulated IPv6 packets as well.
 177 You may also want to run normal ingress filter against inner IPv6 address
 178 to avoid spoofing.
 179 .Pp
 180 By setting the
 181 .Dv IFF_LINK0
 182 flag on the
 183 .Nm
 184 interface, it is possible to disable the input path,
 185 making the direct attacks from the outside impossible.
 186 Note, however, there are other security risks exist.
 187 If you wish to use the configuration,
 188 you must not advertise your 6to4 address to others.
 189 .\"
 190 .Sh 6rd
 191 Like
 192 .Dq 6to4
 193 .Dq 6rd
 194 also requires configuration before it can be used.
 195 The required configuration parameters are:
 196 .Bl -bullet
 197 .It
 198 The IPv6 address and prefix length.
 199 .It
 200 The border router IPv4 address.
 201 .It
 202 The IPv4 WAN address.
 203 .It
 204 The prefix length of the IPv4 WAN address.
 205 .El
 206 .Pp
 207 These can parameters are all configured through
 208 .Xr ifconfig 8 .
 209 .Pp
 210 The IPv6 address and prefix length can be configured like any other IPv6 address.
 211 Note that the prefix length is the IPv6 prefix length excluding the embedded
 212 IPv4 address bits.
 213 The prefix length of the delegated network is the sum of the IPv6 prefix length
 214 and the IPv4 prefix length.
 215 .Pp
 216 The border router IPv4 address is configured with the
 217 .Xr ifconfig 8
 218 .Cm stfv4br
 219 command.
 220 .Pp
 221 The IPv4 WAN address and IPv4 prefix length are configured using the
 222 .Xr ifconfig 8
 223 .Cm stfv4net
 224 command.
 225 .Sh SYSCTL VARIABLES
 226 The following
 227 .Xr sysctl 8
 228 variables can be used to control the behavior of the
 229 .Nm stf .
 230 The default value is shown next to each variable.
 231 .Bl -tag -width indent
 232 .It Va net.link.stf.permit_rfc1918 : No 0
 233 The RFC3056 requires the use of globally unique 32-bit IPv4
 234 addresses.
 235 This sysctl variable controls the behaviour of this requirement.
 236 When it set to not 0,
 237 .Nm stf
 238 allows the use of private IPv4 addresses described in the RFC1918.
 239 This may be useful for an Intranet environment or when some mechanisms
 240 of network address translation (NAT) are used.
 241 .El
 242 .Sh EXAMPLES
 243 Note that
 244 .Li 8504:0506
 245 is equal to
 246 .Li 133.4.5.6 ,
 247 written in hexadecimals.
 248 .Bd -literal
 249 # ifconfig ne0 inet 133.4.5.6 netmask 0xffffff00
 250 # ifconfig stf0 inet6 2002:8504:0506:0000:a00:5aff:fe38:6f86 \\
 251         prefixlen 16 alias
 252 .Ed
 253 .Pp
 254 The following configuration accepts packets from IPv4 source
 255 .Li 9.1.0.0/16
 256 only.
 257 It emits 6to4 packet only for IPv6 destination 2002:0901::/32
 258 (IPv4 destination will match
 259 .Li 9.1.0.0/16 ) .
 260 .Bd -literal
 261 # ifconfig ne0 inet 9.1.2.3 netmask 0xffff0000
 262 # ifconfig stf0 inet6 2002:0901:0203:0000:a00:5aff:fe38:6f86 \\
 263         prefixlen 32 alias
 264 .Ed
 265 .Pp
 266 The following configuration uses the
 267 .Nm
 268 interface as an output-only device.
 269 You need to have alternative IPv6 connectivity
 270 (other than 6to4)
 271 to use this configuration.
 272 For outbound traffic, you can reach other 6to4 networks efficiently via
 273 .Nm stf .
 274 For inbound traffic, you will not receive any 6to4-tunneled packets
 275 (less security drawbacks).
 276 Be careful not to advertise your 6to4 prefix to others
 277 .Pq Li 2002:8504:0506::/48 ,
 278 and not to use your 6to4 prefix as a source.
 279 .Bd -literal
 280 # ifconfig ne0 inet 133.4.5.6 netmask 0xffffff00
 281 # ifconfig stf0 inet6 2002:8504:0506:0000:a00:5aff:fe38:6f86 \\
 282         prefixlen 16 alias deprecated link0
 283 # route add -inet6 2002:: -prefixlen 16 ::1
 284 # route change -inet6 2002:: -prefixlen 16 ::1 -ifp stf0
 285 .Ed
 286 .Pp
 287 The following example configures a
 288 .Dq 6rd
 289 tunnel on a
 290 .Dq 6rd CE
 291 where the ISP's
 292 .Dq 6rd
 293 IPv6 prefix is 2001:db8::/32.
 294 The border router is 192.0.2.1.
 295 The
 296 .Dq 6rd CE
 297 has a WAN address of 192.0.2.2 and the full IPv4 address is embedded in the
 298 .Dq 6rd IPv6 address:
 299 .Bd -literal
 300 # ifconfig stf0 inet6 2001:db8:c000:0202:: prefixlen 32 up
 301 # ifconfig stf0 stfv4br 192.0.2.1
 302 # ifconfig stf0 stfv4net 192.0.2.2/32
 303 .Ed
 304 .\"
 305 .Sh SEE ALSO
 306 .Xr gif 4 ,
 307 .Xr inet 4 ,
 308 .Xr inet6 4
 309 .Rs
 310 .%A Brian Carpenter
 311 .%A Keith Moore
 312 .%T "Connection of IPv6 Domains via IPv4 Clouds"
 313 .%D February 2001
 314 .%R RFC
 315 .%N 3056
 316 .Re
 317 .Rs
 318 .%A Jun-ichiro itojun Hagino
 319 .%T "Possible abuse against IPv6 transition technologies"
 320 .%D July 2000
 321 .%N draft-itojun-ipv6-transition-abuse-01.txt
 322 .%O work in progress
 323 .Re
 324 .\"
 325 .Sh HISTORY
 326 The
 327 .Nm
 328 device first appeared in WIDE/KAME IPv6 stack.
 329 .\"
 330 .Sh BUGS
 331 No more than one
 332 .Nm
 333 interface is allowed for a node,
 334 and no more than one IPv6 interface address is allowed for an
 335 .Nm
 336 interface.
 337 It is to avoid source address selection conflicts
 338 between IPv6 layer and IPv4 layer,
 339 and to cope with ingress filtering rule on the other side.
 340 This is a feature to make
 341 .Nm
 342 work right for all occasions.