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