policy.tex

xorp源码hg

%
% $XORP: xorp/docs/user_manual/policy.tex,v 1.20 2007/01/11 22:32:05 pavlin Exp $
%

\chapter{\label{policy}Policy}
Policy controls which routes to accept and which routes should be advertised.
Moreover, it provides a mechanism for modifying route attributes and enables
{\em route redistribution} which allows routes learnt by a protocol to be
advertised by a {\em different} protocol.


\section{Terminology and Concepts}
A crucial aspect to understand is the difference between {\em import} and {\em
export} policies.
%
\begin{description}
\item[import] filters act upon routes as soon as they are received from a
routing protocol.  Before a protocol even makes a decision on the route, import
filter processing will already have taken place.  Note that import filters may
therefore affect the decision process (e.g. by changing the metric).
%
\item[export] filters act upon routes just before they are advertised by a
routing protocol.  Only routes which have won the decision process (i.e. the
ones used in the forwarding plane) will be considered by export filters.
\end{description}

Normally policies will operate within a single routing protocol, for example  a
policy which sets the MED on all BGP routes (only BGP is involved).  If a policy
involves two different protocols, then {\em route redistribution} will occur
``implicitly''.

\section{Policy Statement}
A {\em policy statement} is the user definition for a policy.  Internally, it
contains a list of {\em terms}.  A term is the most atomic unit of execution of
a policy.  Each single term, if executed, will cause actions to be taken on a
route.  A policy statement should define a logical operation to be run on
routes and this operation may involve multiple terms, which define simpler and
smaller execution steps.

The overall structure of a policy statement looks as follows:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
policy \{\\
\>policy-statement {\em name} \{\\
\>\>term {\em name} \{\\
\>\>\} \\
\>\>\ldots \\
\>\>term {\em name} \{\\
\>\>\} \\
\>\} \\
\}
\end{tabbing} 
\end{alltt}
\end{minipage}
}

Each term of a policy is executed in order.  It is not required that {\em all}
terms run---it is possible for a term to cause the policy to accept or
reject the route terminating the overall execution.

Once a policy is specified, it must be {\em bound} (applied) to a protocol.
This is achieved via the {\tt import} or {\tt export} statement depending on
the type of policy, within a protocol block.  For example:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
protocol \{\\
\>bgp \{\\
\>\>export: "policy1,policy2,\ldots"\\
\>\>import: "drop\_bad"\\
\>\} \\
\}
\end{tabbing} 
\end{alltt}
\end{minipage}
}

It is possible to have multiple policy statements per protocol such as in the
{\tt export} example above.  The policies, like terms, will be executed in
order.  Again, it is possible that not all policies are run---maybe the first
one will cause an accept or reject.

\subsection{Term}
A term is the heart of the policy execution.  It specifies how to match routes
as they enter the system, as they are about to leave and ultimately what
actions to perform on them.  The structure of a term is as follows:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
term {\em name} \{\\
\>from \{\\
\>\>\ldots\\
\>\} \\
\>to \{\\
\>\>\ldots\\
\>\} \\
\>then \{\\
\>\>\ldots\\
\>\} \\
\}
\end{tabbing} 
\end{alltt}
\end{minipage}
}

It is possible to omit the {\tt from}, {\tt to} and {\tt then} block.  If so,
{\tt from} and {\tt to} will match {\em all} routes traversing the filter.  An
empty {\tt then} block will run the {\em default action}.  The default action is
to execute the next term / policy in the list or accept the route if the last
term is being run.

In general, the {\tt from} and {\tt to} block will specify the {\em match
conditions} on a route and the {\tt then} block the actions to be performed on
the route in case of a match.

\subsubsection{Match Conditions}
The overall structure of a match condition is: {\em variable}, {\em operator},
{\em argument}.  A variable is a route attribute such as metric, prefix,
next-hop and so on.  The operator will specify {\em how} this variable is
matched.  For example {\tt $<$} may perform a less-than match whereas {\tt $>$}
may perform a greater-than operation.  The argument will be the value against
which the variable is matched.  The overall result is a {\em logical and} with
the result of each statement. An example would be as follows:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
from \{\\
\>protocol: "static"\\
\>metric < 5\\
\} \\
to \{\\
\>neighbor: 10.0.0.1\\
\} \\
then \{\\
\>\ldots\\
\} \\
\end{tabbing} 
\end{alltt}
\end{minipage}
}

In this example {\tt metric} is a variable, {\tt $<$} an operator and {\tt 5}
the argument.  This will match all static routes with a metric less than 5 being
advertised to the neighbor 10.0.0.1.  Note that the {\tt :} operator is an alias
for {\tt $==$} when matching (in {\tt from} and {\tt to} blocks) which simply
means equality.

\subsubsection{Actions}
All actions are performed sequentially and have a similar syntax to match
conditions. The main difference with respect to match conditions is that the
operator will normally be assignment and that special {\em commands} exist.
These commands are {\tt accept} and {\tt reject}.  If a route is accepted, no
further terms will be executed and the route will be propagated downstream.  If
a route is rejected, once again no further terms will run, and the route will {\em
not} be propagated downstream---it will be suppressed and dropped.  Depending on
whether it is an export or import filter, reject will have different semantics.
On export it will not be advertised and on import it will never be used at all.  

Here is an example of the syntax used when specifying actions:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
from \{\\
\>\ldots\\
\} \\
to \{\\
\>\ldots\\
\} \\
then \{\\
\>metric: 5\\
\>accept\\
\} \\
\end{tabbing} 
\end{alltt}
\end{minipage}
}

This term will cause the metric to be set to 5 and no further terms will be
executed, because of the {\tt accept}. Note that in the case of {\tt then}
blocks, the {\tt :} operator is an alias for {\tt =} which means assignment.

If neither {\tt accept} nor {\tt reject} are specified, the default action will
occur.  The default action will execute the next term or accept the route if the
last term has been reached.

Note that if the {\tt then} block contains an {\tt accept} or {\tt reject}
action, all other actions within the {\tt then} block will be executed
regardless whether in the configuration they are placed before or after
the {\tt accept} or {\tt reject} statements.

\newpage

\section{Sets}
Many times it is useful to match against a set of values.  For example it is
more practical to reference a set of prefixes to match against, which may also
be used in different policies rather than enumerating the prefixes one by one in
each policy.  This is achieved via sets which contain un-ordered items and no
duplicates.  Sets are declared as follows~\footnote{Note that prior to XORP
Release-1.4, the {\tt elements} statement with a complete comma-separated
list of all networks was used instead of {\tt network}.}:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
policy \{\\
\>network4-list {\em name} \{\\
\>\>network 10.0.0.0/8\\
\>\>network 192.168.0.0/16\\
\>\}\\
\>network6-list {\em name} \{\\
\>\>network 2001:0910::/32\\
\>\>network 2001:dead::/32\\
\>\}\\
\} \\
\end{tabbing} 
\end{alltt}
\end{minipage}
}

Two sets cannot have the same name---else there is no way to reference
them within policies.  Sets of different types are created in different
ways.  For example, a set of IPv4 prefixes is created via the {\tt
network4-list} directive whereas IPv6 prefixes would be created using
{\tt network6-list}.  To reference a set in a policy, simply use its
name as a text string.  For example:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
policy \{\\
\>network4-list private \{\\
\>\>network 10.0.0.0/8\\
\>\>network 192.168.0.0/16\\
\>\}\\
\>policy-statement drop-private \{\\
\>\>term a \{\\
\>\>\>from \{\\
\>\>\>\>network4-list: "private"\\
\>\>\>\}\\
\>\>\>then \{\\
\>\>\>\>reject\\
\>\>\>\}\\
\>\>\}\\
\>\} \\
\} \\
\end{tabbing} 
\end{alltt}
\end{minipage}
}

This policy will match when the route is 10.0.0.0/8 or 192.168.0.0/16.  In this
case the match needs to satisfy only one element of the set.  This is not always
the case.  If a route attribute which actually {\em is} a set (such as BGP
communities) was matched against a set the user specifies, depending on the
operator, different semantics would apply.  For example an operator may check
that the sets are equal, or that one has to be the subset of the other and so
on.  Obviously in this case each route has a single prefix so the only
reasonable match would be to check whether that prefix is in the set or not.

Note that it is pure ``coincidence'' that the directive to match a list of
prefixes {\tt network4-list} is the same as the one used to declare the set.  It
is not a requirement.

\section{Ranges}
Certain variables can be matched against linear ranges of their corresponding type.
The policy engine supports matching against ranges of unsigned integers and IPv4 / IPv6 addresses.
Ranges are expressed by specifiying their lower and upper inclusive boundaries separated by two dots, for example:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
from \{\\
\>nexthop4: 10.0.0.11..10.0.0.15\\
\>neighbor: 10.0.0.0..10.0.0.255\\
\>med: 100..200\\
\} \\
\end{tabbing} 
\end{alltt}
\end{minipage}
}

An abbreviated form of specifying a range containing a single value is allowed, in which case both the lower and upper boundary are considered to be equal.  Hence, the following two expressions are equivalent:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
from \{\\
\>neighbor: 10.1.2.3\\
\>med: 100\\
\} \\
from \{\\
\>neighbor: 10.1.2.3..10.1.2.3\\
\>med: 100..100\\
\} \\
\end{tabbing} 
\end{alltt}
\end{minipage}
}


\section{Tracing}
It is often useful to trace routes going through filters in order to debug
policies.  Another utility of this would be to log specific routes or simply to
monitor routes flowing throughout XORP.  This functionality is achieved via policy
tracing.

In order to trace a particular term simply assign an integer to the {\tt trace}
variable in the {\tt then} block.  The higher the integer, the more verbose the
log message is.  Here is an example:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
from \{\\
\>neighbor: 10.0.0.1\\
\} \\
then \{\\
\>trace: 3\\
\}\\
\end{tabbing} 
\end{alltt}
\end{minipage}
}

Assuming this is a BGP import policy, this term would cause all routes learnt
from the BGP peer 10.0.0.1 to be logged verbosely.  Currently there is no useful
meaning associated with the integral verbosity level although 1 normally
indicates a single line of log whereas 3 is the most noisy.

Note that only terms which match may be traced---else the {\tt then} block which
sets up the trace will never be run!  However, it is trivial to put a term which
will match everything (empty {\tt from} and {\tt to} block) which simply enables
tracing.  This may be necessary if {\em all} routes need to be monitored.

\section{Route Redistribution}
Route redistribution is a mechanism for advertising routes learnt via a
different protocol.  An example would be to advertise some static routes using
BGP.  Another possibility is advertising BGP routes using OSPF and so on.  The
key is that the {\tt from} block of a term will be matched in the protocol which
{\em received} the route whereas the {\tt to} block will be matched in the
protocol which is {\em advertising} the route (doing the redistribution).
Route redistribution will always be an export policy---the protocol exporting
(advertising) is the one redistributing.  All actions (such as changing the
metric) will occur in the protocol doing the redistribution.  

Here is an example:

\noindent\framebox[\textwidth][l]{\scriptsize
\begin{minipage}{6in}
\begin{alltt}
\begin{tabbing}
xx\=xx\=xx\=xx\=xx\=\kill
policy \{\\
\>policy-statement "static-to-bgp" \{\\
\>\>term a \{\\
\>\>\>from \{\\
\>\>\>\>protocol: "static"\\
\>\>\>\>metric: 2\\
\>\>\>\}\\
\>\>\>to \{\\
\>\>\>\>neighbor: 10.0.0.1\\
\>\>\>\}\\
\>\>\>then \{\\
\>\>\>\>med: 13\\
\>\>\>\>accept\\
\>\>\>\}\\
\>\>\}\\
\>\} \\
\} \\
\\
protocols \{\\
\>bgp \{\\
\>\>export: "static-to-bgp"\\
\>\}\\
\}\\
\end{tabbing} 
\end{alltt}
\end{minipage}
}

The policy is applied to BGP as it is doing the redistribution.  It is an export
policy because it is advertising.  Since the {\tt from} block contains a
protocol which is not BGP, route redistribution will occur.  In this case, all
static routes with metric 2 will be passed to BGP.  Furthermore, as these routes
are advertised to the BGP peer 10.0.0.1, the MED will be set to 13.

Note that this policy will cause all static routes with metric of 2 to be
advertised to {\em all} BGP peers---not only 10.0.0.1.  This policy does two
things: it sets up the route redistribution, and further more changes the MED 
for a specific peer on those routes.  Other peers will receive the static routes
with the default MED value.  

In order to prevent other peers receiving static routes, another policy should
be appended specifying that all static routes with metric of 2 should be
rejected.  Since this policy is added after the one in the example (in the
{\tt export} statement of BGP) the BGP peer 10.0.0.1 {\em will} receive the
advertisement as no further terms / policies will be executed after the {\tt
accept} of the first policy (which matches).

\section{Common Directives for all Protocols}
All protocols have a common set of route attributes which may be matched,
modified and actions which should take place on a route.  These may be found in
the template file {\tt policy.tp}. 

\subsection{Match Conditions}
Table~\ref{policy_common_match_from} summarizes the match conditions
in a {\tt from} block for all protocols.
\begin{table}[h]
\centering
\begin{tabular}{|l|c|c|p{7.5cm}|}
\hline
Variable & Operator & Argument type & Semantics \\
\hline\hline
{\tt protocol} & {\tt :} & txt & Matches the protocol via which the route was
learnt.  Only valid for export policies.  Used in route redistribution. \\
\hline
{\tt network4} & {\tt :} & ipv4net & Matches the prefix of an IPv4 route. \\