summaryrefslogtreecommitdiffstats
path: root/doc/user/routemap.rst
blob: 791762aa7b88742a21306b8f270a26479fe41b66 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
.. _route-map:

**********
Route Maps
**********

Route maps provide a means to both filter and/or apply actions to route, hence
allowing policy to be applied to routes.

For a route reflector to apply a ``route-map`` to reflected routes, be sure to
include ``bgp route-reflector allow-outbound-policy`` in ``router bgp`` mode.

Route maps are an ordered list of route map entries. Each entry may specify up
to four distinct sets of clauses:

.. glossary::

   Matching Conditions
      A route-map entry may, optionally, specify one or more conditions which
      must be matched if the entry is to be considered further, as governed by
      the Match Policy. If a route-map entry does not explicitly specify any
      matching conditions, then it always matches.

   Set Actions
      A route-map entry may, optionally, specify one or more Set Actions to set
      or modify attributes of the route.

   Matching Policy
      This specifies the policy implied if the :term:`Matching Conditions` are
      met or not met, and which actions of the route-map are to be taken, if
      any. The two possibilities are:

      - :dfn:`permit`: If the entry matches, then carry out the
        :term:`Set Actions`. Then finish processing the route-map, permitting
        the route, unless an :term:`Exit Policy` action indicates otherwise.

      - :dfn:`deny`: If the entry matches, then finish processing the route-map and
        deny the route (return `deny`).

      The `Matching Policy` is specified as part of the command which defines
      the ordered entry in the route-map. See below.

   Call Action
      Call to another route-map, after any :term:`Set Actions` have been
      carried out.  If the route-map called returns `deny` then processing of
      the route-map finishes and the route is denied, regardless of the
      :term:`Matching Policy` or the :term:`Exit Policy`. If the called
      route-map returns `permit`, then :term:`Matching Policy` and :term:`Exit
      Policy` govern further behaviour, as normal.

   Exit Policy
      An entry may, optionally, specify an alternative :dfn:`Exit Policy` to
      take if the entry matched, rather than the normal policy of exiting the
      route-map and permitting the route. The two possibilities are:

      - :dfn:`next`: Continue on with processing of the route-map entries.

      - :dfn:`goto N`: Jump ahead to the first route-map entry whose order in
        the route-map is >= N. Jumping to a previous entry is not permitted.

The default action of a route-map, if no entries match, is to deny.  I.e. a
route-map essentially has as its last entry an empty *deny* entry, which
matches all routes. To change this behaviour, one must specify an empty
*permit* entry as the last entry in the route-map.

To summarise the above:

+--------+--------+----------+
|        | Match  | No Match |
+========+========+==========+
| Permit | action | cont     |
+--------+--------+----------+
| Deny   | deny   | cont     |
+--------+--------+----------+

action
   - Apply *set* statements
   - If *call* is present, call given route-map. If that returns a ``deny``,
     finish processing and return ``deny``.
   - If *Exit Policy* is *next*, goto next route-map entry
   - If *Exit Policy* is *goto*, goto first entry whose order in the
     list is >= the given order.
   - Finish processing the route-map and permit the route.

deny
   The route is denied by the route-map (return ``deny``).

cont
   goto next route-map entry

.. _route-map-show-command:

.. clicmd:: show route-map [WORD] [json]

   Display data about each daemons knowledge of individual route-maps.
   If WORD is supplied narrow choice to that particular route-map.

   If the ``json`` option is specified, output is displayed in JSON format.

.. _route-map-clear-counter-command:

.. clicmd:: clear route-map counter [WORD]

   Clear counters that are being stored about the route-map utilization
   so that subsuquent show commands will indicate since the last clear.
   If WORD is specified clear just that particular route-map's counters.

.. _route-map-command:

Route Map Command
=================

.. clicmd:: route-map ROUTE-MAP-NAME (permit|deny) ORDER

   Configure the `order`'th entry in `route-map-name` with ``Match Policy`` of
   either *permit* or *deny*.

.. _route-map-match-command:

Route Map Match Command
=======================

.. clicmd:: match ip address ACCESS_LIST

   Matches the specified `access_list`

.. clicmd:: match ip address prefix-list PREFIX_LIST

   Matches the specified `PREFIX_LIST`

.. clicmd:: match ip address prefix-len 0-32

   Matches the specified `prefix-len`. This is a Zebra specific command.

.. clicmd:: match ipv6 address ACCESS_LIST

   Matches the specified `access_list`

.. clicmd:: match ipv6 address prefix-list PREFIX_LIST

   Matches the specified `PREFIX_LIST`

.. clicmd:: match ipv6 address prefix-len 0-128

   Matches the specified `prefix-len`. This is a Zebra specific command.

.. clicmd:: match ip next-hop ACCESS_LIST

   Match the next-hop according to the given access-list.

.. clicmd:: match ip next-hop address IPV4_ADDR

   This is a BGP specific match command. Matches the specified `ipv4_addr`.

.. clicmd:: match ip next-hop prefix-list PREFIX_LIST

   Match the next-hop according to the given prefix-list.

.. clicmd:: match ipv6 next-hop ACCESS_LIST

   Match the next-hop according to the given access-list.

.. clicmd:: match ipv6 next-hop address IPV6_ADDR

   This is a BGP specific match command. Matches the specified `ipv6_addr`.

.. clicmd:: match ipv6 next-hop prefix-list PREFIX_LIST

   Match the next-hop according to the given prefix-list.

.. clicmd:: match as-path AS_PATH

   Matches the specified `as_path`.

.. clicmd:: match metric METRIC

   Matches the specified `metric`.

.. clicmd:: match tag TAG

   Matches the specified tag value associated with the route. This tag value
   can be in the range of (1-4294967295).

.. clicmd:: match local-preference METRIC

   Matches the specified `local-preference`.

.. clicmd:: match community COMMUNITY_LIST [<exact-match|any>]

   Matches the specified  `community_list`. ``exact-match`` specifies to
   do the exact matching of the communities, while ``any`` - can match any
   community specified in COMMUNITY_LIST.

.. clicmd:: match peer IPV4_ADDR

   This is a BGP specific match command. Matches the peer ip address
   if the neighbor was specified in this manner.

.. clicmd:: match peer IPV6_ADDR

   This is a BGP specific match command. Matches the peer ipv6
   address if the neighbor was specified in this manner.

.. clicmd:: match peer INTERFACE_NAME

  This is a BGP specific match command. Matches the peer
  interface name specified if the neighbor was specified
  in this manner.

.. clicmd:: match peer PEER_GROUP_NAME

  This is a BGP specific match command. Matches the peer
  group name specified for the peer in question.

.. clicmd:: match source-protocol PROTOCOL_NAME

  This is a ZEBRA and BGP specific match command.  Matches the
  originating protocol specified.

.. clicmd:: match source-instance NUMBER

  This is a ZEBRA specific match command.  The number is a range from (0-255).
  Matches the originating protocols instance specified.

.. clicmd:: match evpn route-type ROUTE_TYPE_NAME

  This is a BGP EVPN specific match command. It matches to EVPN route-type
  from type-1 (EAD route-type) to type-5 (Prefix route-type).
  User can provide in an integral form (1-5) or string form of route-type
  (i.e ead, macip, multicast, es, prefix).

.. clicmd:: match evpn vni NUMBER

  This is a BGP EVPN specific match command which matches to EVPN VNI id.
  The number is a range from (1-6777215).

.. _route-map-set-command:

Route Map Set Command
=====================

.. program:: configure

.. clicmd:: set tag TAG

   Set a tag on the matched route. This tag value can be from (1-4294967295).
   Additionally if you have compiled with the :option:`--enable-realms`
   configure option. Tag values from (1-255) are sent to the Linux kernel as a
   realm value. Then route policy can be applied. See the tc man page.  As
   a note realms cannot currently be used with the installation of nexthops
   as nexthop groups in the linux kernel.

.. clicmd:: set ip next-hop IPV4_ADDRESS

   Set the BGP nexthop address to the specified IPV4_ADDRESS.  For both
   incoming and outgoing route-maps.

.. clicmd:: set ip next-hop peer-address

   Set the BGP nexthop address to the address of the peer.  For an incoming
   route-map this means the ip address of our peer is used.  For an outgoing
   route-map this means the ip address of our self is used to establish the
   peering with our neighbor.

.. clicmd:: set ip next-hop unchanged

   Set the route-map as unchanged.  Pass the route-map through without
   changing it's value.

.. clicmd:: set ipv6 next-hop peer-address

   Set the BGP nexthop address to the address of the peer.  For an incoming
   route-map this means the ipv6 address of our peer is used.  For an outgoing
   route-map this means the ip address of our self is used to establish the
   peering with our neighbor.

.. clicmd:: set ipv6 next-hop prefer-global

   For Incoming and Import Route-maps if we receive a v6 global and v6 LL
   address for the route, then prefer to use the global address as the nexthop.

.. clicmd:: set ipv6 next-hop global IPV6_ADDRESS

   Set the next-hop to the specified IPV6_ADDRESS for both incoming and
   outgoing route-maps.

.. clicmd:: set local-preference LOCAL_PREF

   Set the BGP local preference to `local_pref`.

.. clicmd:: set local-preference +LOCAL_PREF

   Add the BGP local preference to an existing `local_pref`.

.. clicmd:: set local-preference -LOCAL_PREF

   Subtract the BGP local preference from an existing `local_pref`.

.. clicmd:: set distance (1-255)

   Set the Administrative distance to use for the route.
   This is only locally significant and will not be dispersed to peers.

.. clicmd:: set weight WEIGHT

   Set the route's weight.

.. clicmd:: set metric <[+|-](1-4294967295)|rtt|+rtt|-rtt>

   Set the route metric. When used with BGP, set the BGP attribute MED to a
   specific value. Use `+`/`-` to add or subtract the specified value to/from
   the existing/MED. Use `rtt` to set the MED to the round trip time or
   `+rtt`/`-rtt` to add/subtract the round trip time to/from the MED.

.. clicmd:: set min-metric <(0-4294967295)>

   Set the minimum meric for the route.

.. clicmd:: set max-metric <(0-4294967295)>

   Set the maximum meric for the route.

.. clicmd:: set aigp-metric <igp-metric|(1-4294967295)>

   Set the BGP attribute AIGP to a specific value. If ``igp-metric`` is specified,
   then the value is taken from the IGP protocol, otherwise an arbitrary value.

.. clicmd:: set as-path prepend AS_PATH

   Set the BGP AS path to prepend.

.. clicmd:: set as-path exclude AS-NUMBER...

   Drop AS-NUMBER from the BGP AS path.

.. clicmd:: set community COMMUNITY

   Set the BGP community attribute.

.. clicmd:: set extended-comm-list <EXTCOMMUNITY_LIST_NAME> delete

   Set BGP extended community list for deletion.

.. clicmd:: set ipv6 next-hop local IPV6_ADDRESS

   Set the BGP-4+ link local IPv6 nexthop address.

.. clicmd:: set origin ORIGIN <egp|igp|incomplete>

   Set BGP route origin.

.. clicmd:: set table (1-4294967295)

   Set the BGP table to a given table identifier

.. clicmd:: set sr-te color (1-4294967295)

   Set the color of a SR-TE Policy to be applied to a learned route. The SR-TE
   Policy is uniquely determined by the color and the BGP nexthop.

.. clicmd:: set l3vpn next-hop encapsulation gre

   Accept L3VPN traffic over GRE encapsulation.

.. _route-map-call-command:

Route Map Call Command
======================

.. clicmd:: call NAME

   Call route-map `name`. If it returns deny, deny the route and
   finish processing the route-map.


.. _route-map-exit-action-command:

Route Map Exit Action Command
=============================

.. clicmd:: on-match next

   Proceed on to the next entry in the route-map.

.. clicmd:: continue (1-65535)

   Proceed to the specified sequence in the route-map.

.. clicmd:: on-match goto N

   Proceed processing the route-map at the first entry whose order is >= N


.. _route-map-optimization-command:

Route Map Optimization Command
==============================

.. clicmd:: route-map ROUTE-MAP-NAME optimization

   Enable route-map processing optimization for `route-map-name`.
   The optimization is enabled by default.
   Instead of sequentially passing through all the route-map indexes
   until a match is found, the search for the best-match index will be
   based on a look-up in a prefix-tree. A per-route-map prefix-tree
   will be constructed for this purpose. The prefix-tree will compose
   of all the prefixes in all the prefix-lists that are included in the
   match rule of all the sequences of a route-map.


Route Map Examples
==================

A simple example of a route-map:

.. code-block:: frr

   route-map test permit 10
    match ip address 10
    set local-preference 200


This means that if a route matches ip access-list number 10 it's
local-preference value is set to 200.

See :ref:`bgp-configuration-examples` for examples of more sophisticated
usage of route-maps, including of the ``call`` action.