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