% % $XORP: xorp/docs/user_manual/policy.tex,v 1.24 2008/08/06 08:29:20 abittau 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. \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}, {\tt reject}, {\tt next term} and {\tt next policy}. 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. The next term or policy commands will skip evaluation to the next term or policy in the evaluation chain. 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. \subsubsection{Final action} A policy statement can also hold one unnamed term that specifies what the final action on a route should be. This term contains only a {\tt then} block that is executed only if reached. This will be the case if previous terms do not accept or reject the route, or skip to the next policy. Here is an example of an unnamed term: \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xx\=xx\=xx\=xx\=xx\=\kill policy \{\\ \>policy-statement bgp \{ \\ \>\>term a \{ \\ \>\>\>from \{\\ \>\>\>\>med: 1 \\ \>\>\>\}\\ \>\>\>then \{\\ \>\>\>\>accept\\ \>\>\>\}\\ \>\>\}\\ \>\>then \{ \\ \>\>\>reject\\ \>\>\}\\ \>\}\\ \} \\ \end{tabbing} \end{alltt} \end{minipage} } Note the last {\em then} block which lives in an unnamed term. If reached, it will reject any routes that were not accepted / rejected by the previous terms. Hence it acts as a final action. \subsection{Policy subroutines} It is possible to refer (call) a policy from another one with the use of {\em policy subroutines}. This allows factoring out common match conditions into a subroutine and referring to them from multiple policies. Policy subroutines can only be used as a match condition and hence be present only in {\em from} or {\em to} term blocks. If the policy subroutine rejects the route, then false is returned and route matching fails; true is returned otherwise causing a match success. Note that if any actions that modify the route are present in the subroutine, they will be executed even if the route is ultimately discarded by the calling policy. That is, if the {\em to} and {\em from} block in the subroutine match the route, the subroutine {\em then} block will be executed and it may modify the route, even if the caller ultimately decides to reject the route. Here is an example of a policy subroutine: \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xx\=xx\=xx\=xx\=xx\=\kill policy \{\\ \>policy-statement drop-private \{\\ \>\>term a \{\\ \>\>\>from \{\\ \>\>\>\>network4: 10.0.0.0/8 \\ \>\>\>\}\\ \>\>\>then \{\\ \>\>\>\>reject\\ \>\>\>\}\\ \>\>\}\\ \>\} \\ \>policy-statement bgp \{ \\ \>\>term start \{ \\ \>\>\>from \{\\ \>\>\>\>policy: "drop-private" \\ \>\>\>\>med: 1 \\ \>\>\>\}\\ \>\>\>then \{\\ \>\>\>\>accept\\ \>\>\>\}\\ \>\>\}\\ \>\>term reject \{ \\ \>\>\>then \{\\ \>\>\>\>reject\\ \>\>\>\}\\ \>\>\}\\ \>\}\\ \} \\ \end{tabbing} \end{alltt} \end{minipage} } This BGP policy will only accept routes that match term {\em start}. For that to occur, the {\em drop-private} policy must return ``true'', {\em i.e.,} it must accept the route. This will only happen if the route is not ``private'' {\em i.e.,} not 10.0.0.0/8 in this case. \subsection{Applying policies to protocols} Once a policy is specified, it must be 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. With BGP, it is possible to apply policies at a per-peer granularity. For example: \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xx\=xx\=xx\=xx\=xx\=\kill protocol \{\\ \>bgp \{\\ \>\>peer 192.168.1.1 \{ \\ \>\>\>import: "accept" \\ \>\>\} \\ \>\>import: "reject"\\ \>\} \\ \} \end{tabbing} \end{alltt} \end{minipage} } Per-peer policies take precedence over global ones. Thus, the above example would accept all routes from peer 192.168.1.1 and reject all other routes. \subsubsection{Policy expressions} When specifying a policy list to run, it is possible to include a {\em policy expression}. A policy expression is a boolean expression over one or more policies. Whether a route is accepted or not depends on the outcome of the whole expression rather than the individual policies that compose it. Here is an example of a policy expression. \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xx\=xx\=xx\=xx\=xx\=\kill protocol \{\\ \>bgp \{\\ \>\>import: "(good \&\& allowed),(good || trusted),(!bad),reject"\\ \>\} \\ \} \end{tabbing} \end{alltt} \end{minipage} } A policy expression must be enclosed in parenthesis. The first expression will accept routes that are accepted both by the policies {\em good} and {\em allowed}. The second expression will accept routes accepted by any of the two policies in the expression. The third expression will allow only routes rejected by {\em bad}. It is possible to mix policy expressions and standard policy executions ({\em e.g.,} {\em reject} in our example) when listing policies. \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:DB8:AAAA:20::/64\\ \>\>network 2001:DB8:AAAA:30::/64\\ \>\}\\ \} \\ \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. \subsection{Network lists} A list of IPv4 or IPv6 route prefixes can be specified using the {\tt network4-list} or {\tt network6-list} directive respectively. In addition to specifying the prefix, each prefix can have a modifier which specifies how the prefix is matched. Valid modifiers are listed in Table~\ref{tab:policy:mod} and the default one is {\tt exact}. \begin{table} \begin{center} \begin{tabular}{|l|l|} \hline Modifier & Match effect \\ \hline\hline exact & An exact match \\ \hline longer & A higher number of bits than the netmask specified must match \\ \hline orlonger & Exact or longer \\ \hline shorter & A lower number of bits than the netmask specified must match \\ \hline orshorter & Exact or shorter \\ \hline not & Must not match exactly \\ \hline \end{tabular} \end{center} \caption{\label{tab:policy:mod}Modifiers for network lists.} \end{table} Here is an example to illustrate the syntax: \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 \{ \\ \>\>\>modifier: "orlonger"\\ \>\> \} \\ \>\} \\ \} \\ \end{tabbing} \end{alltt} \end{minipage} } \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 specifying 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} The table that follows summarizes the match conditions in a {\tt from} block for all protocols. \begin{center} \begin{tabular}{|l|c|c|p{5.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 :} (or {\tt ==}) & ipv4net & Matches the prefix of an IPv4 route. \\ & {\tt longer} (or {\tt <}) & & Matches the route with a longer netmask. \\ & {\tt orlonger} (or {\tt <=}) & & Matches longer or exact route. \\ & {\tt shorter} (or {\tt >})& & Matches the route with a shorter netmask. \\ & {\tt orshorter} (or {\tt >=}) & & Matches shorter or exact route. \\ & {\tt not} (or {\tt !=}) & & Does not match route. \\ \hline {\tt network6} & {\tt :} & ipv6net & Same as IPv4, but for IPv6 prefixes. \\ & {\tt longer} & & \\ & {\tt orlonger} & & \\ & {\tt shorter} & & \\ & {\tt orshorter} & & \\ & {\tt not} & & \\ \hline {\tt network4-list} & {\tt :} & txt & Matches if the named IPv4 set contains the route.\\ \hline {\tt network6-list} & {\tt :} & txt & Matches if the named IPv6 set contains the route.\\ \hline {\tt prefix-length4} & {\tt :} & u32range & Matches if the IPv4 route has a prefix length within the specified range. \\ \hline {\tt prefix-length6} & {\tt :} & u32range & Matches if the IPv6 route has a prefix length within the specified range. \\ \hline {\tt nexthop4} & {\tt :} & ipv4range & Matches if the IPv4 next-hop of the route lies within the specified range.\\ \hline {\tt nexthop6} & {\tt :} & ipv6range & Matches if the IPv6 next-hop of the route lies within the specified range. \\ \hline {\tt tag} & {\tt :} & u32range & Matches the route tag. Routes can be arbitrarily tagged (labeled) via policies. \\ \hline {\tt policy} & {\tt :} & txt & Executes a policy as a subroutine. If the policy rejects the route, false is returned and no match occurs. Otherwise, true is returned and the match is successful. \\ \hline \end{tabular} \end{center} Note that the {\tt network4} and {\tt prefix-length4} statements are independent and cannot be used together to match, say, all routes within a specific prefix. For example, using both statements {\tt network4 = 10.0.0.0/8} and {\tt prefix-length4 >= 8} is incorrect if the intend is to match all routes within prefix 10.0.0.0/8. Instead, the {\tt network4 <= 10.0.0.0/4} statement alone should be used for that purpose. The same applies for the {\tt network6} and {\tt prefix-length6} statements as well. The match conditions for the {\tt to} block are identical in syntax and semantics as the {\tt from} block except for one case. It is illegal to specify the protocol in the {\tt to} block. The reason for this is that when a policy is bound to a protocol via the {\tt export} or {\tt import} statement, that protocol automatically becomes the one referenced in the {\tt to} block. When a BGP export policy is created, the {\tt to} must be BGP by definition as {\em it} is doing the advertisement. \subsection{Actions} Common actions to all protocols are summarized in following table. \begin{center} \begin{tabular}{|l|c|c|p{7.5cm}|} \hline Variable & Operator & Argument type & Semantics \\ \hline\hline {\tt accept} & none & none & Propagate this route downstream and stop executing all policies associated to this route.\\ \hline {\tt reject} & none & none & Do not propagate this route downstream and stop executing all policies associated to this route.\\ \hline {\tt next} & {\tt :} & txt & The argument can either be ``term'' or ``policy''. This will skip evaluation to the next term or policy in the evaluation chain. \\ \hline {\tt trace} & {\tt :} & u32 & Enable tracing at a specific verbosity level. Currently 1 means a single line of logging and 3 is the most verbose level. \\ \hline {\tt tag} & {\tt :} & u32 & Tag a route. Routes can have an arbitrary tag for use in policy. The router makes no use of this tag except for mapping it into the OSPF or RIP tags if the protocols advertise tagged routes. \\ & {\tt add} & & Add to the tag. \\ & {\tt sub} & & Subtract from the tag. \\ {\tt nexthop4} & {\tt :} & ipv4 & Replaces the IPv4 nexthop. \\ \hline {\tt nexthop6} & {\tt :} & ipv6 & Replaces the IPv6 nexthop. \\ \hline {\tt nexthop4-var} & {\tt :} & txt & Replaces the IPv4 nexthop with a {\em variable}. The variable can be {\em self} or {\em peer-address} indicating either the local or remote address respectively when communicating with a peer. \\ \hline {\tt nexthop6-var} & {\tt :} & txt & Same as with IPv4 but for IPv6. \\ \hline \end{tabular} \end{center} \section{BGP} BGP supports policy and route redistribution. It can be used both as a source for redistribution (BGP-to-something) and as a target (something-to-BGP). The following sections summarize which aspects of BGP routes may be matched and what actions may be taken. These are also specified in the {\tt bgp.tp} template file. The BGP policy engine currently has an interesting feature / bug. An export filter is placed on the RIB branch too. Thus, if an export policy rejects all routes, the RIB will never receive these routes and no routes will go into the forwarding plane. To avoid this, match {\tt neighbor: 0.0.0.0} in the {\tt to} block and {\tt accept}. The next term could match all and reject. This ``feature'' is actually useful if you want a BGP peering but do not wish to change the routing table. \subsection{Match Conditions} The following table summarizes the match conditions specific to BGP. \begin{center} \begin{tabular}{|l|c|c|p{7cm}|} \hline Variable & Operator & Argument type & Semantics \\ \hline\hline {\tt as-path} & {\tt :} & txt & Matches an AS-Path with a regular expression. \\ {\tt as-path-list} & {\tt :} & as-path-list & If the set contains a regular expression which matches an AS-Path, then the term matches. \\ \hline {\tt community} & {\tt :} & txt & Matches against the specified community. \\ {\tt community-list} & {\tt :} & community-list & If the set contains a community which matches, then the term matches. \\ \hline {\tt neighbor} & {\tt :} & ipv4range & In a {\tt from} block it matches whether the route was learnt from a BGP peer in the specified range. In a {\tt to} block it matches whether the route is about to be advertised to a BGP peer in the specified range. \\ \hline {\tt origin} & {\tt :} & u32 & Matches the origin attribute of the route. 0 stands for IGP, 1 for EGP and 2 for INCOMPLETE. \\ \hline {\tt med} & {\tt :} & u32range & Matches the MED of the route. \\ \hline {\tt localpref} & {\tt :} & u32range & Matches the local preference of the route. \\ \hline {\tt was-aggregated} & {\tt :} & bool & True if this route contributed to origination of an aggregate route. \\ \hline \end{tabular} \end{center} \subsection{Actions} The following table summarizes the actions specific to BGP. \begin{center} \begin{tabular}{|l|c|c|p{7cm}|} \hline Variable & Operator & Argument type & Semantics \\ \hline\hline {\tt as-path-prepend} & {\tt :} & txt & Prepends the specified AS-Path to the one on the route. \\ {\tt as-path-expand} & {\tt :} & u32 & Prepends the last AS in the path the specified number of times. \\ \hline {\tt community} & {\tt :} & txt & Sets the community attribute.\\ {\tt community-add} & {\tt :} & txt & Adds the specified community. \\ \hline {\tt community-del} & {\tt :} & txt & Deletes the specified community. \\ \hline {\tt origin} & {\tt :} & u32 & Sets the origin. \\ \hline {\tt med} & {\tt :} & u32 & Sets the MED. \\ & {\tt add} & & Add to the MED. \\ & {\tt sub} & & Subtract from the MED. \\ \hline {\tt med-remove} & {\tt :} & bool & Remove MED if present. \\ \hline {\tt localpref} & {\tt :} & u32 & Sets the localpref. \\ & {\tt add} & & Add to the localpref. \\ & {\tt sub} & & Subtract from the localpref. \\ \hline {\tt aggregate-prefix-len} & {\tt :} & u32 & Originate an aggregate route with this prefix length. \\ \hline {\tt aggregate-brief-mode} & {\tt :} & bool & If true omit AS SET generation in aggregate route. \\ \hline \end{tabular} \end{center} \section{Static Routes} Static routes support policy and may be used as a source for route redistribution. The table that follows summarizes the match conditions specific to static routes. These are also specified in the {\tt static\_routes.tp} template file. Note that the static routes can match only the {\tt from} block, because then can only be exported. \begin{center} \begin{tabular}{|l|c|c|p{7cm}|} \hline Variable & Operator & Argument type & Semantics \\ \hline \hline {\tt metric} & {\tt :} & u32 & Matches the metric of a route.\\ \hline \end{tabular} \end{center} \section{RIP and RIPng} RIP and RIPng support policy and route redistribution. Each of them can be used both as a source for redistribution (RIP/RIPng-to-something) and as a target (something-to-RIP/RIPng). The following sections summarize which aspects of RIP and RIPng routes may be matched and what actions may be taken. These are also specified in the {\tt rip.tp} and {\tt ripng.tp} template files. \subsection{Match Conditions} The following table summarizes the match conditions specific to RIP and RIPng. \begin{center} \begin{tabular}{|l|c|c|p{7cm}|} \hline Variable & Operator & Argument type & Semantics \\ \hline \hline {\tt metric} & {\tt :} & u32 & Matches the metric of a route.\\ \hline {\tt tag} & {\tt :} & u32range & Matches the route tag field in a route. \\ \hline \end{tabular} \end{center} \subsection{Actions} The following table summarizes the actions specific to RIP and RIPng. \begin{center} \begin{tabular}{|l|c|c|p{7cm}|} \hline Variable & Operator & Argument type & Semantics \\ \hline \hline {\tt metric} & {\tt :} & u32 & Sets the metric. \\ & {\tt add} & & Add to the metric. \\ & {\tt sub} & & Subtract from the metric. \\ \hline {\tt tag} & {\tt :} & u32 & Sets the route tag field. \\ & {\tt add} & & Adds to the tag. \\ & {\tt sub} & & Subtracts from the tag. \\ \hline \end{tabular} \end{center} \section{OSPF} OSPF supports policy and route redistribution. It can be used both as a source for redistribution (OSPF-to-something) and as a target (something-to-OSPF). The following sections summarize which aspects of OSPF routes may be matched and what actions may be taken. These are also specified in the {\tt ospfv2.tp} template file. \subsection{Match Conditions} The following table summarizes the match conditions specific to OSPF. \begin{center} \begin{tabular}{|l|c|c|p{7cm}|} \hline Variable & Operator & Argument type & Semantics \\ \hline\hline {\tt metric} & {\tt :} & u32 & Matches metric \\ \hline \hline {\tt external-type} & {\tt :} & u32 & Matches an external type 1 or 2 route. \\ \hline \hline {\tt tag} & {\tt :} & u32range & Matches tag field in AS-external-LSA. \\ \hline \end{tabular} \end{center} \subsection{Actions} The table that follows summarizes the actions specific to OSPF. \begin{center} \begin{tabular}{|l|c|c|p{7cm}|} \hline Variable & Operator & Argument type & Semantics \\ \hline\hline \hline {\tt metric} & {\tt :} & u32 & Set the metric. \\ & {\tt add} & & Add to the metric. \\ & {\tt sub} & & Subtract from the metric. \\ \hline \hline {\tt external-type} & {\tt :} & u32 & Sets the external type to 1 or 2. \\ \hline \hline {\tt tag} & {\tt :} & u32 & Set tag field in AS-external-LSA. \\ & {\tt add} & & Adds to the tag. \\ & {\tt sub} & & Subtracts from the tag. \\ \hline \end{tabular} \end{center} \section{Examples} Some common policies are presented in this section for a better understanding of the syntax. Here is a simple one: \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xx\=xx\=xx\=xx\=xx\=\kill policy \{\\ \>policy-statement medout \{\\ \>\>term a \{\\ \>\>\>then \{\\ \>\>\>\>med: 42\\ \>\>\>\}\\ \>\>\} \\ \>\} \\ \}\\ \\ protocols \{\\ \>bgp \{\\ \>\>export: "medout"\\ \>\}\\ \}\\ \end{tabbing} \end{alltt} \end{minipage} } This will cause all routes leaving BGP to have a MED of 42. The whole decision process is unaffected as routes come in with their original MED. If this were used as an import policy, then routes flowing into the decision process would have a modified MED. As a consequence, it is also possible that the advertised routes will have a MED of 42, even though it is used as an import policy. \newpage Here is a more complicated 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 friend \{\\ \>\>\>from \{\\ \>\>\>\>protocol: "static"\\ \>\>\>\}\\ \>\>\>to \{\\ \>\>\>\>neighbor: 10.0.0.1\\ \>\>\>\}\\ \>\>\>then \{\\ \>\>\>\>med: 1\\ \>\>\>\>accept\\ \>\>\>\}\\ \>\>\} \\ \>\>term metric \{\\ \>\>\>from \{\\ \>\>\>\>protocol: "static"\\ \>\>\>\>metric: 7\\ \>\>\>\}\\ \>\>\>to \{\\ \>\>\>\>neighbor: 10.0.0.2\\ \>\>\>\}\\ \>\>\>then \{\\ \>\>\>\>trace: 1\\ \>\>\>\>med: 7\\ \>\>\>\>accept\\ \>\>\>\}\\ \>\>\} \\ \>\>term drop \{\\ \>\>\>from \{\\ \>\>\>\>protocol: "static"\\ \>\>\>\}\\ \>\>\>then \{\\ \>\>\>\>reject\\ \>\>\>\}\\ \>\>\} \\ \>\} \\ \} \\ \\ protocols \{\\ \>bgp \{\\ \>\>export: "static-to-bgp" \\ \>\}\\ \} \end{tabbing} \end{alltt} \end{minipage} } In this example, all static routes are redistributed to BGP. The BGP peer 10.0.0.1 will receive all of them with a MED of 1. For some reason, static routes with a metric of 7 are important and they are advertised to the BGP peer 10.0.0.2 with a MED of 7 and are also logged. Note that 10.0.0.1 will receive these static routes with a MED of 1, even if they had a metric of 7. Finally, all static routes which are now in BGP are dropped on the export path. All other BGP peers will not receive any of the static routes. \section{Policy commands} Two classes of policy commands are supported by {\em xorpsh}. First, there is a mechanism for testing policies. Second, there are commands for showing policy configurations. \subsection{test policy} It is possible to test a routing policy against a route to determine whether it will be accepted and what route characteristics will be modified. Here is an example of how one can test the policy {\em import} against the prefix 10.0.0.0/8. \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xxxxxxxxxxxxxxxx\=\kill user@hostname> {\bf test policy import 10.0.0.0/8}\\ Policy decision: rejected \end{tabbing} \end{alltt} \end{minipage} } In this case the route was rejected and no modifications occurred to it. If the policy modifies or matches protocol specific route attributes, we must specify under which protocol to run the route. Here is an example. \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xxxxxxxxxxxxxxxx\=\kill user@hostname> {\bf test policy import2 10.0.0.0/8} "{\bf --protocol=ospf4}"\\ Policy decision: accepted \\ Route modifications: \\ tag 123 \end{tabbing} \end{alltt} \end{minipage} } In this case we ran the policy {\em import2} in the context of {\em ospf4}. The route was accepted and the tag was modified to 123. If the policy matches protocol specific route attributes, we must supply their value. The general syntax is \verb|--name=value|. As with the protocol directive, the whole argument must be enclosed by quotes. Here is an example. \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xxxxxxxxxxxxxxxx\=\kill user@hostname> {\bf test policy med1 10.0.0.0/8} "{\bf --protocol=bgp --med=1}"\\ Policy decision: accepted \\ user@hostname> {\bf test policy med1 10.0.0.0/8} "{\bf --protocol=bgp --med=2}"\\ Policy decision: rejected \end{tabbing} \end{alltt} \end{minipage} } In this example we ran the route with a {\em med} of 1 and 2. The policy only accepts routes with a {\em med} of 1 though. Multiple protocol attributes can be passed as an argument. The route attributes names are the same as those used in match conditions in the policy configuration. (Strictly speaking they equal those in the policy ``var map'', which is initialized in the XORP template files.) \subsection{show policy} The {\tt show policy} command show the policy configuration. The command takes an argument indicating which part of the configuration to show. Table~\ref{tab:policy:show} lists the possible arguments. \begin{table} \begin{center} \begin{tabular}{|l|l|} \hline Argument & Meaning \\ \hline\hline network4-list & Display IPv4 prefix lists. \\ network6-list & Display IPv4 prefix lists. \\ as-path-list & Display AS path lists. \\ community-list & Display BGP community lists. \\ policy-statement & Display policy statements. \\ \hline \end{tabular} \end{center} \caption{\label{tab:policy:show}Possible show policy commands.} \end{table} For example, to list all configured IPv4 prefix lists one types: \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xxxxxxxxxxxxxxxx\=\kill user@hostname> {\bf show policy network4-list}\\ test \>9.9.0.0/16 \\ private \>10.0.0.0/8,192.168.0.0/16 \end{tabbing} \end{alltt} \end{minipage} } The name of the list appears on the left and the contents on the right. One can show a specific list by giving its name as an additional argument to the command. Here is an example. \noindent\framebox[\textwidth][l]{\scriptsize \begin{minipage}{6in} \begin{alltt} \begin{tabbing} xxxxxxxxxxxxxxxx\=\kill user@hostname> {\bf show policy network4-list private}\\ 10.0.0.0/8,192.168.0.0/16 \end{tabbing} \end{alltt} \end{minipage} } In this case, only the contents is displayed, without the name.