summaryrefslogtreecommitdiffstats
path: root/man/man8/ip-rule.8
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man/man8/ip-rule.8358
1 files changed, 358 insertions, 0 deletions
diff --git a/man/man8/ip-rule.8 b/man/man8/ip-rule.8
new file mode 100644
index 0000000..2c12bf6
--- /dev/null
+++ b/man/man8/ip-rule.8
@@ -0,0 +1,358 @@
+.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 "[ " list
+.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 pref
+.IR NUMBER " ] [ "
+.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 control 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 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 prescribes to return the route found
+in the routing table referenced by the rule.
+
+.B blackhole
+- the rule prescribes to silently drop the packet.
+
+.B unreachable
+- the rule prescribes to generate a 'Network is unreachable' error.
+
+.B prohibit
+- the rule prescribes to generate 'Communication is administratively
+prohibited' error.
+
+.B nat
+- the rule prescribes to translate 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>