doc/user/routemap.rst

   1 .. _route-map:
   2
   3 **********
   4 Route Maps
   5 **********
   6
   7 Route maps provide a means to both filter and/or apply actions to route, hence
   8 allowing policy to be applied to routes.
   9
  10 For a route reflector to apply a ``route-map`` to reflected routes, be sure to
  11 include ``bgp route-reflector allow-outbound-policy`` in ``router bgp`` mode.
  12
  13 Route maps are an ordered list of route map entries. Each entry may specify up
  14 to four distinct sets of clauses:
  15
  16 .. glossary::
  17
  18    Matching Conditions
  19       A route-map entry may, optionally, specify one or more conditions which
  20       must be matched if the entry is to be considered further, as governed by
  21       the Match Policy. If a route-map entry does not explicitly specify any
  22       matching conditions, then it always matches.
  23
  24    Set Actions
  25       A route-map entry may, optionally, specify one or more Set Actions to set
  26       or modify attributes of the route.
  27
  28    Matching Policy
  29       This specifies the policy implied if the :term:`Matching Conditions` are
  30       met or not met, and which actions of the route-map are to be taken, if
  31       any. The two possibilities are:
  32
  33       - :dfn:`permit`: If the entry matches, then carry out the
  34         :term:`Set Actions`. Then finish processing the route-map, permitting
  35         the route, unless an :term:`Exit Policy` action indicates otherwise.
  36
  37       - :dfn:`deny`: If the entry matches, then finish processing the route-map and
  38         deny the route (return `deny`).
  39
  40       The `Matching Policy` is specified as part of the command which defines
  41       the ordered entry in the route-map. See below.
  42
  43    Call Action
  44       Call to another route-map, after any :term:`Set Actions` have been
  45       carried out.  If the route-map called returns `deny` then processing of
  46       the route-map finishes and the route is denied, regardless of the
  47       :term:`Matching Policy` or the :term:`Exit Policy`. If the called
  48       route-map returns `permit`, then :term:`Matching Policy` and :term:`Exit
  49       Policy` govern further behaviour, as normal.
  50
  51    Exit Policy
  52       An entry may, optionally, specify an alternative :dfn:`Exit Policy` to
  53       take if the entry matched, rather than the normal policy of exiting the
  54       route-map and permitting the route. The two possibilities are:
  55
  56       - :dfn:`next`: Continue on with processing of the route-map entries.
  57
  58       - :dfn:`goto N`: Jump ahead to the first route-map entry whose order in
  59         the route-map is >= N. Jumping to a previous entry is not permitted.
  60
  61 The default action of a route-map, if no entries match, is to deny.  I.e. a
  62 route-map essentially has as its last entry an empty *deny* entry, which
  63 matches all routes. To change this behaviour, one must specify an empty
  64 *permit* entry as the last entry in the route-map.
  65
  66 To summarise the above:
  67
  68 +--------+--------+----------+
  69 |        | Match  | No Match |
  70 +========+========+==========+
  71 | Permit | action | cont     |
  72 +--------+--------+----------+
  73 | Deny   | deny   | cont     |
  74 +--------+--------+----------+
  75
  76 action
  77    - Apply *set* statements
  78    - If *call* is present, call given route-map. If that returns a ``deny``,
  79      finish processing and return ``deny``.
  80    - If *Exit Policy* is *next*, goto next route-map entry
  81    - If *Exit Policy* is *goto*, goto first entry whose order in the
  82      list is >= the given order.
  83    - Finish processing the route-map and permit the route.
  84
  85 deny
  86    The route is denied by the route-map (return ``deny``).
  87
  88 cont
  89    goto next route-map entry
  90
  91 .. _route-map-show-command:
  92
  93 .. index:: show route-map [WORD]
  94 .. clicmd:: show route-map [WORD]
  95
  96    Display data about each daemons knowledge of individual route-maps.
  97    If WORD is supplied narrow choice to that particular route-map.
  98
  99 .. _route-map-clear-counter-command:
 100
 101 .. index:: clear route-map counter [WORD]
 102 .. clicmd:: clear route-map counter [WORD]
 103
 104    Clear counters that are being stored about the route-map utilization
 105    so that subsuquent show commands will indicate since the last clear.
 106    If WORD is specified clear just that particular route-map's counters.
 107
 108 .. _route-map-command:
 109
 110 Route Map Command
 111 =================
 112
 113 .. index:: route-map ROUTE-MAP-NAME (permit|deny) ORDER
 114 .. clicmd:: route-map ROUTE-MAP-NAME (permit|deny) ORDER
 115
 116    Configure the `order`'th entry in `route-map-name` with ``Match Policy`` of
 117    either *permit* or *deny*.
 118
 119 .. _route-map-match-command:
 120
 121 Route Map Match Command
 122 =======================
 123
 124 .. index:: match ip address ACCESS_LIST
 125 .. clicmd:: match ip address ACCESS_LIST
 126
 127    Matches the specified `access_list`
 128
 129 .. index:: match ip address prefix-list PREFIX_LIST
 130 .. clicmd:: match ip address prefix-list PREFIX_LIST
 131
 132    Matches the specified `PREFIX_LIST`
 133
 134 .. index:: match ip address prefix-len 0-32
 135 .. clicmd:: match ip address prefix-len 0-32
 136
 137    Matches the specified `prefix-len`. This is a Zebra specific command.
 138
 139 .. index:: match ipv6 address ACCESS_LIST
 140 .. clicmd:: match ipv6 address ACCESS_LIST
 141
 142    Matches the specified `access_list`
 143
 144 .. index:: match ipv6 address prefix-list PREFIX_LIST
 145 .. clicmd:: match ipv6 address prefix-list PREFIX_LIST
 146
 147    Matches the specified `PREFIX_LIST`
 148
 149 .. index:: match ipv6 address prefix-len 0-128
 150 .. clicmd:: match ipv6 address prefix-len 0-128
 151
 152    Matches the specified `prefix-len`. This is a Zebra specific command.
 153
 154 .. index:: match ip next-hop address IPV4_ADDR
 155 .. clicmd:: match ip next-hop address IPV4_ADDR
 156
 157    This is a BGP specific match command. Matches the specified `ipv4_addr`.
 158
 159 .. index:: match ipv6 next-hop IPV6_ADDR
 160 .. clicmd:: match ipv6 next-hop IPV6_ADDR
 161
 162    This is a BGP specific match command. Matches the specified `ipv6_addr`.
 163
 164 .. index:: match as-path AS_PATH
 165 .. clicmd:: match as-path AS_PATH
 166
 167    Matches the specified `as_path`.
 168
 169 .. index:: match metric METRIC
 170 .. clicmd:: match metric METRIC
 171
 172    Matches the specified `metric`.
 173
 174 .. index:: match tag TAG
 175 .. clicmd:: match tag TAG
 176
 177    Matches the specified tag value associated with the route. This tag value
 178    can be in the range of (1-4294967295).
 179
 180 .. index:: match local-preference METRIC
 181 .. clicmd:: match local-preference METRIC
 182
 183    Matches the specified `local-preference`.
 184
 185 .. index:: match community COMMUNITY_LIST
 186 .. clicmd:: match community COMMUNITY_LIST
 187
 188    Matches the specified  `community_list`
 189
 190 .. index:: match peer IPV4_ADDR
 191 .. clicmd:: match peer IPV4_ADDR
 192
 193    This is a BGP specific match command. Matches the peer ip address
 194    if the neighbor was specified in this manner.
 195
 196 .. index:: match peer IPV6_ADDR
 197 .. clicmd:: match peer IPV6_ADDR
 198
 199    This is a BGP specific match command. Matches the peer ipv6
 200    address if the neighbor was specified in this manner.
 201
 202 .. index:: match peer INTERFACE_NAME
 203 .. clicmd:: match peer INTERFACE_NAME
 204
 205   This is a BGP specific match command. Matches the peer
 206   interface name specified if the neighbor was specified
 207   in this manner.
 208
 209 .. index:: match source-protocol PROTOCOL_NAME
 210 .. clicmd:: match source-protocol PROTOCOL_NAME
 211
 212   This is a ZEBRA specific match command.  Matches the
 213   originating protocol specified.
 214
 215 .. index:: match source-instance NUMBER
 216 .. clicmd:: match source-instance NUMBER
 217
 218   This is a ZEBRA specific match command.  The number is a range from (0-255).
 219   Matches the originating protocols instance specified.
 220
 221 .. _route-map-set-command:
 222
 223 Route Map Set Command
 224 =====================
 225
 226 .. program:: configure
 227
 228 .. index:: set tag TAG
 229 .. clicmd:: set tag TAG
 230
 231    Set a tag on the matched route. This tag value can be from (1-4294967295).
 232    Additionally if you have compiled with the :option:`--enable-realms`
 233    configure option. Tag values from (1-255) are sent to the Linux kernel as a
 234    realm value. Then route policy can be applied. See the tc man page.
 235
 236 .. index:: set ip next-hop IPV4_ADDRESS
 237 .. clicmd:: set ip next-hop IPV4_ADDRESS
 238
 239    Set the BGP nexthop address to the specified IPV4_ADDRESS.  For both
 240    incoming and outgoing route-maps.
 241
 242 .. index:: set ip next-hop peer-address
 243 .. clicmd:: set ip next-hop peer-address
 244
 245    Set the BGP nexthop address to the address of the peer.  For an incoming
 246    route-map this means the ip address of our peer is used.  For an outgoing
 247    route-map this means the ip address of our self is used to establish the
 248    peering with our neighbor.
 249
 250 .. index:: set ip next-hop unchanged
 251 .. clicmd:: set ip next-hop unchanged
 252
 253    Set the route-map as unchanged.  Pass the route-map through without
 254    changing it's value.
 255
 256 .. index:: set ipv6 next-hop peer-address
 257 .. clicmd:: set ipv6 next-hop peer-address
 258
 259    Set the BGP nexthop address to the address of the peer.  For an incoming
 260    route-map this means the ipv6 address of our peer is used.  For an outgoing
 261    route-map this means the ip address of our self is used to establish the
 262    peering with our neighbor.
 263
 264 .. index:: set ipv6 next-hop prefer-global
 265 .. clicmd:: set ipv6 next-hop prefer-global
 266
 267    For Incoming and Import Route-maps if we receive a v6 global and v6 LL
 268    address for the route, then prefer to use the global address as the nexthop.
 269
 270 .. index:: set ipv6 next-hop global IPV6_ADDRESS
 271 .. clicmd:: set ipv6 next-hop global IPV6_ADDRESS
 272
 273    Set the next-hop to the specified IPV6_ADDRESS for both incoming and
 274    outgoing route-maps.
 275
 276 .. index:: set local-preference LOCAL_PREF
 277 .. clicmd:: set local-preference LOCAL_PREF
 278
 279    Set the BGP local preference to `local_pref`.
 280
 281 .. index:: set local-preference +LOCAL_PREF
 282 .. clicmd:: set local-preference +LOCAL_PREF
 283
 284    Add the BGP local preference to an existing `local_pref`.
 285
 286 .. index:: set local-preference -LOCAL_PREF
 287 .. clicmd:: set local-preference -LOCAL_PREF
 288
 289    Subtract the BGP local preference from an existing `local_pref`.
 290
 291 .. index:: [no] set distance DISTANCE
 292 .. clicmd:: [no] set distance DISTANCE
 293
 294    Set the Administrative distance to DISTANCE to use for the route.
 295    This is only locally significant and will not be dispersed to peers.
 296
 297 .. index:: set weight WEIGHT
 298 .. clicmd:: set weight WEIGHT
 299
 300    Set the route's weight.
 301
 302 .. index:: set metric METRIC
 303 .. clicmd:: set metric METRIC
 304
 305    Set the BGP attribute MED.
 306
 307 .. index:: set as-path prepend AS_PATH
 308 .. clicmd:: set as-path prepend AS_PATH
 309
 310    Set the BGP AS path to prepend.
 311
 312 .. index:: set community COMMUNITY
 313 .. clicmd:: set community COMMUNITY
 314
 315    Set the BGP community attribute.
 316
 317 .. index:: set ipv6 next-hop local IPV6_ADDRESS
 318 .. clicmd:: set ipv6 next-hop local IPV6_ADDRESS
 319
 320    Set the BGP-4+ link local IPv6 nexthop address.
 321
 322 .. index:: set origin ORIGIN <egp|igp|incomplete>
 323 .. clicmd:: set origin ORIGIN <egp|igp|incomplete>
 324
 325    Set BGP route origin.
 326
 327 .. index:: set table (1-4294967295)
 328 .. clicmd:: set table (1-4294967295)
 329
 330    Set the BGP table to a given table identifier
 331
 332 .. _route-map-call-command:
 333
 334 Route Map Call Command
 335 ======================
 336
 337 .. index:: call NAME
 338 .. clicmd:: call NAME
 339
 340    Call route-map `name`. If it returns deny, deny the route and
 341    finish processing the route-map.
 342
 343 .. _route-map-exit-action-command:
 344
 345 Route Map Exit Action Command
 346 =============================
 347
 348 .. index:: on-match next
 349 .. clicmd:: on-match next
 350
 351 .. index:: continue
 352 .. clicmd:: continue
 353
 354    Proceed on to the next entry in the route-map.
 355
 356 .. index:: on-match goto N
 357 .. clicmd:: on-match goto N
 358
 359 .. index:: continue N
 360 .. clicmd:: continue N
 361
 362    Proceed processing the route-map at the first entry whose order is >= N
 363
 364 .. _route-map-optimization-command:
 365
 366 Route Map Optimization Command
 367 ==============================
 368
 369 .. index:: route-map optimization
 370 .. clicmd:: route-map optimization
 371
 372    Enable route-map processing optimization. The optimization is
 373    enabled by default.
 374    Instead of sequentially passing through all the route-map indexes
 375    until a match is found, the search for the best-match index will be
 376    based on a look-up in a prefix-tree. A per-route-map prefix-tree
 377    will be constructed for this purpose. The prefix-tree will compose
 378    of all the prefixes in all the prefix-lists that are included in the
 379    match rule of all the sequences of a route-map.
 380
 381 .. index:: no route-map optimization
 382 .. clicmd:: no route-map optimization
 383
 384    Disable the route-map processing optimization.
 385
 386 Route Map Examples
 387 ==================
 388
 389 A simple example of a route-map:
 390
 391 .. code-block:: frr
 392
 393    route-map test permit 10
 394     match ip address 10
 395     set local-preference 200
 396
 397
 398 This means that if a route matches ip access-list number 10 it's
 399 local-preference value is set to 200.
 400
 401 See :ref:`bgp-configuration-examples` for examples of more sophisticated
 402 usage of route-maps, including of the ``call`` action.
 403