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