5331 want sockaddr(3SOCKET)

[illumos-gate.git] / usr / src / man / man7p / inet6.7p

'\" te
.\" Copyright (C) 2002, 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 INET6 7P "Oct 3, 2002"
.SH NAME
inet6 \- Internet protocol family for Internet Protocol version 6
.SH SYNOPSIS
.LP
.nf
\fB#include <sys/types.h>
#include <netinet/in.h>\fR
.fi

.SH DESCRIPTION
.LP
The \fBinet6\fR protocol family implements a collection of protocols that are
centered around the Internet Protocol version 6 (\fBIPv6\fR) and share a common
address format. The \fBinet6\fR protocol family can be accessed using the
socket interface, where it supports the \fBSOCK_STREAM\fR, \fBSOCK_DGRAM\fR,
and \fBSOCK_RAW\fR socket types, or the Transport Level Interface (\fBTLI\fR),
where it supports  the connectionless (\fBT_CLTS\fR) and connection oriented
(\fBT_COTS_ORD\fR) service types.
.SH PROTOCOLS
.LP
The Internet protocol family for \fBIPv6\fR included the Internet Protocol
Version 6 (\fBIPv6\fR), the Neighbor Discovery Protocol (\fBNDP\fR), the
Internet Control Message Protocol (\fBICMPv6\fR), the Transmission Control
Protocol (\fBTCP\fR), and the User Datagram Protocol (\fBUDP\fR).
.sp
.LP
\fBTCP\fR supports the socket interface's \fBSOCK_STREAM\fR abstraction and
\fBTLI\fR's  \fBT_COTS_ORD\fR service  type. \fBUDP\fR supports the
\fBSOCK_DGRAM\fR socket abstraction and the \fBTLI\fR \fBT_CLTS\fR service
type. See \fBtcp\fR(7P) and \fBudp\fR(7P). A direct interface to \fBIPv6\fR is
available using the socket interface. See \fBip6\fR(7P). \fBICMPv6\fR is used
by the kernel to handle and report errors in protocol processing. It  is also
accessible to user programs. See \fBicmp6\fR(7P). \fBNDP\fR is used to
translate 128-bit \fBIPv6\fR addresses into 48-bit Ethernet addresses.
.sp
.LP
\fBIPv6\fR addresses come in three types: unicast, anycast, and multicast. A
unicast address is an identifier for a single network interface. An anycast
address is an identifier for a set of interfaces; a packet sent to an anycast
address is delivered to the "nearest"  interface identified by that address,
pursuant to the routing protocol's measure of distance. A multicast address is
an identifier for a set of interfaces; a packet sent to a multicast address is
delivered to all  interfaces identified by that address. There are no broadcast
addresses as such in \fBIPv6\fR; their functionality is superseded by multicast
addresses.
.sp
.LP
For \fBIPv6\fR addresses, there are three scopes within which unicast addresses
are guaranteed to be unique. The scope is indicated by the address prefix. The
three varieties are link-local (the address is unique on that physical link),
site-local (the address is unique within that site), and global (the address is
globally unique).
.sp
.LP
The three highest order  bits for global unicast addresses are set to
\fB001\fR. The ten highest order bits for site-local addresses are set to
\fB1111 1110 11\fR. The ten highest order bits for link-local addresses are set
to \fB1111 1110 11\fR. For multicast addresses, the eight highest order bits
are set to \fB1111 1111\fR. Anycast addresses have the same format as unicast
addresses.
.sp
.LP
\fBIPv6\fR addresses do not follow the concept of "address class" seen in
\fBIP\fR.
.sp
.LP
A global unicast address is divided into the following segments:
.RS +4
.TP
.ie t \(bu
.el o
The first three bits are the Format Prefix identifying a unicast address.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The next 13 bits are the Top-Level Aggregation (\fBTLA\fR) identifier. For
example, the identifier could specify the \fBISP\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The next eight bits are reserved for future use.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The next 24 bits are the Next-Level Aggregation (\fBNLA\fR) identifier.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The next 16 bits are the Site-Level Aggregation (\fBSLA\fR) identifier.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The last 64 bits are the interface \fBID\fR. This will most often be the
hardware address of the link in \fBIEEE EUI-64\fR format.
.RE
.sp
.LP
Link-local unicast addresses are divided in this manner:
.RS +4
.TP
.ie t \(bu
.el o
The first ten bits are the Format Prefix identifying a link-local address.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The next 54 bits are zero.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The last 64 bits are the interface \fBID\fR. This will most often be the
hardware address of the link in \fBIEEE EUI-64\fR format.
.RE
.sp
.LP
Site-local unicast addresses are divided in this manner:
.RS +4
.TP
.ie t \(bu
.el o
The first ten bits are the Format Prefix identifying a site-local address.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The next 38 bits are zero.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The next 16 bits are the subnet \fBID\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The last 64 bits are the interface \fBID\fR. This will most often be the
hardware address of the link in \fBIEEE EUI-64\fR format.
.RE
.SH ADDRESSING
.LP
\fBIPv6\fR addresses are sixteen byte quantities, stored in network byte order.
The socket \fBAPI\fR uses the \fBsockaddr_in6\fR structure when passing
\fBIPv6\fR addresses between an application and the kernel. The
\fBsockaddr_in6\fR structure has the following members:
.sp
.in +2
.nf
sa_familty_t     sin6_family;
in_port_t        sin6_port;
uint32_t         sin6_flowinfo;
struct in6_addr  sin6_addr;
uint32_t         sin6_scope_id;
uint32_t         __sin6_src_id;
.fi
.in -2

.sp
.LP
Library routines are provided to  manipulate  structures of this form. See
\fBinet\fR(3SOCKET).
.sp
.LP
The \fBsin6_addr\fR field of the \fBsockaddr_in6\fR structure specifies a local
or remote \fBIPv6\fR address. Each network interface has one or more \fBIPv6\fR
addresses configured, that is, a link-local address, a site-local address, and
one or more global unicast \fBIPv6\fR addresses. The special value of all zeros
may be used on this field to test for "wildcard" matching. Given in a
\fBbind\fR(3SOCKET) call, this value leaves the local \fBIPv6\fR address of the
socket unspecified, so that the socket will receive connections or messages
directed at any of the valid \fBIPv6\fR addresses of the system. This can prove
useful when a process neither knows nor cares what the local \fBIPv6\fR address
is, or when a process wishes to receive requests using all of its network
interfaces.
.sp
.LP
The \fBsockaddr_in6\fR structure given in  the \fBbind()\fR call must specify
an \fIin6_addr\fR value of either all zeros or one of the system's valid
\fBIPv6\fR addresses. Requests to bind any other address will elicit the error
\fBEADDRNOTAVAI\fR. When a \fBconnect\fR(3SOCKET) call is made for a socket
that has a wildcard local address, the system sets the \fBsin6_addr\fR field of
the socket to the \fBIPv6\fR address of the network interface through which the
packets for that connection are routed.
.sp
.LP
The \fBsin6_port\fR field of the \fBsockaddr_in6\fR structure specifies a port
number used by \fBTCP\fR or \fBUDP\fR. The local port address specified in a
\fBbind()\fR call is restricted to be greater than \fBIPPORT_RESERVED\fR
(defined in <\fBnetinet/in.h\fR>) unless the creating process is running as the
super-user,  providing a space of protected port numbers. In addition, the
local port address cannot be in use by any socket of the same address family
and type. Requests to bind sockets to port numbers being used by other sockets
return the error \fBEADDRINUSE\fR. If the local port address is specified as
\fB0\fR, the system picks a unique port address greater than
\fBIPPORT_RESERVED\fR. A unique local port address is also selected when a
socket which is not bound is used in a \fBconnect\fR(3SOCKET) or \fBsendto()\fR
call. See \fBsend\fR(3SOCKET). This allows programs that do not care which
local port number is used to set up \fBTCP\fR connections by simply calling
\fBsocket\fR(3SOCKET) and then \fBconnect\fR(3SOCKET), and then sending
\fBUDP\fR datagrams with a \fBsocket()\fR call followed by a \fBsendto()\fR
call.
.sp
.LP
Although this implementation restricts sockets to unique local port numbers,
\fBTCP\fR allows multiple simultaneous connections involving the same local
port number so long as the remote \fBIPv6\fR addresses or port numbers are
different for each connection. Programs may explicitly override the socket
restriction by setting the \fBSO_REUSEADDR\fR socket option with
\fBsetsockopt()\fR. See \fBgetsockopt\fR(3SOCKET).
.sp
.LP
In addition, the same port may be bound by two separate sockets if one is an
\fBIP\fR socket and the other an \fBIPv6\fR socket.
.sp
.LP
\fBTLI\fR applies somewhat different semantics to the binding of local port
numbers. These semantics apply when Internet family protocols are used using
the \fBTLI\fR.
.SH SOURCE ADDRESS SELECTION
.LP
IPv6 source address selection is done on a per destination basis, and utilizes
a list of rules from which the best source address is selected from candidate
addresses. The candidate set comprises a set of local addresses assigned on the
system which are up and not anycast.  If just one candidate exists in the
candidate set, it is selected.
.sp
.LP
Conceptually, each selection rule prefers one address over another, or
determines their equivalence. If a rule produces a tie, a subsequent rule is
used to break the tie.
.sp
.LP
The sense of some rules may be reversed on a per-socket basis using the
IPV6_SRC_PREFERENCES socket option (see \fBip6\fR(7P)). The flag values for
this option are defined in <\fBnetinet/in.h\fR> and are referenced in the
description of the appropriate rules below.
.sp
.LP
As the selection rules indicate, the candidate addresses are SA and SB and the
destination is D.
.sp
.ne 2
.na
\fBPrefer the same address\fR
.ad
.RS 30n
If SA == D, prefer SA.  If SB == D, prefer SB.
.RE

.sp
.ne 2
.na
\fBPrefer appropriate scope\fR
.ad
.RS 30n
Here, Scope(X) is the scope of X according to the IPv6 Addressing Architecture.
.sp
If Scope(SA) < Scope(SB): If Scope(SA) < Scope(D), then prefer SB and otherwise
prefer SA.
.sp
If Scope(SB) < Scope(SA): If Scope(SB) < Scope(D), then prefer SA and otherwise
prefer SB.
.RE

.sp
.ne 2
.na
\fBAvoid deprecated addresses\fR
.ad
.RS 30n
If one of the addresses is deprecated (IFF_DEPRECATED) and the other is not,
prefer the one that isn't deprecated.
.RE

.sp
.ne 2
.na
\fBPrefer preferred addresses\fR
.ad
.RS 30n
If one of the addresses is preferred (IFF_PREFERRED) and the other is not,
prefer the one that is preferred.
.RE

.sp
.ne 2
.na
\fBPrefer outgoing interface\fR
.ad
.RS 30n
If one of the addresses is assigned to the interface that will be used to send
packets to D and the other is not, then prefer the former.
.RE

.sp
.ne 2
.na
\fBPrefer matching label\fR
.ad
.RS 30n
This rule uses labels which are obtained through the IPv6 default address
selection policy table. See \fBipaddrsel\fR(1M) for a description of the
default contents of the table and how the table is configured.
.sp
If Label(SA) == Label(D) and Label(SB) != Label(D), then prefer SA.
.sp
If Label(SB) == Label(D) and Label(SA) != Label(D), then prefer SB.
.RE

.sp
.ne 2
.na
\fBPrefer public addresses\fR
.ad
.RS 30n
This rule prefers public addresses over temporary addresses, as defined in
\fIRFC 3041\fR. Temporary addresses are disabled by default and may be enabled
by appropriate settings in \fBndpd.conf\fR(4).
.sp
The sense of this rule may be set on a per-socket basis using the
IPV6_SRC_PREFERENCES socket option.  Passing the flag IPV6_PREFER_SRC_TMP or
IPV6_PREFER_SRC_PUBLIC will cause temporary or public addresses to be
preferred, respectively, for that particular socket.  See \fBip6\fR(7P) for
more information about IPv6 socket options.
.RE

.sp
.ne 2
.na
\fBUse longest matching prefix.\fR
.ad
.sp .6
.RS 4n
This rule prefers the source address that has the longer matching prefix with
the destination. Because this is the last rule and because both source
addresses could have equal matching prefixes, this rule does an \fBxor\fR of
each source address with the destination, then selects the source address with
the smaller \fBxor\fR value in order to break any potential tie.
.sp
If SA ^ D < SB ^ D, then prefer SA.
.sp
If SB ^ D < SA ^ D, then prefer SB.
.RE

.sp
.LP
Applications can override this algorithm by calling  \fBbind\fR(3SOCKET) and
specifying an address.
.SH SEE ALSO
.LP
\fBioctl\fR(2), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET),
\fBgetipnodebyaddr\fR(3SOCKET),
\fBgetipnodebyname\fR(3SOCKET),\fBgetprotobyname\fR(3SOCKET),
\fBgetservbyname\fR(3SOCKET), \fBgetsockopt\fR(3SOCKET), \fBinet\fR(3SOCKET),
\fBsend\fR(3SOCKET), \fBsockaddr\fR(3SOCKET),
\fBicmp6\fR(7P), \fBip6\fR(7P), \fBtcp\fR(7P), \fBudp\fR(7P)
.sp
.LP
Conta, A. and Deering, S., \fIInternet Control Message Protocol (ICMPv6) for
the Internet Protocol Version 6 (IPv6) Specification\fR, RFC 1885, December
1995.
.sp
.LP
Deering, S. and Hinden, B., \fIInternet Protocol, Version 6 (IPv6)
Specification\fR, RFC 1883, December 1995.
.sp
.LP
Hinden, B. and Deering, S.,  \fIIP Version 6 Addressing Architecture\fR, RFC
1884, December 1995.
.sp
.LP
Draves, R., \fIRFC 3484, Default Address Selection for IPv6.\fR The Internet
Society.  February 2003.
.sp
.LP
Narten, T., and Draves, R. \fIRFC 3041, Privacy Extensions for Stateless
Address Autoconfiguration in IPv6.\fR The Internet Society.  January 2001.
.SH NOTES
.LP
The \fBIPv6\fR support is subject to change as the Internet protocols develop.
Users should not depend on details of the current implementation, but rather
the services exported.