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