man/man8/ip-rule.8

   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 "[ " list
  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  fwmark
  40 .IR FWMARK\fR[\fB/\fIMASK "] ] [ "
  41 .B  iif
  42 .IR STRING " ] [ "
  43 .B  oif
  44 .IR STRING " ] [ "
  45 .B  pref
  46 .IR NUMBER " ] [ "
  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
  60
  61 .ti -8
  62 .IR ACTION " := [ "
  63 .B  table
  64 .IR TABLE_ID " ] [ "
  65 .B  protocol
  66 .IR PROTO " ] [ "
  67 .B  nat
  68 .IR ADDRESS " ] [ "
  69 .B realms
  70 .RI "[" SRCREALM "\fB/\fR]" DSTREALM " ] ["
  71 .B goto
  72 .IR NUMBER " ] " SUPPRESSOR
  73
  74 .ti -8
  75 .IR SUPPRESSOR " := [ "
  76 .B  suppress_prefixlength
  77 .IR NUMBER " ] [ "
  78 .B  suppress_ifgroup
  79 .IR GROUP " ]"
  80
  81 .ti -8
  82 .IR TABLE_ID " := [ "
  83 .BR local " | " main " | " default " |"
  84 .IR NUMBER " ]"
  85
  86 .SH DESCRIPTION
  87 .I ip rule
  88 manipulates rules
  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.
 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
 116 of each rule is applied to {source address, destination address, incoming
 117 interface, tos, fwmark} and, if the selector matches the packet,
 118 the action is performed. The action predicate may return with success.
 119 In this case, it will either give a route or failure indication
 120 and the RPDB lookup is terminated. Otherwise, the RPDB program
 121 continues with the next rule.
 122
 123 .P
 124 Semantically, the natural action is to select the nexthop and the output device.
 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.
 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
 161 table is empty. It is reserved for some post-processing if no previous
 162 default rules selected the packet.
 163 This rule may also be deleted.
 164
 165 .P
 166 Each RPDB entry has additional
 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
 170 optional attributes, which routes have, namely
 171 .BR "realms" .
 172 These values do not override those contained in the routing tables. They
 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
 178 .RS
 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.
 196 .RE
 197
 198 .TP
 199 .B ip rule add - insert a new rule
 200 .TP
 201 .B ip rule delete - delete a rule
 202 .RS
 203 .TP
 204 .BI type " TYPE " (default)
 205 the type of this rule. The list of valid types was given in the previous
 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"
 218 select the incoming device to match. If the interface is loopback,
 219 the rule only matches packets originating from this host. This means
 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"
 225 select the outgoing device to match. The outgoing interface is only
 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
 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
 259 .TP
 260 .BI priority " PREFERENCE"
 261 the priority of this rule.
 262 .I PREFERENCE
 263 is an unsigned integer value, higher number means lower priority, and rules get
 264 processed in order of increasing number. Each rule
 265 should have an explicitly set
 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
 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
 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
 288 .TP
 289 .BI realms " FROM/TO"
 290 Realms to select if the rule matched and the routing table lookup
 291 succeeded. Realm
 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
 308 immediately. It is assumed that after a script finishes a batch of
 309 updates, it flushes the routing cache with
 310 .BR "ip route flush cache" .
 311 .RE
 312 .TP
 313 .B ip rule flush - also dumps all the deleted rules.
 314 .RS
 315 .TP
 316 .BI protocol " PROTO"
 317 Select the originating protocol.
 318 .RE
 319 .TP
 320 .B ip rule show - list rules
 321 This command has no arguments.
 322 The options list or lst are synonyms with show.
 323
 324 .TP
 325 .B ip rule save
 326 .RS
 327 .TP
 328 .BI protocol " PROTO"
 329 Select the originating protocol.
 330 .RE
 331 .TP
 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
 351 .SH SEE ALSO
 352 .br
 353 .BR ip (8)
 354
 355 .SH AUTHOR
 356 Original Manpage by Michail Litvak <mci@owl.openwall.com>