1.\" $OpenBSD: ip6.4,v 1.15 2003/06/06 10:29:41 jmc Exp $ 2.\" $KAME: ip6.4,v 1.12 2000/06/08 21:19:39 itojun Exp $ 3.\" 4.\" Copyright (C) 1999 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.\" Copyright (c) 1983, 1991, 1993 32.\" The Regents of the University of California. All rights reserved. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 3. Neither the name of the University nor the names of its contributors 43.\" may be used to endorse or promote products derived from this software 44.\" without specific prior written permission. 45.\" 46.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 47.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 48.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 49.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 50.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 51.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 52.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 53.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 54.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 55.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 56.\" SUCH DAMAGE. 57.\" 58.Dd December 17, 1999 59.Dt IP6 4 60.Os 61.Sh NAME 62.Nm ip6 63.Nd Internet Protocol version 6 (IPv6) 64.Sh SYNOPSIS 65.Fd #include <sys/socket.h> 66.Fd #include <netinet/in.h> 67.Ft int 68.Fn socket AF_INET6 SOCK_RAW proto 69.Sh DESCRIPTION 70.Tn IPv6 71is the network layer protocol used by the Internet protocol version 6 family 72.Pq Dv AF_INET6 . 73Options may be set at the 74.Tn IPv6 75level when using higher-level protocols that are based on 76.Tn IPv6 77(such as 78.Tn TCP 79and 80.Tn UDP ) . 81It may also be accessed through a 82.Dq raw socket 83when developing new protocols, or special-purpose applications. 84.Pp 85There are several 86.Tn IPv6-level 87.Xr setsockopt 2 / Ns Xr getsockopt 2 88options. 89They are separated into the basic IPv6 sockets API 90.Pq defined in RFC2553 , 91and the advanced API 92.Pq defined in RFC2292 . 93The basic API looks very similar to the API presented in 94.Xr ip 4 . 95Advanced API uses ancillary data and can handle more complex cases. 96.Pp 97To specify some socket options, a certain level of privilege 98(i.e. root privilege) is required. 99.\" 100.Ss Basic IPv6 sockets API 101.Dv IPV6_UNICAST_HOPS 102may be used to set the hoplimit field in the 103.Tn IPv6 104header. 105As the symbol name suggests, the option controls the hoplimit field 106on unicast packets. 107If -1 is specified, the kernel will use a default value. 108If a value of 0 to 255 is specified, the packet will have the specified 109value as hoplimit. 110Other values are considered invalid, and 111.Dv EINVAL 112will be returned. 113For example: 114.Bd -literal -offset indent 115int hlim = 60; /* max = 255 */ 116setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, &hlim, sizeof(hlim)); 117.Ed 118.Pp 119.Tn IPv6 120multicasting is supported only on 121.Dv AF_INET6 122sockets of type 123.Dv SOCK_DGRAM 124and 125.Dv SOCK_RAW , 126and only on networks where the interface driver supports multicasting. 127.Pp 128The 129.Dv IPV6_MULTICAST_HOPS 130option changes the hoplimit for outgoing multicast datagrams 131in order to control the scope of the multicasts: 132.Bd -literal -offset indent 133unsigned int hlim; /* range: 0 to 255, default = 1 */ 134setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_HOPS, &hlim, sizeof(hlim)); 135.Ed 136.Pp 137Datagrams with a hoplimit of 1 are not forwarded beyond the local network. 138Multicast datagrams with a hoplimit of 0 will not be transmitted on any network, 139but may be delivered locally if the sending host belongs to the destination 140group and if multicast loopback has not been disabled on the sending socket 141(see below). 142Multicast datagrams with a hoplimit greater than 1 may be forwarded 143to other networks if a multicast router is attached to the local network. 144.Pp 145For hosts with multiple interfaces, each multicast transmission is 146sent from the primary network interface. 147The 148.Dv IPV6_MULTICAST_IF 149option overrides the default for 150subsequent transmissions from a given socket: 151.Bd -literal -offset indent 152unsigned int outif; 153outif = if_nametoindex("ne0"); 154setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_IF, &outif, sizeof(outif)); 155.Ed 156.Pp 157where "outif" is an interface index of the desired interface, 158or 0 to specify the default interface. 159.Pp 160If a multicast datagram is sent to a group to which the sending host itself 161belongs (on the outgoing interface), a copy of the datagram is, by default, 162looped back by the IPv6 layer for local delivery. 163The 164.Dv IPV6_MULTICAST_LOOP 165option gives the sender explicit control 166over whether or not subsequent datagrams are looped back: 167.Bd -literal -offset indent 168u_char loop; /* 0 = disable, 1 = enable (default) */ 169setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_LOOP, &loop, sizeof(loop)); 170.Ed 171.Pp 172This option 173improves performance for applications that may have no more than one 174instance on a single host (such as a router daemon), by eliminating 175the overhead of receiving their own transmissions. 176It should generally not be used by applications for which there 177may be more than one instance on a single host (such as a conferencing 178program) or for which the sender does not belong to the destination 179group (such as a time querying program). 180.Pp 181A multicast datagram sent with an initial hoplimit greater than 1 may be 182delivered to the sending host on a different interface from that on which 183it was sent, if the host belongs to the destination group on that other 184interface. 185The loopback control option has no effect on such delivery. 186.Pp 187A host must become a member of a multicast group before it can receive 188datagrams sent to the group. 189To join a multicast group, use the 190.Dv IPV6_JOIN_GROUP 191option: 192.Bd -literal -offset indent 193struct ipv6_mreq mreq6; 194setsockopt(s, IPPROTO_IPV6, IPV6_JOIN_GROUP, &mreq6, sizeof(mreq6)); 195.Ed 196.Pp 197where 198.Fa mreq6 199is the following structure: 200.Bd -literal -offset indent 201struct ipv6_mreq { 202 struct in6_addr ipv6mr_multiaddr; 203 unsigned int ipv6mr_interface; 204}; 205.Ed 206.Pp 207.Dv ipv6mr_interface 208should be 0 to choose the default multicast interface, or the 209interface index of a particular multicast-capable interface if 210the host is multihomed. 211Membership is associated with a single interface; 212programs running on multihomed hosts may need to 213join the same group on more than one interface. 214.Pp 215To drop a membership, use: 216.Bd -literal -offset indent 217struct ipv6_mreq mreq6; 218setsockopt(s, IPPROTO_IPV6, IPV6_LEAVE_GROUP, &mreq6, sizeof(mreq6)); 219.Ed 220.Pp 221where 222.Fa mreq6 223contains the same values as used to add the membership. 224Memberships are dropped when the socket is closed or the process exits. 225.Pp 226.Dv IPV6_PORTRANGE 227controls how ephemeral ports are allocated for 228.Dv SOCK_STREAM 229and 230.Dv SOCK_DGRAM 231sockets. 232For example, 233.Bd -literal -offset indent 234int range = IPV6_PORTRANGE_LOW; /* see <netinet/in.h> */ 235setsockopt(s, IPPROTO_IPV6, IPV6_PORTRANGE, &range, sizeof(range)); 236.Ed 237.\" 238.Ss Advanced IPv6 sockets API 239The advanced IPv6 sockets API lets userland programs specify or obtain 240details about the IPv6 header and the IPv6 extension headers on packets. 241The advanced API uses ancillary data for passing data from/to the kernel. 242.Pp 243There are 244.Xr setsockopt 2 / Ns Xr getsockopt 2 245options to get optional information on incoming packets. 246They are 247.Dv IPV6_PKTINFO , 248.Dv IPV6_HOPLIMIT , 249.Dv IPV6_HOPOPTS , 250.Dv IPV6_DSTOPTS , 251and 252.Dv IPV6_RTHDR . 253.Bd -literal -offset indent 254int on = 1; 255 256setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof(on)); 257setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on)); 258setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS, &on, sizeof(on)); 259setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on)); 260setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on)); 261.Ed 262.Pp 263When any of these options are enabled, the corresponding data is 264returned as control information by 265.Xr recvmsg 2 , 266as one or more ancillary data objects. 267.Pp 268If 269.Dv IPV6_PKTINFO 270is enabled, the destination IPv6 address and the arriving interface index 271will be available via 272.Li struct in6_pktinfo 273on ancillary data stream. 274You can pick the structure by checking for an ancillary data item with 275.Li cmsg_level 276equal to 277.Dv IPPROTO_IPV6 , 278and 279.Li cmsg_type 280equal to 281.Dv IPV6_PKTINFO . 282.Pp 283If 284.Dv IPV6_HOPLIMIT 285is enabled, the hoplimit value on the packet will be made available to the 286userland program. 287The ancillary data stream will contain an integer data item with 288.Li cmsg_level 289equal to 290.Dv IPPROTO_IPV6 , 291and 292.Li cmsg_type 293equal to 294.Dv IPV6_HOPLIMIT . 295.Pp 296.Xr inet6_option_space 3 297and friends help parse ancillary data items for 298.Dv IPV6_HOPOPTS 299and 300.Dv IPV6_DSTOPTS . 301Similarly, 302.Xr inet6_rthdr_space 3 303and friends help parse ancillary data items for 304.Dv IPV6_RTHDR . 305.Pp 306.Dv IPV6_HOPOPTS 307and 308.Dv IPV6_DSTOPTS 309may appear multiple times on an ancillary data stream 310(note that the behavior is slightly different than the specification). 311Other ancillary data items can appear no more than once. 312.Pp 313For outgoing direction, 314ancillary data items with normal payload data can be passed using 315.Xr sendmsg 2 . 316Ancillary data items will be parsed by the kernel, and used to construct 317the IPv6 header and extension headers. 318For the 5 319.Li cmsg_level 320values listed above, the ancillary data format is the same as the inbound case. 321Additionally, the 322.Dv IPV6_NEXTHOP 323data object can also be specified. 324The 325.Dv IPV6_NEXTHOP 326ancillary data object specifies the next hop for the 327datagram as a socket address structure. 328In the 329.Li cmsghdr 330structure 331containing this ancillary data, the 332.Li cmsg_level 333member will be 334.Dv IPPROTO_IPV6 , 335the 336.Li cmsg_type 337member will be 338.Dv IPV6_NEXTHOP , 339and the first byte of 340.Li cmsg_data[] 341will be the first byte of the socket address structure. 342.Pp 343If the socket address structure contains an IPv6 address (i.e., the 344sin6_family member is 345.Dv AF_INET6 346), then the node identified by that 347address must be a neighbor of the sending host. 348If that address 349equals the destination IPv6 address of the datagram, then this is 350equivalent to the existing 351.Dv SO_DONTROUTE 352socket option. 353.Pp 354For applications that do not, or are unable to use 355.Xr sendmsg 2 356or 357.Xr recvmsg 2 , 358the 359.Dv IPV6_PKTOPTIONS 360socket option is defined. 361Setting the socket option specifies any of the optional output fields: 362.Bd -literal -offset indent 363setsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, len); 364.Ed 365.Pp 366The fourth argument points to a buffer containing one or more 367ancillary data objects, and the fifth argument is the total length of 368all these objects. 369The application fills in this buffer exactly as 370if the buffer were being passed to 371.Xr sendmsg 2 372as control information. 373.Pp 374The options set by calling 375.Xr setsockopt 2 376for 377.Dv IPV6_PKTOPTIONS 378are 379called "sticky" options because once set they apply to all packets 380sent on that socket. 381The application can call 382.Xr setsockopt 2 383again to 384change all the sticky options, or it can call 385.Xr setsockopt 2 386with a 387length of 0 to remove all the sticky options for the socket. 388.Pp 389The corresponding receive option 390.Bd -literal -offset indent 391getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, &len); 392.Ed 393.Pp 394returns a buffer with one or more ancillary data objects for all the 395optional receive information that the application has previously 396specified that it wants to receive. 397The fourth argument points to 398the buffer that is filled in by the call. 399The fifth argument is a 400pointer to a value-result integer: when the function is called the 401integer specifies the size of the buffer pointed to by the fourth 402argument, and on return this integer contains the actual number of 403bytes that were returned. 404The application processes this buffer 405exactly as if the buffer were returned by 406.Xr recvmsg 2 407as control information. 408.\" 409.Ss Advanced API and TCP sockets 410When using 411.Xr getsockopt 2 412with the 413.Dv IPV6_PKTOPTIONS 414option and a 415.Tn TCP 416socket, only the options from the most recently received segment are 417retained and returned to the caller, and only after the socket option 418has been set. 419.\" That is, 420.\" .Tn TCP 421.\" need not start saving a copy of the options until the application says 422.\" to do so. 423The application is not allowed to specify ancillary data in a call to 424.Xr sendmsg 2 425on a 426.Tn TCP 427socket, and none of the ancillary data that we 428described above is ever returned as control information by 429.Xr recvmsg 2 430on a 431.Tn TCP 432socket. 433.\" 434.Ss Conflict resolution 435In some cases, there are multiple APIs defined for manipulating 436a IPv6 header field. 437A good example is the outgoing interface for multicast datagrams: 438it can be manipulated by 439.Dv IPV6_MULTICAST_IF 440in basic API, 441.Dv IPV6_PKTINFO 442in advanced API, and the 443.Li sin6_scope_id 444field of the socket address passed to 445.Xr sendto 2 . 446.Pp 447When conflicting options are given to the kernel, 448the kernel will get the value in the following order of preference: 449(1) options specified by using ancillary data, 450(2) options specified by a sticky option of the advanced API, 451(3) options specified by using the basic API, and lastly 452(4) options specified by a socket address. 453Note that the conflict resolution is undefined in the API specification 454and implementation dependent. 455.\" 456.Ss "Raw IPv6 Sockets" 457Raw 458.Tn IPv6 459sockets are connectionless, and are normally used with the 460.Xr sendto 2 461and 462.Xr recvfrom 2 463calls, though the 464.Xr connect 2 465call may also be used to fix the destination for future 466packets (in which case the 467.Xr read 2 468or 469.Xr recv 2 470and 471.Xr write 2 472or 473.Xr send 2 474system calls may be used). 475.Pp 476If 477.Fa proto 478is 0, the default protocol 479.Dv IPPROTO_RAW 480is used for outgoing packets, and only incoming packets destined 481for that protocol are received. 482If 483.Fa proto 484is non-zero, that protocol number will be used on outgoing packets 485and to filter incoming packets. 486.Pp 487Outgoing packets automatically have an 488.Tn IPv6 489header prepended to them (based on the destination address and the 490protocol number the socket is created with). 491Incoming packets are received without an 492.Tn IPv6 493header or extension headers. 494.Pp 495All data sent via raw sockets MUST be in network byte order and all 496data received via raw sockets will be in network byte order. 497This differs from the IPv4 raw sockets, which did not specify a byte 498ordering and typically used the host's byte order. 499.Pp 500Another difference from IPv4 raw sockets is that complete packets 501(that is, IPv6 packets with extension headers) cannot be read or 502written using the IPv6 raw sockets API. 503Instead, ancillary data 504objects are used to transfer the extension headers, as described above. 505Should an application need access to the 506complete IPv6 packet, some other technique, such as the datalink 507interfaces, such as 508.Xr bpf 4 , 509must be used. 510.Pp 511All fields in the IPv6 header that an application might want to 512change (i.e., everything other than the version number) can be 513modified using ancillary data and/or socket options by the 514application for output. 515All fields in a received IPv6 header (other 516than the version number and Next Header fields) and all extension 517headers are also made available to the application as ancillary data 518on input. 519Hence there is no need for a socket option similar to the 520IPv4 521.Dv IP_HDRINCL 522socket option. 523.Pp 524When writing to a raw socket the kernel will automatically fragment 525the packet if its size exceeds the path MTU, inserting the required 526fragmentation headers. 527On input the kernel reassembles received fragments, so the reader 528of a raw socket never sees any fragment headers. 529.Pp 530Most IPv4 implementations give special treatment to a raw socket 531created with a third argument to 532.Xr socket 2 533of 534.Dv IPPROTO_RAW , 535whose value is normally 255. 536We note that this value has no special meaning to 537an IPv6 raw socket (and the IANA currently reserves the value of 255 538when used as a next-header field). 539.\" Note: This feature was added to 540.\" IPv4 in 1988 by Van Jacobson to support traceroute, allowing a 541.\" complete IP header to be passed by the application, before the 542.\" .Dv IP_HDRINCL 543.\" socket option was added. 544.Pp 545For ICMPv6 raw sockets, 546the kernel will calculate and insert the ICMPv6 checksum 547since this checksum is mandatory. 548.Pp 549For other raw IPv6 sockets (that is, for raw IPv6 sockets created 550with a third argument other than IPPROTO_ICMPV6), the application 551must set the new IPV6_CHECKSUM socket option to have the kernel (1) 552compute and store a pseudo-header checksum for output, 553and (2) verify the received 554pseudo-header checksum on input, 555discarding the packet if the checksum is in error. 556This option prevents applications from having to perform source 557address selection on the packets they send. 558The checksum will 559incorporate the IPv6 pseudo-header, defined in Section 8.1 of RFC2460. 560This new socket option also specifies an integer offset into 561the user data of where the checksum is located. 562.Bd -literal -offset indent 563int offset = 2; 564setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset)); 565.Ed 566.Pp 567By default, this socket option is disabled. 568Setting the offset to -1 also disables the option. 569By disabled we mean (1) the kernel will 570not calculate and store a checksum for outgoing packets, and (2) the 571kernel will not verify a checksum for received packets. 572.Pp 573Note: Since the checksum is always calculated by the kernel for an 574ICMPv6 socket, applications are not able to generate ICMPv6 packets 575with incorrect checksums (presumably for testing purposes) using this 576API. 577.\" 578.Sh DIAGNOSTICS 579A socket operation may fail with one of the following errors returned: 580.Bl -tag -width [EADDRNOTAVAIL] 581.It Bq Er EISCONN 582when trying to establish a connection on a socket which already 583has one, or when trying to send a datagram with the destination 584address specified and the socket is already connected. 585.It Bq Er ENOTCONN 586when trying to send a datagram, but no destination address is 587specified, and the socket hasn't been connected. 588.It Bq Er ENOBUFS 589when the system runs out of memory for an internal data structure. 590.It Bq Er EADDRNOTAVAIL 591when an attempt is made to create a socket with a network address 592for which no network interface exists. 593.It Bq Er EACCES 594when an attempt is made to create a raw IPv6 socket by a non-privileged process. 595.El 596.Pp 597The following errors specific to 598.Tn IPv6 599may occur: 600.Bl -tag -width EADDRNOTAVAILxx 601.It Bq Er EINVAL 602An unknown socket option name was given. 603.It Bq Er EINVAL 604The ancillary data items were improperly formed, or option name was unknown. 605.El 606.\" 607.Sh SEE ALSO 608.Xr getsockopt 2 , 609.Xr recv 2 , 610.Xr send 2 , 611.Xr setsockopt 2 , 612.Xr inet6_option_space 3 , 613.Xr inet6_rthdr_space 3 , 614.Xr icmp6 4 , 615.Xr inet6 4 616.Rs 617.%A W. Stevens 618.%A M. Thomas 619.%R RFC 620.%N 2292 621.%D February 1998 622.%T "Advanced Sockets API for IPv6" 623.Re 624.Rs 625.%A S. Deering 626.%A R. Hinden 627.%R RFC 628.%N 2460 629.%D December 1998 630.%T "Internet Protocol, Version 6 (IPv6) Specification" 631.Re 632.Rs 633.%A R. Gilligan 634.%A S. Thomson 635.%A J. Bound 636.%A W. Stevens 637.%R RFC 638.%N 2553 639.%D March 1999 640.%T "Basic Socket Interface Extensions for IPv6" 641.Re 642.\" 643.Sh STANDARDS 644Most of the socket options are defined in 645RFC2292 and/or RFC2553. 646.Dv IPV6_PORTRANGE 647and conflict resolution rule 648is not defined in the RFCs and should be considered implementation dependent. 649.\" 650.Sh HISTORY 651The implementation is based on KAME stack 652.Po 653which is a descendant of WIDE hydrangea IPv6 stack kit 654.Pc . 655.Pp 656Part of the document was shamelessly copied from RFC2553 and RFC2292. 657.\" 658.Sh BUGS 659The 660.Dv IPV6_NEXTHOP 661object/option is not fully implemented as of writing this. 662