path: root/usr/src/man/man8/ipaddrsel.8

'\" te
.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright (C) 2017, Sebastian Wiedenroth
.\" 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 IPADDRSEL 8 "March 30, 2022"
.SH NAME
ipaddrsel \- configure IPv6 default address selection
.SH SYNOPSIS
.nf
\fB/usr/sbin/ipaddrsel\fR
.fi

.LP
.nf
\fB/usr/sbin/ipaddrsel\fR \fB-f\fR \fIfile\fR
.fi

.LP
.nf
\fB/usr/sbin/ipaddrsel\fR \fB-d\fR
.fi

.SH DESCRIPTION
Use the \fBipaddrsel\fR utility to configure the IPv6 default address selection
policy table. The policy table is a longest-matching-prefix lookup table that
is used for IPv6 source address selection and for destination address ordering
when resolving names to \fBAF_INET6\fR addresses. For a description of how the
policy table is used for source address selection, see \fBinet6\fR(4P). For a
description of how the policy table is used for destination address ordering,
see \fBgetaddrinfo\fR(3SOCKET).
.sp
.LP
The unmodified policy table is valid for all typical IPv6 deployments. Modify
the table only if a circumstance exists for which the default behavior of the
IPv6 source address selection or destination address ordering mechanism is
unsatisfactory. See the  section for examples of such circumstances. You should
carefully consider your addressing strategy before you change the table from
the provided default.
.sp
.LP
When the \fBipaddrsel\fR command is issued without any arguments, the address
selection policy currently in use is printed. The format of the output is
compatible with the format of the configuration file that the \fB-f\fR option
accepts.
.LP
Note -
.sp
.RS 2
If the \fBusesrc\fR subcommand to \fBifconfig\fR(8) is applied to a particular
physical interface, the selection policy specified by \fBusesrc\fR overrides
the source address selection policies specified by \fBipaddrsel\fR. This is
true for packets that are locally generated and for applications that do not
choose a non-zero source address using \fBbind\fR(3SOCKET).
.RE
.SS "The Configuration File"
The configuration file that the \fB-f\fR option accepts can contain either
comment lines or policy entries. Comment lines have a '\fB#\fR' character as
the first non-blank character. and they are ignored by the \fBipaddrsel\fR
utility. Policy entry lines have the following format:
.sp
.in +2
.nf
\fIprefix\fR/\fIprefix_length\fR \fIprecedence\fR \fIlabel\fR [# \fIcomment\fR]
.fi
.in -2

.sp
.LP
The \fIprefix\fR must be an IPv6 prefix in a format consistent with
\fBinet\fR(3C). The \fIprefix_length\fR is an integer ranging from 0 to
128. The IPv6 source address selection and destination address ordering
algorithms determine the precedence or label of an address by doing a
longest-prefix-match lookup using the prefixes in this table, much like
next-hop determination for a destination is done by doing a
longest-prefix-match lookup using an IP routing table.
.sp
.LP
The precedence is a non-negative integer that represents how the destination
address ordering mechanism will sort addresses returned from name lookups. In
general, addresses with a higher precedence will be in front of addresses with
a lower precedence. Other factors, such as destinations with undesirable source
addresses can, however, override these precedence values.
.sp
.LP
The label is a string of at most fifteen characters, not including the
\fINULL\fR terminator. The label allows particular source address prefixes to
be used with destination prefixes of the same label. Specifically, for a
particular destination address, the IPv6 source address selection algorithm
prefers source addresses whose label is equal that of the destination.
.sp
.LP
The label may be followed by an optional comment.
.sp
.LP
The file must contain a default policy entry, which is an entry with
\fB::0/0\fR as its \fIprefix\fR and \fIprefix_length\fR. This is to ensure that
all possible addresses match a policy.
.SH OPTIONS
The \fBippadrsel\fR utility supports the following options:
.sp
.ne 2
.na
\fB\fB-f\fR \fIfile\fR\fR
.ad
.RS 11n
Replace the address selection policy table with the policy specified in the
\fIfile\fR.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 11n
Revert the kernel's address selection policy table back to the default table.
Invoking \fBipaddrsel\fR in this way only changes the currently running
kernel's policy table, and does not alter the configuration file
\fB/etc/inet/ipaddrsel.conf\fR. To revert the configuration file back to its
default settings, use \fBipaddrsel\fR \fB-d\fR, then dump the contents of the
table to the configuration file by redirecting the output of \fBipaddrsel\fR to
\fB/etc/inet/ipaddrsel.conf\fR.
.sp
.in +2
.nf
example# \fBipaddrsel -d\fR
example# \fBipaddrsel > /etc/inet/ipaddrsel.conf\fR
.fi
.in -2
.sp

.RE

.SH EXAMPLES
\fBExample 1 \fRThe Default Policy in \fB/etc/inet/ipaddrsel.conf\fR
.sp
.LP
The following example is the default policy that is located in
\fB/etc/inet/ipaddrsel.conf\fR:

.sp
.in +2
.nf
# Prefix                            Precedence Label
::1/128                                     50 Loopback
::/0                                        40 Default
::ffff:0.0.0.0/96                           35 IPv4
2002::/16                                   30 6to4
2001::/32                                    5 Teredo
fc00::/7                                     3 ULA
::/96                                        1 IPv4_Compatible
fec0::/10                                    1 Site_Local
3ffe::/16                                    1 6bone
.fi
.in -2
.sp

.LP
\fBExample 2 \fRAssigning a Lower Precedence to Link-local and Site-local
Addresses
.sp
.LP
By default, the destination address ordering rules sort addresses of smaller
scope before those of larger scope. For example, if a name resolves to a global
and a site-local address, the site local address would be ordered before the
global address. An administrator can override this ordering rule by assigning a
lower precedence to addresses of smaller scope, as the following table
demonstrates.

.sp
.in +2
.nf
# Prefix                            Precedence Label
::1/128                                     50 Loopback
::/0                                        40 Default
2002::/16                                   30 6to4
fec0::/10                                   27 Site-Local
fe80::/10                                   23 Link-Local
::/96                                       20 IPv4_Compatible
::ffff:0.0.0.0/96                           10 IPv4
.fi
.in -2
.sp

.LP
\fBExample 3 \fRAssigning Higher Precedence to IPv4 Destinations
.sp
.LP
By default, IPv6 addresses are ordered in front of IPv4 addresses in name
lookups. \fB::ffff:0.0.0.0/96\fR has the precedence of 35 in the default table.
In the following example, IPv4 addresses are assigned higher precedence and are
ordered in front of IPv6 destinations:

.sp
.in +2
.nf
# Prefix                            Precedence Label
::1/128                                     50 Loopback
::/0                                        40 Default
::ffff:0.0.0.0/96                           60 IPv4
2002::/16                                   30 6to4
2001::/32                                    5 Teredo
fc00::/7                                     3 ULA
::/96                                        1 IPv4_Compatible
fec0::/10                                    1 Site_Local
3ffe::/16                                    1 6bone
.fi
.in -2
.sp

.LP
\fBExample 4 \fREnsuring that a Particular Source Address is Used
.sp
.LP
This example ensures that a particular source address is used only when
communicating with destinations in a particular network.

.sp
.LP
The following policy table assigns the label "ClientNet" to a particular source
address on the local system, \fB2001:1111:1111::1\fR. The table assigns the same
label to a network, \fB2001:2222:2222::/48\fR. The result of this policy is that
the \fB2001:1111:1111::1\fR source address will only be used when communicating
with destinations contained in the \fB2001:2222:2222::/48\fR network. For this
example, this network is the \fBClientNet\fR, which could represent a
particular client's network.

.sp
.in +2
.nf
# Prefix                            Precedence Label
::1/128                                     50 Loopback
2001:1111:1111::1/128                       40 ClientNet
2001:2222:2222::/48                         40 ClientNet
::/0                                        40 Default
2002::/16                                   30 6to4
::/96                                       20 IPv4_Compatible
::ffff:0.0.0.0/96                           10 IPv4
.fi
.in -2
.sp

.sp
.LP
This example assumes that the local system has one physical interface, and that
all global prefixes are assigned to that physical interface.

.SH EXIT STATUS
\fBipaddrsel\fR returns the following exit values:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
\fBipaddrsel\fR successfully completed.
.RE

.sp
.ne 2
.na
\fB>\fB0\fR\fR
.ad
.RS 6n
An error occurred. If a failure is encountered, the kernel's current policy
table is unchanged.
.RE

.SH FILES
.ne 2
.na
\fB\fB/etc/inet/ipaddrsel.conf\fR\fR
.ad
.RS 28n
The file that contains the IPv6 default address selection policy to be
installed at boot time. This file is loaded before any Internet services are
started.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.BR inet (3C),
.BR getaddrinfo (3SOCKET),
.BR inet6 (4P),
.BR ipaddrsel.conf (5),
.BR attributes (7),
.BR nscd (8)
.SH NOTES
The ipnodes cache kept by \fBnscd\fR(8) contains addresses that are ordered
using the destination address ordering algorithm, which is one of the reasons
why \fBipaddrsel\fR is called before \fBnscd\fR in the boot sequence. If
\fBipaddrsel\fR is used to change the address selection policy after \fBnscd\fR
has started, you should invalidate the \fBnscd\fR ipnodes cache by invoking the
following command:
.sp
.in +2
.nf
example# \fB/usr/sbin/nscd -i ipnodes\fR
.fi
.in -2
.sp