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 distincts 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 explicitely 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
 109 .. clicmd:: match ip address 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
 124 .. clicmd:: match ipv6 address 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 .. _route-map-set-command:
 184
 185 Route Map Set Command
 186 =====================
 187
 188 .. program:: configure
 189
 190 .. index:: set tag TAG
 191 .. clicmd:: set tag TAG
 192
 193    Set a tag on the matched route. This tag value can be from (1-4294967295).
 194    Additionally if you have compiled with the :option:`--enable-realms`
 195    configure option. Tag values from (1-255) are sent to the Linux kernel as a
 196    realm value. Then route policy can be applied. See the tc man page.
 197
 198 .. index:: set ip next-hop IPV4_ADDRESS
 199 .. clicmd:: set ip next-hop IPV4_ADDRESS
 200
 201    Set the BGP nexthop address.
 202
 203 .. index:: set local-preference LOCAL_PREF
 204 .. clicmd:: set local-preference LOCAL_PREF
 205
 206    Set the BGP local preference to `local_pref`.
 207
 208 .. index:: set weight WEIGHT
 209 .. clicmd:: set weight WEIGHT
 210
 211    Set the route's weight.
 212
 213 .. index:: set metric METRIC
 214 .. clicmd:: set metric METRIC
 215
 216    Set the BGP attribute MED.
 217
 218 .. index:: set as-path prepend AS_PATH
 219 .. clicmd:: set as-path prepend AS_PATH
 220
 221    Set the BGP AS path to prepend.
 222
 223 .. index:: set community COMMUNITY
 224 .. clicmd:: set community COMMUNITY
 225
 226    Set the BGP community attribute.
 227
 228 .. index:: set ipv6 next-hop global IPV6_ADDRESS
 229 .. clicmd:: set ipv6 next-hop global IPV6_ADDRESS
 230
 231    Set the BGP-4+ global IPv6 nexthop address.
 232
 233 .. index:: set ipv6 next-hop local IPV6_ADDRESS
 234 .. clicmd:: set ipv6 next-hop local IPV6_ADDRESS
 235
 236    Set the BGP-4+ link local IPv6 nexthop address.
 237
 238 .. _route-map-call-command:
 239
 240 Route Map Call Command
 241 ======================
 242
 243 .. index:: call NAME
 244 .. clicmd:: call NAME
 245
 246    Call route-map `name`. If it returns deny, deny the route and
 247    finish processing the route-map.
 248
 249 .. _route-map-exit-action-command:
 250
 251 Route Map Exit Action Command
 252 =============================
 253
 254 .. index:: on-match next
 255 .. clicmd:: on-match next
 256
 257 .. index:: continue
 258 .. clicmd:: continue
 259
 260    Proceed on to the next entry in the route-map.
 261
 262 .. index:: on-match goto N
 263 .. clicmd:: on-match goto N
 264
 265 .. index:: continue N
 266 .. clicmd:: continue N
 267
 268    Proceed processing the route-map at the first entry whose order is >= N
 269
 270 Route Map Examples
 271 ==================
 272
 273 A simple example of a route-map:
 274
 275 ::
 276
 277   route-map test permit 10
 278    match ip address 10
 279    set local-preference 200
 280
 281
 282 This means that if a route matches ip access-list number 10 it's
 283 local-preference value is set to 200.
 284
 285 See :ref:`bgp-configuration-examples` for examples of more sophisticated
 286 useage of route-maps, including of the ``call`` action.
 287