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 Route maps are an ordered list of route map entries. Each entry may specify up
  11 to four distinct sets of clauses:
  12
  13 .. glossary::
  14
  15    Matching Conditions
  16       A route-map entry may, optionally, specify one or more conditions which
  17       must be matched if the entry is to be considered further, as governed by
  18       the Match Policy. If a route-map entry does not explicitly specify any
  19       matching conditions, then it always matches.
  20
  21    Set Actions
  22       A route-map entry may, optionally, specify one or more Set Actions to set
  23       or modify attributes of the route.
  24
  25    Matching Policy
  26       This specifies the policy implied if the :term:`Matching Conditions` are
  27       met or not met, and which actions of the route-map are to be taken, if
  28       any. The two possibilities are:
  29
  30       - :dfn:`permit`: If the entry matches, then carry out the
  31         :term:`Set Actions`. Then finish processing the route-map, permitting
  32         the route, unless an :term:`Exit Policy` action indicates otherwise.
  33
  34       - :dfn:`deny`: If the entry matches, then finish processing the route-map and
  35         deny the route (return `deny`).
  36
  37       The `Matching Policy` is specified as part of the command which defines
  38       the ordered entry in the route-map. See below.
  39
  40    Call Action
  41       Call to another route-map, after any :term:`Set Actions` have been carried out.
  42       If the route-map called returns `deny` then processing of the route-map
  43       finishes and the route is denied, regardless of the :term:Matching Policy` or
  44       the :term:`Exit Policy`. If the called route-map returns `permit`, then
  45       :term:`Matching Policy` and :term:`Exit Policy` govern further behaviour, as normal.
  46
  47    Exit Policy
  48       An entry may, optionally, specify an alternative :dfn:`Exit Policy` to
  49       take if the entry matched, rather than the normal policy of exiting the
  50       route-map and permitting the route. The two possibilities are:
  51
  52       - :dfn:`next`: Continue on with processing of the route-map entries.
  53
  54       - :dfn:`goto N`: Jump ahead to the first route-map entry whose order in
  55         the route-map is >= N. Jumping to a previous entry is not permitted.
  56
  57 The default action of a route-map, if no entries match, is to deny.  I.e. a
  58 route-map essentially has as its last entry an empty *deny* entry, which
  59 matches all routes. To change this behaviour, one must specify an empty
  60 *permit* entry as the last entry in the route-map.
  61
  62 To summarise the above:
  63
  64 +--------+--------+----------+
  65 |        | Match  | No Match |
  66 +========+========+==========+
  67 | Permit | action | cont     |
  68 +--------+--------+----------+
  69 | Deny   | deny   | cont     |
  70 +--------+--------+----------+
  71
  72 action
  73    - Apply *set* statements
  74    - If *call* is present, call given route-map. If that returns a ``deny``,
  75      finish processing and return ``deny``.
  76    - If *Exit Policy* is *next*, goto next route-map entry
  77    - If *Exit Policy* is *goto*, goto first entry whose order in the
  78      list is >= the given order.
  79    - Finish processing the route-map and permit the route.
  80
  81 deny
  82    The route is denied by the route-map (return ``deny``).
  83
  84 cont
  85    goto next route-map entry
  86
  87 .. _route-map-command:
  88
  89 Route Map Command
  90 =================
  91
  92 .. index:: route-map ROUTE-MAP-NAME (permit|deny) ORDER
  93 .. clicmd:: route-map ROUTE-MAP-NAME (permit|deny) ORDER
  94
  95    Configure the `order`'th entry in `route-map-name` with ``Match Policy`` of
  96    either *permit* or *deny*.
  97
  98 .. _route-map-match-command:
  99
 100 Route Map Match Command
 101 =======================
 102
 103 .. index:: match ip address ACCESS_LIST
 104 .. clicmd:: match ip address ACCESS_LIST
 105
 106    Matches the specified `access_list`
 107
 108 .. index:: match ip address prefix-list PREFIX_LIST
 109 .. clicmd:: match ip address prefix-list PREFIX_LIST
 110
 111    Matches the specified `PREFIX_LIST`
 112
 113 .. index:: match ip address prefix-len 0-32
 114 .. clicmd:: match ip address prefix-len 0-32
 115
 116    Matches the specified `prefix-len`. This is a Zebra specific command.
 117
 118 .. index:: match ipv6 address ACCESS_LIST
 119 .. clicmd:: match ipv6 address ACCESS_LIST
 120
 121    Matches the specified `access_list`
 122
 123 .. index:: match ipv6 address prefix-list PREFIX_LIST
 124 .. clicmd:: match ipv6 address prefix-list PREFIX_LIST
 125
 126    Matches the specified `PREFIX_LIST`
 127
 128 .. index:: match ipv6 address prefix-len 0-128
 129 .. clicmd:: match ipv6 address prefix-len 0-128
 130
 131    Matches the specified `prefix-len`. This is a Zebra specific command.
 132
 133 .. index:: match ip next-hop IPV4_ADDR
 134 .. clicmd:: match ip next-hop IPV4_ADDR
 135
 136    Matches the specified `ipv4_addr`.
 137
 138 .. index:: match aspath AS_PATH
 139 .. clicmd:: match aspath AS_PATH
 140
 141    Matches the specified `as_path`.
 142
 143 .. index:: match metric METRIC
 144 .. clicmd:: match metric METRIC
 145
 146    Matches the specified `metric`.
 147
 148 .. index:: match tag TAG
 149 .. clicmd:: match tag TAG
 150
 151    Matches the specified tag value associated with the route. This tag value
 152    can be in the range of (1-4294967295).
 153
 154 .. index:: match local-preference METRIC
 155 .. clicmd:: match local-preference METRIC
 156
 157    Matches the specified `local-preference`.
 158
 159 .. index:: match community COMMUNITY_LIST
 160 .. clicmd:: match community COMMUNITY_LIST
 161
 162    Matches the specified  `community_list`
 163
 164 .. index:: match peer IPV4_ADDR
 165 .. clicmd:: match peer IPV4_ADDR
 166
 167    This is a BGP specific match command. Matches the peer ip address
 168    if the neighbor was specified in this manner.
 169
 170 .. index:: match peer IPV6_ADDR
 171 .. clicmd:: match peer IPV6_ADDR
 172
 173    This is a BGP specific match command. Matches the peer ipv6
 174    address if the neighbor was specified in this manner.
 175
 176 .. index:: match peer INTERFACE_NAME
 177 .. clicmd:: match peer INTERFACE_NAME
 178
 179   This is a BGP specific match command. Matches the peer
 180   interface name specified if the neighbor was specified
 181   in this manner.
 182
 183 .. index:: match source-protocol PROTOCOL_NAME
 184 .. clicmd:: match source-protocol PROTOCOL_NAME
 185
 186   This is a ZEBRA specific match command.  Matches the
 187   originating protocol specified.
 188
 189 .. index:: match source-instance NUMBER
 190 .. clicmd:: match source-instance NUMBER
 191
 192   This is a ZEBRA specific match command.  The number is a range from (0-255).
 193   Matches the originating protocols instance specified.
 194
 195 .. _route-map-set-command:
 196
 197 Route Map Set Command
 198 =====================
 199
 200 .. program:: configure
 201
 202 .. index:: set tag TAG
 203 .. clicmd:: set tag TAG
 204
 205    Set a tag on the matched route. This tag value can be from (1-4294967295).
 206    Additionally if you have compiled with the :option:`--enable-realms`
 207    configure option. Tag values from (1-255) are sent to the Linux kernel as a
 208    realm value. Then route policy can be applied. See the tc man page.
 209
 210 .. index:: set ip next-hop IPV4_ADDRESS
 211 .. clicmd:: set ip next-hop IPV4_ADDRESS
 212
 213    Set the BGP nexthop address to the specified IPV4_ADDRESS.  For both
 214    incoming and outgoing route-maps.
 215
 216 .. index:: set ip next-hop peer-address
 217 .. clicmd:: set ip next-hop peer-address
 218
 219    Set the BGP nexthop address to the address of the peer.  For an incoming
 220    route-map this means the ip address of our peer is used.  For an outgoing
 221    route-map this means the ip address of our self is used to establish the
 222    peering with our neighbor.
 223
 224 .. index:: set ip next-hop unchanged
 225 .. clicmd:: set ip next-hop unchanged
 226
 227    Set the route-map as unchanged.  Pass the route-map through without
 228    changing it's value.
 229
 230 .. index:: set ipv6 next-hop peer-address
 231 .. clicmd:: set ipv6 next-hop peer-address
 232
 233    Set the BGP nexthop address to the address of the peer.  For an incoming
 234    route-map this means the ipv6 address of our peer is used.  For an outgoing
 235    route-map this means the ip address of our self is used to establish the
 236    peering with our neighbor.
 237
 238 .. index:: set ipv6 next-hop prefer-global
 239 .. clicmd:: set ipv6 next-hop prefer-global
 240
 241    For Incoming and Import Route-maps if we receive a v6 global and v6 LL
 242    address for the route, then prefer to use the global address as the nexthop.
 243
 244 .. index:: set ipv6 next-hop global IPV6_ADDRESS
 245 .. clicmd:: set ipv6 next-hop global IPV6_ADDRESS
 246
 247    Set the next-hop to the specified IPV6_ADDRESS for both incoming and
 248    outgoing route-maps.
 249
 250 .. index:: set local-preference LOCAL_PREF
 251 .. clicmd:: set local-preference LOCAL_PREF
 252
 253    Set the BGP local preference to `local_pref`.
 254
 255 .. index:: set weight WEIGHT
 256 .. clicmd:: set weight WEIGHT
 257
 258    Set the route's weight.
 259
 260 .. index:: set metric METRIC
 261 .. clicmd:: set metric METRIC
 262
 263    Set the BGP attribute MED.
 264
 265 .. index:: set as-path prepend AS_PATH
 266 .. clicmd:: set as-path prepend AS_PATH
 267
 268    Set the BGP AS path to prepend.
 269
 270 .. index:: set community COMMUNITY
 271 .. clicmd:: set community COMMUNITY
 272
 273    Set the BGP community attribute.
 274
 275 .. index:: set ipv6 next-hop local IPV6_ADDRESS
 276 .. clicmd:: set ipv6 next-hop local IPV6_ADDRESS
 277
 278    Set the BGP-4+ link local IPv6 nexthop address.
 279
 280 .. index:: set origin ORIGIN <egp|igp|incomplete>
 281 .. clicmd:: set origin ORIGIN <egp|igp|incomplete>
 282
 283    Set BGP route origin.
 284
 285 .. _route-map-call-command:
 286
 287 Route Map Call Command
 288 ======================
 289
 290 .. index:: call NAME
 291 .. clicmd:: call NAME
 292
 293    Call route-map `name`. If it returns deny, deny the route and
 294    finish processing the route-map.
 295
 296 .. _route-map-exit-action-command:
 297
 298 Route Map Exit Action Command
 299 =============================
 300
 301 .. index:: on-match next
 302 .. clicmd:: on-match next
 303
 304 .. index:: continue
 305 .. clicmd:: continue
 306
 307    Proceed on to the next entry in the route-map.
 308
 309 .. index:: on-match goto N
 310 .. clicmd:: on-match goto N
 311
 312 .. index:: continue N
 313 .. clicmd:: continue N
 314
 315    Proceed processing the route-map at the first entry whose order is >= N
 316
 317 Route Map Examples
 318 ==================
 319
 320 A simple example of a route-map:
 321
 322 .. code-block:: frr
 323
 324    route-map test permit 10
 325     match ip address 10
 326     set local-preference 200
 327
 328
 329 This means that if a route matches ip access-list number 10 it's
 330 local-preference value is set to 200.
 331
 332 See :ref:`bgp-configuration-examples` for examples of more sophisticated
 333 usage of route-maps, including of the ``call`` action.
 334