'\" te .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH IP6 7P "Dec 2, 2008" .SH NAME ip6 \- Internet Protocol Version 6 .SH SYNOPSIS .LP .nf #include #include #include .fi .LP .nf s = socket(AF_INET6, SOCK_RAW, proto); .fi .LP .nf t = t_open ("/dev/rawip6", O_RDWR); .fi .SH DESCRIPTION .sp .LP The \fBIPv6\fR protocol is the next generation of the internetwork datagram delivery protocol of the Internet protocol family. Programs may use \fBIPv6\fR through higher-level protocols such as the Transmission Control Protocol (\fBTCP\fR) or the User Datagram Protocol (\fBUDP\fR), or may interface directly to \fBIPv6\fR. See \fBtcp\fR(7P) and \fBudp\fR(7P). Direct access may be by means of the socket interface, using a "raw socket," or by means of the Transport Level Interface (\fBTLI\fR). The protocol options and \fBIPv6\fR extension headers defined in the \fBIPv6\fR specification may be set in outgoing datagrams. .SH APPLICATION PROGRAMMING INTERFACE .sp .LP The \fBSTREAMS\fR driver \fB/dev/rawip6\fR is the \fBTLI\fR transport provider that provides raw access to \fBIPv6\fR. .sp .LP Raw \fBIPv6\fR sockets are connectionless and are normally used with the \fBsendto()\fR and \fBrecvfrom()\fR calls (see \fBsend\fR(3SOCKET) and \fBrecv\fR(3SOCKET)), although the \fBconnect\fR(3SOCKET) call may also be used to fix the destination for future datagrams. In this case, the \fBread\fR(2) or \fBrecv\fR(3SOCKET) and \fBwrite\fR(2) or \fBsend\fR(3SOCKET) calls may be used. Ancillary data may also be sent or received over raw \fBIPv6\fR sockets using the \fBsendmsg\fR(3SOCKET) and \fBrecvmsg\fR(3SOCKET) system calls. .sp .LP Unlike raw \fBIP\fR, \fBIPv6\fR applications do not include a complete \fBIPv6\fR header when sending; there is no \fBIPv6\fR analog to the \fBIP\fR \fBIP_HDRINCL\fR socket option. \fBIPv6\fR header values may be specified or received as ancillary data to a \fBsendmsg\fR(3SOCKET) or \fBrecvmsg\fR(3SOCKET) system call, or may be specified as "sticky" options on a per-socket basis by using the \fBsetsockopt\fR(3SOCKET) system call. Such sticky options are applied to all outbound packets unless overridden by ancillary data. If any ancillary data is specified in a \fBsendmsg\fR(3SOCKET) call, all sticky options not explicitly overridden revert to default values for that datagram only; the sticky options persist as set for subsequent datagrams. .sp .LP Since \fBsendmsg\fR(3SOCKET) is not supported for \fBSOCK_STREAM\fR upper level protocols such as \fBTCP\fR, ancillary data is unsupported for \fBTCP\fR. Sticky options, however, are supported. .sp .LP Since \fBsendmsg\fR(3SOCKET) is supported for \fBSOCK_DGRAM\fR upper level protocols, both ancillary data and sticky options are supported for \fBUDP\fR, \fBICMP6\fR, and raw \fBIPv6\fR sockets. .sp .LP The socket options supported at the \fBIPv6\fR level are: .sp .ne 2 .na \fB\fBIPV6_BOUND_IF\fR\fR .ad .RS 24n Limit reception and transmission of packets to this interface. Takes an integer as an argument; the integer is the selected interace index. .RE .sp .ne 2 .na \fB\fBIPV6_UNSPEC_SRC\fR\fR .ad .RS 24n Boolean. Allow/disallow sending with a zero source address. .RE .sp .ne 2 .na \fB\fBIPV6_UNICAST_HOPS\fR\fR .ad .RS 24n Default hop limit for unicast datagrams. This option takes an integer as an argument. Its value becomes the new default value for \fBip6_hops\fR that \fBIPv6\fR will use on outgoing unicast datagrams sent from that socket. The initial default is \fB60\fR. .RE .sp .ne 2 .na \fB\fBIPV6_CHECKSUM\fR\fR .ad .RS 24n Specify the integer offset in bytes into the user data of the checksum location. Does not apply to the \fBICMP6\fR protocol. Note: checksums are required for all \fBIPv6\fR datagrams; this is different from \fBIP\fR, in which datagram checksums were optional. \fBIPv6\fR will compute the \fBULP\fR checksum if the value in the checksum field is zero. .RE .sp .ne 2 .na \fB\fBIPV6_SEC_OPT\fR\fR .ad .RS 24n Enable or obtain IPsec security settings for this socket. For more details on the protection services of IPsec, see \fBipsec\fR(7P). .RE .sp .ne 2 .na \fB\fBIPV6_DONTFRAG\fR\fR .ad .RS 24n Boolean. Control fragmentation. .RE .sp .ne 2 .na \fB\fBIPV6_USE_MIN_MTU\fR\fR .ad .RS 24n Controls whether path MTU discovery is used. If set to 1, path MTU discovery is never used and IPv6 packets are sent with the IPv6 minimum MTU. If set to -1, path MTU discovery is not used for multicast and multicast packets are sent with the IPv6 minimum MTU. If set to 0, path MTU is always performed. .RE .sp .ne 2 .na \fB\fBIPV6_V6ONLY\fR\fR .ad .RS 24n Boolean. If set, only V6 packets can be sent or received .RE .sp .ne 2 .na \fB\fBIPV6_SRC_PREFERENCES\fR\fR .ad .RS 24n Enable or obtain Source Address Selection rule settings for this socket. For more details on the Source Address Selection rules, see \fBinet6\fR(7P). .RE .sp .LP The following options are boolean switches controlling the reception of ancillary data: .sp .ne 2 .na \fB\fBIPV6_RECVPKTINFO\fR\fR .ad .RS 25n Enable/disable receipt of the index of the interface the packet arrived on, and of the inbound packet's destination address. .RE .sp .ne 2 .na \fB\fBIPV6_RECVHOPLIMIT\fR\fR .ad .RS 25n Enable/disable receipt of the inbound packet's current hoplimit. .RE .sp .ne 2 .na \fB\fBIPV6_RECVHOPOPTS\fR\fR .ad .RS 25n Enable/disable receipt of the inbound packet's \fBIPv6\fR hop-by-hop extension header. .RE .sp .ne 2 .na \fB\fBIPV6_RECVDSTOPTS\fR\fR .ad .RS 25n Enable/disable receipt of the inbound packet's \fBIPv6\fR destination options extension header. .RE .sp .ne 2 .na \fB\fBIPV6_RECVRTHDR\fR\fR .ad .RS 25n Enable/disable receipt of the inbound packet's \fBIPv6\fR routing header. .RE .sp .ne 2 .na \fB\fBIPV6_RECVRTHDRDSTOPTS\fR\fR .ad .RS 25n Enable/disable receipt of the inbound packet's intermediate-hops options extension header. This option is obsolete. IPV6_RECVDSTOPTS turns on receipt of both destination option headers. .RE .sp .ne 2 .na \fB\fBIPV6_RECVTCLASS\fR\fR .ad .RS 25n Enable/disable receipt of the traffic class of the inbound packet. .RE .sp .ne 2 .na \fB\fBIPV6_RECVPATHMTU\fR\fR .ad .RS 25n Enable/disable receipt of the path mtu of the inbound packet. .RE .sp .LP The following options may be set as sticky options with \fBsetsockopt\fR(3SOCKET) or as ancillary data to a \fBsendmsg\fR(3SOCKET) system call: .sp .ne 2 .na \fB\fBIPV6_PKTINFO\fR\fR .ad .RS 21n Set the source address and/or interface out which the packet(s) will be sent. Takes a \fBstruct\fR \fBin6_pktinfo\fR as the parameter. .RE .sp .ne 2 .na \fB\fBIPV6_HOPLIMIT\fR\fR .ad .RS 21n Set the initial hoplimit for outbound datagrams. Takes an integer as the parameter. Note: This option sets the hoplimit only for ancillary data or sticky options and does not change the default hoplimit for the socket; see \fBIPV6_UNICAST_HOPS\fR and \fBIPV6_MULTICAST_HOPS\fR to change the socket's default hoplimit. .RE .sp .ne 2 .na \fB\fBIPV6_NEXTHOP\fR\fR .ad .RS 21n Specify the \fBIPv6\fR address of the first hop, which must be a neighbor of the sending host. Takes a \fBstruct\fR \fBsockaddr_in6\fR as the parameter. When this option specifies the same address as the destination \fBIPv6\fR address of the datagram, this is equivalent to the existing \fBSO_DONTROUTE\fR option. .RE .sp .ne 2 .na \fB\fBIPV6_HOPOPTS\fR\fR .ad .RS 21n Specify one or more hop-by-hop options. Variable length. Takes a complete \fBIPv6\fR hop-by-hop options extension header as the parameter. .RE .sp .ne 2 .na \fB\fBIPV6_DSTOPTS\fR\fR .ad .RS 21n Specify one or more destination options. Variable length. Takes a complete \fBIPv6\fR destination options extension header as the parameter. .RE .sp .ne 2 .na \fB\fBIPV6_RTHDR\fR\fR .ad .RS 21n Specify the \fBIPv6\fR routing header. Variable length. Takes a complete \fBIPv6\fR routing header as the parameter. Currently, only type 0 routing headers are supported. .RE .sp .ne 2 .na \fB\fBIPV6_RTHDRDSTOPTS\fR\fR .ad .RS 21n Specify one or more destination options for all intermediate hops. May be configured, but will not be applied unless an \fBIPv6\fR routing header is also configured. Variable length. Takes a complete \fBIPv6\fR destination options extension header as the parameter. .RE .sp .ne 2 .na \fB\fBIPV6_PATHMTU\fR\fR .ad .RS 21n Get the path MTU associated with a connected socket. Takes a ip6_mtuinfo as the parameter. .RE .sp .ne 2 .na \fB\fBIPV6_TCLASS\fR\fR .ad .RS 21n Set the traffic class associated with outgoing packets. The parameter is an integer. If the parameter is less then -1 or greater then 256, EINVAL is returned. If the parameter is equal to -1, use the default. If the parameter is between 0 and 255 inclusive, use that value. .RE .sp .LP The following options affect the socket's multicast behavior: .sp .ne 2 .na \fB\fBIPV6_JOIN_GROUP\fR\fR .ad .RS 28n Join a multicast group. Takes a \fBstruct\fR \fBipv6_mreq\fR as the parameter; the structure contains a multicast address and an interface index. .RE .sp .ne 2 .na \fB\fBIPV6_LEAVE_GROUP\fR\fR .ad .RS 28n Leave a multicast group. Takes a \fBstruct\fR \fBipv6_mreq\fR as the parameter; the structure contains a multicast address and an interface index. .RE .sp .ne 2 .na \fB\fBMCAST_JOIN_GROUP\fR\fR .ad .RS 28n Functionally equivalent to IPV6_JOIN_GROUP. Takes a \fBstruct\fR \fBgroup_req\fR as the parameter. The structure contains a multicast address and an interface index. .RE .sp .ne 2 .na \fB\fBMCAST_BLOCK_SOURCE\fR\fR .ad .RS 28n Block multicast packets on a particular multicast group whose source address matches the given source address. The specified group must be joined previously using IPV6_JOIN_GROUP or MCAST_JOIN_GROUP. Takes a \fBstruct\fR \fBgroup_source_req\fR as the parameter. The structure contains an interface index, a multicast address, and a source address. .RE .sp .ne 2 .na \fB\fBMCAST_UNBLOCK_SOURCE\fR\fR .ad .RS 28n Unblock multicast packets which were previously blocked using MCAST_BLOCK_SOURCE. Takes a \fBstruct\fR \fBgroup_source_req\fR as the parameter. The structure contains an interface index, a multicast address, and a source address. .RE .sp .ne 2 .na \fB\fBMCAST_LEAVE_GROUP\fR\fR .ad .RS 28n Functionally equivalent to IPV6_LEAVE_GROUP. Takes a \fBstruct\fR \fBgroup_req\fR as the parameter. The structure contains a multicast address and an interface index. .RE .sp .ne 2 .na \fB\fBMCAST_JOIN_SOURCE_GROUP\fR\fR .ad .RS 28n Begin receiving packets for the given multicast group whose source address matches the specified address. Takes a \fBstruct\fR \fBgroup_source_req\fR as the parameter. The structure contains an interface index, a multicast address, and a source address. .RE .sp .ne 2 .na \fB\fBMCAST_LEAVE_SOURCE_GROUP\fR\fR .ad .RS 28n Stop receiving packets for the given multicast group whose source address matches the specified address. Takes a \fBstruct\fR \fBgroup_source_req\fR as the parameter. The structure contains an interface index, a multicast address, and a source address. .RE .sp .ne 2 .na \fB\fBIPV6_MULTICAST_IF\fR\fR .ad .RS 28n The outgoing interface for multicast packets. This option takes an integer as an argument; the integer is the interface index of the selected interface. .RE .sp .ne 2 .na \fB\fBIPV6_MULTICAST_HOPS\fR\fR .ad .RS 28n Default hop limit for multicast datagrams. This option takes an integer as an argument. Its value becomes the new default value for \fBip6_hops\fR that \fBIPv6\fR will use on outgoing multicast datagrams sent from that socket. The initial default is \fB1\fR. .RE .sp .ne 2 .na \fB\fBIPV6_MULTICAST_LOOP\fR\fR .ad .RS 28n Loopback for multicast datagrams. Normally multicast datagrams are delivered to members on the sending host. Setting the unsigned character argument to 0 will cause the opposite behavior. .RE .sp .LP The multicast socket options can be used with any datagram socket type in the \fBIPv6\fR family. .sp .LP At the socket level, the socket option \fBSO_DONTROUTE\fR may be applied. This option forces datagrams being sent to bypass routing and forwarding by forcing the \fBIPv6\fR hoplimit field to \fB1\fR, meaning that the packet will not be forwarded by routers. .sp .LP Raw \fBIPv6\fR datagrams can also be sent and received using the \fBTLI\fR connectionless primitives. .sp .LP Datagrams flow through the \fBIPv6\fR layer in two directions: from the network \fIup\fR to user processes and from user processes \fIdown\fR to the network. Using this orientation, \fBIPv6\fR is layered \fIabove\fR the network interface drivers and \fIbelow\fR the transport protocols such as \fBUDP\fR and \fBTCP\fR. The Internet Control Message Protocol (\fBICMPv6\fR) for the Internet Protocol Version 6 (\fBIPv6\fR) is logically a part of \fBIPv6\fR. See \fBicmp6\fR(7P). .sp .LP Unlike \fBIP\fR, \fBIPv6\fR provides no checksum of the \fBIPv6\fR header. Also unlike \fBIP\fR, upper level protocol checksums are required. \fBIPv6\fR will compute the \fBULP\fR/data portion checksum if the checksum field contains a zero (see \fBIPV6_CHECKSUM\fR option above). .sp .LP \fBIPv6\fR extension headers in received datagrams are processed in the \fBIPv6\fR layer according to the protocol specification. Currently recognized \fBIPv6\fR extension headers include hop-by-hop options header, destination options header, routing header (currently, only type 0 routing headers are supported), and fragment header. .sp .LP By default, the IPv6 layer will not forward IPv6 packets that are not addressed to it. This behavior can be overridden by using \fBrouteadm\fR(1M) to enable the ipv6-forwarding option. IPv6 forwarding is configured at boot time based on the setting of \fBrouteadm\fR(1M)'s ipv6-forwarding option. .sp .LP For backwards compatibility, IPv6 forwarding can be enabled or disabled using \fBndd\fR(1M)'s ip_forwarding variable. It is set to 1 if IPv6 forwarding is enabled, or 0 if it is disabled. .sp .LP Additionally, finer-grained forwarding can be configured in IPv6. Each interface can be configured to forward IPv6 packets by setting the IFF_ROUTER interface flag. This flag can be set and cleared using \fBifconfig\fR(1M)'s router and -router options. If an interface's IFF_ROUTER flag is set, packets can be forwarded to or from the interface. If it is clear, packets will neither be forwarded from this interface to others, nor forwarded to this interface. Setting the ip6_forwarding variable sets all of the IPv6 interfaces' IFF_ROUTER flags. .sp .LP For backwards compatibility, each interface creates an \fBip6_forwarding /dev/ip6\fR variable that can be modified using \fBndd\fR(1M). An interface's \fB:ip6_forwarding ndd\fR variable is a boolean variable that mirrors the status of its IFF_ROUTER interface flag. It is set to 1 if the flag is set, or 0 if it is clear. This interface specific \fB:ip6_forwarding ndd\fR variable is obsolete and may be removed in a future release of Solaris. The \fBifconfig\fR(1M) router and -router interfaces are preferred. .sp .LP The \fBIPv6\fR layer will send an \fBICMP6\fR message back to the source host in many cases when it receives a datagram that can not be handled. A "\fBtime\fR \fBexceeded\fR" \fBICMP6\fR message will be sent if the \fBip6_hops\fR field in the \fBIPv6\fR header drops to zero in the process of forwarding a datagram. A "\fBdestination\fR \fBunreachable\fR" message will be sent by a router or by the originating host if a datagram can not be sent on because there is no route to the final destination; it will be sent by a router when it encounters a firewall prohibition; it will be sent by a destination node when the transport protocol (that is, \fBTCP\fR) has no listener. A "\fBpacket\fR \fBtoo\fR \fBbig\fR" message will be sent by a router if the packet is larger than the \fBMTU\fR of the outgoing link (this is used for Path \fBMTU\fR Discovery). A "\fBparameter\fR \fBproblem\fR" message will be sent if there is a problem with a field in the \fBIPv6\fR header or any of the \fBIPv6\fR extension headers such that the packet cannot be fully processed. .sp .LP The \fBIPv6\fR layer supports fragmentation and reassembly. Datagrams are fragmented on output if the datagram is larger than the maximum transmission unit (\fBMTU\fR) of the network interface. Fragments of received datagrams are dropped from the reassembly queues if the complete datagram is not reconstructed within a short time period. .sp .LP Errors in sending discovered at the network interface driver layer are passed by IPv6 back up to the user process. .SH SEE ALSO .sp .LP \fBsvcs\fR(1), \fBndd\fR(1M), \fBrouteadm\fR(1M), \fBsvcadm\fR(1M), \fBread\fR(2), \fBwrite\fR(2), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET), \fBgetsockopt\fR(3SOCKET), \fBrecv\fR(3SOCKET), \fBrecvmsg\fR(3SOCKET), \fBsend\fR(3SOCKET), \fBsendmsg\fR(3SOCKET), \fBsetsockopt\fR(3SOCKET), \fBdefaultrouter\fR(4), \fBsmf\fR(5), \fBicmp6\fR(7P), \fBif_tcp\fR(7P), \fBipsec\fR(7P), \fBinet6\fR(7P), \fBrouting\fR(7P), \fBtcp\fR(7P), \fBudp\fR(7P) .sp .LP Deering, S. and Hinden, B. \fI RFC 2460, Internet Protocol, Version 6 (IPv6) Specification\fR. The Internet Society. December, 1998. .sp .LP Stevens, W., and Thomas, M. \fIRFC 2292, Advanced Sockets API for IPv6\fR. Network Working Group. February 1998. .SH DIAGNOSTICS .sp .LP A socket operation may fail with one of the following errors returned: .sp .ne 2 .na \fB\fBEPROTONOSUPPORT\fR\fR .ad .RS 19n Unsupported protocol (for example, IPPROTO_RAW.) .RE .sp .ne 2 .na \fB\fBEACCES\fR\fR .ad .RS 19n A \fBbind()\fR operation was attempted with a "reserved" port number and the effective user ID of the process was not the privileged user. .RE .sp .ne 2 .na \fB\fBEADDRINUSE\fR\fR .ad .RS 19n A \fBbind()\fR operation was attempted on a socket with a network address/port pair that has already been bound to another socket. .RE .sp .ne 2 .na \fB\fBEADDRNOTAVAIL\fR\fR .ad .RS 19n A \fBbind()\fR operation was attempted for an address that is not configured on this machine. .RE .sp .ne 2 .na \fB\fBEINVAL\fR\fR .ad .RS 19n A \fBsendmsg()\fR operation with a non-NULL \fBmsg_accrights\fR was attempted. .RE .sp .ne 2 .na \fB\fBEINVAL\fR\fR .ad .RS 19n A \fBgetsockopt()\fR or \fBsetsockopt()\fR operation with an unknown socket option name was given. .RE .sp .ne 2 .na \fB\fBEINVAL\fR\fR .ad .RS 19n A \fBgetsockopt()\fR or \fBsetsockopt()\fR operation was attempted with the \fBIPv6\fR option field improperly formed; an option field was shorter than the minimum value or longer than the option buffer provided; the value in the option field was invalid. .RE .sp .ne 2 .na \fB\fBEISCONN\fR\fR .ad .RS 19n A \fBconnect()\fR operation was attempted on a socket on which a \fBconnect()\fR operation had already been performed, and the socket could not be successfully disconnected before making the new connection. .RE .sp .ne 2 .na \fB\fBEISCONN\fR\fR .ad .RS 19n A \fBsendto()\fR or \fBsendmsg()\fR operation specifying an address to which the message should be sent was attempted on a socket on which a \fBconnect()\fR operation had already been performed. .RE .sp .ne 2 .na \fB\fBEMSGSIZE\fR\fR .ad .RS 19n A \fBsend()\fR, \fBsendto()\fR, or \fBsendmsg()\fR operation was attempted to send a datagram that was too large for an interface, but was not allowed to be fragmented (such as broadcasts). .RE .sp .ne 2 .na \fB\fBENETUNREACH\fR\fR .ad .RS 19n An attempt was made to establish a connection via \fBconnect()\fR, or to send a datagram by means of \fBsendto()\fR or \fBsendmsg()\fR, where there was no matching entry in the routing table; or if an \fBICMP\fR "\fBdestination unreachable\fR" message was received. .RE .sp .ne 2 .na \fB\fBENOTCONN\fR\fR .ad .RS 19n A \fBsend()\fR or \fBwrite()\fR operation, or a \fBsendto()\fR or \fBsendmsg()\fR operation not specifying an address to which the message should be sent, was attempted on a socket on which a \fBconnect()\fR operation had not already been performed. .RE .sp .ne 2 .na \fB\fBENOBUFS\fR\fR .ad .RS 19n The system ran out of memory for fragmentation buffers or other internal data structures. .RE .sp .ne 2 .na \fB\fBENOMEM\fR\fR .ad .RS 19n The system was unable to allocate memory for an \fBIPv6\fR socket option or other internal data structures. .RE .sp .ne 2 .na \fB\fBENOPROTOOPT\fR\fR .ad .RS 19n An \fBIP\fR socket option was attempted on an \fBIPv6\fR socket, or an \fBIPv6\fR socket option was attempted on an \fBIP\fR socket. .RE .sp .ne 2 .na \fB\fBENOPROTOOPT\fR\fR .ad .RS 19n Invalid socket type for the option. .RE .SH NOTES .sp .LP Applications using the sockets \fBAPI\fR must use the Advanced Sockets \fBAPI\fR for \fBIPv6\fR (\fIRFC 2292\fR) to see elements of the inbound packet's \fBIPv6\fR header or extension headers. .sp .LP The \fBip6\fR service is managed by the service management facility, \fBsmf\fR(5), under the service identifier: .sp .in +2 .nf svc:/network/initial:default .fi .in -2 .sp .sp .LP Administrative actions on this service, such as enabling, disabling, or requesting restart, can be performed using \fBsvcadm\fR(1M). The service's status can be queried using the \fBsvcs\fR(1) command.