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