2005-11-04 Paul Jakma <paul.jakma@sun.com>
* quagga.info: Update auto-built file
* ospf6d.texi: Add example config
* bgpd.texi: Add example configs. Couple of cleanups of format
and macros.
* routemap.texi: Add an explanation of how route-maps work.
Document the call and exit-policy commands.
diff --git a/doc/routemap.texi b/doc/routemap.texi
index 11351a4..db3e72d 100644
--- a/doc/routemap.texi
+++ b/doc/routemap.texi
@@ -1,30 +1,135 @@
@node Route Map
@chapter Route Map
-Route map is a very useful function in zebra. There is a match and set
-statement permitted in a route map.
-
-@example
-@group
-route-map test permit 10
- match ip address 10
- set local-preference 200
-@end group
-@end example
-
-This means that if a route matches ip access-list number 10 it's
-local-preference value is set to 200.
+Route maps provide a means to both filter and/or apply actions to
+route, hence allowing policy to be applied to routes.
@menu
* Route Map Command::
* Route Map Match Command::
-* Route Map Set Command::
+* Route Map Set Command::
+* Route Map Call Command::
+* Route Map Exit Action Command::
+* Route Map Examples::
@end menu
+Route-maps are an ordered list of route-map entries. Each entry may
+specify up to four distincts sets of clauses:
+
+@table @samp
+@item Matching Policy
+
+This specifies the policy implied if the @samp{Matching Conditions} are
+met or not met, and which actions of the route-map are to be taken, if
+any. The two possibilities are:
+
+@itemize @minus
+@item
+@samp{permit}: If the entry matches, then carry out the @samp{Set
+Actions}. Then finish processing the route-map, permitting the route,
+unless an @samp{Exit Action} indicates otherwise.
+
+@item
+@samp{deny}: If the entry matches, then finish processing the route-map and
+deny the route (return @samp{deny}).
+@end itemize
+
+The @samp{Matching Policy} is specified as part of the command which
+defines the ordered entry in the route-map. See below.
+
+@item Matching Conditions
+
+A route-map entry may, optionally, specify one or more conditions which
+must be matched if the entry is to be considered further, as governed
+by the Match Policy. If a route-map entry does not explicitely specify
+any matching conditions, then it always matches.
+
+@item Set Actions
+
+A route-map entry may, optionally, specify one or more @samp{Set
+Actions} to set or modify attributes of the route.
+
+@item Call Action
+
+Call to another route-map, after any @samp{Set Actions} have been
+carried out. If the route-map called returns @samp{deny} then
+processing of the route-map finishes and the route is denied,
+regardless of the @samp{Matching Policy} or the @samp{Exit Policy}. If
+the called route-map returns @samp{permit}, then @samp{Matching Policy}
+and @samp{Exit Policy} govern further behaviour, as normal.
+
+@item Exit Policy
+
+An entry may, optionally, specify an alternative @samp{Exit Policy} to
+take if the entry matched, rather than the normal policy of exiting the
+route-map and permitting the route. The two possibilities are:
+
+@itemize @minus
+@item
+@samp{next}: Continue on with processing of the route-map entries.
+
+@item
+@samp{goto N}: Jump ahead to the first route-map entry whose order in
+the route-map is >= N. Jumping to a previous entry is not permitted.
+@end itemize
+@end table
+
+The default action of a route-map, if no entries match, is to deny.
+I.e. a route-map essentially has as its last entry an empty @samp{deny}
+entry, which matches all routes. To change this behaviour, one must
+specify an empty @samp{permit} entry as the last entry in the route-map.
+
+To summarise the above:
+
+@multitable {permit} {action} {No Match}
+@headitem @tab Match @tab No Match
+@item @emph{Permit} @tab action @tab cont
+@item @emph{Deny} @tab deny @tab cont
+@end multitable
+
+@table @samp
+
+@item action
+@itemize @minus
+@item
+Apply @emph{set} statements
+
+@item
+If @emph{call} is present, call given route-map. If that returns a @samp{deny}, finish
+processing and return @samp{deny}.
+
+@item
+If @samp{Exit Policy} is @emph{next}, goto next route-map entry
+
+@item
+If @samp{Exit Policy} is @emph{goto}, goto first entry whose order in the list
+is >= the given order.
+
+@item
+Finish processing the route-map and permit the route.
+@end itemize
+
+@item deny
+@itemize @minus
+@item
+The route is denied by the route-map (return @samp{deny}).
+@end itemize
+
+@item cont
+@itemize @minus
+@item
+goto next route-map entry
+@end itemize
+@end table
+
@node Route Map Command
@section Route Map Command
-@deffn {Command} {route-map @var{route-map-name} permit @var{priority}} {}
+@deffn {Command} {route-map @var{route-map-name} (permit|deny) @var{order}} {}
+
+Configure the @var{order}'th entry in @var{route-map-name} with
+@samp{Match Policy} of either @emph{permit} or @emph{deny}.
+
@end deffn
@node Route Map Match Command
@@ -85,3 +190,42 @@
Set the BGP-4+ link local IPv6 nexthop address.
@end deffn
+@node Route Map Call Command
+@section Route Map Call Command
+
+@deffn {Route-map Command} {call @var{name}} {}
+Call route-map @var{name}. If it returns deny, deny the route and
+finish processing the route-map.
+@end deffn
+
+@node Route Map Exit Action Command
+@section Route Map Exit Action Command
+
+@deffn {Route-map Command} {on-match next} {}
+@deffnx {Route-map Command} {continue} {}
+Proceed on to the next entry in the route-map.
+@end deffn
+
+@deffn {Route-map Command} {on-match goto @var{N}} {}
+@deffnx {Route-map Command} {continue @var{N}} {}
+Proceed processing the route-map at the first entry whose order is >= N
+@end deffn
+
+@node Route Map Examples
+@section Route Map Examples
+
+A simple example of a route-map:
+
+@example
+@group
+route-map test permit 10
+ match ip address 10
+ set local-preference 200
+@end group
+@end example
+
+This means that if a route matches ip access-list number 10 it's
+local-preference value is set to 200.
+
+See @ref{BGP Configuration Examples} for examples of more sophisticated
+useage of route-maps, including of the @samp{call} action.