Adding upstream version 9.1.upstream/9.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 426 insertions, 0 deletions

diff --git a/doc/user/routemap.rst b/doc/user/routemap.rst
new file mode 100644
index 0000000..3d43e74
--- /dev/null
+++ b/doc/user/routemap.rst
@@ -0,0 +1,426 @@
+.. _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
+
+   Matches the specified  `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
+
+.. clicmd:: continue
+
+   Proceed on to the next entry in the route-map.
+
+.. clicmd:: on-match goto N
+
+.. clicmd:: continue 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.
+