doc/routemap.texi

   1 @node Route Map
   2 @chapter Route Map
   3
   4 Route maps provide a means to both filter and/or apply actions to
   5 route, hence allowing policy to be applied to routes.
   6
   7 @menu
   8 * Route Map Command::
   9 * Route Map Match Command::
  10 * Route Map Set Command::
  11 * Route Map Call Command::
  12 * Route Map Exit Action Command::
  13 * Route Map Examples::
  14 @end menu
  15
  16 Route-maps are an ordered list of route-map entries. Each entry may
  17 specify up to four distincts sets of clauses:
  18
  19 @table @samp
  20 @item Matching Policy
  21
  22 This specifies the policy implied if the @samp{Matching Conditions} are
  23 met or not met, and which actions of the route-map are to be taken, if
  24 any. The two possibilities are:
  25
  26 @itemize @minus
  27 @item
  28 @samp{permit}: If the entry matches, then carry out the @samp{Set
  29 Actions}. Then finish processing the route-map, permitting the route,
  30 unless an @samp{Exit Action} indicates otherwise.
  31
  32 @item
  33 @samp{deny}: If the entry matches, then finish processing the route-map and
  34 deny the route (return @samp{deny}).
  35 @end itemize
  36
  37 The @samp{Matching Policy} is specified as part of the command which
  38 defines the ordered entry in the route-map. See below.
  39
  40 @item Matching Conditions
  41
  42 A route-map entry may, optionally, specify one or more conditions which
  43 must be matched if the entry is to be considered further, as governed
  44 by the Match Policy. If a route-map entry does not explicitely specify
  45 any matching conditions, then it always matches.
  46
  47 @item Set Actions
  48
  49 A route-map entry may, optionally, specify one or more @samp{Set
  50 Actions} to set or modify attributes of the route.
  51
  52 @item Call Action
  53
  54 Call to another route-map, after any @samp{Set Actions} have been
  55 carried out. If the route-map called returns @samp{deny} then
  56 processing of the route-map finishes and the route is denied,
  57 regardless of the @samp{Matching Policy} or the @samp{Exit Policy}. If
  58 the called route-map returns @samp{permit}, then @samp{Matching Policy}
  59 and @samp{Exit Policy} govern further behaviour, as normal.
  60
  61 @item Exit Policy
  62
  63 An entry may, optionally, specify an alternative @samp{Exit Policy} to
  64 take if the entry matched, rather than the normal policy of exiting the
  65 route-map and permitting the route. The two possibilities are:
  66
  67 @itemize @minus
  68 @item
  69 @samp{next}: Continue on with processing of the route-map entries.
  70
  71 @item
  72 @samp{goto N}: Jump ahead to the first route-map entry whose order in
  73 the route-map is >= N. Jumping to a previous entry is not permitted.
  74 @end itemize
  75 @end table
  76
  77 The default action of a route-map, if no entries match, is to deny.
  78 I.e. a route-map essentially has as its last entry an empty @samp{deny}
  79 entry, which matches all routes. To change this behaviour, one must
  80 specify an empty @samp{permit} entry as the last entry in the route-map.
  81
  82 To summarise the above:
  83
  84 @multitable {permit} {action} {No Match}
  85 @headitem           @tab Match  @tab No Match
  86 @item @emph{Permit} @tab action @tab cont
  87 @item @emph{Deny}   @tab deny   @tab cont
  88 @end multitable
  89
  90 @table @samp
  91
  92 @item action
  93 @itemize @minus
  94 @item
  95 Apply @emph{set} statements
  96
  97 @item
  98 If @emph{call} is present, call given route-map. If that returns a @samp{deny}, finish
  99 processing and return @samp{deny}.
 100
 101 @item
 102 If @samp{Exit Policy} is @emph{next}, goto next route-map entry
 103
 104 @item
 105 If @samp{Exit Policy} is @emph{goto}, goto first entry whose order in the list
 106 is >= the given order.
 107
 108 @item
 109 Finish processing the route-map and permit the route.
 110 @end itemize
 111
 112 @item deny
 113 @itemize @minus
 114 @item
 115 The route is denied by the route-map (return @samp{deny}).
 116 @end itemize
 117
 118 @item cont
 119 @itemize @minus
 120 @item
 121 goto next route-map entry
 122 @end itemize
 123 @end table
 124
 125 @node Route Map Command
 126 @section Route Map Command
 127
 128 @deffn {Command} {route-map @var{route-map-name} (permit|deny) @var{order}} {}
 129
 130 Configure the @var{order}'th entry in @var{route-map-name} with
 131 @samp{Match Policy} of either @emph{permit} or @emph{deny}.
 132
 133 @end deffn
 134
 135 @node Route Map Match Command
 136 @section Route Map Match Command
 137
 138 @deffn {Route-map Command} {match ip address @var{access_list}} {}
 139 Matches the specified @var{access_list}
 140 @end deffn
 141
 142 @deffn {Route-map Command} {match ip next-hop @var{ipv4_addr}} {}
 143 Matches the specified @var{ipv4_addr}.
 144 @end deffn
 145
 146 @deffn {Route-map Command} {match aspath @var{as_path}} {}
 147 Matches the specified @var{as_path}.
 148 @end deffn
 149
 150 @deffn {Route-map Command} {match metric @var{metric}} {}
 151 Matches the specified @var{metric}.
 152 @end deffn
 153
 154 @deffn {Route-map Command} {match community @var{community_list}} {}
 155 Matches the specified  @var{community_list}
 156 @end deffn
 157
 158 @deffn {Route-map Command} {match pathlimit as @var{ASN}} {}
 159 Matches the specified AS-Pathlimit @var{ASN}.
 160 @end deffn
 161
 162 @node Route Map Set Command
 163 @section Route Map Set Command
 164
 165 @deffn {Route-map Command} {set ip next-hop @var{ipv4_address}} {}
 166 Set the BGP nexthop address.
 167 @end deffn
 168
 169 @deffn {Route-map Command} {set local-preference @var{local_pref}} {}
 170 Set the BGP local preference.
 171 @end deffn
 172
 173 @deffn {Route-map Command} {set weight @var{weight}} {}
 174 Set the route's weight.
 175 @end deffn
 176
 177 @deffn {Route-map Command} {set metric @var{metric}} {}
 178 Set the BGP attribute MED.
 179 @end deffn
 180
 181 @deffn {Route-map Command} {set as-path prepend @var{as_path}} {}
 182 Set the BGP AS path to prepend.
 183 @end deffn
 184
 185 @deffn {Route-map Command} {set community @var{community}} {}
 186 Set the BGP community attribute.
 187 @end deffn
 188
 189 @deffn {Route-map Command} {set ipv6 next-hop global @var{ipv6_address}} {}
 190 Set the BGP-4+ global IPv6 nexthop address.
 191 @end deffn
 192
 193 @deffn {Route-map Command} {set ipv6 next-hop local @var{ipv6_address}} {}
 194 Set the BGP-4+ link local IPv6 nexthop address.
 195 @end deffn
 196
 197 @deffn {Route-map Command} {set pathlimit ttl @var{ttl}} {}
 198 Sets the specified AS-Pathlimit @var{ttl} on the route. This will also cause
 199 the AS to be set to the local AS.
 200
 201 Note that the AS-Pathlimit RFC specifies that speakers advertising this
 202 attribute should set Atomic-aggregate on all less specific routes. Setting
 203 AS-Pathlimit by route-map does not do this, the user must do so themselves,
 204 as they wish.
 205 @end deffn
 206
 207 @node Route Map Call Command
 208 @section Route Map Call Command
 209
 210 @deffn {Route-map Command} {call @var{name}} {}
 211 Call route-map @var{name}. If it returns deny, deny the route and
 212 finish processing the route-map.
 213 @end deffn
 214
 215 @node Route Map Exit Action Command
 216 @section Route Map Exit Action Command
 217
 218 @deffn {Route-map Command} {on-match next} {}
 219 @deffnx {Route-map Command} {continue} {}
 220 Proceed on to the next entry in the route-map.
 221 @end deffn
 222
 223 @deffn {Route-map Command} {on-match goto @var{N}} {}
 224 @deffnx {Route-map Command} {continue @var{N}} {}
 225 Proceed processing the route-map at the first entry whose order is >= N
 226 @end deffn
 227
 228 @node Route Map Examples
 229 @section Route Map Examples
 230
 231 A simple example of a route-map:
 232
 233 @example
 234 @group
 235 route-map test permit 10
 236  match ip address 10
 237  set local-preference 200
 238 @end group
 239 @end example
 240
 241 This means that if a route matches ip access-list number 10 it's
 242 local-preference value is set to 200.
 243
 244 See @ref{BGP Configuration Examples} for examples of more sophisticated
 245 useage of route-maps, including of the @samp{call} action.