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 " | " add " | " del " | " flush " ]"
  19 .I  SELECTOR ACTION
  20
  21 .ti -8
  22 .IR SELECTOR " := [ "
  23 .B  from
  24 .IR PREFIX " ] [ "
  25 .B  to
  26 .IR PREFIX " ] [ "
  27 .B  tos
  28 .IR TOS " ] [ "
  29 .B  fwmark
  30 .IR FWMARK[/MASK] " ] [ "
  31 .B  iif
  32 .IR STRING " ] [ "
  33 .B  oif
  34 .IR STRING " ] [ "
  35 .B  pref
  36 .IR NUMBER " ]"
  37
  38 .ti -8
  39 .IR ACTION " := [ "
  40 .B  table
  41 .IR TABLE_ID " ] [ "
  42 .B  nat
  43 .IR ADDRESS " ] [ "
  44 .BR prohibit " | " reject " | " unreachable " ] [ " realms
  45 .RI "[" SRCREALM "/]" DSTREALM " ]"
  46
  47 .ti -8
  48 .IR TABLE_ID " := [ "
  49 .BR local " | " main " | " default " |"
  50 .IR NUMBER " ]"
  51
  52 .SH DESCRIPTION
  53 .I ip rule
  54 manipulates rules
  55 in the routing policy database control the route selection algorithm.
  56
  57 .P
  58 Classic routing algorithms used in the Internet make routing decisions
  59 based only on the destination address of packets (and in theory,
  60 but not in practice, on the TOS field).
  61
  62 .P
  63 In some circumstances we want to route packets differently depending not only
  64 on destination addresses, but also on other packet fields: source address,
  65 IP protocol, transport protocol ports or even packet payload.
  66 This task is called 'policy routing'.
  67
  68 .P
  69 To solve this task, the conventional destination based routing table, ordered
  70 according to the longest match rule, is replaced with a 'routing policy
  71 database' (or RPDB), which selects routes by executing some set of rules.
  72
  73 .P
  74 Each policy routing rule consists of a
  75 .B selector
  76 and an
  77 .B action predicate.
  78 The RPDB is scanned in the order of increasing priority. The selector
  79 of each rule is applied to {source address, destination address, incoming
  80 interface, tos, fwmark} and, if the selector matches the packet,
  81 the action is performed.  The action predicate may return with success.
  82 In this case, it will either give a route or failure indication
  83 and the RPDB lookup is terminated. Otherwise, the RPDB program
  84 continues on the next rule.
  85
  86 .P
  87 Semantically, natural action is to select the nexthop and the output device.
  88
  89 .P
  90 At startup time the kernel configures the default RPDB consisting of three
  91 rules:
  92
  93 .TP
  94 1.
  95 Priority: 0, Selector: match anything, Action: lookup routing
  96 table
  97 .B local
  98 (ID 255).
  99 The
 100 .B local
 101 table is a special routing table containing
 102 high priority control routes for local and broadcast addresses.
 103 .sp
 104 Rule 0 is special. It cannot be deleted or overridden.
 105
 106 .TP
 107 2.
 108 Priority: 32766, Selector: match anything, Action: lookup routing
 109 table
 110 .B main
 111 (ID 254).
 112 The
 113 .B main
 114 table is the normal routing table containing all non-policy
 115 routes. This rule may be deleted and/or overridden with other
 116 ones by the administrator.
 117
 118 .TP
 119 3.
 120 Priority: 32767, Selector: match anything, Action: lookup routing
 121 table
 122 .B default
 123 (ID 253).
 124 The
 125 .B default
 126 table is empty.  It is reserved for some post-processing if no previous
 127 default rules selected the packet.
 128 This rule may also be deleted.
 129
 130 .P
 131 Each RPDB entry has additional
 132 attributes.  F.e. each rule has a pointer to some routing
 133 table.  NAT and masquerading rules have an attribute to select new IP
 134 address to translate/masquerade.  Besides that, rules have some
 135 optional attributes, which routes have, namely
 136 .BR "realms" .
 137 These values do not override those contained in the routing tables.  They
 138 are only used if the route did not select any attributes.
 139
 140 .sp
 141 The RPDB may contain rules of the following types:
 142
 143 .in +8
 144 .B unicast
 145 - the rule prescribes to return the route found
 146 in the routing table referenced by the rule.
 147
 148 .B blackhole
 149 - the rule prescribes to silently drop the packet.
 150
 151 .B unreachable
 152 - the rule prescribes to generate a 'Network is unreachable' error.
 153
 154 .B prohibit
 155 - the rule prescribes to generate 'Communication is administratively
 156 prohibited' error.
 157
 158 .B nat
 159 - the rule prescribes to translate the source address
 160 of the IP packet into some other value.
 161 .in -8
 162
 163 .SS ip rule add - insert a new rule
 164 .SS ip rule delete - delete a rule
 165
 166 .TP
 167 .BI type " TYPE " (default)
 168 the type of this rule.  The list of valid types was given in the previous
 169 subsection.
 170
 171 .TP
 172 .BI from " PREFIX"
 173 select the source prefix to match.
 174
 175 .TP
 176 .BI to " PREFIX"
 177 select the destination prefix to match.
 178
 179 .TP
 180 .BI iif " NAME"
 181 select the incoming device to match.  If the interface is loopback,
 182 the rule only matches packets originating from this host.  This means
 183 that you may create separate routing tables for forwarded and local
 184 packets and, hence, completely segregate them.
 185
 186 .TP
 187 .BI oif " NAME"
 188 select the outgoing device to match.  The outgoing interface is only
 189 available for packets originating from local sockets that are bound to
 190 a device.
 191
 192 .TP
 193 .BI tos " TOS"
 194 .TP
 195 .BI dsfield " TOS"
 196 select the TOS value to match.
 197
 198 .TP
 199 .BI fwmark " MARK"
 200 select the
 201 .B fwmark
 202 value to match.
 203
 204 .TP
 205 .BI priority " PREFERENCE"
 206 the priority of this rule.  Each rule should have an explicitly
 207 set
 208 .I unique
 209 priority value.
 210 The options preference and order are synonyms with priority.
 211
 212 .TP
 213 .BI table " TABLEID"
 214 the routing table identifier to lookup if the rule selector matches.
 215 It is also possible to use lookup instead of table.
 216
 217 .TP
 218 .BI realms " FROM/TO"
 219 Realms to select if the rule matched and the routing table lookup
 220 succeeded.  Realm
 221 .I TO
 222 is only used if the route did not select any realm.
 223
 224 .TP
 225 .BI nat " ADDRESS"
 226 The base of the IP address block to translate (for source addresses).
 227 The
 228 .I ADDRESS
 229 may be either the start of the block of NAT addresses (selected by NAT
 230 routes) or a local host address (or even zero).
 231 In the last case the router does not translate the packets, but
 232 masquerades them to this address.
 233 Using map-to instead of nat means the same thing.
 234
 235 .B Warning:
 236 Changes to the RPDB made with these commands do not become active
 237 immediately.  It is assumed that after a script finishes a batch of
 238 updates, it flushes the routing cache with
 239 .BR "ip route flush cache" .
 240
 241 .SS ip rule flush - also dumps all the deleted rules.
 242 This command has no arguments.
 243
 244 .SS ip rule show - list rules
 245 This command has no arguments.
 246 The options list or lst are synonyms with show.
 247
 248 .SH SEE ALSO
 249 .br
 250 .BR ip (8)
 251
 252 .SH AUTHOR
 253 Original Manpage by Michail Litvak <mci@owl.openwall.com>