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
61 .\" $FreeBSD: src/share/man/man4/ip6.4,v 1.1.2.8 2001/12/17 11:30:12 ru Exp $
62 .\" $DragonFly: src/share/man/man4/ip6.4,v 1.2 2003/06/17 04:36:59 dillon Exp $
70 .Nd Internet Protocol version 6 (IPv6)
77 .Fn socket AF_INET6 SOCK_RAW proto
81 is the network layer protocol used by the Internet protocol version 6 family
83 Options may be set at the
85 level when using higher-level protocols that are based on
91 It may also be accessed through a
93 when developing new protocols, or special-purpose applications.
97 .Xr setsockopt 2 Ns / Ns Xr getsockopt 2
99 They are separated into the basic IPv6 sockets API
100 (defined in RFC2553),
102 (defined in RFC2292).
103 The basic API looks very similar to the API presented in
105 Advanced API uses ancillary data and can handle more complex cases.
107 To specify some of socket options, certain privilege
108 (i.e. root privilege) is required.
110 .Ss Basic IPv6 sockets API
111 .Dv IPV6_UNICAST_HOPS
112 may be used to set the hoplimit field in the
115 As symbol name suggests, the option controls hoplimit field on unicast packets.
116 If -1 is specified, the kernel will use a default value.
117 If a value of 0 to 255 is specified, the packet will have the specified
119 Other values are considered invalid, and
123 .Bd -literal -offset indent
124 int hlim = 60; /* max = 255 */
125 setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, &hlim, sizeof(hlim));
129 multicasting is supported only on
135 and only on networks where the interface driver supports multicasting.
138 .Dv IPV6_MULTICAST_HOPS
139 option changes the hoplimit for outgoing multicast datagrams
140 in order to control the scope of the multicasts:
141 .Bd -literal -offset indent
142 unsigned int hlim; /* range: 0 to 255, default = 1 */
143 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_HOPS, &hlim, sizeof(hlim));
146 Datagrams with a hoplimit of 1 are not forwarded beyond the local network.
147 Multicast datagrams with a hoplimit of 0 will not be transmitted on any network,
148 but may be delivered locally if the sending host belongs to the destination
149 group and if multicast loopback has not been disabled on the sending socket
151 Multicast datagrams with hoplimit greater than 1 may be forwarded
152 to other networks if a multicast router is attached to the local network.
154 For hosts with multiple interfaces, each multicast transmission is
155 sent from the primary network interface.
157 .Dv IPV6_MULTICAST_IF
158 option overrides the default for
159 subsequent transmissions from a given socket:
160 .Bd -literal -offset indent
162 outif = if_nametoindex("ne0");
163 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_IF, &outif, sizeof(outif));
166 where "outif" is an interface index of the desired interface,
167 or 0 to specify the default interface.
169 If a multicast datagram is sent to a group to which the sending host itself
170 belongs (on the outgoing interface), a copy of the datagram is, by default,
171 looped back by the IPv6 layer for local delivery.
173 .Dv IPV6_MULTICAST_LOOP
174 option gives the sender explicit control
175 over whether or not subsequent datagrams are looped back:
176 .Bd -literal -offset indent
177 u_char loop; /* 0 = disable, 1 = enable (default) */
178 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_LOOP, &loop, sizeof(loop));
182 improves performance for applications that may have no more than one
183 instance on a single host (such as a router daemon), by eliminating
184 the overhead of receiving their own transmissions.
185 It should generally not be used by applications for which there
186 may be more than one instance on a single host (such as a conferencing
187 program) or for which the sender does not belong to the destination
188 group (such as a time querying program).
190 A multicast datagram sent with an initial hoplimit greater than 1 may be delivered
191 to the sending host on a different interface from that on which it was sent,
192 if the host belongs to the destination group on that other interface.
193 The loopback control option has no effect on such delivery.
195 A host must become a member of a multicast group before it can receive
196 datagrams sent to the group.
197 To join a multicast group, use the
200 .Bd -literal -offset indent
201 struct ipv6_mreq mreq6;
202 setsockopt(s, IPPROTO_IPV6, IPV6_JOIN_GROUP, &mreq6, sizeof(mreq6));
207 is the following structure:
208 .Bd -literal -offset indent
210 struct in6_addr ipv6mr_multiaddr;
211 u_int ipv6mr_interface;
216 should be 0 to choose the default multicast interface, or the
217 interface index of a particular multicast-capable interface if
218 the host is multihomed.
219 Membership is associated with a single interface;
220 programs running on multihomed hosts may need to
221 join the same group on more than one interface.
223 To drop a membership, use:
224 .Bd -literal -offset indent
225 struct ipv6_mreq mreq6;
226 setsockopt(s, IPPROTO_IPV6, IPV6_LEAVE_GROUP, &mreq6, sizeof(mreq6));
231 contains the same values as used to add the membership.
232 Memberships are dropped when the socket is closed or the process exits.
235 controls how ephemeral ports are allocated for
241 .Bd -literal -offset indent
242 int range = IPV6_PORTRANGE_LOW; /* see <netinet/in.h> */
243 setsockopt(s, IPPROTO_IPV6, IPV6_PORTRANGE, &range, sizeof(range));
249 wildcard listening socket.
250 The following example sets the option to 1:
251 .Bd -literal -offset indent
253 setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, &on, sizeof(on));
258 wildcard listening socket will accept IPv6 traffic only.
259 If set to 0, it will accept IPv4 traffic as well,
260 as if it was from IPv4 mapped address like
261 .Li ::ffff:10.1.1.1 .
262 .\" RFC2553 defines the behavior when the variable is set to 0.
263 Note that if you set it this to 0,
264 IPv4 access control gets much more complicated.
265 For example, even if you have no listening
267 listening socket on port
269 you will end up accepting IPv4 traffic by
271 listening socket on the same port.
272 The default value for this flag is copied at socket instantiation time,
274 .Li net.inet6.ip6.v6only
283 .Ss Advanced IPv6 sockets API
284 The advanced IPv6 sockets API lets userland programs specify or obtain
285 details about the IPv6 header and the IPv6 extension headers on packets.
286 The advanced API uses ancillary data for passing data from/to the kernel.
289 .Xr setsockopt 2 Ns / Ns Xr getsockopt 2
290 options to get optional information on incoming packets.
298 .Bd -literal -offset indent
301 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof(on));
302 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on));
303 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS, &on, sizeof(on));
304 setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on));
305 setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on));
308 When any of these options are enabled, the corresponding data is
309 returned as control information by
311 as one or more ancillary data objects.
315 is enabled, the destination IPv6 address and the arriving interface index
316 will be available via
317 .Li struct in6_pktinfo
318 on ancillary data stream.
319 You can pick the structure by checking for an ancillary data item with
330 is enabled, hoplimit value on the packet will be made available to the
332 Ancillary data stream will contain an integer data item with
341 .Xr inet6_option_space 3
342 and friends will help you parse ancillary data items for
347 .Xr inet6_rthdr_space 3
348 and friends will help you parse ancillary data items for
354 may appear multiple times on an ancillary data stream
355 (note that the behavior is slightly different than the specification).
356 Other ancillary data item will appear no more than once.
358 For outgoing direction,
359 you can pass ancillary data items with normal payload data, using
361 Ancillary data items will be parsed by the kernel, and used to construct
362 the IPv6 header and extension headers.
365 values listed above, ancillary data format is the same as inbound case.
366 Additionally, you can specify
371 ancillary data object specifies the next hop for the
372 datagram as a socket address structure.
376 containing this ancillary data, the
384 and the first byte of
386 will be the first byte of the socket address structure.
388 If the socket address structure contains an IPv6 address (e.g., the
389 sin6_family member is
391 then the node identified by that
392 address must be a neighbor of the sending host.
394 equals the destination IPv6 address of the datagram, then this is
395 equivalent to the existing
399 For applications that do not, or unable to use
404 socket option is defined.
405 Setting the socket option specifies any of the optional output fields:
406 .Bd -literal -offset indent
407 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, len);
410 The fourth argument points to a buffer containing one or more
411 ancillary data objects, and the fifth argument is the total length of
413 The application fills in this buffer exactly as
414 if the buffer were being passed to
416 as control information.
418 The options set by calling
423 called "sticky" options because once set they apply to all packets
425 The application can call
428 change all the sticky options, or it can call
431 length of 0 to remove all the sticky options for the socket.
433 The corresponding receive option
434 .Bd -literal -offset indent
435 getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, &len);
438 returns a buffer with one or more ancillary data objects for all the
439 optional receive information that the application has previously
440 specified that it wants to receive.
441 The fourth argument points to
442 the buffer that is filled in by the call.
443 The fifth argument is a
444 pointer to a value-result integer: when the function is called the
445 integer specifies the size of the buffer pointed to by the fourth
446 argument, and on return this integer contains the actual number of
447 bytes that were returned.
448 The application processes this buffer
449 exactly as if the buffer were returned by
451 as control information.
453 .Ss Advanced API and TCP sockets
460 socket, only the options from the most recently received segment are
461 retained and returned to the caller, and only after the socket option
465 .\" need not start saving a copy of the options until the application says
467 The application is not allowed to specify ancillary data in a call to
471 socket, and none of the ancillary data that we
472 described above is ever returned as control information by
478 .Ss Conflict resolution
479 In some cases, there are multiple APIs defined for manipulating
481 A good example is the outgoing interface for multicast datagrams:
482 it can be manipulated by
483 .Dv IPV6_MULTICAST_IF
488 field of the socket address passed to
491 When conflicting options are given to the kernel,
492 the kernel will get the value in the following preference:
493 (1) options specified by using ancillary data,
494 (2) options specified by a sticky option of the advanced API,
495 (3) options specified by using the basic API, and lastly
496 (4) options specified by a socket address.
497 Note that the conflict resolution is undefined in the API specifcation
498 and implementation dependent.
500 .Ss "Raw IPv6 Sockets"
503 sockets are connectionless, and are normally used with the
509 call may also be used to fix the destination for future
510 packets (in which case the
518 system calls may be used).
522 is 0, the default protocol
524 is used for outgoing packets, and only incoming packets destined
525 for that protocol are received.
528 is non-zero, that protocol number will be used on outgoing packets
529 and to filter incoming packets.
531 Outgoing packets automatically have an
533 header prepended to them (based on the destination address and the
534 protocol number the socket is created with).
535 Incoming packets are received without
537 header nor extension headers.
539 All data sent via raw sockets MUST be in network byte order and all
540 data received via raw sockets will be in network byte order.
541 This differs from the IPv4 raw sockets, which did not specify a byte
542 ordering and typically used the host's byte order.
544 Another difference from IPv4 raw sockets is that complete packets
545 (that is, IPv6 packets with extension headers) cannot be read or
546 written using the IPv6 raw sockets API.
547 Instead, ancillary data
548 objects are used to transfer the extension headers, as described above.
549 Should an application need access to the
550 complete IPv6 packet, some other technique, such as the datalink
555 All fields in the IPv6 header that an application might want to
556 change (i.e., everything other than the version number) can be
557 modified using ancillary data and/or socket options by the
558 application for output.
559 All fields in a received IPv6 header (other
560 than the version number and Next Header fields) and all extension
561 headers are also made available to the application as ancillary data
563 Hence there is no need for a socket option similar to the
568 When writing to a raw socket the kernel will automatically fragment
569 the packet if its size exceeds the path MTU, inserting the required
570 fragmentation headers. 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 psuedo 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. Setting the offset to -1
612 also disables the option. By disabled we mean (1) the kernel will
613 not calculate and store a checksum for outgoing packets, and (2) the
614 kernel will not verify a checksum for received packets.
616 Note: Since the checksum is always calculated by the kernel for an
617 ICMPv6 socket, applications are not able to generate ICMPv6 packets
618 with incorrect checksums (presumably for testing purposes) using this
622 A socket operation may fail with one of the following errors returned:
625 when trying to establish a connection on a socket which already
626 has one, or when trying to send a datagram with the destination
627 address specified and the socket is already connected;
629 when trying to send a datagram, but no destination address is
630 specified, and the socket hasn't been connected;
632 when the system runs out of memory for an internal data structure;
633 .It Bq Er EADDRNOTAVAIL
634 when an attempt is made to create a socket with a network address
635 for which no network interface exists.
637 when an attempt is made to create a raw IPv6 socket by a non-privileged process.
640 The following errors specific to
643 .Bl -tag -width EADDRNOTAVAILxx
645 An unknown socket option name was given.
647 The ancillary data items were improperly formed, or option name was unknown.
655 .Xr inet6_option_space 3 ,
656 .Xr inet6_rthdr_space 3 ,
666 .%T "Advanced Sockets API for IPv6"
674 .%T "Internet Protocol, Version 6 (IPv6) Specification"
684 .%T "Basic Socket Interface Extensions for IPv6"
688 Most of the socket options are defined in
689 RFC2292 and/or RFC2553.
692 socket option is defined in draft-ietf-ipngwg-rfc2553bis-03.
696 conflict resolution rule
697 are not defined in the RFCs and should be considered implementation dependent.
700 The implementation is based on KAME stack
701 (which is descendant of WIDE hydrangea IPv6 stack kit).
703 Part of the document was shamelessly copied from RFC2553 and RFC2292.
708 object/option is not fully implemented as of writing this.