Debian Codegraph @

upstream/debian-unstable/man8/ip-rule.8

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