ip-rule.8 (8329B)
- .TH IP\-RULE 8 "20 Dec 2011" "iproute2" "Linux"
- .SH "NAME"
- ip-rule \- routing policy database management
- .SH "SYNOPSIS"
- .sp
- .ad l
- .in +8
- .ti -8
- .B ip
- .RI "[ " OPTIONS " ]"
- .B rule
- .RI "{ " COMMAND " | "
- .BR help " }"
- .sp
- .ti -8
- .B ip rule
- .RB "[ " show
- .RI "[ " SELECTOR " ]]"
- .ti -8
- .B ip rule
- .RB "{ " add " | " del " }"
- .I SELECTOR ACTION
- .ti -8
- .B ip rule
- .RB "{ " flush " | " save " | " restore " }"
- .ti -8
- .IR SELECTOR " := [ "
- .BR not " ] ["
- .B from
- .IR PREFIX " ] [ "
- .B to
- .IR PREFIX " ] [ "
- .B tos
- .IR TOS " ] [ "
- .B fwmark
- .IR FWMARK\fR[\fB/\fIMASK "] ] [ "
- .B iif
- .IR STRING " ] [ "
- .B oif
- .IR STRING " ] [ "
- .B priority
- .IR PREFERENCE " ] [ "
- .IR l3mdev " ] [ "
- .B uidrange
- .IR NUMBER "-" NUMBER " ] [ "
- .B ipproto
- .IR PROTOCOL " ] [ "
- .BR sport " [ "
- .IR NUMBER " | "
- .IR NUMBER "-" NUMBER " ] ] [ "
- .BR dport " [ "
- .IR NUMBER " | "
- .IR NUMBER "-" NUMBER " ] ] [ "
- .B tun_id
- .IR TUN_ID " ]"
- .BR
- .ti -8
- .IR ACTION " := [ "
- .B table
- .IR TABLE_ID " ] [ "
- .B protocol
- .IR PROTO " ] [ "
- .B nat
- .IR ADDRESS " ] [ "
- .B realms
- .RI "[" SRCREALM "\fB/\fR]" DSTREALM " ] ["
- .B goto
- .IR NUMBER " ] " SUPPRESSOR
- .ti -8
- .IR SUPPRESSOR " := [ "
- .B suppress_prefixlength
- .IR NUMBER " ] [ "
- .B suppress_ifgroup
- .IR GROUP " ]"
- .ti -8
- .IR TABLE_ID " := [ "
- .BR local " | " main " | " default " |"
- .IR NUMBER " ]"
- .SH DESCRIPTION
- .I ip rule
- manipulates rules
- in the routing policy database that controls the route selection algorithm.
- .P
- Classic routing algorithms used in the Internet make routing decisions
- based only on the destination address of packets (and in theory,
- but not in practice, on the TOS field).
- .P
- In some circumstances, we want to route packets differently depending not only
- on destination addresses but also on other packet fields: source address,
- IP protocol, transport protocol ports or even packet payload.
- This task is called 'policy routing'.
- .P
- To solve this task, the conventional destination based routing table, ordered
- according to the longest match rule, is replaced with a 'routing policy
- database' (or RPDB), which selects routes by executing some set of rules.
- .P
- Each policy routing rule consists of a
- .B selector
- and an
- .B action predicate.
- The RPDB is scanned in order of decreasing priority (note that a lower number
- means higher priority, see the description of
- .I PREFERENCE
- below). The selector
- of each rule is applied to {source address, destination address, incoming
- interface, tos, fwmark} and, if the selector matches the packet,
- the action is performed. The action predicate may return with success.
- In this case, it will either give a route or failure indication
- and the RPDB lookup is terminated. Otherwise, the RPDB program
- continues with the next rule.
- .P
- Semantically, the natural action is to select the nexthop and the output device.
- .P
- At startup time the kernel configures the default RPDB consisting of three
- rules:
- .TP
- 1.
- Priority: 0, Selector: match anything, Action: lookup routing
- table
- .B local
- (ID 255).
- The
- .B local
- table is a special routing table containing
- high priority control routes for local and broadcast addresses.
- .TP
- 2.
- Priority: 32766, Selector: match anything, Action: lookup routing
- table
- .B main
- (ID 254).
- The
- .B main
- table is the normal routing table containing all non-policy
- routes. This rule may be deleted and/or overridden with other
- ones by the administrator.
- .TP
- 3.
- Priority: 32767, Selector: match anything, Action: lookup routing
- table
- .B default
- (ID 253).
- The
- .B default
- table is empty. It is reserved for some post-processing if no previous
- default rules selected the packet.
- This rule may also be deleted.
- .P
- Each RPDB entry has additional
- attributes. F.e. each rule has a pointer to some routing
- table. NAT and masquerading rules have an attribute to select new IP
- address to translate/masquerade. Besides that, rules have some
- optional attributes, which routes have, namely
- .BR "realms" .
- These values do not override those contained in the routing tables. They
- are only used if the route did not select any attributes.
- .sp
- The RPDB may contain rules of the following types:
- .RS
- .B unicast
- - the rule returns the route found
- in the routing table referenced by the rule.
- .B blackhole
- - the rule causes a silent drop the packet.
- .B unreachable
- - the rule generates a 'Network is unreachable' error.
- .B prohibit
- - the rule generates 'Communication is administratively
- prohibited' error.
- .B nat
- - the rule translates the source address
- of the IP packet into some other value.
- .RE
- .TP
- .B ip rule add - insert a new rule
- .TP
- .B ip rule delete - delete a rule
- .RS
- .TP
- .BI type " TYPE " (default)
- the type of this rule. The list of valid types was given in the previous
- subsection.
- .TP
- .BI from " PREFIX"
- select the source prefix to match.
- .TP
- .BI to " PREFIX"
- select the destination prefix to match.
- .TP
- .BI iif " NAME"
- select the incoming device to match. If the interface is loopback,
- the rule only matches packets originating from this host. This means
- that you may create separate routing tables for forwarded and local
- packets and, hence, completely segregate them.
- .TP
- .BI oif " NAME"
- select the outgoing device to match. The outgoing interface is only
- available for packets originating from local sockets that are bound to
- a device.
- .TP
- .BI tos " TOS"
- .TP
- .BI dsfield " TOS"
- select the TOS value to match.
- .TP
- .BI fwmark " MARK"
- select the
- .B fwmark
- value to match.
- .TP
- .BI uidrange " NUMBER-NUMBER"
- select the
- .B uid
- value to match.
- .TP
- .BI ipproto " PROTOCOL"
- select the ip protocol value to match.
- .TP
- .BI sport " NUMBER | NUMBER-NUMBER"
- select the source port value to match. supports port range.
- .TP
- .BI dport " NUMBER | NUMBER-NUMBER"
- select the destination port value to match. supports port range.
- .TP
- .BI priority " PREFERENCE"
- the priority of this rule.
- .I PREFERENCE
- is an unsigned integer value, higher number means lower priority, and rules get
- processed in order of increasing number. Each rule
- should have an explicitly set
- .I unique
- priority value.
- The options preference and order are synonyms with priority.
- .TP
- .BI table " TABLEID"
- the routing table identifier to lookup if the rule selector matches.
- It is also possible to use lookup instead of table.
- .TP
- .BI protocol " PROTO"
- 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.
- .TP
- .BI suppress_prefixlength " NUMBER"
- reject routing decisions that have a prefix length of NUMBER or less.
- .TP
- .BI suppress_ifgroup " GROUP"
- reject routing decisions that use a device belonging to the interface
- group GROUP.
- .TP
- .BI realms " FROM/TO"
- Realms to select if the rule matched and the routing table lookup
- succeeded. Realm
- .I TO
- is only used if the route did not select any realm.
- .TP
- .BI nat " ADDRESS"
- The base of the IP address block to translate (for source addresses).
- The
- .I ADDRESS
- may be either the start of the block of NAT addresses (selected by NAT
- routes) or a local host address (or even zero).
- In the last case the router does not translate the packets, but
- masquerades them to this address.
- Using map-to instead of nat means the same thing.
- .B Warning:
- Changes to the RPDB made with these commands do not become active
- immediately. It is assumed that after a script finishes a batch of
- updates, it flushes the routing cache with
- .BR "ip route flush cache" .
- .RE
- .TP
- .B ip rule flush - also dumps all the deleted rules.
- .RS
- .TP
- .BI protocol " PROTO"
- Select the originating protocol.
- .RE
- .TP
- .B ip rule show - list rules
- This command has no arguments.
- The options list or lst are synonyms with show.
- .TP
- .B ip rule save
- .RS
- .TP
- .BI protocol " PROTO"
- Select the originating protocol.
- .RE
- .TP
- save rules table information to stdout
- .RS
- This command behaves like
- .BR "ip rule show"
- except that the output is raw data suitable for passing to
- .BR "ip rule restore" .
- .RE
- .TP
- .B ip rule restore
- restore rules table information from stdin
- .RS
- This command expects to read a data stream as returned from
- .BR "ip rule save" .
- It will attempt to restore the rules table information exactly as
- it was at the time of the save. Any rules already in the table are
- left unchanged, and duplicates are not ignored.
- .RE
- .SH SEE ALSO
- .br
- .BR ip (8)
- .SH AUTHOR
- Original Manpage by Michail Litvak <mci@owl.openwall.com>