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 September 2, 2009 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 affect 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 ping6 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 net.inet6 branch 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_MAXFRAGPACKETS 223.Pq ip6.maxfragpackets 224Integer: default maximum number of fragmented packets the node will accept. 2250 means that the node will not accept any fragmented packets. 226-1 means that the node will accept as many fragmented packets as it receives. 227The flag is provided basically for avoiding possible DoS attacks. 228.It Dv IPV6CTL_ACCEPT_RTADV 229.Pq ip6.accept_rtadv 230Boolean: the default value of a per-interface flag to 231enable/disable receiving of 232.Tn ICMPv6 233router advertisement packets, 234and autoconfiguration of address prefixes and default routers. 235The node must be a host 236(not a router) 237for the option to be meaningful. 238Defaults to off. 239.It Dv IPV6CTL_AUTO_LINKLOCAL 240.Pq ip6.auto_linklocal 241Boolean: the default value of a per-interface flag to 242enable/disable performing automatic link-local address configuration. 243Defaults to on. 244.It Dv IPV6CTL_KEEPFAITH 245.Pq ip6.keepfaith 246Boolean: enable/disable 247.Dq FAITH 248TCP relay IPv6-to-IPv4 translator code in the kernel. 249Refer 250.Xr faith 4 251and 252.Xr faithd 8 253for detail. 254Defaults to off. 255.It Dv IPV6CTL_LOG_INTERVAL 256.Pq ip6.log_interval 257Integer: default interval between 258.Tn IPv6 259packet forwarding engine log output 260(in seconds). 261.It Dv IPV6CTL_HDRNESTLIMIT 262.Pq ip6.hdrnestlimit 263Integer: default number of the maximum 264.Tn IPv6 265extension headers 266permitted on incoming 267.Tn IPv6 268packets. 269If set to 0, the node will accept as many extension headers as possible. 270.It Dv IPV6CTL_DAD_COUNT 271.Pq ip6.dad_count 272Integer: default number of 273.Tn IPv6 274DAD 275.Pq duplicated address detection 276probe packets. 277The packets will be generated when 278.Tn IPv6 279interface addresses are configured. 280.It Dv IPV6CTL_AUTO_FLOWLABEL 281.Pq ip6.auto_flowlabel 282Boolean: enable/disable automatic filling of 283.Tn IPv6 284flowlabel field, for outstanding connected transport protocol packets. 285The field might be used by intermediate routers to identify packet flows. 286Defaults to on. 287.It Dv IPV6CTL_DEFMCASTHLIM 288.Pq ip6.defmcasthlim 289Integer: default hop limit value for an 290.Tn IPv6 291multicast packet sourced by the node. 292This value applies to all the transport protocols on top of 293.Tn IPv6 . 294There are APIs to override the value as documented in 295.Xr ip6 4 . 296.It Dv IPV6CTL_GIF_HLIM 297.Pq ip6.gifhlim 298Integer: default maximum hop limit value for an 299.Tn IPv6 300packet generated by 301.Xr gif 4 302tunnel interface. 303.It Dv IPV6CTL_KAME_VERSION 304.Pq ip6.kame_version 305String: identifies the version of KAME 306.Tn IPv6 307stack implemented in the kernel. 308.It Dv IPV6CTL_USE_DEPRECATED 309.Pq ip6.use_deprecated 310Boolean: enable/disable use of deprecated address, 311specified in RFC2462 5.5.4. 312Defaults to on. 313.It Dv IPV6CTL_RR_PRUNE 314.Pq ip6.rr_prune 315Integer: default interval between 316.Tn IPv6 317router renumbering prefix babysitting, in seconds. 318.It Dv IPV6CTL_V6ONLY 319.Pq ip6.v6only 320Boolean: enable/disable the prohibited use of 321.Tn IPv4 322mapped address on 323.Dv AF_INET6 324sockets. 325Defaults to on. 326.It Dv IPV6CTL_RTEXPIRE 327.Pq ip6.rtexpire 328Integer: lifetime in seconds of protocol-cloned 329.Tn IP 330routes after the last reference drops (default one hour). 331.\"This value varies dynamically as described above. 332.It Dv IPV6CTL_RTMINEXPIRE 333.Pq ip6.rtminexpire 334Integer: minimum value of ip.rtexpire (default ten seconds). 335.\"This value has no effect on user modifications, but restricts the dynamic 336.\"adaptation described above. 337.It Dv IPV6CTL_RTMAXCACHE 338.Pq ip6.rtmaxcache 339Integer: trigger level of cached, unreferenced, protocol-cloned routes 340which initiates dynamic adaptation (default 128). 341.El 342.Ss Interaction between IPv4/v6 sockets 343By default, 344.Fx 345does not route IPv4 traffic to 346.Dv AF_INET6 347sockets. 348The default behavior intentionally violates RFC2553 for security reasons. 349Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. 350IPv4 traffic may be routed with certain 351per-socket/per-node configuration, however, it is not recommended to do so. 352Consult 353.Xr ip6 4 354for details. 355.Pp 356The behavior of 357.Dv AF_INET6 358TCP/UDP socket is documented in RFC2553. 359Basically, it says this: 360.Bl -bullet -compact 361.It 362A specific bind on an 363.Dv AF_INET6 364socket 365.Xr ( bind 2 366with an address specified) 367should accept IPv6 traffic to that address only. 368.It 369If you perform a wildcard bind 370on an 371.Dv AF_INET6 372socket 373.Xr ( bind 2 374to IPv6 address 375.Li :: ) , 376and there is no wildcard bind 377.Dv AF_INET 378socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 379should be routed to that 380.Dv AF_INET6 381socket. 382IPv4 traffic should be seen as if it came from an IPv6 address like 383.Li ::ffff:10.1.1.1 . 384This is called an IPv4 mapped address. 385.It 386If there are both a wildcard bind 387.Dv AF_INET 388socket and a wildcard bind 389.Dv AF_INET6 390socket on one TCP/UDP port, they should behave separately. 391IPv4 traffic should be routed to the 392.Dv AF_INET 393socket and IPv6 should be routed to the 394.Dv AF_INET6 395socket. 396.El 397.Pp 398However, RFC2553 does not define the ordering constraint between calls to 399.Xr bind 2 , 400nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers 401relate to each other 402(should they be integrated or separated). 403Implemented behavior is very different from kernel to kernel. 404Therefore, it is unwise to rely too much upon the behavior of 405.Dv AF_INET6 406wildcard bind sockets. 407It is recommended to listen to two sockets, one for 408.Dv AF_INET 409and another for 410.Dv AF_INET6 , 411when you would like to accept both IPv4 and IPv6 traffic. 412.Pp 413It should also be noted that 414malicious parties can take advantage of the complexity presented above, 415and are able to bypass access control, 416if the target node routes IPv4 traffic to 417.Dv AF_INET6 418socket. 419Users are advised to take care handling connections 420from IPv4 mapped address to 421.Dv AF_INET6 422sockets. 423.Sh SEE ALSO 424.Xr ioctl 2 , 425.Xr socket 2 , 426.Xr sysctl 3 , 427.Xr icmp6 4 , 428.Xr intro 4 , 429.Xr ip6 4 , 430.Xr tcp 4 , 431.Xr udp 4 432.Sh STANDARDS 433.Rs 434.%A Tatsuya Jinmei 435.%A Atsushi Onoe 436.%T "An Extension of Format for IPv6 Scoped Addresses" 437.%R internet draft 438.%D June 2000 439.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 440.%O work in progress material 441.Re 442.Sh HISTORY 443The 444.Nm 445protocol interfaces are defined in RFC2553 and RFC2292. 446The implementation described herein appeared in the WIDE/KAME project. 447.Sh BUGS 448The IPv6 support is subject to change as the Internet protocols develop. 449Users should not depend on details of the current implementation, 450but rather the services exported. 451.Pp 452Users are suggested to implement 453.Dq version independent 454code as much as possible, as you will need to support both 455.Xr inet 4 456and 457.Nm . 458