1.\" $FreeBSD$ 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 January 29, 1999 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 uint8_t sin6_len; 81 sa_family_t sin6_family; 82 in_port_t sin6_port; 83 uint32_t sin6_flowinfo; 84 struct in6_addr sin6_addr; 85 uint32_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 RFC2292. 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 3/4, 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_KEEPFAITH 318.Pq ip6.keepfaith 319Boolean: enable/disable 320.Dq FAITH 321TCP relay IPv6-to-IPv4 translator code in the kernel. 322Refer 323.Xr faith 4 324and 325.Xr faithd 8 326for detail. 327Defaults to off. 328.It Dv IPV6CTL_LOG_INTERVAL 329.Pq ip6.log_interval 330Integer: default interval between 331.Tn IPv6 332packet forwarding engine log output 333(in seconds). 334.It Dv IPV6CTL_HDRNESTLIMIT 335.Pq ip6.hdrnestlimit 336Integer: default number of the maximum 337.Tn IPv6 338extension headers 339permitted on incoming 340.Tn IPv6 341packets. 342If set to 0, the node will accept as many extension headers as possible. 343.It Dv IPV6CTL_DAD_COUNT 344.Pq ip6.dad_count 345Integer: default number of 346.Tn IPv6 347DAD 348.Pq duplicated address detection 349probe packets. 350The packets will be generated when 351.Tn IPv6 352interface addresses are configured. 353.It Dv IPV6CTL_AUTO_FLOWLABEL 354.Pq ip6.auto_flowlabel 355Boolean: enable/disable automatic filling of 356.Tn IPv6 357flowlabel field, for outstanding connected transport protocol packets. 358The field might be used by intermediate routers to identify packet flows. 359Defaults to on. 360.It Dv IPV6CTL_DEFMCASTHLIM 361.Pq ip6.defmcasthlim 362Integer: default hop limit value for an 363.Tn IPv6 364multicast packet sourced by the node. 365This value applies to all the transport protocols on top of 366.Tn IPv6 . 367There are APIs to override the value as documented in 368.Xr ip6 4 . 369.It Dv IPV6CTL_GIF_HLIM 370.Pq ip6.gifhlim 371Integer: default maximum hop limit value for an 372.Tn IPv6 373packet generated by 374.Xr gif 4 375tunnel interface. 376.It Dv IPV6CTL_KAME_VERSION 377.Pq ip6.kame_version 378String: identifies the version of KAME 379.Tn IPv6 380stack implemented in the kernel. 381.It Dv IPV6CTL_USE_DEPRECATED 382.Pq ip6.use_deprecated 383Boolean: enable/disable use of deprecated address, 384specified in RFC2462 5.5.4. 385Defaults to on. 386.It Dv IPV6CTL_RR_PRUNE 387.Pq ip6.rr_prune 388Integer: default interval between 389.Tn IPv6 390router renumbering prefix babysitting, in seconds. 391.It Dv IPV6CTL_V6ONLY 392.Pq ip6.v6only 393Boolean: enable/disable the prohibited use of 394.Tn IPv4 395mapped address on 396.Dv AF_INET6 397sockets. 398Defaults to on. 399.It Dv IPV6CTL_RTEXPIRE 400.Pq ip6.rtexpire 401Integer: lifetime in seconds of protocol-cloned 402.Tn IP 403routes after the last reference drops (default one hour). 404.\"This value varies dynamically as described above. 405.It Dv IPV6CTL_RTMINEXPIRE 406.Pq ip6.rtminexpire 407Integer: minimum value of ip.rtexpire (default ten seconds). 408.\"This value has no effect on user modifications, but restricts the dynamic 409.\"adaptation described above. 410.It Dv IPV6CTL_RTMAXCACHE 411.Pq ip6.rtmaxcache 412Integer: trigger level of cached, unreferenced, protocol-cloned routes 413which initiates dynamic adaptation (default 128). 414.El 415.Ss Interaction between IPv4/v6 sockets 416By default, 417.Fx 418does not route IPv4 traffic to 419.Dv AF_INET6 420sockets. 421The default behavior intentionally violates RFC2553 for security reasons. 422Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. 423IPv4 traffic may be routed with certain 424per-socket/per-node configuration, however, it is not recommended to do so. 425Consult 426.Xr ip6 4 427for details. 428.Pp 429The behavior of 430.Dv AF_INET6 431TCP/UDP socket is documented in RFC2553. 432Basically, it says this: 433.Bl -bullet -compact 434.It 435A specific bind on an 436.Dv AF_INET6 437socket 438.Xr ( bind 2 439with an address specified) 440should accept IPv6 traffic to that address only. 441.It 442If you perform a wildcard bind 443on an 444.Dv AF_INET6 445socket 446.Xr ( bind 2 447to IPv6 address 448.Li :: ) , 449and there is no wildcard bind 450.Dv AF_INET 451socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 452should be routed to that 453.Dv AF_INET6 454socket. 455IPv4 traffic should be seen as if it came from an IPv6 address like 456.Li ::ffff:10.1.1.1 . 457This is called an IPv4 mapped address. 458.It 459If there are both a wildcard bind 460.Dv AF_INET 461socket and a wildcard bind 462.Dv AF_INET6 463socket on one TCP/UDP port, they should behave separately. 464IPv4 traffic should be routed to the 465.Dv AF_INET 466socket and IPv6 should be routed to the 467.Dv AF_INET6 468socket. 469.El 470.Pp 471However, RFC2553 does not define the ordering constraint between calls to 472.Xr bind 2 , 473nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers 474relate to each other 475(should they be integrated or separated). 476Implemented behavior is very different from kernel to kernel. 477Therefore, it is unwise to rely too much upon the behavior of 478.Dv AF_INET6 479wildcard bind sockets. 480It is recommended to listen to two sockets, one for 481.Dv AF_INET 482and another for 483.Dv AF_INET6 , 484when you would like to accept both IPv4 and IPv6 traffic. 485.Pp 486It should also be noted that 487malicious parties can take advantage of the complexity presented above, 488and are able to bypass access control, 489if the target node routes IPv4 traffic to 490.Dv AF_INET6 491socket. 492Users are advised to take care handling connections 493from IPv4 mapped address to 494.Dv AF_INET6 495sockets. 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