1.\" $NetBSD: in_getifa.9,v 1.4 2007/03/02 20:31:58 wiz Exp $ 2.\" 3.\" Copyright (c) 2006 David Young. All rights reserved. 4.\" 5.\" This code was written by David Young. 6.\" 7.\" Redistribution and use in source and binary forms, with or 8.\" without modification, are permitted provided that the following 9.\" conditions are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above 13.\" copyright notice, this list of conditions and the following 14.\" disclaimer in the documentation and/or other materials provided 15.\" with the distribution. 16.\" 3. David Young's name may not be used to endorse or promote 17.\" products derived from this software without specific prior 18.\" written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY DAVID YOUNG ``AS IS'' AND ANY 21.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 23.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DAVID 24.\" YOUNG BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 26.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 28.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 31.\" OF SUCH DAMAGE. 32.\" 33.Dd February 22, 2007 34.Os 35.Dt IN_GETIFA 9 36.Sh NAME 37.Nm in_getifa 38.Nd Look up the IPv4 source address best matching an IPv4 destination 39.Sh SYNOPSIS 40.Cd options IPSELSRC 41.In netinet/in_selsrc.h 42.Ft struct ifaddr * 43.Fn in_getifa "struct ifaddr *ifa" "const struct sockaddr *dst0" 44.Sh DESCRIPTION 45.Nm 46enforces the IPv4 source-address selection policy. 47Add the source-address selection policy mechanism to your kernel with 48.Cd options IPSELSRC . 49.Cd options IPSELSRC 50lets the operator set the policy for choosing the source address 51of any socket bound to the 52.Dq wildcard 53address, 54.Dv INADDR_ANY . 55Note that the policy is applied 56.Em after 57the kernel makes its forwarding decision, thereby choosing the 58output interface; 59in other words, this mechanism does not affect whether or not 60.Nx 61is a 62.Dq strong ES . 63.Pp 64An operator affects the source-address selection using 65.Xr sysctl 8 66and 67.Xr ifconfig 8 . 68Operators set policies with 69.Xr sysctl 8 . 70Some policies consider the 71.Dq preference number 72of an address. 73An operator may set preference numbers for each address with 74.Xr ifconfig 8 . 75.Pp 76A source-address policy is a priority-ordered list of source-address 77ranking functions. 78A ranking function maps its arguments, 79.Po 80.Em source address , 81.Em source index , 82.Em source preference , 83.Em destination address 84.Pc , 85to integers. 86The 87.Em source index 88is the position of 89.Em source address 90in the interface address list; the index of the first address is 0. 91The 92.Em source preference 93is the preference number the operator assigned 94to 95.Em source address . 96The 97.Em destination address 98is the socket peer / packet destination. 99.Pp 100Presently, there are four ranking functions to choose from: 101.Bl -tag -width "common-prefix-len" 102.It index 103ranks by 104.Em source index ; 105lower indices are ranked more highly. 106.It preference 107ranks by 108.Em source preference ; 109higher preference numbers are ranked more highly. 110.It common-prefix-len 111ranks each 112.Em source address 113by the length of the longest prefix it has in common with 114.Em destination address ; 115longer common prefixes rank more highly. 116.It same-category 117determines the "categories" of 118.Em source 119and 120.Em destination address . 121A category is one of 122.Em private , 123.Em link-local , 124or 125.Em other . 126If the categories exactly match, same-category assigns a rank of 2. 127Some sources are ranked 1 by category: 128a 129.Em link-local 130source with a 131.Em private 132destination, a 133.Em private 134source with a 135.Em link-local 136destination, and a 137.Em private 138source with an 139.Em other 140destination rank 1. 141All other sources rank 0. 142.Pp 143Categories are defined as follows. 144.Bl -tag -width "link-local" 145.It private 146RFC1918 networks, 192.168/16, 172.16/12, and 10/8 147.It link-local 148169.254/16, 224/24 149.It other 150all other networks---i.e., not private, not link-local 151.El 152.El 153.Pp 154To apply a policy, the kernel applies all ranking functions in the policy 155to every source address, producing a vector of ranks for each source. 156The kernel sorts the sources in descending, lexicographical order by their 157rank-vector, and chooses the highest-ranking (first) source. 158The kernel breaks ties by choosing the source with the least 159.Em source index . 160.Pp 161The operator may set a policy on individual interfaces. 162The operator may also set a global policy that applies to all 163interfaces whose policy he does not set individually. 164.Pp 165Here is the sysctl tree for the policy at system startup: 166.Pp 167.Bd -literal -offset indent 168net.inet.ip.selectsrc.default = index 169net.inet.ip.interfaces.ath0.selectsrc = 170net.inet.ip.interfaces.sip0.selectsrc = 171net.inet.ip.interfaces.sip1.selectsrc = 172net.inet.ip.interfaces.lo0.selectsrc = 173net.inet.ip.interfaces.pflog0.selectsrc = 174.Ed 175.Pp 176The policy on every interface is the 177.Dq empty 178policy, so the default policy applies. 179The default policy, 180.Em index , 181is the 182.Dq historical 183policy in 184.Nx . 185.Pp 186The operator may override the default policy on ath0, 187.Bd -literal -offset indent 188 # sysctl -w net.inet.ip.interfaces.ath0.selectsrc=same-category,common-prefix-len,preference 189.Ed 190.Pp 191yielding this policy: 192.Bd -literal -offset indent 193net.inet.ip.selectsrc.default = index 194net.inet.ip.interfaces.ath0.selectsrc = same-category,common-prefix-len,preference 195.Ed 196.Pp 197The operator may set a new default, 198.Bd -literal -offset indent 199# sysctl -w net.inet.ip.selectsrc.debug=\ 200\*[Gt] same-category,common-prefix-len,preference 201# sysctl -w net.inet.ip.interfaces.ath0.selectsrc= 202.Ed 203.Pp 204yielding this policy: 205.Bd -literal -offset indent 206net.inet.ip.selectsrc.default = same-category,common-prefix-len,preference 207net.inet.ip.interfaces.ath0.selectsrc = 208.Ed 209.Pp 210In a number of applications, the policy above will usually pick 211suitable source addresses if ath0 is configured in this way: 212.Bd -literal -offset indent 213# ifconfig ath0 inet 64.198.255.1/24 214# ifconfig ath0 inet 10.0.0.1/24 215# ifconfig ath0 inet 169.254.1.1/24 216# ifconfig ath0 inet 192.168.49.1/24 preference 5 217# ifconfig ath0 inet 192.168.37.1/24 preference 9 218.Ed 219A sysctl, net.inet.ip.selectsrc.debug, turns on and off debug messages 220concerned with source selection. 221You may set it to 0 (no messages) or 1. 222.Sh SEE ALSO 223.Xr ifconfig 8 , 224.Xr sysctl 8 225.Sh STANDARDS 226The family of IPv6 source-address selection policies defined by 227.Li RFC3484 228resembles the family of IPv4 policies that 229.Nm 230enforces. 231.Sh AUTHORS 232.An David Young Aq dyoung@NetBSD.org 233.Sh BUGS 234With 235.Cd options IPSELSRC , 236a new interface 237.Xr ioctl 2 , 238.Dv SIOCSIFADDRPREF , 239was introduced. 240It ought to be documented in 241.Xr inet 4 . 242Also, 243.Xr options 4 244ought to cross-reference this manual page. 245.Pp 246This work should be used to set IPv6 source-address selection 247policies, especially the family of policies defined by 248.Li RFC3484 . 249