NetBSD/share/man/man9/in_getifa.9

.\" $NetBSD: in_getifa.9,v 1.2 2006/11/19 00:26:52 wiz Exp $
.\"
.\" Copyright (c) 2006 David Young.  All rights reserved.
.\"
.\" This code was written by David Young.
.\"
.\" Redistribution and use in source and binary forms, with or
.\" without modification, are permitted provided that the following
.\" conditions are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above
.\"    copyright notice, this list of conditions and the following
.\"    disclaimer in the documentation and/or other materials provided
.\"    with the distribution.
.\" 3. David Young's name may not be used to endorse or promote
.\"    products derived from this software without specific prior
.\"    written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY DAVID YOUNG ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
.\" PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL DAVID
.\" YOUNG BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
.\" OF SUCH DAMAGE.
.\"
.Dd October 15, 2006
.Os
.Dt IN_GETIFA 9
.Sh NAME
.Nm in_getifa
.Nd Look up the IPv4 source address best matching an IPv4 destination
.Sh SYNOPSIS
.Cd options IPSELSRC
.In netinet/in_selsrc.h
.Ft struct ifaddr *
.Fn in_getifa "struct ifaddr *ifa" "const struct sockaddr *dst0"
.Sh DESCRIPTION
.Nm
enforces the IPv4 source-address selection policy.
Add the source-address selection policy mechanism to your kernel with
.Cd options IPSELSRC .
.Cd options IPSELSRC
lets the operator set the policy for choosing the source address
of any socket bound to the
.Dq wildcard
address,
.Dv INADDR_ANY .
Note that the policy is applied
.Em after
the kernel makes its forwarding decision, thereby choosing the
output interface;
in other words, this mechanism does not affect whether or not
.Nx
is a
.Dq strong ES .
.Pp
An operator affects the source-address selection using
.Xr sysctl 8
and
.Xr ifconfig 8 .
Operators set policies with
.Xr sysctl 8 .
Some policies consider the
.Dq preference number
of an address.
An operator may set preference numbers for each address with
.Xr ifconfig 8 .
.Pp
A source-address policy is a priority-ordered list of source-address
ranking functions.
A ranking function maps its arguments,
.Po
.Em source address ,
.Em source index ,
.Em source preference ,
.Em destination address
.Pc ,
to integers.
The
.Em source index
is the position of
.Em source address
in the interface address list; the index of the first address is 0.
The
.Em source preference
is the preference number the operator assigned
to
.Em source address .
The
.Em destination address
is the socket peer / packet destination.
.Pp
Presently, there are four ranking functions to choose from:
.Bl -tag -width "common-prefix-len"
.It index
ranks by
.Em source index ;
lower indices are ranked more highly.
.It preference
ranks by
.Em source preference ;
lower preference numbers are ranked more highly.
.It common-prefix-len
ranks each
.Em source address
by the length of the longest prefix it has in common with
.Em destination address ;
longer common prefixes rank more highly.
.It same-category
determines the "categories" of
.Em source
and
.Em destination address .
A category is one of
.Em private ,
.Em link-local ,
or
.Em other .
If the categories exactly match, same-category assigns a rank of 2.
Some sources are ranked 1 by category:
a
.Em link-local
source with a
.Em private
destination, a
.Em private
source with a
.Em link-local
destination, and a
.Em private
source with an
.Em other
destination rank 1.
All other sources rank 0.
.Pp
Categories are defined as follows.
.Bl -tag -width "link-local"
.It private
RFC1918 networks, 192.168/16, 172.16/12, and 10/8
.It link-local
169.254/16, 224/24
.It other
all other networks---i.e., not private, not link-local
.El
.El
.Pp
To apply a policy, the kernel applies all ranking functions in the policy
to every source address, producing a vector of ranks for each source.
The kernel sorts the sources in descending, lexicographical order by their
rank-vector, and chooses the highest-ranking (first) source.
The kernel breaks ties by choosing the source with the least
.Em source index .
.Pp
The operator may set a policy on individual interfaces.
The operator may also set a global policy that applies to all
interfaces whose policy he does not set individually.
.Pp
Here is the sysctl tree for the policy at system startup:
.Pp
.Bd -literal -offset indent
net.inet.ip.selectsrc.default = index
net.inet.ip.interfaces.ath0.selectsrc =
net.inet.ip.interfaces.sip0.selectsrc =
net.inet.ip.interfaces.sip1.selectsrc =
net.inet.ip.interfaces.lo0.selectsrc =
net.inet.ip.interfaces.pflog0.selectsrc =
.Ed
.Pp
The policy on every interface is the
.Dq empty
policy, so the default policy applies.
The default policy,
.Em index ,
is the
.Dq historical
policy in
.Nx .
.Pp
The operator may override the default policy on ath0,
.Bd -literal -offset indent
	# sysctl -w net.inet.ip.interfaces.ath0.selectsrc=same-category,common-prefix-len,preference
.Ed
.Pp
yielding this policy:
.Bd -literal -offset indent
net.inet.ip.selectsrc.default = index
net.inet.ip.interfaces.ath0.selectsrc = same-category,common-prefix-len,preference
.Ed
.Pp
The operator may set a new default,
.Bd -literal -offset indent
# sysctl -w net.inet.ip.selectsrc.debug=\
\*[Gt] same-category,common-prefix-len,preference
# sysctl -w net.inet.ip.interfaces.ath0.selectsrc=
.Ed
.Pp
yielding this policy:
.Bd -literal -offset indent
net.inet.ip.selectsrc.default = same-category,common-prefix-len,preference
net.inet.ip.interfaces.ath0.selectsrc =
.Ed
.Pp
In a number of applications, the policy above will usually pick
suitable source addresses if ath0 is configured in this way:
.Bd -literal -offset indent
# ifconfig ath0 inet 64.198.255.1/24
# ifconfig ath0 inet 10.0.0.1/24
# ifconfig ath0 inet 169.254.1.1/24
# ifconfig ath0 inet 192.168.49.1/24 preference 5
# ifconfig ath0 inet 192.168.37.1/24 preference 9
.Ed
A sysctl, net.inet.ip.selectsrc.debug, turns on and off debug messages
concerned with source selection.
You may set it to 0 (no messages) or 1.
.Sh SEE ALSO
.Xr ifconfig 8 ,
.Xr sysctl 8
.Sh STANDARDS
The family of IPv6 source-address selection policies defined by
.Li RFC3484
resembles the family of IPv4 policies that
.Nm
enforces.
.Sh AUTHORS
.An David Young Aq dyoung@NetBSD.org
.Sh BUGS
With
.Cd options IPSELSRC ,
a new interface
.Xr ioctl 2 ,
.Dv SIOCSIFADDRPREF ,
was introduced.
It ought to be documented in
.Xr inet 4 .
Also,
.Xr options 4
ought to cross-reference this manual page.
.Pp
This work should be used to set IPv6 source-address selection
policies, especially the family of policies defined by
.Li RFC3484 .