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:: [no] set metric <[+|-](1-4294967295)|rtt|+rtt|-rtt>
 303 .. clicmd:: [no] set metric <[+|-](1-4294967295)|rtt|+rtt|-rtt>
 304
 305    Set the BGP attribute MED to a specific value. Use `+`/`-` to add or subtract
 306    the specified value to/from the MED. Use `rtt` to set the MED to the round
 307    trip time or `+rtt`/`-rtt` to add/subtract the round trip time to/from the
 308    MED.
 309
 310 .. index:: set as-path prepend AS_PATH
 311 .. clicmd:: set as-path prepend AS_PATH
 312
 313    Set the BGP AS path to prepend.
 314
 315 .. index:: set community COMMUNITY
 316 .. clicmd:: set community COMMUNITY
 317
 318    Set the BGP community attribute.
 319
 320 .. index:: set ipv6 next-hop local IPV6_ADDRESS
 321 .. clicmd:: set ipv6 next-hop local IPV6_ADDRESS
 322
 323    Set the BGP-4+ link local IPv6 nexthop address.
 324
 325 .. index:: set origin ORIGIN <egp|igp|incomplete>
 326 .. clicmd:: set origin ORIGIN <egp|igp|incomplete>
 327
 328    Set BGP route origin.
 329
 330 .. index:: set table (1-4294967295)
 331 .. clicmd:: set table (1-4294967295)
 332
 333    Set the BGP table to a given table identifier
 334
 335 .. index:: set sr-te color (1-4294967295)
 336 .. clicmd:: set sr-te color (1-4294967295)
 337
 338    Set the color of a SR-TE Policy to be applied to a learned route. The SR-TE
 339    Policy is uniquely determined by the color and the BGP nexthop.
 340
 341 .. _route-map-call-command:
 342
 343 Route Map Call Command
 344 ======================
 345
 346 .. index:: call NAME
 347 .. clicmd:: call NAME
 348
 349    Call route-map `name`. If it returns deny, deny the route and
 350    finish processing the route-map.
 351
 352 .. _route-map-exit-action-command:
 353
 354 Route Map Exit Action Command
 355 =============================
 356
 357 .. index:: on-match next
 358 .. clicmd:: on-match next
 359
 360 .. index:: continue
 361 .. clicmd:: continue
 362
 363    Proceed on to the next entry in the route-map.
 364
 365 .. index:: on-match goto N
 366 .. clicmd:: on-match goto N
 367
 368 .. index:: continue N
 369 .. clicmd:: continue N
 370
 371    Proceed processing the route-map at the first entry whose order is >= N
 372
 373 .. _route-map-optimization-command:
 374
 375 Route Map Optimization Command
 376 ==============================
 377
 378 .. index:: route-map optimization
 379 .. clicmd:: route-map optimization
 380
 381    Enable route-map processing optimization. The optimization is
 382    enabled by default.
 383    Instead of sequentially passing through all the route-map indexes
 384    until a match is found, the search for the best-match index will be
 385    based on a look-up in a prefix-tree. A per-route-map prefix-tree
 386    will be constructed for this purpose. The prefix-tree will compose
 387    of all the prefixes in all the prefix-lists that are included in the
 388    match rule of all the sequences of a route-map.
 389
 390 .. index:: no route-map optimization
 391 .. clicmd:: no route-map optimization
 392
 393    Disable the route-map processing optimization.
 394
 395 Route Map Examples
 396 ==================
 397
 398 A simple example of a route-map:
 399
 400 .. code-block:: frr
 401
 402    route-map test permit 10
 403     match ip address 10
 404     set local-preference 200
 405
 406
 407 This means that if a route matches ip access-list number 10 it's
 408 local-preference value is set to 200.
 409
 410 See :ref:`bgp-configuration-examples` for examples of more sophisticated
 411 usage of route-maps, including of the ``call`` action.
 412