[mirror_frr.git] / doc / user / routemap.rst

.. _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.

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-command:

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

.. index:: route-map ROUTE-MAP-NAME (permit|deny) ORDER
.. 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
=======================

.. index:: match ip address ACCESS_LIST
.. clicmd:: match ip address ACCESS_LIST

   Matches the specified `access_list`

.. index:: match ip address PREFIX-LIST
.. clicmd:: match ip address PREFIX-LIST

   Matches the specified `prefix-list`

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

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

.. index:: match ipv6 address ACCESS_LIST
.. clicmd:: match ipv6 address ACCESS_LIST

   Matches the specified `access_list`

.. index:: match ipv6 address PREFIX-LIST
.. clicmd:: match ipv6 address PREFIX-LIST

   Matches the specified `prefix-list`

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

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

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

   Matches the specified `ipv4_addr`.

.. index:: match aspath AS_PATH
.. clicmd:: match aspath AS_PATH

   Matches the specified `as_path`.

.. index:: match metric METRIC
.. clicmd:: match metric METRIC

   Matches the specified `metric`.

.. index:: match tag TAG
.. clicmd:: match tag TAG

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

.. index:: match local-preference METRIC
.. clicmd:: match local-preference METRIC

   Matches the specified `local-preference`.

.. index:: match community COMMUNITY_LIST
.. clicmd:: match community COMMUNITY_LIST

   Matches the specified  `community_list`

.. index:: match peer IPV4_ADDR
.. 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.

.. index:: match peer IPV6_ADDR
.. 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.

.. index:: match peer INTERFACE_NAME
.. 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.

.. _route-map-set-command:

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

.. program:: configure

.. index:: set tag TAG
.. 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.

.. index:: set ip next-hop IPV4_ADDRESS
.. clicmd:: set ip next-hop IPV4_ADDRESS

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

.. index:: set ip next-hop peer-address
.. 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.

.. index:: set ip next-hop unchanged
.. clicmd:: set ip next-hop unchanged

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

.. index:: set ipv6 next-hop peer-address
.. 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.

.. index:: set ipv6 next-hop prefer-global
.. 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.

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

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

.. index:: set local-preference LOCAL_PREF
.. clicmd:: set local-preference LOCAL_PREF

   Set the BGP local preference to `local_pref`.

.. index:: set weight WEIGHT
.. clicmd:: set weight WEIGHT

   Set the route's weight.

.. index:: set metric METRIC
.. clicmd:: set metric METRIC

   Set the BGP attribute MED.

.. index:: set as-path prepend AS_PATH
.. clicmd:: set as-path prepend AS_PATH

   Set the BGP AS path to prepend.

.. index:: set community COMMUNITY
.. clicmd:: set community COMMUNITY

   Set the BGP community attribute.

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

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

.. _route-map-call-command:

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

.. index:: call NAME
.. 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
=============================

.. index:: on-match next
.. clicmd:: on-match next

.. index:: continue
.. clicmd:: continue

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

.. index:: on-match goto N
.. clicmd:: on-match goto N

.. index:: continue N
.. clicmd:: continue N

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

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.
Commit	Line	Data
	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
	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 to the specified IPV4_ADDRESS. For both
	202	incoming and outgoing route-maps.
	203
	204	.. index:: set ip next-hop peer-address
	205	.. clicmd:: set ip next-hop peer-address
	206
	207	Set the BGP nexthop address to the address of the peer. For an incoming
	208	route-map this means the ip address of our peer is used. For an outgoing
	209	route-map this means the ip address of our self is used to establish the
	210	peering with our neighbor.
	211
	212	.. index:: set ip next-hop unchanged
	213	.. clicmd:: set ip next-hop unchanged
	214
	215	Set the route-map as unchanged. Pass the route-map through without
	216	changing it's value.
	217
	218	.. index:: set ipv6 next-hop peer-address
	219	.. clicmd:: set ipv6 next-hop peer-address
	220
	221	Set the BGP nexthop address to the address of the peer. For an incoming
	222	route-map this means the ipv6 address of our peer is used. For an outgoing
	223	route-map this means the ip address of our self is used to establish the
	224	peering with our neighbor.
	225
	226	.. index:: set ipv6 next-hop prefer-global
	227	.. clicmd:: set ipv6 next-hop prefer-global
	228
	229	For Incoming and Import Route-maps if we receive a v6 global and v6 LL
	230	address for the route, then prefer to use the global address as the nexthop.
	231
	232	.. index:: set ipv6 next-hop global IPV6_ADDRESS
	233	.. clicmd:: set ipv6 next-hop global IPV6_ADDRESS
	234
	235	Set the next-hop to the specified IPV6_ADDRESS for both incoming and
	236	outgoing route-maps.
	237
	238	.. index:: set local-preference LOCAL_PREF
	239	.. clicmd:: set local-preference LOCAL_PREF
	240
	241	Set the BGP local preference to `local_pref`.
	242
	243	.. index:: set weight WEIGHT
	244	.. clicmd:: set weight WEIGHT
	245
	246	Set the route's weight.
	247
	248	.. index:: set metric METRIC
	249	.. clicmd:: set metric METRIC
	250
	251	Set the BGP attribute MED.
	252
	253	.. index:: set as-path prepend AS_PATH
	254	.. clicmd:: set as-path prepend AS_PATH
	255
	256	Set the BGP AS path to prepend.
	257
	258	.. index:: set community COMMUNITY
	259	.. clicmd:: set community COMMUNITY
	260
	261	Set the BGP community attribute.
	262
	263	.. index:: set ipv6 next-hop local IPV6_ADDRESS
	264	.. clicmd:: set ipv6 next-hop local IPV6_ADDRESS
	265
	266	Set the BGP-4+ link local IPv6 nexthop address.
	267
	268	.. _route-map-call-command:
	269
	270	Route Map Call Command
	271	======================
	272
	273	.. index:: call NAME
	274	.. clicmd:: call NAME
	275
	276	Call route-map `name`. If it returns deny, deny the route and
	277	finish processing the route-map.
	278
	279	.. _route-map-exit-action-command:
	280
	281	Route Map Exit Action Command
	282	=============================
	283
	284	.. index:: on-match next
	285	.. clicmd:: on-match next
	286
	287	.. index:: continue
	288	.. clicmd:: continue
	289
	290	Proceed on to the next entry in the route-map.
	291
	292	.. index:: on-match goto N
	293	.. clicmd:: on-match goto N
	294
	295	.. index:: continue N
	296	.. clicmd:: continue N
	297
	298	Proceed processing the route-map at the first entry whose order is >= N
	299
	300	Route Map Examples
	301	==================
	302
	303	A simple example of a route-map:
	304
	305	.. code-block:: frr
	306
	307	route-map test permit 10
	308	match ip address 10
	309	set local-preference 200
	310
	311
	312	This means that if a route matches ip access-list number 10 it's
	313	local-preference value is set to 200.
	314
	315	See :ref:`bgp-configuration-examples` for examples of more sophisticated
	316	usage of route-maps, including of the ``call`` action.
	317