1.\" $FreeBSD$ 2.\" $KAME: inet6.4,v 1.16 2000/07/05 08:18:42 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 u_int8_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 IMPLEMENTATION 164supplied with KAME kit. 165.Sh PROTOCOLS 166The 167.Nm 168family is comprised of the 169.Tn IPv6 170network protocol, Internet Control 171Message Protocol version 6 172.Pq Tn ICMPv6 , 173Transmission Control Protocol 174.Pq Tn TCP , 175and User Datagram Protocol 176.Pq Tn UDP . 177.Tn TCP 178is used to support the 179.Dv SOCK_STREAM 180abstraction while 181.Tn UDP 182is used to support the 183.Dv SOCK_DGRAM 184abstraction. 185Note that 186.Tn TCP 187and 188.Tn UDP 189are common to 190.Xr inet 4 191and 192.Nm . 193A raw interface to 194.Tn IPv6 195is available 196by creating an Internet socket of type 197.Dv SOCK_RAW . 198The 199.Tn ICMPv6 200message protocol is accessible from a raw socket. 201.\" .Pp 202.\" The 128-bit IPv6 address contains both network and host parts. 203.\" However, direct examination of addresses is discouraged. 204.\" For those programs which absolutely need to break addresses 205.\" into their component parts, the following 206.\" .Xr ioctl 2 207.\" commands are provided for a datagram socket in the 208.\" .Nm 209.\" domain; they have the same form as the 210.\" .Dv SIOCIFADDR 211.\" command (see 212.\" .Xr intro 4 ) . 213.\" .Pp 214.\" .Bl -tag -width SIOCSIFNETMASK 215.\" .It Dv SIOCSIFNETMASK 216.\" Set interface network mask. 217.\" The network mask defines the network part of the address; 218.\" if it contains more of the address than the address type would indicate, 219.\" then subnets are in use. 220.\" .It Dv SIOCGIFNETMASK 221.\" Get interface network mask. 222.\" .El 223.\" .Sh ROUTING 224.\" The current implementation of Internet protocols includes some routing-table 225.\" adaptations to provide enhanced caching of certain end-to-end 226.\" information necessary for Transaction TCP and Path MTU Discovery. The 227.\" following changes are the most significant: 228.\" .Bl -enum 229.\" .It 230.\" All IP routes, except those with the 231.\" .Dv RTF_CLONING 232.\" flag and those to multicast destinations, have the 233.\" .Dv RTF_PRCLONING 234.\" flag forcibly enabled (they are thus said to be 235.\" .Dq "protocol cloning" ). 236.\" .It 237.\" When the last reference to an IP route is dropped, the route is 238.\" examined to determine if it was created by cloning such a route. If 239.\" this is the case, the 240.\" .Dv RTF_PROTO3 241.\" flag is turned on, and the expiration timer is initialized to go off 242.\" in net.inet.ip.rtexpire seconds. If such a route is re-referenced, 243.\" the flag and expiration timer are reset. 244.\" .It 245.\" A kernel timeout runs once every ten minutes, or sooner if there are 246.\" soon-to-expire routes in the kernel routing table, and deletes the 247.\" expired routes. 248.\" .El 249.\" .Pp 250.\" A dynamic process is in place to modify the value of 251.\" net.inet.ip.rtexpire if the number of cached routes grows too large. 252.\" If after an expiration run there are still more than 253.\" net.inet.ip.rtmaxcache unreferenced routes remaining, the rtexpire 254.\" value is multiplied by 3/4, and any routes which have longer 255.\" expiration times have those times adjusted. This process is damped 256.\" somewhat by specification of a minimum rtexpire value 257.\" (net.inet.ip.rtminexpire), and by restricting the reduction to once in 258.\" a ten-minute period. 259.\" .Pp 260.\" If some external process deletes the original route from which a 261.\" protocol-cloned route was generated, the ``child route'' is deleted. 262.\" (This is actually a generic mechanism in the routing code support for 263.\" protocol-requested cloning.) 264.\" .Pp 265.\" No attempt is made to manage routes which were not created by protocol 266.\" cloning; these are assumed to be static, under the management of an 267.\" external routing process, or under the management of a link layer 268.\" (e.g., 269.\" .Tn ARP 270.\" for Ethernets). 271.\" .Pp 272.\" Only certain types of network activity will result in the cloning of a 273.\" route using this mechanism. Specifically, those protocols (such as 274.\" .Tn TCP 275.\" and 276.\" .Tn UDP ) 277.\" which themselves cache a long-lasting reference to route for a destination 278.\" will trigger the mechanism; whereas raw 279.\" .Tn IP 280.\" packets, whether locally-generated or forwarded, will not. 281.Ss MIB Variables 282A number of variables are implemented in the net.inet6 branch of the 283.Xr sysctl 3 284MIB. 285In addition to the variables supported by the transport protocols 286(for which the respective manual pages may be consulted), 287the following general variables are defined: 288.Bl -tag -width IPV6CTL_MAXFRAGPACKETS 289.It Dv IPV6CTL_FORWARDING 290.Pq ip6.forwarding 291Boolean: enable/disable forwarding of 292.Tn IPv6 293packets. 294Also, identify if the node is acting as a router. 295Defaults to off. 296.It Dv IPV6CTL_SENDREDIRECTS 297.Pq ip6.redirect 298Boolean: enable/disable sending of 299.Tn ICMPv6 300redirects in response to unforwardable 301.Tn IPv6 302packets. 303This option is ignored unless the node is routing 304.Tn IPv6 305packets, 306and should normally be enabled on all systems. 307Defaults to on. 308.It Dv IPV6CTL_DEFHLIM 309.Pq ip6.hlim 310Integer: default hop limit value to use for outgoing 311.Tn IPv6 312packets. 313This value applies to all the transport protocols on top of 314.Tn IPv6 . 315There are APIs to override the value. 316.It Dv IPV6CTL_MAXFRAGPACKETS 317.Pq ip6.maxfragpackets 318Integer: default maximum number of fragmented packets the node will accept. 3190 means that the node will not accept any fragmented packets. 320-1 means that the node will accept as many fragmented packets as it receives. 321The flag is provided basically for avoiding possible DoS attacks. 322.It Dv IPV6CTL_ACCEPT_RTADV 323.Pq ip6.accept_rtadv 324Boolean: enable/disable receiving of 325.Tn ICMPv6 326router advertisement packets, 327and autoconfiguration of address prefixes and default routers. 328The node must be a host 329.Pq not a router 330for the option to be meaningful. 331Defaults to off. 332.It Dv IPV6CTL_KEEPFAITH 333.Pq ip6.keepfaith 334Boolean: enable/disable 335.Dq FAITH 336TCP relay IPv6-to-IPv4 translator code in the kernel. 337Refer 338.Xr faith 4 339and 340.Xr faithd 8 341for detail. 342Defaults to off. 343.It Dv IPV6CTL_LOG_INTERVAL 344.Pq ip6.log_interval 345Integer: default interval between 346.Tn IPv6 347packet forwarding engine log output 348.Pq in seconds . 349.It Dv IPV6CTL_HDRNESTLIMIT 350.Pq ip6.hdrnestlimit 351Integer: default number of the maximum 352.Tn IPv6 353extension headers 354permitted on incoming 355.Tn IPv6 356packets. 357If set to 0, the node will accept as many extension headers as possible. 358.It Dv IPV6CTL_DAD_COUNT 359.Pq ip6.dad_count 360Integer: default number of 361.Tn IPv6 362DAD 363.Pq duplicated address detection 364probe packets. 365The packets will be generated when 366.Tn IPv6 367interface addresses are configured. 368.It Dv IPV6CTL_AUTO_FLOWLABEL 369.Pq ip6.auto_flowlabel 370Boolean: enable/disable automatic filling of 371.Tn IPv6 372flowlabel field, for outstanding connected transport protocol packets. 373The field might be used by intermediate routers to identify packet flows. 374Defaults to on. 375.It Dv IPV6CTL_DEFMCASTHLIM 376.Pq ip6.defmcasthlim 377Integer: default hop limit value for an 378.Tn IPv6 379multicast packet sourced by the node. 380This value applies to all the transport protocols on top of 381.Tn IPv6 . 382There are APIs to override the value as documented in 383.Xr ip6 4 . 384.It Dv IPV6CTL_GIF_HLIM 385.Pq ip6.gifhlim 386Integer: default maximum hop limit value for an 387.Tn IPv6 388packet generated by 389.Xr gif 4 390tunnel interface. 391.It Dv IPV6CTL_KAME_VERSION 392.Pq ip6.kame_version 393String: identifies the version of KAME 394.Tn IPv6 395stack implemented in the kernel. 396.It Dv IPV6CTL_USE_DEPRECATED 397.Pq ip6.use_deprecated 398Boolean: enable/disable use of deprecated address, 399specified in RFC2462 5.5.4. 400Defaults to on. 401.It Dv IPV6CTL_RR_PRUNE 402.Pq ip6.rr_prune 403Integer: default interval between 404.Tn IPv6 405router renumbering prefix babysitting, in seconds. 406.It Dv IPV6CTL_MAPPED_ADDR 407.Pq ip6.mapped_addr 408Boolean: enable/disable use of 409.Tn IPv4 410mapped address on 411.Dv AF_INET6 412sockets. 413Defaults to on. 414.It Dv IPV6CTL_RTEXPIRE 415.Pq ip6.rtexpire 416Integer: lifetime in seconds of protocol-cloned 417.Tn IP 418routes after the last reference drops (default one hour). 419.\"This value varies dynamically as described above. 420.It Dv IPV6CTL_RTMINEXPIRE 421.Pq ip6.rtminexpire 422Integer: minimum value of ip.rtexpire (default ten seconds). 423.\"This value has no effect on user modifications, but restricts the dynamic 424.\"adaptation described above. 425.It Dv IPV6CTL_RTMAXCACHE 426.Pq ip6.rtmaxcache 427Integer: trigger level of cached, unreferenced, protocol-cloned routes 428which initiates dynamic adaptation (default 128). 429.El 430.Ss Interaction between IPv4/v6 sockets 431The behavior of 432.Dv AF_INET6 433TCP/UDP socket is documented in RFC2553. 434Basically, it says as follows: 435.Bl -bullet -compact 436.It 437Specific bind on 438.Dv AF_INET6 439socket 440.Po 441.Xr bind 2 442with address specified 443.Pc 444should accept IPv6 traffic to that address only. 445.It 446If you perform wildcard bind 447on 448.Dv AF_INET6 449socket 450.Po 451.Xr bind 2 452to IPv6 address 453.Li :: 454.Pc , 455and there is no wildcard bind 456.Dv AF_INET 457socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 458should be routed to that 459.Dv AF_INET6 460socket. 461IPv4 traffic should be seen as if it came from IPv6 address like 462.Li ::ffff:10.1.1.1 . 463This is called IPv4 mapped address. 464.It 465If there are both wildcard bind 466.Dv AF_INET 467socket and wildcard bind 468.Dv AF_INET6 469socket on one TCP/UDP port, they should behave separately. 470IPv4 traffic should be routed to 471.Dv AF_INET 472socket and IPv6 should be routed to 473.Dv AF_INET6 474socket. 475.El 476.Pp 477However, RFC2553 does not define the constraint between the order of 478.Xr bind 2 , 479nor how IPv4 TCP/UDP port number and IPv6 TCP/UDP port number 480relate each other 481.Po 482should they be integrated or separated 483.Pc . 484Implemented behavior is very different across kernel to kernel. 485Therefore, it is unwise to rely too much upon the behavior of 486.Dv AF_INET6 487wildcard bind socket. 488It is recommended to listen to two sockets, one for 489.Dv AF_INET 490and another for 491.Dv AF_INET6 , 492when you would like to accept both IPv4 and IPv6 traffic. 493.Pp 494It should also be noted that 495malicious parties can take advantage of the complexity presented above, 496and are able to bypass access control, 497if the target node routes IPv4 traffic to 498.Dv AF_INET6 499socket. 500Users are advised to take caution handling connections 501from IPv4 mapped address to 502.Dv AF_INET6 503sockets. 504.\".Pp 505.\"Because of the above, by default, 506.\"KAME/NetBSD and KAME/OpenBSD 507.\"does not route IPv4 traffic to 508.\".Dv AF_INET6 509.\"socket. 510.\"Listen to two sockets if you want to accept both IPv4 and IPv6 traffic. 511.\"On KAME/NetBSD, IPv4 traffic may be routed with certain 512.\"per-socket/per-node configuration, however, it is not recommended. 513.\"Consult 514.\".Xr ip6 4 515.\"for details. 516.Sh SEE ALSO 517.Xr ioctl 2 , 518.Xr socket 2 , 519.Xr sysctl 3 , 520.Xr icmp6 4 , 521.Xr intro 4 , 522.Xr ip6 4 , 523.Xr tcp 4 , 524.Xr ttcp 4 , 525.Xr udp 4 526.Sh STANDARDS 527.Rs 528.%A Tatsuya Jinmei 529.%A Atsushi Onoe 530.%T "An Extension of Format for IPv6 Scoped Addresses" 531.%R internet draft 532.%D June 2000 533.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 534.%O work in progress material 535.Re 536.Sh HISTORY 537The 538.Nm 539protocol interface are defined in RFC2553 and RFC2292. 540The implementation described herein appeared in WIDE/KAME project. 541.Sh BUGS 542The IPv6 support is subject to change as the Internet protocols develop. 543Users should not depend on details of the current implementation, 544but rather the services exported. 545.Pp 546Users are suggested to implement 547.Dq version independent 548code as much as possible, as you will need to support both 549.Xr inet 4 550and 551.Nm . 552