1.\" $FreeBSD: src/share/man/man4/inet6.4,v 1.4.2.9 2002/05/15 16:45:30 ume Exp $ 2.\" $KAME: inet6.4,v 1.21 2001/04/05 01:00:18 itojun Exp $ 3.\" 4.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd March 1, 2024 32.Dt INET6 4 33.Os 34.Sh NAME 35.Nm inet6 36.Nd Internet protocol version 6 family 37.Sh SYNOPSIS 38.In sys/types.h 39.In netinet/in.h 40.Sh DESCRIPTION 41The 42.Nm 43family is an updated version of 44.Xr inet 4 45family. 46While 47.Xr inet 4 48implements Internet Protocol version 4, 49.Nm 50implements Internet Protocol version 6. 51.Pp 52.Nm 53is a collection of protocols layered atop the 54.Em Internet Protocol version 6 55.Pq Tn IPv6 56transport layer, and utilizing the IPv6 address format. 57The 58.Nm 59family provides protocol support for the 60.Dv SOCK_STREAM , SOCK_DGRAM , 61and 62.Dv SOCK_RAW 63socket types; the 64.Dv SOCK_RAW 65interface provides access to the 66.Tn IPv6 67protocol. 68.Sh ADDRESSING 69IPv6 addresses are 16 byte quantities, stored in network standard byteorder. 70The include file 71.In netinet/in.h 72defines this address 73as a discriminated union. 74.Pp 75Sockets bound to the 76.Nm 77family utilize the following addressing structure: 78.Bd -literal -offset indent 79struct sockaddr_in6 { 80 u_int8_t sin6_len; 81 sa_family_t sin6_family; 82 u_int16_t sin6_port; 83 u_int32_t sin6_flowinfo; 84 struct in6_addr sin6_addr; 85 u_int32_t sin6_scope_id; 86}; 87.Ed 88.Pp 89Sockets may be created with the local address 90.Dq Dv :: 91(which is equal to IPv6 address 92.Dv 0:0:0:0:0:0:0:0 ) 93to affect 94.Dq wildcard 95matching on incoming messages. 96.Pp 97The IPv6 specification defines scoped addresses, 98like link-local or site-local addresses. 99A scoped address is ambiguous to the kernel, 100if it is specified without a scope identifier. 101To manipulate scoped addresses properly from the userland, 102programs must use the advanced API defined in RFC 2292. 103A compact description of the advanced API is available in 104.Xr ip6 4 . 105If a scoped address is specified without an explicit scope, 106the kernel may raise an error. 107Note that scoped addresses are not for daily use at this moment, 108both from a specification and an implementation point of view. 109.Pp 110The KAME implementation supports an extended numeric IPv6 address notation 111for link-local addresses, 112like 113.Dq Li fe80::1%de0 114to specify 115.Do 116.Li fe80::1 117on 118.Li de0 119interface 120.Dc . 121This notation is supported by 122.Xr getaddrinfo 3 123and 124.Xr getnameinfo 3 . 125Some of normal userland programs, such as 126.Xr telnet 1 127or 128.Xr ftp 1 , 129are able to use this notation. 130With special programs 131like 132.Xr ping6 8 , 133you can specify the outgoing interface by an extra command line option 134to disambiguate scoped addresses. 135.Pp 136Scoped addresses are handled specially in the kernel. 137In kernel structures like routing tables or interface structures, 138a scoped address will have its interface index embedded into the address. 139Therefore, 140the address in some kernel structures is not the same as that on the wire. 141The embedded index will become visible through a 142.Dv PF_ROUTE 143socket, kernel memory accesses via 144.Xr kvm 3 145and on some other occasions. 146HOWEVER, users should never use the embedded form. 147For details please consult 148.Pa IMPLEMENTATION 149supplied with KAME kit. 150.Sh PROTOCOLS 151The 152.Nm 153family is comprised of the 154.Tn IPv6 155network protocol, Internet Control 156Message Protocol version 6 157.Pq Tn ICMPv6 , 158Transmission Control Protocol 159.Pq Tn TCP , 160and User Datagram Protocol 161.Pq Tn UDP . 162.Tn TCP 163is used to support the 164.Dv SOCK_STREAM 165abstraction while 166.Tn UDP 167is used to support the 168.Dv SOCK_DGRAM 169abstraction. 170Note that 171.Tn TCP 172and 173.Tn UDP 174are common to 175.Xr inet 4 176and 177.Nm . 178A raw interface to 179.Tn IPv6 180is available 181by creating an Internet socket of type 182.Dv SOCK_RAW . 183The 184.Tn ICMPv6 185message protocol is accessible from a raw socket. 186.\" .Pp 187.\" The 128-bit IPv6 address contains both network and host parts. 188.\" However, direct examination of addresses is discouraged. 189.\" For those programs which absolutely need to break addresses 190.\" into their component parts, the following 191.\" .Xr ioctl 2 192.\" commands are provided for a datagram socket in the 193.\" .Nm 194.\" domain; they have the same form as the 195.\" .Dv SIOCIFADDR 196.\" command (see 197.\" .Xr intro 4 ) . 198.\" .Pp 199.\" .Bl -tag -width SIOCSIFNETMASK 200.\" .It Dv SIOCSIFNETMASK 201.\" Set interface network mask. 202.\" The network mask defines the network part of the address; 203.\" if it contains more of the address than the address type would indicate, 204.\" then subnets are in use. 205.\" .It Dv SIOCGIFNETMASK 206.\" Get interface network mask. 207.\" .El 208.\" .Sh ROUTING 209.\" The current implementation of Internet protocols includes some routing-table 210.\" adaptations to provide enhanced caching of certain end-to-end 211.\" information necessary for Transaction TCP and Path MTU Discovery. The 212.\" following changes are the most significant: 213.\" .Bl -enum 214.\" .It 215.\" All IP routes, except those with the 216.\" .Dv RTF_CLONING 217.\" flag and those to multicast destinations, have the 218.\" .Dv RTF_PRCLONING 219.\" flag forcibly enabled (they are thus said to be 220.\" .Dq "protocol cloning" ). 221.\" .It 222.\" When the last reference to an IP route is dropped, the route is 223.\" examined to determine if it was created by cloning such a route. If 224.\" this is the case, the 225.\" .Dv RTF_PROTO3 226.\" flag is turned on, and the expiration timer is initialized to go off 227.\" in net.inet.ip.rtexpire seconds. If such a route is re-referenced, 228.\" the flag and expiration timer are reset. 229.\" .It 230.\" A kernel timeout runs once every ten minutes, or sooner if there are 231.\" soon-to-expire routes in the kernel routing table, and deletes the 232.\" expired routes. 233.\" .El 234.\" .Pp 235.\" A dynamic process is in place to modify the value of 236.\" net.inet.ip.rtexpire if the number of cached routes grows too large. 237.\" If after an expiration run there are still more than 238.\" net.inet.ip.rtmaxcache unreferenced routes remaining, the rtexpire 239.\" value is multiplied by \(34, and any routes which have longer 240.\" expiration times have those times adjusted. This process is damped 241.\" somewhat by specification of a minimum rtexpire value 242.\" (net.inet.ip.rtminexpire), and by restricting the reduction to once in 243.\" a ten-minute period. 244.\" .Pp 245.\" If some external process deletes the original route from which a 246.\" protocol-cloned route was generated, the ``child route'' is deleted. 247.\" (This is actually a generic mechanism in the routing code support for 248.\" protocol-requested cloning.) 249.\" .Pp 250.\" No attempt is made to manage routes which were not created by protocol 251.\" cloning; these are assumed to be static, under the management of an 252.\" external routing process, or under the management of a link layer 253.\" (e.g., 254.\" .Tn ARP 255.\" for Ethernets). 256.\" .Pp 257.\" Only certain types of network activity will result in the cloning of a 258.\" route using this mechanism. Specifically, those protocols (such as 259.\" .Tn TCP 260.\" and 261.\" .Tn UDP ) 262.\" which themselves cache a long-lasting reference to route for a destination 263.\" will trigger the mechanism; whereas raw 264.\" .Tn IP 265.\" packets, whether locally-generated or forwarded, will not. 266.Ss MIB Variables 267A number of variables are implemented in the net.inet6 branch of the 268.Xr sysctl 3 269MIB. 270In addition to the variables supported by the transport protocols 271(for which the respective manual pages may be consulted), 272the following general variables are defined: 273.Bl -tag -width IPV6CTL_MAXFRAGPACKETS 274.It Dv IPV6CTL_FORWARDING 275.Pq ip6.forwarding 276Boolean: enable/disable forwarding of 277.Tn IPv6 278packets. 279Also, identify if the node is acting as a router. 280Defaults to off. 281.It Dv IPV6CTL_SENDREDIRECTS 282.Pq ip6.redirect 283Boolean: enable/disable sending of 284.Tn ICMPv6 285redirects in response to unforwardable 286.Tn IPv6 287packets. 288This option is ignored unless the node is routing 289.Tn IPv6 290packets, 291and should normally be enabled on all systems. 292Defaults to on. 293.It Dv IPV6CTL_DEFHLIM 294.Pq ip6.hlim 295Integer: default hop limit value to use for outgoing 296.Tn IPv6 297packets. 298This value applies to all the transport protocols on top of 299.Tn IPv6 . 300There are APIs to override the value. 301.It Dv IPV6CTL_MAXFRAGPACKETS 302.Pq ip6.maxfragpackets 303Integer: default maximum number of fragmented packets the node will accept. 3040 means that the node will not accept any fragmented packets. 305-1 means that the node will accept as many fragmented packets as it receives. 306The flag is provided basically for avoiding possible DoS attacks. 307.It Dv IPV6CTL_ACCEPT_RTADV 308.Pq ip6.accept_rtadv 309Boolean: enable/disable receiving of 310.Tn ICMPv6 311router advertisement packets, 312and autoconfiguration of address prefixes and default routers. 313The node must be a host 314(not a router) 315for the option to be meaningful. 316Defaults to off. 317.It Dv IPV6CTL_AUTO_LINKLOCAL 318.Pq ip6.auto_linklocal 319Boolean: the default value of a per-interface flag to enable/disable 320performing automatic link-local address configuration. 321Defaults to on. 322.It Dv IPV6CTL_LOG_INTERVAL 323.Pq ip6.log_interval 324Integer: default interval between 325.Tn IPv6 326packet forwarding engine log output 327(in seconds). 328.It Dv IPV6CTL_HDRNESTLIMIT 329.Pq ip6.hdrnestlimit 330Integer: default number of the maximum 331.Tn IPv6 332extension headers 333permitted on incoming 334.Tn IPv6 335packets. 336If set to 0, the node will accept as many extension headers as possible. 337.It Dv IPV6CTL_DAD_COUNT 338.Pq ip6.dad_count 339Integer: default number of 340.Tn IPv6 341DAD 342.Pq duplicated address detection 343probe packets. 344The packets will be generated when 345.Tn IPv6 346interface addresses are configured. 347.It Dv IPV6CTL_AUTO_FLOWLABEL 348.Pq ip6.auto_flowlabel 349Boolean: enable/disable automatic filling of 350.Tn IPv6 351flowlabel field, for outstanding connected transport protocol packets. 352The field might be used by intermediate routers to identify packet flows. 353Defaults to on. 354.It Dv IPV6CTL_DEFMCASTHLIM 355.Pq ip6.defmcasthlim 356Integer: default hop limit value for an 357.Tn IPv6 358multicast packet sourced by the node. 359This value applies to all the transport protocols on top of 360.Tn IPv6 . 361There are APIs to override the value as documented in 362.Xr ip6 4 . 363.It Dv IPV6CTL_GIF_HLIM 364.Pq ip6.gifhlim 365Integer: default maximum hop limit value for an 366.Tn IPv6 367packet generated by 368.Xr gif 4 369tunnel interface. 370.It Dv IPV6CTL_KAME_VERSION 371.Pq ip6.kame_version 372String: identifies the version of KAME 373.Tn IPv6 374stack implemented in the kernel. 375.It Dv IPV6CTL_USE_DEPRECATED 376.Pq ip6.use_deprecated 377Boolean: enable/disable use of deprecated address, 378specified in RFC 2462 5.5.4. 379Defaults to on. 380.It Dv IPV6CTL_RR_PRUNE 381.Pq ip6.rr_prune 382Integer: default interval between 383.Tn IPv6 384router renumbering prefix babysitting, in seconds. 385.It Dv IPV6CTL_RTEXPIRE 386.Pq ip6.rtexpire 387Integer: lifetime in seconds of protocol-cloned 388.Tn IP 389routes after the last reference drops (default one hour). 390.\"This value varies dynamically as described above. 391.It Dv IPV6CTL_RTMINEXPIRE 392.Pq ip6.rtminexpire 393Integer: minimum value of ip.rtexpire (default ten seconds). 394.\"This value has no effect on user modifications, but restricts the dynamic 395.\"adaptation described above. 396.It Dv IPV6CTL_RTMAXCACHE 397.Pq ip6.rtmaxcache 398Integer: trigger level of cached, unreferenced, protocol-cloned routes 399which initiates dynamic adaptation (default 128). 400.El 401.Ss Interaction between IPv4/v6 sockets 402The behavior of 403.Dv AF_INET6 404TCP/UDP socket is documented in RFC 2553. 405Basically, it says this: 406.Bl -bullet -compact 407.It 408A specific bind on an 409.Dv AF_INET6 410socket 411.Xr ( bind 2 412with an address specified) 413should accept IPv6 traffic to that address only. 414.It 415If you perform a wildcard bind 416on an 417.Dv AF_INET6 418socket 419.Xr ( bind 2 420to IPv6 address 421.Li :: ) , 422and there is no wildcard bind 423.Dv AF_INET 424socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 425should be routed to that 426.Dv AF_INET6 427socket. 428IPv4 traffic should be seen as if it came from an IPv6 address like 429.Li ::ffff:10.1.1.1 . 430This is called an IPv4 mapped address. 431.It 432If there are both a wildcard bind 433.Dv AF_INET 434socket and a wildcard bind 435.Dv AF_INET6 436socket on one TCP/UDP port, they should behave separately. 437IPv4 traffic should be routed to the 438.Dv AF_INET 439socket and IPv6 should be routed to the 440.Dv AF_INET6 441socket. 442.El 443.Pp 444However, RFC 2553 does not define the ordering constraint between calls to 445.Xr bind 2 , 446nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers 447relate to each other 448(should they be integrated or separated). 449Implemented behavior is very different from kernel to kernel. 450Therefore, it is unwise to rely too much upon the behavior of 451.Dv AF_INET6 452wildcard bind sockets. 453It is recommended to listen to two sockets, one for 454.Dv AF_INET 455and another for 456.Dv AF_INET6 , 457when you would like to accept both IPv4 and IPv6 traffic. 458.Pp 459It should also be noted that 460malicious parties can take advantage of the complexity presented above, 461and are able to bypass access control, 462if the target node routes IPv4 traffic to 463.Dv AF_INET6 464socket. 465Users are advised to take care handling connections 466from IPv4 mapped address to 467.Dv AF_INET6 468sockets. 469.\".Pp 470.\"Because of the above, by default, 471.\"KAME/NetBSD and KAME/OpenBSD 472.\"does not route IPv4 traffic to 473.\".Dv AF_INET6 474.\"sockets. 475.\"Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. 476.\"On KAME/NetBSD, IPv4 traffic may be routed with certain 477.\"per-socket/per-node configuration, however, it is not recommended. 478.\"Consult 479.\".Xr ip6 4 480.\"for details. 481.Sh SEE ALSO 482.Xr ioctl 2 , 483.Xr socket 2 , 484.Xr sysctl 3 , 485.Xr icmp6 4 , 486.Xr intro 4 , 487.Xr ip6 4 , 488.Xr tcp 4 , 489.Xr udp 4 490.Sh STANDARDS 491.Rs 492.%A Tatsuya Jinmei 493.%A Atsushi Onoe 494.%T "An Extension of Format for IPv6 Scoped Addresses" 495.%R internet draft 496.%D June 2000 497.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 498.%O work in progress material 499.Re 500.Sh HISTORY 501The 502.Nm 503protocol interfaces are defined in RFC 2553 and RFC 2292. 504The implementation described herein appeared in the WIDE/KAME project. 505.Sh BUGS 506The IPv6 support is subject to change as the Internet protocols develop. 507Users should not depend on details of the current implementation, 508but rather the services exported. 509.Pp 510Users are suggested to implement 511.Dq version independent 512code as much as possible, as you will need to support both 513.Xr inet 4 514and 515.Nm . 516