]>
Commit | Line | Data |
---|---|---|
2a9721f1 SH |
1 | .TH IP\-RULE 8 "20 Dec 2011" "iproute2" "Linux" |
2 | .SH "NAME" | |
aab2702d | 3 | ip-rule \- routing policy database management |
2a9721f1 SH |
4 | .SH "SYNOPSIS" |
5 | .sp | |
6 | .ad l | |
7 | .in +8 | |
8 | .ti -8 | |
9 | .B ip | |
10 | .RI "[ " OPTIONS " ]" | |
11 | .B rule | |
582b0fc6 | 12 | .RI "{ " COMMAND " | " |
2a9721f1 SH |
13 | .BR help " }" |
14 | .sp | |
15 | ||
16 | .ti -8 | |
17 | .B ip rule | |
ca89c521 HL |
18 | .RB "[ " list |
19 | .RI "[ " SELECTOR " ]]" | |
582b0fc6 PS |
20 | |
21 | .ti -8 | |
22 | .B ip rule | |
23 | .RB "{ " add " | " del " }" | |
2a9721f1 SH |
24 | .I SELECTOR ACTION |
25 | ||
2f4e171f | 26 | .ti -8 |
582b0fc6 PS |
27 | .B ip rule |
28 | .RB "{ " flush " | " save " | " restore " }" | |
2f4e171f | 29 | |
2a9721f1 SH |
30 | .ti -8 |
31 | .IR SELECTOR " := [ " | |
582b0fc6 | 32 | .BR not " ] [" |
2a9721f1 SH |
33 | .B from |
34 | .IR PREFIX " ] [ " | |
35 | .B to | |
36 | .IR PREFIX " ] [ " | |
37 | .B tos | |
38 | .IR TOS " ] [ " | |
39 | .B fwmark | |
582b0fc6 | 40 | .IR FWMARK\fR[\fB/\fIMASK "] ] [ " |
2a9721f1 SH |
41 | .B iif |
42 | .IR STRING " ] [ " | |
43 | .B oif | |
44 | .IR STRING " ] [ " | |
45 | .B pref | |
ca89c521 | 46 | .IR NUMBER " ] [ " |
f686f764 RP |
47 | .IR l3mdev " ] [ " |
48 | .B uidrange | |
49 | .IR NUMBER "-" NUMBER " ] [ " | |
50 | .B ipproto | |
51 | .IR PROTOCOL " ] [ " | |
52 | .BR sport " [ " | |
53 | .IR NUMBER " | " | |
54 | .IR NUMBER "-" NUMBER " ] ] [ " | |
55 | .BR dport " [ " | |
56 | .IR NUMBER " | " | |
57 | .IR NUMBER "-" NUMBER " ] ]" | |
58 | .BR | |
59 | ||
2a9721f1 SH |
60 | |
61 | .ti -8 | |
62 | .IR ACTION " := [ " | |
63 | .B table | |
64 | .IR TABLE_ID " ] [ " | |
7c083da7 DS |
65 | .B protocol |
66 | .IR PROTO " ] [ " | |
2a9721f1 SH |
67 | .B nat |
68 | .IR ADDRESS " ] [ " | |
ccaf6eb5 | 69 | .B realms |
582b0fc6 PS |
70 | .RI "[" SRCREALM "\fB/\fR]" DSTREALM " ] [" |
71 | .B goto | |
72 | .IR NUMBER " ] " SUPPRESSOR | |
b1d0525f ST |
73 | |
74 | .ti -8 | |
75 | .IR SUPPRESSOR " := [ " | |
76 | .B suppress_prefixlength | |
77 | .IR NUMBER " ] [ " | |
78 | .B suppress_ifgroup | |
79 | .IR GROUP " ]" | |
2a9721f1 SH |
80 | |
81 | .ti -8 | |
82 | .IR TABLE_ID " := [ " | |
83 | .BR local " | " main " | " default " |" | |
84 | .IR NUMBER " ]" | |
85 | ||
86 | .SH DESCRIPTION | |
87 | .I ip rule | |
5699275b | 88 | manipulates rules |
2a9721f1 SH |
89 | in the routing policy database control the route selection algorithm. |
90 | ||
91 | .P | |
92 | Classic routing algorithms used in the Internet make routing decisions | |
93 | based only on the destination address of packets (and in theory, | |
94 | but not in practice, on the TOS field). | |
95 | ||
96 | .P | |
97 | In some circumstances we want to route packets differently depending not only | |
98 | on destination addresses, but also on other packet fields: source address, | |
99 | IP protocol, transport protocol ports or even packet payload. | |
100 | This task is called 'policy routing'. | |
101 | ||
102 | .P | |
103 | To solve this task, the conventional destination based routing table, ordered | |
104 | according to the longest match rule, is replaced with a 'routing policy | |
105 | database' (or RPDB), which selects routes by executing some set of rules. | |
106 | ||
107 | .P | |
108 | Each policy routing rule consists of a | |
109 | .B selector | |
110 | and an | |
111 | .B action predicate. | |
843fc900 PS |
112 | The RPDB is scanned in order of decreasing priority (note that lower number |
113 | means higher priority, see the description of | |
114 | .I PREFERENCE | |
115 | below). The selector | |
2a9721f1 SH |
116 | of each rule is applied to {source address, destination address, incoming |
117 | interface, tos, fwmark} and, if the selector matches the packet, | |
a89d5329 | 118 | the action is performed. The action predicate may return with success. |
2a9721f1 SH |
119 | In this case, it will either give a route or failure indication |
120 | and the RPDB lookup is terminated. Otherwise, the RPDB program | |
49572501 | 121 | continues with the next rule. |
2a9721f1 SH |
122 | |
123 | .P | |
49572501 | 124 | Semantically, the natural action is to select the nexthop and the output device. |
2a9721f1 SH |
125 | |
126 | .P | |
127 | At startup time the kernel configures the default RPDB consisting of three | |
128 | rules: | |
129 | ||
130 | .TP | |
131 | 1. | |
132 | Priority: 0, Selector: match anything, Action: lookup routing | |
133 | table | |
134 | .B local | |
135 | (ID 255). | |
136 | The | |
137 | .B local | |
138 | table is a special routing table containing | |
139 | high priority control routes for local and broadcast addresses. | |
2a9721f1 SH |
140 | |
141 | .TP | |
142 | 2. | |
143 | Priority: 32766, Selector: match anything, Action: lookup routing | |
144 | table | |
145 | .B main | |
146 | (ID 254). | |
147 | The | |
148 | .B main | |
149 | table is the normal routing table containing all non-policy | |
150 | routes. This rule may be deleted and/or overridden with other | |
151 | ones by the administrator. | |
152 | ||
153 | .TP | |
154 | 3. | |
155 | Priority: 32767, Selector: match anything, Action: lookup routing | |
156 | table | |
157 | .B default | |
158 | (ID 253). | |
159 | The | |
160 | .B default | |
a89d5329 | 161 | table is empty. It is reserved for some post-processing if no previous |
2a9721f1 SH |
162 | default rules selected the packet. |
163 | This rule may also be deleted. | |
164 | ||
165 | .P | |
166 | Each RPDB entry has additional | |
a89d5329 PŠ |
167 | attributes. F.e. each rule has a pointer to some routing |
168 | table. NAT and masquerading rules have an attribute to select new IP | |
169 | address to translate/masquerade. Besides that, rules have some | |
2a9721f1 SH |
170 | optional attributes, which routes have, namely |
171 | .BR "realms" . | |
a89d5329 | 172 | These values do not override those contained in the routing tables. They |
2a9721f1 SH |
173 | are only used if the route did not select any attributes. |
174 | ||
175 | .sp | |
176 | The RPDB may contain rules of the following types: | |
177 | ||
1284fd3a | 178 | .RS |
2a9721f1 SH |
179 | .B unicast |
180 | - the rule prescribes to return the route found | |
181 | in the routing table referenced by the rule. | |
182 | ||
183 | .B blackhole | |
184 | - the rule prescribes to silently drop the packet. | |
185 | ||
186 | .B unreachable | |
187 | - the rule prescribes to generate a 'Network is unreachable' error. | |
188 | ||
189 | .B prohibit | |
190 | - the rule prescribes to generate 'Communication is administratively | |
191 | prohibited' error. | |
192 | ||
193 | .B nat | |
194 | - the rule prescribes to translate the source address | |
195 | of the IP packet into some other value. | |
1284fd3a | 196 | .RE |
2a9721f1 | 197 | |
1284fd3a | 198 | .TP |
199 | .B ip rule add - insert a new rule | |
200 | .TP | |
201 | .B ip rule delete - delete a rule | |
202 | .RS | |
2a9721f1 SH |
203 | .TP |
204 | .BI type " TYPE " (default) | |
a89d5329 | 205 | the type of this rule. The list of valid types was given in the previous |
2a9721f1 SH |
206 | subsection. |
207 | ||
208 | .TP | |
209 | .BI from " PREFIX" | |
210 | select the source prefix to match. | |
211 | ||
212 | .TP | |
213 | .BI to " PREFIX" | |
214 | select the destination prefix to match. | |
215 | ||
216 | .TP | |
217 | .BI iif " NAME" | |
a89d5329 PŠ |
218 | select the incoming device to match. If the interface is loopback, |
219 | the rule only matches packets originating from this host. This means | |
2a9721f1 SH |
220 | that you may create separate routing tables for forwarded and local |
221 | packets and, hence, completely segregate them. | |
222 | ||
223 | .TP | |
224 | .BI oif " NAME" | |
a89d5329 | 225 | select the outgoing device to match. The outgoing interface is only |
2a9721f1 SH |
226 | available for packets originating from local sockets that are bound to |
227 | a device. | |
228 | ||
229 | .TP | |
230 | .BI tos " TOS" | |
231 | .TP | |
232 | .BI dsfield " TOS" | |
233 | select the TOS value to match. | |
234 | ||
235 | .TP | |
236 | .BI fwmark " MARK" | |
237 | select the | |
238 | .B fwmark | |
239 | value to match. | |
240 | ||
f686f764 RP |
241 | .TP |
242 | .BI uidrange " NUMBER-NUMBER" | |
243 | select the | |
244 | .B uid | |
245 | value to match. | |
246 | ||
247 | .TP | |
248 | .BI ipproto " PROTOCOL" | |
249 | select the ip protocol value to match. | |
250 | ||
251 | .TP | |
252 | .BI sport " NUMBER | NUMBER-NUMBER" | |
253 | select the source port value to match. supports port range. | |
254 | ||
255 | .TP | |
256 | .BI dport " NUMBER | NUMBER-NUMBER" | |
257 | select the destination port value to match. supports port range. | |
258 | ||
2a9721f1 SH |
259 | .TP |
260 | .BI priority " PREFERENCE" | |
31a29009 PS |
261 | the priority of this rule. |
262 | .I PREFERENCE | |
843fc900 PS |
263 | is an unsigned integer value, higher number means lower priority, and rules get |
264 | processed in order of increasing number. Each rule | |
31a29009 | 265 | should have an explicitly set |
2a9721f1 SH |
266 | .I unique |
267 | priority value. | |
268 | The options preference and order are synonyms with priority. | |
269 | ||
270 | .TP | |
271 | .BI table " TABLEID" | |
272 | the routing table identifier to lookup if the rule selector matches. | |
273 | It is also possible to use lookup instead of table. | |
274 | ||
7c083da7 DS |
275 | .TP |
276 | .BI protocol " PROTO" | |
277 | the routing protocol who installed the rule in question. As an example when zebra installs a rule it would get RTPROT_ZEBRA as the installing protocol. | |
278 | ||
b1d0525f ST |
279 | .TP |
280 | .BI suppress_prefixlength " NUMBER" | |
281 | reject routing decisions that have a prefix length of NUMBER or less. | |
282 | ||
283 | .TP | |
284 | .BI suppress_ifgroup " GROUP" | |
285 | reject routing decisions that use a device belonging to the interface | |
286 | group GROUP. | |
287 | ||
2a9721f1 SH |
288 | .TP |
289 | .BI realms " FROM/TO" | |
290 | Realms to select if the rule matched and the routing table lookup | |
a89d5329 | 291 | succeeded. Realm |
2a9721f1 SH |
292 | .I TO |
293 | is only used if the route did not select any realm. | |
294 | ||
295 | .TP | |
296 | .BI nat " ADDRESS" | |
297 | The base of the IP address block to translate (for source addresses). | |
298 | The | |
299 | .I ADDRESS | |
300 | may be either the start of the block of NAT addresses (selected by NAT | |
301 | routes) or a local host address (or even zero). | |
302 | In the last case the router does not translate the packets, but | |
303 | masquerades them to this address. | |
304 | Using map-to instead of nat means the same thing. | |
305 | ||
306 | .B Warning: | |
307 | Changes to the RPDB made with these commands do not become active | |
a89d5329 | 308 | immediately. It is assumed that after a script finishes a batch of |
2a9721f1 SH |
309 | updates, it flushes the routing cache with |
310 | .BR "ip route flush cache" . | |
1284fd3a | 311 | .RE |
312 | .TP | |
313 | .B ip rule flush - also dumps all the deleted rules. | |
7c083da7 DS |
314 | .RS |
315 | .TP | |
316 | .BI protocol " PROTO" | |
317 | Select the originating protocol. | |
318 | .RE | |
1284fd3a | 319 | .TP |
320 | .B ip rule show - list rules | |
2a9721f1 SH |
321 | This command has no arguments. |
322 | The options list or lst are synonyms with show. | |
323 | ||
2f4e171f KT |
324 | .TP |
325 | .B ip rule save | |
7c083da7 DS |
326 | .RS |
327 | .TP | |
328 | .BI protocol " PROTO" | |
329 | Select the originating protocol. | |
330 | .RE | |
331 | .TP | |
2f4e171f KT |
332 | save rules table information to stdout |
333 | .RS | |
334 | This command behaves like | |
335 | .BR "ip rule show" | |
336 | except that the output is raw data suitable for passing to | |
337 | .BR "ip rule restore" . | |
338 | .RE | |
339 | ||
340 | .TP | |
341 | .B ip rule restore | |
342 | restore rules table information from stdin | |
343 | .RS | |
344 | This command expects to read a data stream as returned from | |
345 | .BR "ip rule save" . | |
346 | It will attempt to restore the rules table information exactly as | |
347 | it was at the time of the save. Any rules already in the table are | |
348 | left unchanged, and duplicates are not ignored. | |
349 | .RE | |
350 | ||
2a9721f1 SH |
351 | .SH SEE ALSO |
352 | .br | |
353 | .BR ip (8) | |
354 | ||
355 | .SH AUTHOR | |
356 | Original Manpage by Michail Litvak <mci@owl.openwall.com> |