1.\" $FreeBSD: src/share/man/man4/inet6.4,v 1.4.2.9 2002/05/15 16:45:30 ume Exp $ 2.\" $DragonFly: src/share/man/man4/inet6.4,v 1.2 2003/06/17 04:36:59 dillon Exp $ 3.\" $KAME: inet6.4,v 1.21 2001/04/05 01:00:18 itojun Exp $ 4.\" 5.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the project nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd January 29, 1999 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.Aq Pa 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 u_int8_t sin6_len; 82 u_int8_t sin6_family; 83 u_int16_t sin6_port; 84 u_int32_t sin6_flowinfo; 85 struct in6_addr sin6_addr; 86 u_int32_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.\" .Pp 188.\" The 128-bit IPv6 address contains both network and host parts. 189.\" However, direct examination of addresses is discouraged. 190.\" For those programs which absolutely need to break addresses 191.\" into their component parts, the following 192.\" .Xr ioctl 2 193.\" commands are provided for a datagram socket in the 194.\" .Nm 195.\" domain; they have the same form as the 196.\" .Dv SIOCIFADDR 197.\" command (see 198.\" .Xr intro 4 ) . 199.\" .Pp 200.\" .Bl -tag -width SIOCSIFNETMASK 201.\" .It Dv SIOCSIFNETMASK 202.\" Set interface network mask. 203.\" The network mask defines the network part of the address; 204.\" if it contains more of the address than the address type would indicate, 205.\" then subnets are in use. 206.\" .It Dv SIOCGIFNETMASK 207.\" Get interface network mask. 208.\" .El 209.\" .Sh ROUTING 210.\" The current implementation of Internet protocols includes some routing-table 211.\" adaptations to provide enhanced caching of certain end-to-end 212.\" information necessary for Transaction TCP and Path MTU Discovery. The 213.\" following changes are the most significant: 214.\" .Bl -enum 215.\" .It 216.\" All IP routes, except those with the 217.\" .Dv RTF_CLONING 218.\" flag and those to multicast destinations, have the 219.\" .Dv RTF_PRCLONING 220.\" flag forcibly enabled (they are thus said to be 221.\" .Dq "protocol cloning" ). 222.\" .It 223.\" When the last reference to an IP route is dropped, the route is 224.\" examined to determine if it was created by cloning such a route. If 225.\" this is the case, the 226.\" .Dv RTF_PROTO3 227.\" flag is turned on, and the expiration timer is initialized to go off 228.\" in net.inet.ip.rtexpire seconds. If such a route is re-referenced, 229.\" the flag and expiration timer are reset. 230.\" .It 231.\" A kernel timeout runs once every ten minutes, or sooner if there are 232.\" soon-to-expire routes in the kernel routing table, and deletes the 233.\" expired routes. 234.\" .El 235.\" .Pp 236.\" A dynamic process is in place to modify the value of 237.\" net.inet.ip.rtexpire if the number of cached routes grows too large. 238.\" If after an expiration run there are still more than 239.\" net.inet.ip.rtmaxcache unreferenced routes remaining, the rtexpire 240.\" value is multiplied by 3/4, and any routes which have longer 241.\" expiration times have those times adjusted. This process is damped 242.\" somewhat by specification of a minimum rtexpire value 243.\" (net.inet.ip.rtminexpire), and by restricting the reduction to once in 244.\" a ten-minute period. 245.\" .Pp 246.\" If some external process deletes the original route from which a 247.\" protocol-cloned route was generated, the ``child route'' is deleted. 248.\" (This is actually a generic mechanism in the routing code support for 249.\" protocol-requested cloning.) 250.\" .Pp 251.\" No attempt is made to manage routes which were not created by protocol 252.\" cloning; these are assumed to be static, under the management of an 253.\" external routing process, or under the management of a link layer 254.\" (e.g., 255.\" .Tn ARP 256.\" for Ethernets). 257.\" .Pp 258.\" Only certain types of network activity will result in the cloning of a 259.\" route using this mechanism. Specifically, those protocols (such as 260.\" .Tn TCP 261.\" and 262.\" .Tn UDP ) 263.\" which themselves cache a long-lasting reference to route for a destination 264.\" will trigger the mechanism; whereas raw 265.\" .Tn IP 266.\" packets, whether locally-generated or forwarded, will not. 267.Ss MIB Variables 268A number of variables are implemented in the net.inet6 branch of the 269.Xr sysctl 3 270MIB. 271In addition to the variables supported by the transport protocols 272(for which the respective manual pages may be consulted), 273the following general variables are defined: 274.Bl -tag -width IPV6CTL_MAXFRAGPACKETS 275.It Dv IPV6CTL_FORWARDING 276.Pq ip6.forwarding 277Boolean: enable/disable forwarding of 278.Tn IPv6 279packets. 280Also, identify if the node is acting as a router. 281Defaults to off. 282.It Dv IPV6CTL_SENDREDIRECTS 283.Pq ip6.redirect 284Boolean: enable/disable sending of 285.Tn ICMPv6 286redirects in response to unforwardable 287.Tn IPv6 288packets. 289This option is ignored unless the node is routing 290.Tn IPv6 291packets, 292and should normally be enabled on all systems. 293Defaults to on. 294.It Dv IPV6CTL_DEFHLIM 295.Pq ip6.hlim 296Integer: default hop limit value to use for outgoing 297.Tn IPv6 298packets. 299This value applies to all the transport protocols on top of 300.Tn IPv6 . 301There are APIs to override the value. 302.It Dv IPV6CTL_MAXFRAGPACKETS 303.Pq ip6.maxfragpackets 304Integer: default maximum number of fragmented packets the node will accept. 3050 means that the node will not accept any fragmented packets. 306-1 means that the node will accept as many fragmented packets as it receives. 307The flag is provided basically for avoiding possible DoS attacks. 308.It Dv IPV6CTL_ACCEPT_RTADV 309.Pq ip6.accept_rtadv 310Boolean: enable/disable receiving of 311.Tn ICMPv6 312router advertisement packets, 313and autoconfiguration of address prefixes and default routers. 314The node must be a host 315(not a router) 316for the option to be meaningful. 317Defaults to off. 318.It Dv IPV6CTL_KEEPFAITH 319.Pq ip6.keepfaith 320Boolean: enable/disable 321.Dq FAITH 322TCP relay IPv6-to-IPv4 translator code in the kernel. 323Refer 324.Xr faith 4 325and 326.Xr faithd 8 327for detail. 328Defaults to off. 329.It Dv IPV6CTL_LOG_INTERVAL 330.Pq ip6.log_interval 331Integer: default interval between 332.Tn IPv6 333packet forwarding engine log output 334(in seconds). 335.It Dv IPV6CTL_HDRNESTLIMIT 336.Pq ip6.hdrnestlimit 337Integer: default number of the maximum 338.Tn IPv6 339extension headers 340permitted on incoming 341.Tn IPv6 342packets. 343If set to 0, the node will accept as many extension headers as possible. 344.It Dv IPV6CTL_DAD_COUNT 345.Pq ip6.dad_count 346Integer: default number of 347.Tn IPv6 348DAD 349.Pq duplicated address detection 350probe packets. 351The packets will be generated when 352.Tn IPv6 353interface addresses are configured. 354.It Dv IPV6CTL_AUTO_FLOWLABEL 355.Pq ip6.auto_flowlabel 356Boolean: enable/disable automatic filling of 357.Tn IPv6 358flowlabel field, for outstanding connected transport protocol packets. 359The field might be used by intermediate routers to identify packet flows. 360Defaults to on. 361.It Dv IPV6CTL_DEFMCASTHLIM 362.Pq ip6.defmcasthlim 363Integer: default hop limit value for an 364.Tn IPv6 365multicast packet sourced by the node. 366This value applies to all the transport protocols on top of 367.Tn IPv6 . 368There are APIs to override the value as documented in 369.Xr ip6 4 . 370.It Dv IPV6CTL_GIF_HLIM 371.Pq ip6.gifhlim 372Integer: default maximum hop limit value for an 373.Tn IPv6 374packet generated by 375.Xr gif 4 376tunnel interface. 377.It Dv IPV6CTL_KAME_VERSION 378.Pq ip6.kame_version 379String: identifies the version of KAME 380.Tn IPv6 381stack implemented in the kernel. 382.It Dv IPV6CTL_USE_DEPRECATED 383.Pq ip6.use_deprecated 384Boolean: enable/disable use of deprecated address, 385specified in RFC2462 5.5.4. 386Defaults to on. 387.It Dv IPV6CTL_RR_PRUNE 388.Pq ip6.rr_prune 389Integer: default interval between 390.Tn IPv6 391router renumbering prefix babysitting, in seconds. 392.It Dv IPV6CTL_V6ONLY 393.Pq ip6.v6only 394Boolean: enable/disable the prohibited use of 395.Tn IPv4 396mapped address on 397.Dv AF_INET6 398sockets. 399Defaults to off. 400.It Dv IPV6CTL_RTEXPIRE 401.Pq ip6.rtexpire 402Integer: lifetime in seconds of protocol-cloned 403.Tn IP 404routes after the last reference drops (default one hour). 405.\"This value varies dynamically as described above. 406.It Dv IPV6CTL_RTMINEXPIRE 407.Pq ip6.rtminexpire 408Integer: minimum value of ip.rtexpire (default ten seconds). 409.\"This value has no effect on user modifications, but restricts the dynamic 410.\"adaptation described above. 411.It Dv IPV6CTL_RTMAXCACHE 412.Pq ip6.rtmaxcache 413Integer: trigger level of cached, unreferenced, protocol-cloned routes 414which initiates dynamic adaptation (default 128). 415.El 416.Ss Interaction between IPv4/v6 sockets 417The behavior of 418.Dv AF_INET6 419TCP/UDP socket is documented in RFC2553. 420Basically, it says this: 421.Bl -bullet -compact 422.It 423A specific bind on an 424.Dv AF_INET6 425socket 426.Xr ( bind 2 427with an address specified) 428should accept IPv6 traffic to that address only. 429.It 430If you perform a wildcard bind 431on an 432.Dv AF_INET6 433socket 434.Xr ( bind 2 435to IPv6 address 436.Li :: ) , 437and there is no wildcard bind 438.Dv AF_INET 439socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 440should be routed to that 441.Dv AF_INET6 442socket. 443IPv4 traffic should be seen as if it came from an IPv6 address like 444.Li ::ffff:10.1.1.1 . 445This is called an IPv4 mapped address. 446.It 447If there are both a wildcard bind 448.Dv AF_INET 449socket and a wildcard bind 450.Dv AF_INET6 451socket on one TCP/UDP port, they should behave separately. 452IPv4 traffic should be routed to the 453.Dv AF_INET 454socket and IPv6 should be routed to the 455.Dv AF_INET6 456socket. 457.El 458.Pp 459However, RFC2553 does not define the ordering constraint between calls to 460.Xr bind 2 , 461nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers 462relate to each other 463(should they be integrated or separated). 464Implemented behavior is very different from kernel to kernel. 465Therefore, it is unwise to rely too much upon the behavior of 466.Dv AF_INET6 467wildcard bind sockets. 468It is recommended to listen to two sockets, one for 469.Dv AF_INET 470and another for 471.Dv AF_INET6 , 472when you would like to accept both IPv4 and IPv6 traffic. 473.Pp 474It should also be noted that 475malicious parties can take advantage of the complexity presented above, 476and are able to bypass access control, 477if the target node routes IPv4 traffic to 478.Dv AF_INET6 479socket. 480Users are advised to take care handling connections 481from IPv4 mapped address to 482.Dv AF_INET6 483sockets. 484.\".Pp 485.\"Because of the above, by default, 486.\"KAME/NetBSD and KAME/OpenBSD 487.\"does not route IPv4 traffic to 488.\".Dv AF_INET6 489.\"sockets. 490.\"Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. 491.\"On KAME/NetBSD, IPv4 traffic may be routed with certain 492.\"per-socket/per-node configuration, however, it is not recommended. 493.\"Consult 494.\".Xr ip6 4 495.\"for details. 496.Sh SEE ALSO 497.Xr ioctl 2 , 498.Xr socket 2 , 499.Xr sysctl 3 , 500.Xr icmp6 4 , 501.Xr intro 4 , 502.Xr ip6 4 , 503.Xr tcp 4 , 504.Xr ttcp 4 , 505.Xr udp 4 506.Sh STANDARDS 507.Rs 508.%A Tatsuya Jinmei 509.%A Atsushi Onoe 510.%T "An Extension of Format for IPv6 Scoped Addresses" 511.%R internet draft 512.%D June 2000 513.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 514.%O work in progress material 515.Re 516.Sh HISTORY 517The 518.Nm 519protocol interfaces are defined in RFC2553 and RFC2292. 520The implementation described herein appeared in the WIDE/KAME project. 521.Sh BUGS 522The IPv6 support is subject to change as the Internet protocols develop. 523Users should not depend on details of the current implementation, 524but rather the services exported. 525.Pp 526Users are suggested to implement 527.Dq version independent 528code as much as possible, as you will need to support both 529.Xr inet 4 530and 531.Nm . 532