1 .\" $KAME: ip6.4,v 1.14 2001/02/26 09:31:39 itojun Exp $
3 .\" Copyright (C) 1999 WIDE Project.
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the project nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" Copyright (c) 1983, 1991, 1993
31 .\" The Regents of the University of California. All rights reserved.
33 .\" Redistribution and use in source and binary forms, with or without
34 .\" modification, are permitted provided that the following conditions
36 .\" 1. Redistributions of source code must retain the above copyright
37 .\" notice, this list of conditions and the following disclaimer.
38 .\" 2. Redistributions in binary form must reproduce the above copyright
39 .\" notice, this list of conditions and the following disclaimer in the
40 .\" documentation and/or other materials provided with the distribution.
41 .\" 3. All advertising materials mentioning features or use of this software
42 .\" must display the following acknowledgement:
43 .\" This product includes software developed by the University of
44 .\" California, Berkeley and its contributors.
45 .\" 4. Neither the name of the University nor the names of its contributors
46 .\" may be used to endorse or promote products derived from this software
47 .\" without specific prior written permission.
49 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
50 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
51 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
52 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
53 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
54 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
55 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
56 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
57 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
58 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
69 .Nd Internet Protocol version 6 (IPv6)
76 .Fn socket AF_INET6 SOCK_RAW proto
80 is the network layer protocol used by the Internet protocol version 6 family
82 Options may be set at the
84 level when using higher-level protocols that are based on
90 It may also be accessed through a
92 when developing new protocols, or special-purpose applications.
96 .Xr setsockopt 2 Ns / Ns Xr getsockopt 2
98 They are separated into the basic IPv6 sockets API
101 (defined in RFC2292).
102 The basic API looks very similar to the API presented in
104 Advanced API uses ancillary data and can handle more complex cases.
106 To specify some of socket options, certain privilege
107 (i.e., root privilege) is required.
109 .Ss Basic IPv6 sockets API
110 .Dv IPV6_UNICAST_HOPS
111 may be used to set the hoplimit field in the
114 As symbol name suggests, the option controls hoplimit field on unicast packets.
115 If -1 is specified, the kernel will use a default value.
116 If a value of 0 to 255 is specified, the packet will have the specified
118 Other values are considered invalid, and
122 .Bd -literal -offset indent
123 int hlim = 60; /* max = 255 */
124 setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, &hlim, sizeof(hlim));
128 multicasting is supported only on
134 and only on networks where the interface driver supports multicasting.
137 .Dv IPV6_MULTICAST_HOPS
138 option changes the hoplimit for outgoing multicast datagrams
139 in order to control the scope of the multicasts:
140 .Bd -literal -offset indent
141 unsigned int hlim; /* range: 0 to 255, default = 1 */
142 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_HOPS, &hlim, sizeof(hlim));
145 Datagrams with a hoplimit of 1 are not forwarded beyond the local network.
146 Multicast datagrams with a hoplimit of 0 will not be transmitted on any network,
147 but may be delivered locally if the sending host belongs to the destination
148 group and if multicast loopback has not been disabled on the sending socket
150 Multicast datagrams with hoplimit greater than 1 may be forwarded
151 to other networks if a multicast router is attached to the local network.
153 For hosts with multiple interfaces, each multicast transmission is
154 sent from the primary network interface.
156 .Dv IPV6_MULTICAST_IF
157 option overrides the default for
158 subsequent transmissions from a given socket:
159 .Bd -literal -offset indent
161 outif = if_nametoindex("ne0");
162 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_IF, &outif, sizeof(outif));
165 where "outif" is an interface index of the desired interface,
166 or 0 to specify the default interface.
168 If a multicast datagram is sent to a group to which the sending host itself
169 belongs (on the outgoing interface), a copy of the datagram is, by default,
170 looped back by the IPv6 layer for local delivery.
172 .Dv IPV6_MULTICAST_LOOP
173 option gives the sender explicit control
174 over whether or not subsequent datagrams are looped back:
175 .Bd -literal -offset indent
176 u_char loop; /* 0 = disable, 1 = enable (default) */
177 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_LOOP, &loop, sizeof(loop));
181 improves performance for applications that may have no more than one
182 instance on a single host (such as a router daemon), by eliminating
183 the overhead of receiving their own transmissions.
184 It should generally not be used by applications for which there
185 may be more than one instance on a single host (such as a conferencing
186 program) or for which the sender does not belong to the destination
187 group (such as a time querying program).
189 A multicast datagram sent with an initial hoplimit greater than 1 may be delivered
190 to the sending host on a different interface from that on which it was sent,
191 if the host belongs to the destination group on that other interface.
192 The loopback control option has no effect on such delivery.
194 A host must become a member of a multicast group before it can receive
195 datagrams sent to the group.
196 To join a multicast group, use the
199 .Bd -literal -offset indent
200 struct ipv6_mreq mreq6;
201 setsockopt(s, IPPROTO_IPV6, IPV6_JOIN_GROUP, &mreq6, sizeof(mreq6));
206 is the following structure:
207 .Bd -literal -offset indent
209 struct in6_addr ipv6mr_multiaddr;
210 u_int ipv6mr_interface;
215 should be 0 to choose the default multicast interface, or the
216 interface index of a particular multicast-capable interface if
217 the host is multihomed.
218 Membership is associated with a single interface;
219 programs running on multihomed hosts may need to
220 join the same group on more than one interface.
222 To drop a membership, use:
223 .Bd -literal -offset indent
224 struct ipv6_mreq mreq6;
225 setsockopt(s, IPPROTO_IPV6, IPV6_LEAVE_GROUP, &mreq6, sizeof(mreq6));
230 contains the same values as used to add the membership.
231 Memberships are dropped when the socket is closed or the process exits.
234 controls how ephemeral ports are allocated for
240 .Bd -literal -offset indent
241 int range = IPV6_PORTRANGE_LOW; /* see <netinet/in.h> */
242 setsockopt(s, IPPROTO_IPV6, IPV6_PORTRANGE, &range, sizeof(range));
248 wildcard listening socket.
249 The following example sets the option to 1:
250 .Bd -literal -offset indent
252 setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, &on, sizeof(on));
257 wildcard listening socket will accept IPv6 traffic only.
258 If set to 0, it will accept IPv4 traffic as well,
259 as if it was from IPv4 mapped address like
260 .Li ::ffff:10.1.1.1 .
261 .\" RFC2553 defines the behavior when the variable is set to 0.
262 Note that if you set it this to 0,
263 IPv4 access control gets much more complicated.
264 For example, even if you have no listening
266 listening socket on port
268 you will end up accepting IPv4 traffic by
270 listening socket on the same port.
271 The default value for this flag is copied at socket instantiation time,
273 .Li net.inet6.ip6.v6only
282 .Ss Advanced IPv6 sockets API
283 The advanced IPv6 sockets API lets userland programs specify or obtain
284 details about the IPv6 header and the IPv6 extension headers on packets.
285 The advanced API uses ancillary data for passing data from/to the kernel.
288 .Xr setsockopt 2 Ns / Ns Xr getsockopt 2
289 options to get optional information on incoming packets.
297 .Bd -literal -offset indent
300 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof(on));
301 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on));
302 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS, &on, sizeof(on));
303 setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on));
304 setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on));
307 When any of these options are enabled, the corresponding data is
308 returned as control information by
310 as one or more ancillary data objects.
314 is enabled, the destination IPv6 address and the arriving interface index
315 will be available via
316 .Li struct in6_pktinfo
317 on ancillary data stream.
318 You can pick the structure by checking for an ancillary data item with
329 is enabled, hoplimit value on the packet will be made available to the
331 Ancillary data stream will contain an integer data item with
340 .Xr inet6_option_space 3
341 and friends will help you parse ancillary data items for
346 .Xr inet6_rthdr_space 3
347 and friends will help you parse ancillary data items for
353 may appear multiple times on an ancillary data stream
354 (note that the behavior is slightly different than the specification).
355 Other ancillary data item will appear no more than once.
357 For outgoing direction,
358 you can pass ancillary data items with normal payload data, using
360 Ancillary data items will be parsed by the kernel, and used to construct
361 the IPv6 header and extension headers.
364 values listed above, ancillary data format is the same as inbound case.
365 Additionally, you can specify
370 ancillary data object specifies the next hop for the
371 datagram as a socket address structure.
375 containing this ancillary data, the
383 and the first byte of
385 will be the first byte of the socket address structure.
387 If the socket address structure contains an IPv6 address (e.g., the
388 sin6_family member is
390 then the node identified by that
391 address must be a neighbor of the sending host.
393 equals the destination IPv6 address of the datagram, then this is
394 equivalent to the existing
398 For applications that do not, or unable to use
403 socket option is defined.
404 Setting the socket option specifies any of the optional output fields:
405 .Bd -literal -offset indent
406 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, len);
409 The fourth argument points to a buffer containing one or more
410 ancillary data objects, and the fifth argument is the total length of
412 The application fills in this buffer exactly as
413 if the buffer were being passed to
415 as control information.
417 The options set by calling
422 called "sticky" options because once set they apply to all packets
424 The application can call
427 change all the sticky options, or it can call
430 length of 0 to remove all the sticky options for the socket.
432 The corresponding receive option
433 .Bd -literal -offset indent
434 getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, &len);
437 returns a buffer with one or more ancillary data objects for all the
438 optional receive information that the application has previously
439 specified that it wants to receive.
440 The fourth argument points to
441 the buffer that is filled in by the call.
442 The fifth argument is a
443 pointer to a value-result integer: when the function is called the
444 integer specifies the size of the buffer pointed to by the fourth
445 argument, and on return this integer contains the actual number of
446 bytes that were returned.
447 The application processes this buffer
448 exactly as if the buffer were returned by
450 as control information.
452 .Ss Advanced API and TCP sockets
459 socket, only the options from the most recently received segment are
460 retained and returned to the caller, and only after the socket option
464 .\" need not start saving a copy of the options until the application says
466 The application is not allowed to specify ancillary data in a call to
470 socket, and none of the ancillary data that we
471 described above is ever returned as control information by
477 .Ss Conflict resolution
478 In some cases, there are multiple APIs defined for manipulating
480 A good example is the outgoing interface for multicast datagrams:
481 it can be manipulated by
482 .Dv IPV6_MULTICAST_IF
487 field of the socket address passed to
490 When conflicting options are given to the kernel,
491 the kernel will get the value in the following preference:
492 (1) options specified by using ancillary data,
493 (2) options specified by a sticky option of the advanced API,
494 (3) options specified by using the basic API, and lastly
495 (4) options specified by a socket address.
496 Note that the conflict resolution is undefined in the API specification
497 and implementation dependent.
499 .Ss "Raw IPv6 Sockets"
502 sockets are connectionless, and are normally used with the
508 call may also be used to fix the destination for future
509 packets (in which case the
517 system calls may be used).
521 is 0, the default protocol
523 is used for outgoing packets, and only incoming packets destined
524 for that protocol are received.
527 is non-zero, that protocol number will be used on outgoing packets
528 and to filter incoming packets.
530 Outgoing packets automatically have an
532 header prepended to them (based on the destination address and the
533 protocol number the socket is created with).
534 Incoming packets are received without
536 header nor extension headers.
538 All data sent via raw sockets MUST be in network byte order and all
539 data received via raw sockets will be in network byte order.
540 This differs from the IPv4 raw sockets, which did not specify a byte
541 ordering and typically used the host's byte order.
543 Another difference from IPv4 raw sockets is that complete packets
544 (that is, IPv6 packets with extension headers) cannot be read or
545 written using the IPv6 raw sockets API.
546 Instead, ancillary data
547 objects are used to transfer the extension headers, as described above.
548 Should an application need access to the
549 complete IPv6 packet, some other technique, such as the datalink
554 All fields in the IPv6 header that an application might want to
555 change (i.e., everything other than the version number) can be
556 modified using ancillary data and/or socket options by the
557 application for output.
558 All fields in a received IPv6 header (other
559 than the version number and Next Header fields) and all extension
560 headers are also made available to the application as ancillary data
562 Hence there is no need for a socket option similar to the
567 When writing to a raw socket the kernel will automatically fragment
568 the packet if its size exceeds the path MTU, inserting the required
569 fragmentation headers.
570 On input the kernel reassembles received
571 fragments, so the reader of a raw socket never sees any fragment
574 Most IPv4 implementations give special treatment to a raw socket
575 created with a third argument to
579 whose value is normally 255.
580 We note that this value has no special meaning to
581 an IPv6 raw socket (and the IANA currently reserves the value of 255
582 when used as a next-header field).
583 .\" Note: This feature was added to
584 .\" IPv4 in 1988 by Van Jacobson to support traceroute, allowing a
585 .\" complete IP header to be passed by the application, before the
587 .\" socket option was added.
589 For ICMPv6 raw sockets,
590 the kernel will calculate and insert the ICMPv6 checksum for
591 since this checksum is mandatory.
593 For other raw IPv6 sockets (that is, for raw IPv6 sockets created
594 with a third argument other than IPPROTO_ICMPV6), the application
595 must set the new IPV6_CHECKSUM socket option to have the kernel (1)
596 compute and store a pseudo header checksum for output,
597 and (2) verify the received
598 pseudo header checksum on input,
599 discarding the packet if the checksum is in error.
600 This option prevents applications from having to perform source
601 address selection on the packets they send.
603 incorporate the IPv6 pseudo-header, defined in Section 8.1 of RFC2460.
604 This new socket option also specifies an integer offset into
605 the user data of where the checksum is located.
606 .Bd -literal -offset indent
608 setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset));
611 By default, this socket option is disabled.
612 Setting the offset to -1
613 also disables the option.
614 By disabled we mean (1) the kernel will
615 not calculate and store a checksum for outgoing packets, and (2) the
616 kernel will not verify a checksum for received packets.
618 Note: Since the checksum is always calculated by the kernel for an
619 ICMPv6 socket, applications are not able to generate ICMPv6 packets
620 with incorrect checksums (presumably for testing purposes) using this
624 A socket operation may fail with one of the following errors returned:
627 when trying to establish a connection on a socket which already
628 has one, or when trying to send a datagram with the destination
629 address specified and the socket is already connected;
631 when trying to send a datagram, but no destination address is
632 specified, and the socket hasn't been connected;
634 when the system runs out of memory for an internal data structure;
635 .It Bq Er EADDRNOTAVAIL
636 when an attempt is made to create a socket with a network address
637 for which no network interface exists.
639 when an attempt is made to create a raw IPv6 socket by a non-privileged process.
642 The following errors specific to
645 .Bl -tag -width EADDRNOTAVAILxx
647 An unknown socket option name was given.
649 The ancillary data items were improperly formed, or option name was unknown.
657 .Xr inet6_option_space 3 ,
658 .Xr inet6_rthdr_space 3 ,
668 .%T "Advanced Sockets API for IPv6"
676 .%T "Internet Protocol, Version 6 (IPv6) Specification"
686 .%T "Basic Socket Interface Extensions for IPv6"
690 Most of the socket options are defined in
691 RFC2292 and/or RFC2553.
694 socket option is defined in draft-ietf-ipngwg-rfc2553bis-03.
698 conflict resolution rule
699 are not defined in the RFCs and should be considered implementation dependent.
702 The implementation is based on KAME stack
703 (which is descendant of WIDE hydrangea IPv6 stack kit).
705 Part of the document was shamelessly copied from RFC2553 and RFC2292.
710 object/option is not fully implemented as of writing this.