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 79.Pp 80Due to the way 6to4 protocol is specified, 81.Nm 82interface requires certain configuration to work properly. 83Single 84(no more than 1) 85valid 6to4 address needs to be configured to the interface. 86.Dq A valid 6to4 address 87is an address which has the following properties. 88If any of the following properties are not satisfied, 89.Nm 90raises runtime error on packet transmission. 91Read the specification for more details. 92.Bl -bullet 93.It 94matches 95.Li 2002:xxyy:zzuu::/48 96where 97.Li xxyy:zzuu 98is a hexadecimal notation of an IPv4 address for the node. 99IPv4 address can be taken from any of interfaces your node has. 100Since the specification forbids the use of IPv4 private address, 101the address needs to be a global IPv4 address. 102.It 103Subnet identifier portion 104(48th to 63rd bit) 105and interface identifier portion 106(lower 64 bits) 107are properly filled to avoid address collisions. 108.El 109.Pp 110If you would like the node to behave as a relay router, 111the prefix length for the IPv6 interface address needs to be 16 so that 112the node would consider any 6to4 destination as 113.Dq on-link . 114If you would like to restrict 6to4 peers to be inside certain IPv4 prefix, 115you may want to configure IPv6 prefix length as 116.Dq 16 + IPv4 prefix length . 117.Nm 118interface will check the IPv4 source address on packets, 119if the IPv6 prefix length is larger than 16. 120.Pp 121.Nm 122can be configured to be ECN friendly. 123This can be configured by 124.Dv IFF_LINK1 . 125See 126.Xr gif 4 127for details. 128.Pp 129Please note that 6to4 specification is written as 130.Dq accept tunnelled packet from everyone 131tunnelling device. 132By enabling 133.Nm 134device, you are making it much easier for malicious parties to inject 135fabricated IPv6 packet to your node. 136Also, malicious party can inject an IPv6 packet with fabricated source address 137to make your node generate improper tunnelled packet. 138Administrators must take caution when enabling the interface. 139To prevent possible attacks, 140.Nm 141interface filters out the following packets. 142Note that the checks are no way complete: 143.Bl -bullet 144.It 145Packets with IPv4 unspecified address as outer IPv4 source/destination 146.Pq Li 0.0.0.0/8 147.It 148Packets with loopback address as outer IPv4 source/destination 149.Pq Li 127.0.0.0/8 150.It 151Packets with IPv4 multicast address as outer IPv4 source/destination 152.Pq Li 224.0.0.0/4 153.It 154Packets with limited broadcast address as outer IPv4 source/destination 155.Pq Li 255.0.0.0/8 156.It 157Packets 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 160Packets with subnet broadcast address as outer IPv4 source/destination. 161The check is made against subnet broadcast addresses for 162all of the directly connected subnets. 163.It 164Packets that does not pass ingress filtering. 165Outer IPv4 source address must meet the IPv4 topology on the routing table. 166Ingress filter can be turned off by 167.Dv IFF_LINK2 168bit. 169.It 170The same set of rules are applied against the IPv4 address embedded into 171inner IPv6 address, if the IPv6 address matches 6to4 prefix. 172.El 173.Pp 174It is recommended to filter/audit 175incoming IPv4 packet with IP protocol number 41, as necessary. 176It is also recommended to filter/audit encapsulated IPv6 packets as well. 177You may also want to run normal ingress filter against inner IPv6 address 178to avoid spoofing. 179.Pp 180By setting the 181.Dv IFF_LINK0 182flag on the 183.Nm 184interface, it is possible to disable the input path, 185making the direct attacks from the outside impossible. 186Note, however, there are other security risks exist. 187If you wish to use the configuration, 188you must not advertise your 6to4 address to others. 189.\" 190.Sh 6rd 191Like 192.Dq 6to4 193.Dq 6rd 194also requires configuration before it can be used. 195The required configuration parameters are: 196.Bl -bullet 197.It 198The IPv6 address and prefix length. 199.It 200The border router IPv4 address. 201.It 202The IPv4 WAN address. 203.It 204The prefix length of the IPv4 WAN address. 205.El 206.Pp 207These can parameters are all configured through 208.Xr ifconfig 8 . 209.Pp 210The IPv6 address and prefix length can be configured like any other IPv6 address. 211Note that the prefix length is the IPv6 prefix length excluding the embedded 212IPv4 address bits. 213The prefix length of the delegated network is the sum of the IPv6 prefix length 214and the IPv4 prefix length. 215.Pp 216The border router IPv4 address is configured with the 217.Xr ifconfig 8 218.Cm stfv4br 219command. 220.Pp 221The IPv4 WAN address and IPv4 prefix length are configured using the 222.Xr ifconfig 8 223.Cm stfv4net 224command. 225.Sh SYSCTL VARIABLES 226The following 227.Xr sysctl 8 228variables can be used to control the behavior of the 229.Nm stf . 230The default value is shown next to each variable. 231.Bl -tag -width indent 232.It Va net.link.stf.permit_rfc1918 : No 0 233The RFC3056 requires the use of globally unique 32-bit IPv4 234addresses. 235This sysctl variable controls the behaviour of this requirement. 236When it set to not 0, 237.Nm stf 238allows the use of private IPv4 addresses described in the RFC1918. 239This may be useful for an Intranet environment or when some mechanisms 240of network address translation (NAT) are used. 241.El 242.Sh EXAMPLES 243Note that 244.Li 8504:0506 245is equal to 246.Li 133.4.5.6 , 247written 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 254The following configuration accepts packets from IPv4 source 255.Li 9.1.0.0/16 256only. 257It 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 266The following configuration uses the 267.Nm 268interface as an output-only device. 269You need to have alternative IPv6 connectivity 270(other than 6to4) 271to use this configuration. 272For outbound traffic, you can reach other 6to4 networks efficiently via 273.Nm stf . 274For inbound traffic, you will not receive any 6to4-tunneled packets 275(less security drawbacks). 276Be careful not to advertise your 6to4 prefix to others 277.Pq Li 2002:8504:0506::/48 , 278and 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 287The following example configures a 288.Dq 6rd 289tunnel on a 290.Dq 6rd CE 291where the ISP's 292.Dq 6rd 293IPv6 prefix is 2001:db8::/32. 294The border router is 192.0.2.1. 295The 296.Dq 6rd CE 297has 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 326The 327.Nm 328device first appeared in WIDE/KAME IPv6 stack. 329.\" 330.Sh BUGS 331No more than one 332.Nm 333interface is allowed for a node, 334and no more than one IPv6 interface address is allowed for an 335.Nm 336interface. 337It is to avoid source address selection conflicts 338between IPv6 layer and IPv4 layer, 339and to cope with ingress filtering rule on the other side. 340This is a feature to make 341.Nm 342work right for all occasions. 343