1.\" $KAME: inet6.4,v 1.21 2001/04/05 01:00:18 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 February 22, 2023 33.Dt INET6 4 34.Os 35.Sh NAME 36.Nm inet6 37.Nd Internet protocol version 6 family 38.Sh SYNOPSIS 39.In sys/types.h 40.In netinet/in.h 41.Sh DESCRIPTION 42The 43.Nm 44family is an updated version of 45.Xr inet 4 46family. 47While 48.Xr inet 4 49implements Internet Protocol version 4, 50.Nm 51implements Internet Protocol version 6. 52.Pp 53.Nm 54is a collection of protocols layered atop the 55.Em Internet Protocol version 6 56.Pq Tn IPv6 57transport layer, and utilizing the IPv6 address format. 58The 59.Nm 60family provides protocol support for the 61.Dv SOCK_STREAM , SOCK_DGRAM , 62and 63.Dv SOCK_RAW 64socket types; the 65.Dv SOCK_RAW 66interface provides access to the 67.Tn IPv6 68protocol. 69.Sh ADDRESSING 70IPv6 addresses are 16 byte quantities, stored in network standard byteorder. 71The include file 72.In netinet/in.h 73defines this address 74as a discriminated union. 75.Pp 76Sockets bound to the 77.Nm 78family utilize the following addressing structure: 79.Bd -literal -offset indent 80struct sockaddr_in6 { 81 uint8_t sin6_len; 82 sa_family_t sin6_family; 83 in_port_t sin6_port; 84 uint32_t sin6_flowinfo; 85 struct in6_addr sin6_addr; 86 uint32_t sin6_scope_id; 87}; 88.Ed 89.Pp 90Sockets may be created with the local address 91.Dq Dv :: 92(which is equal to IPv6 address 93.Dv 0:0:0:0:0:0:0:0 ) 94to effect 95.Dq wildcard 96matching on incoming messages. 97.Pp 98The IPv6 specification defines scoped addresses, 99like link-local or site-local addresses. 100A scoped address is ambiguous to the kernel, 101if it is specified without a scope identifier. 102To manipulate scoped addresses properly from the userland, 103programs must use the advanced API defined in RFC2292. 104A compact description of the advanced API is available in 105.Xr ip6 4 . 106If a scoped address is specified without an explicit scope, 107the kernel may raise an error. 108Note that scoped addresses are not for daily use at this moment, 109both from a specification and an implementation point of view. 110.Pp 111The KAME implementation supports an extended numeric IPv6 address notation 112for link-local addresses, 113like 114.Dq Li fe80::1%de0 115to specify 116.Do 117.Li fe80::1 118on 119.Li de0 120interface 121.Dc . 122This notation is supported by 123.Xr getaddrinfo 3 124and 125.Xr getnameinfo 3 . 126Some of normal userland programs, such as 127.Xr telnet 1 128or 129.Xr ftp 1 , 130are able to use this notation. 131With special programs 132like 133.Xr ping 8 , 134you can specify the outgoing interface by an extra command line option 135to disambiguate scoped addresses. 136.Pp 137Scoped addresses are handled specially in the kernel. 138In kernel structures like routing tables or interface structures, 139a scoped address will have its interface index embedded into the address. 140Therefore, 141the address in some kernel structures is not the same as that on the wire. 142The embedded index will become visible through a 143.Dv PF_ROUTE 144socket, kernel memory accesses via 145.Xr kvm 3 146and on some other occasions. 147HOWEVER, users should never use the embedded form. 148For details please consult 149.Pa IMPLEMENTATION 150supplied with KAME kit. 151.Sh PROTOCOLS 152The 153.Nm 154family is comprised of the 155.Tn IPv6 156network protocol, Internet Control 157Message Protocol version 6 158.Pq Tn ICMPv6 , 159Transmission Control Protocol 160.Pq Tn TCP , 161and User Datagram Protocol 162.Pq Tn UDP . 163.Tn TCP 164is used to support the 165.Dv SOCK_STREAM 166abstraction while 167.Tn UDP 168is used to support the 169.Dv SOCK_DGRAM 170abstraction. 171Note that 172.Tn TCP 173and 174.Tn UDP 175are common to 176.Xr inet 4 177and 178.Nm . 179A raw interface to 180.Tn IPv6 181is available 182by creating an Internet socket of type 183.Dv SOCK_RAW . 184The 185.Tn ICMPv6 186message protocol is accessible from a raw socket. 187.Ss MIB Variables 188A number of variables are implemented in the 189.Va net.inet6 190branch of the 191.Xr sysctl 3 192MIB. 193In addition to the variables supported by the transport protocols 194(for which the respective manual pages may be consulted), 195the following general variables are defined: 196.Bl -tag -width IPV6CTL_MAXFRAGPACKETS 197.It Dv IPV6CTL_FORWARDING 198.Pq ip6.forwarding 199Boolean: enable/disable forwarding of 200.Tn IPv6 201packets. 202Also, identify if the node is acting as a router. 203Defaults to off. 204.It Dv IPV6CTL_SENDREDIRECTS 205.Pq ip6.redirect 206Boolean: enable/disable sending of 207.Tn ICMPv6 208redirects in response to unforwardable 209.Tn IPv6 210packets. 211This option is ignored unless the node is routing 212.Tn IPv6 213packets, 214and should normally be enabled on all systems. 215Defaults to on. 216.It Dv IPV6CTL_DEFHLIM 217.Pq ip6.hlim 218Integer: default hop limit value to use for outgoing 219.Tn IPv6 220packets. 221This value applies to all the transport protocols on top of 222.Tn IPv6 . 223There are APIs to override the value. 224.It Dv IPV6CTL_MAXFRAGS 225.Pq ip6.maxfrags 226Integer: maximum number of fragments the host will accept and simultaneously 227hold across all reassembly queues in all VNETs. 228If set to 0, fragment reassembly is disabled. 229If set to -1, this limit is not applied. 230This limit is recalculated when the number of mbuf clusters is changed. 231This is a global limit. 232.It Dv IPV6CTL_MAXFRAGPACKETS 233.Pq ip6.maxfragpackets 234Integer: maximum number of fragmented packets the node will accept and 235simultaneously hold in the reassembly queue for a particular VNET. 2360 means that the node will not accept any fragmented packets for that VNET. 237-1 means that the node will not apply this limit for that VNET. 238This limit is recalculated when the number of mbuf clusters is changed. 239This is a per-VNET limit. 240.It Dv IPV6CTL_MAXFRAGBUCKETSIZE 241.Pq ip6.maxfragbucketsize 242Integer: maximum number of reassembly queues per bucket. 243Fragmented packets are hashed to buckets. 244Each bucket has a list of reassembly queues. 245The system must compare the incoming packets to the existing reassembly queues 246in the bucket to find a matching reassembly queue. 247To preserve system resources, the system limits the number of reassembly 248queues allowed in each bucket. 249This limit is recalculated when the number of mbuf clusters is changed or 250when the value of 251.Va ip6.maxfragpackets 252changes. 253This is a per-VNET limit. 254.It Dv IPV6CTL_MAXFRAGSPERPACKET 255.Pq ip6.maxfragsperpacket 256Integer: maximum number of fragments the host will accept and hold in the 257ressembly queue for a packet. 258This is a per-VNET limit. 259.It Dv IPV6CTL_ACCEPT_RTADV 260.Pq ip6.accept_rtadv 261Boolean: the default value of a per-interface flag to 262enable/disable receiving of 263.Tn ICMPv6 264router advertisement packets, 265and autoconfiguration of address prefixes and default routers. 266The node must be a host 267(not a router) 268for the option to be meaningful. 269Defaults to off. 270.It Dv IPV6CTL_AUTO_LINKLOCAL 271.Pq ip6.auto_linklocal 272Boolean: the default value of a per-interface flag to 273enable/disable performing automatic link-local address configuration. 274Defaults to on. 275.It Dv IPV6CTL_LOG_INTERVAL 276.Pq ip6.log_interval 277Integer: default interval between 278.Tn IPv6 279packet forwarding engine log output 280(in seconds). 281.It Dv IPV6CTL_HDRNESTLIMIT 282.Pq ip6.hdrnestlimit 283Integer: default number of the maximum 284.Tn IPv6 285extension headers 286permitted on incoming 287.Tn IPv6 288packets. 289If set to 0, the node will accept as many extension headers as possible. 290.It Dv IPV6CTL_DAD_COUNT 291.Pq ip6.dad_count 292Integer: default number of 293.Tn IPv6 294DAD 295.Pq duplicated address detection 296probe packets. 297The packets will be generated when 298.Tn IPv6 299interface addresses are configured. 300.It Dv IPV6CTL_AUTO_FLOWLABEL 301.Pq ip6.auto_flowlabel 302Boolean: enable/disable automatic filling of 303.Tn IPv6 304flowlabel field, for outstanding connected transport protocol packets. 305The field might be used by intermediate routers to identify packet flows. 306Defaults to on. 307.It Dv IPV6CTL_DEFMCASTHLIM 308.Pq ip6.defmcasthlim 309Integer: default hop limit value for an 310.Tn IPv6 311multicast packet sourced by the node. 312This value applies to all the transport protocols on top of 313.Tn IPv6 . 314There are APIs to override the value as documented in 315.Xr ip6 4 . 316.It Dv IPV6CTL_GIF_HLIM 317.Pq ip6.gifhlim 318Integer: default maximum hop limit value for an 319.Tn IPv6 320packet generated by 321.Xr gif 4 322tunnel interface. 323.It Dv IPV6CTL_KAME_VERSION 324.Pq ip6.kame_version 325String: identifies the version of KAME 326.Tn IPv6 327stack implemented in the kernel. 328.It Dv IPV6CTL_USE_DEPRECATED 329.Pq ip6.use_deprecated 330Boolean: enable/disable use of deprecated address, 331specified in RFC2462 5.5.4. 332Defaults to on. 333.It Dv IPV6CTL_RR_PRUNE 334.Pq ip6.rr_prune 335Integer: default interval between 336.Tn IPv6 337router renumbering prefix babysitting, in seconds. 338.It Dv IPV6CTL_V6ONLY 339.Pq ip6.v6only 340Boolean: enable/disable the prohibited use of 341.Tn IPv4 342mapped address on 343.Dv AF_INET6 344sockets. 345Defaults to on. 346.It Va ip6.log_cannot_forward 347Boolean: log packets that can't be forwarded because of unspecified source 348address or destination address beyond the scope of the source address as 349described in RFC4443. 350Enabled by default. 351.It Va ip6.source_address_validation 352Boolean: perform source address validation for packets destined for the local 353host. 354Consider this as following Section 3.2 of RFC3704/BCP84, where we treat local 355host as our own infrastructure. 356This has no effect on packets to be forwarded, so don't consider it as 357anti-spoof feature for a router. 358Enabled by default. 359.El 360.Ss Interaction between IPv4/v6 sockets 361By default, 362.Fx 363does not route IPv4 traffic to 364.Dv AF_INET6 365sockets. 366The default behavior intentionally violates RFC2553 for security reasons. 367Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. 368IPv4 traffic may be routed with certain 369per-socket/per-node configuration, however, it is not recommended to do so. 370Consult 371.Xr ip6 4 372for details. 373.Pp 374The behavior of 375.Dv AF_INET6 376TCP/UDP socket is documented in RFC2553. 377Basically, it says this: 378.Bl -bullet -compact 379.It 380A specific bind on an 381.Dv AF_INET6 382socket 383.Xr ( bind 2 384with an address specified) 385should accept IPv6 traffic to that address only. 386.It 387If you perform a wildcard bind 388on an 389.Dv AF_INET6 390socket 391.Xr ( bind 2 392to IPv6 address 393.Li :: ) , 394and there is no wildcard bind 395.Dv AF_INET 396socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 397should be routed to that 398.Dv AF_INET6 399socket. 400IPv4 traffic should be seen as if it came from an IPv6 address like 401.Li ::ffff:10.1.1.1 . 402This is called an IPv4 mapped address. 403.It 404If there are both a wildcard bind 405.Dv AF_INET 406socket and a wildcard bind 407.Dv AF_INET6 408socket on one TCP/UDP port, they should behave separately. 409IPv4 traffic should be routed to the 410.Dv AF_INET 411socket and IPv6 should be routed to the 412.Dv AF_INET6 413socket. 414.El 415.Pp 416However, RFC2553 does not define the ordering constraint between calls to 417.Xr bind 2 , 418nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers 419relate to each other 420(should they be integrated or separated). 421Implemented behavior is very different from kernel to kernel. 422Therefore, it is unwise to rely too much upon the behavior of 423.Dv AF_INET6 424wildcard bind sockets. 425It is recommended to listen to two sockets, one for 426.Dv AF_INET 427and another for 428.Dv AF_INET6 , 429when you would like to accept both IPv4 and IPv6 traffic. 430.Pp 431It should also be noted that 432malicious parties can take advantage of the complexity presented above, 433and are able to bypass access control, 434if the target node routes IPv4 traffic to 435.Dv AF_INET6 436socket. 437Users are advised to take care handling connections 438from IPv4 mapped address to 439.Dv AF_INET6 440sockets. 441.Sh SEE ALSO 442.Xr ioctl 2 , 443.Xr socket 2 , 444.Xr sysctl 3 , 445.Xr icmp6 4 , 446.Xr intro 4 , 447.Xr ip6 4 , 448.Xr tcp 4 , 449.Xr udp 4 450.Rs 451.%A A. Conta 452.%A S. Deering 453.%A M. Gupta 454.%T "Internet Control Message Protocol (ICMPv6) for the Internet" \ 455 "Protocol Version 6 (IPv6) Specification" 456.%R RFC 4443 457.%D March 2006 458.Re 459.Sh STANDARDS 460.Rs 461.%A Tatsuya Jinmei 462.%A Atsushi Onoe 463.%T "An Extension of Format for IPv6 Scoped Addresses" 464.%R internet draft 465.%D June 2000 466.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 467.%O work in progress material 468.Re 469.Sh HISTORY 470The 471.Nm 472protocol interfaces are defined in RFC2553 and RFC2292. 473The implementation described herein appeared in the WIDE/KAME project. 474.Sh BUGS 475The IPv6 support is subject to change as the Internet protocols develop. 476Users should not depend on details of the current implementation, 477but rather the services exported. 478.Pp 479Users are suggested to implement 480.Dq version independent 481code as much as possible, as you will need to support both 482.Xr inet 4 483and 484.Nm . 485