1.\" $NetBSD: inet6.4,v 1.16 2000/06/26 16:12:33 kleink Exp $ 2.\" $KAME: inet6.4,v 1.15 2000/06/15 14:21:50 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.Fd #include <sys/types.h> 39.Fd #include <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.Aq Pa 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.Po 92which is equal to IPv6 address 93.Dv 0:0:0:0:0:0:0:0 94.Pc 95to effect 96.Dq wildcard 97matching on incoming messages. 98The address in a 99.Xr connect 2 100or 101.Xr sendto 2 102call may be given as 103.Dq Dv :: 104to mean 105.Dq this host . 106.Dq Dv :: 107can be obtained by setting 108.Dv sin6_addr 109field into 0, or by using the address contained in variable 110.Dv in6addr_any . 111.Pp 112IPv6 specification defines scoped address, 113like link-local or site-local address. 114A scoped address is ambiguous to the kernel, 115if it is specified without scope identifier. 116To manipulate scoped addresses properly from the userland, 117programs must use advanced API defined in RFC2292. 118Compact description on the advanced API is available in 119.Xr ip6 4 . 120If scoped addresses are specified without explicit scope, 121the kernel may raise error. 122Note that scoped addresses are not for daily use at this moment, 123both from specification and implementation point of view. 124.Pp 125KAME implementation supports extended numeric IPv6 address notation 126for link-local addresses, 127like 128.Dq Li fe80::1%de0 129to specify 130.Do 131.Li fe80::1 132on 133.Li de0 134interface 135.Dc . 136The notation is supported by 137.Xr getaddrinfo 3 138and 139.Xr getnameinfo 3 . 140Some of normal userland programs, such as 141.Xr telnet 1 142or 143.Xr ftp 1 , 144are able to use the notation. 145With special programs 146like 147.Xr ping6 8 , 148you can specify outgoing interface by extra command line option 149to disambiguate scoped addresses. 150.Pp 151Scoped addresses are handled specially in the kernel. 152In the kernel structures like routing tables or interface structure, 153scoped addresses will have its interface index embedded into the address. 154Therefore, 155the address on some of the kernel structure is not the same as that on the wire. 156The embedded index will become visible on 157.Dv PF_ROUTE 158socket, kernel memory accesses via 159.Xr kvm 3 160and some other occasions. 161HOWEVER, users should never use the embedded form. 162For details please consult 163.Pa sys/netinet6/IMPLEMENTATION . 164.Sh PROTOCOLS 165The 166.Nm 167family is comprised of the 168.Tn IPv6 169network protocol, Internet Control 170Message Protocol version 6 171.Pq Tn ICMPv6 , 172Transmission Control Protocol 173.Pq Tn TCP , 174and User Datagram Protocol 175.Pq Tn UDP . 176.Tn TCP 177is used to support the 178.Dv SOCK_STREAM 179abstraction while 180.Tn UDP 181is used to support the 182.Dv SOCK_DGRAM 183abstraction. 184Note that 185.Tn TCP 186and 187.Tn UDP 188are common to 189.Xr inet 4 190and 191.Nm inet6 . 192A raw interface to 193.Tn IPv6 194is available 195by creating an Internet socket of type 196.Dv SOCK_RAW . 197The 198.Tn ICMPv6 199message protocol is accessible from a raw socket. 200.\" .Pp 201.\" The 128-bit IPv6 address contains both network and host parts. 202.\" However, direct examination of addresses is discouraged. 203.\" For those programs which absolutely need to break addresses 204.\" into their component parts, the following 205.\" .Xr ioctl 2 206.\" commands are provided for a datagram socket in the 207.\" .Nm 208.\" domain; they have the same form as the 209.\" .Dv SIOCIFADDR 210.\" command (see 211.\" .Xr intro 4 ) . 212.\" .Pp 213.\" .Bl -tag -width SIOCSIFNETMASK 214.\" .It Dv SIOCSIFNETMASK 215.\" Set interface network mask. 216.\" The network mask defines the network part of the address; 217.\" if it contains more of the address than the address type would indicate, 218.\" then subnets are in use. 219.\" .It Dv SIOCGIFNETMASK 220.\" Get interface network mask. 221.\" .El 222.\" .Sh ROUTING 223.\" The current implementation of Internet protocols includes some routing-table 224.\" adaptations to provide enhanced caching of certain end-to-end 225.\" information necessary for Transaction TCP and Path MTU Discovery. The 226.\" following changes are the most significant: 227.\" .Bl -enum 228.\" .It 229.\" All IP routes, except those with the 230.\" .Dv RTF_CLONING 231.\" flag and those to multicast destinations, have the 232.\" .Dv RTF_PRCLONING 233.\" flag forcibly enabled (they are thus said to be 234.\" .Dq "protocol cloning" ). 235.\" .It 236.\" When the last reference to an IP route is dropped, the route is 237.\" examined to determine if it was created by cloning such a route. If 238.\" this is the case, the 239.\" .Dv RTF_PROTO3 240.\" flag is turned on, and the expiration timer is initialized to go off 241.\" in net.inet.ip.rtexpire seconds. If such a route is re-referenced, 242.\" the flag and expiration timer are reset. 243.\" .It 244.\" A kernel timeout runs once every ten minutes, or sooner if there are 245.\" soon-to-expire routes in the kernel routing table, and deletes the 246.\" expired routes. 247.\" .El 248.\" .Pp 249.\" A dynamic process is in place to modify the value of 250.\" net.inet.ip.rtexpire if the number of cached routes grows too large. 251.\" If after an expiration run there are still more than 252.\" net.inet.ip.rtmaxcache unreferenced routes remaining, the rtexpire 253.\" value is multiplied by 3/4, and any routes which have longer 254.\" expiration times have those times adjusted. This process is damped 255.\" somewhat by specification of a minimum rtexpire value 256.\" (net.inet.ip.rtminexpire), and by restricting the reduction to once in 257.\" a ten-minute period. 258.\" .Pp 259.\" If some external process deletes the original route from which a 260.\" protocol-cloned route was generated, the ``child route'' is deleted. 261.\" (This is actually a generic mechanism in the routing code support for 262.\" protocol-requested cloning.) 263.\" .Pp 264.\" No attempt is made to manage routes which were not created by protocol 265.\" cloning; these are assumed to be static, under the management of an 266.\" external routing process, or under the management of a link layer 267.\" (e.g., 268.\" .Tn ARP 269.\" for Ethernets). 270.\" .Pp 271.\" Only certain types of network activity will result in the cloning of a 272.\" route using this mechanism. Specifically, those protocols (such as 273.\" .Tn TCP 274.\" and 275.\" .Tn UDP ) 276.\" which themselves cache a long-lasting reference to route for a destination 277.\" will trigger the mechanism; whereas raw 278.\" .Tn IP 279.\" packets, whether locally-generated or forwarded, will not. 280.Ss Interaction between IPv4/v6 sockets 281The behavior of 282.Dv AF_INET6 283TCP/UDP socket is documented in RFC2553. 284Basically, it says as follows: 285.Bl -bullet -compact 286.It 287Specific bind on 288.Dv AF_INET6 289socket 290.Po 291.Xr bind 2 292with address specified 293.Pc 294should accept IPv6 traffic to that address only. 295.It 296If you perform wildcard bind 297on 298.Dv AF_INET6 299socket 300.Po 301.Xr bind 2 302to IPv6 address 303.Li :: 304.Pc , 305and there is no wildcard bind 306.Dv AF_INET 307socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 308should be routed to that 309.Dv AF_INET6 310socket. 311IPv4 traffic should be seen as if it came from IPv6 address like 312.Li ::ffff:10.1.1.1 . 313This is called IPv4 mapped address. 314.It 315If there are both wildcard bind 316.Dv AF_INET 317socket and wildcard bind 318.Dv AF_INET6 319socket on one TCP/UDP port, they should behave separately. 320IPv4 traffic should be routed to 321.Dv AF_INET 322socket and IPv6 should be routed to 323.Dv AF_INET6 324socket. 325.El 326.Pp 327However, RFC2553 does not define the constraint between the order of 328.Xr bind 2 , 329nor how IPv4 TCP/UDP port number and IPv6 TCP/UDP port number 330relate each other 331.Po 332should they be integrated or separated 333.Pc . 334Implemented behavior is very different across kernel to kernel. 335Therefore, it is unwise to rely too much upon the behavior of 336.Dv AF_INET6 337wildcard bind socket. 338It is recommended to listen to two sockets, one for 339.Dv AF_INET 340and another for 341.Dv AF_INET6 , 342when you would like to accept both IPv4 and IPv6 traffic. 343.Pp 344It should also be noted that 345malicious parties can take advantage of the complexity presented above, 346and are able to bypass access control, 347if the target node routes IPv4 traffic to 348.Dv AF_INET6 349socket. 350Users are advised to take caution handling connections 351from IPv4 mapped address to 352.Dv AF_INET6 353sockets. 354.Pp 355Because of the above, by default, 356.Nx 357does not route IPv4 traffic to 358.Dv AF_INET6 359socket. 360Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. 361IPv4 traffic may be routed with certain 362per-socket/per-node configuration, however, it is not recommended to do so. 363Consult 364.Xr ip6 4 365for details. 366.Sh SEE ALSO 367.Xr ioctl 2 , 368.Xr socket 2 , 369.Xr sysctl 3 , 370.Xr icmp6 4 , 371.Xr intro 4 , 372.Xr ip6 4 , 373.Xr tcp 4 , 374.Xr udp 4 375.Sh STANDARDS 376.Rs 377.%A Tatsuya Jinmei 378.%A Atsushi Onoe 379.%T "An Extension of Format for IPv6 Scoped Addresses" 380.%R internet draft 381.%D March 2000 382.%N draft-ietf-ipngwg-scopedaddr-format-01.txt 383.%O work in progress material 384.Re 385.Sh HISTORY 386The 387.Nm 388protocol interface are defined in RFC2553 and RFC2292. 389The implementation described herein appeared in WIDE/KAME project. 390.Sh BUGS 391The IPv6 support is subject to change as the Internet protocols develop. 392Users should not depend on details of the current implementation, 393but rather the services exported. 394.Pp 395Users are suggested to implement 396.Dq version independent 397code as much as possible, as you will need to support both 398.Xr inet 4 399and 400.Nm inet6 . 401