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