1.\" $NetBSD: inet6.4,v 1.17 2000/11/24 10:10:34 itojun Exp $ 2.\" $KAME: inet6.4,v 1.18 2000/11/24 08:50:32 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. 98.Pp 99IPv6 specification defines scoped address, 100like link-local or site-local address. 101A scoped address is ambiguous to the kernel, 102if it is specified without scope identifier. 103To manipulate scoped addresses properly from the userland, 104programs must use advanced API defined in RFC2292. 105Compact description on the advanced API is available in 106.Xr ip6 4 . 107If scoped addresses are specified without explicit scope, 108the kernel may raise error. 109Note that scoped addresses are not for daily use at this moment, 110both from specification and implementation point of view. 111.Pp 112KAME implementation supports extended numeric IPv6 address notation 113for link-local addresses, 114like 115.Dq Li fe80::1%de0 116to specify 117.Do 118.Li fe80::1 119on 120.Li de0 121interface 122.Dc . 123The notation is supported by 124.Xr getaddrinfo 3 125and 126.Xr getnameinfo 3 . 127Some of normal userland programs, such as 128.Xr telnet 1 129or 130.Xr ftp 1 , 131are able to use the notation. 132With special programs 133like 134.Xr ping6 8 , 135you can specify outgoing interface by extra command line option 136to disambiguate scoped addresses. 137.Pp 138Scoped addresses are handled specially in the kernel. 139In the kernel structures like routing tables or interface structure, 140scoped addresses will have its interface index embedded into the address. 141Therefore, 142the address on some of the kernel structure is not the same as that on the wire. 143The embedded index will become visible on 144.Dv PF_ROUTE 145socket, kernel memory accesses via 146.Xr kvm 3 147and some other occasions. 148HOWEVER, users should never use the embedded form. 149For details please consult 150.Pa sys/netinet6/IMPLEMENTATION . 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 inet6 . 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 Interaction between IPv4/v6 sockets 268The behavior of 269.Dv AF_INET6 270TCP/UDP socket is documented in RFC2553. 271Basically, it says as follows: 272.Bl -bullet -compact 273.It 274Specific bind on 275.Dv AF_INET6 276socket 277.Po 278.Xr bind 2 279with address specified 280.Pc 281should accept IPv6 traffic to that address only. 282.It 283If you perform wildcard bind 284on 285.Dv AF_INET6 286socket 287.Po 288.Xr bind 2 289to IPv6 address 290.Li :: 291.Pc , 292and there is no wildcard bind 293.Dv AF_INET 294socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 295should be routed to that 296.Dv AF_INET6 297socket. 298IPv4 traffic should be seen as if it came from IPv6 address like 299.Li ::ffff:10.1.1.1 . 300This is called IPv4 mapped address. 301.It 302If there are both wildcard bind 303.Dv AF_INET 304socket and wildcard bind 305.Dv AF_INET6 306socket on one TCP/UDP port, they should behave separately. 307IPv4 traffic should be routed to 308.Dv AF_INET 309socket and IPv6 should be routed to 310.Dv AF_INET6 311socket. 312.El 313.Pp 314However, RFC2553 does not define the constraint between the order of 315.Xr bind 2 , 316nor how IPv4 TCP/UDP port number and IPv6 TCP/UDP port number 317relate each other 318.Po 319should they be integrated or separated 320.Pc . 321Implemented behavior is very different across kernel to kernel. 322Therefore, it is unwise to rely too much upon the behavior of 323.Dv AF_INET6 324wildcard bind socket. 325It is recommended to listen to two sockets, one for 326.Dv AF_INET 327and another for 328.Dv AF_INET6 , 329when you would like to accept both IPv4 and IPv6 traffic. 330.Pp 331It should also be noted that 332malicious parties can take advantage of the complexity presented above, 333and are able to bypass access control, 334if the target node routes IPv4 traffic to 335.Dv AF_INET6 336socket. 337Users are advised to take caution handling connections 338from IPv4 mapped address to 339.Dv AF_INET6 340sockets. 341.Pp 342Because of the above, by default, 343.Nx 344does not route IPv4 traffic to 345.Dv AF_INET6 346socket. 347Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. 348IPv4 traffic may be routed with certain 349per-socket/per-node configuration, however, it is not recommended to do so. 350Consult 351.Xr ip6 4 352for details. 353.Sh SEE ALSO 354.Xr ioctl 2 , 355.Xr socket 2 , 356.Xr sysctl 3 , 357.Xr icmp6 4 , 358.Xr intro 4 , 359.Xr ip6 4 , 360.Xr tcp 4 , 361.Xr udp 4 362.Sh STANDARDS 363.Rs 364.%A Tatsuya Jinmei 365.%A Atsushi Onoe 366.%T "An Extension of Format for IPv6 Scoped Addresses" 367.%R internet draft 368.%D June 2000 369.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 370.%O work in progress material 371.Re 372.Sh HISTORY 373The 374.Nm 375protocol interface are defined in RFC2553 and RFC2292. 376The implementation described herein appeared in WIDE/KAME project. 377.Sh BUGS 378The IPv6 support is subject to change as the Internet protocols develop. 379Users should not depend on details of the current implementation, 380but rather the services exported. 381.Pp 382Users are suggested to implement 383.Dq version independent 384code as much as possible, as you will need to support both 385.Xr inet 4 386and 387.Nm inet6 . 388