From 55180d774a4f0fab3869c9720446289e0aee1e3b Mon Sep 17 00:00:00 2001 From: Nathan Bahr Date: Tue, 24 Sep 2024 21:53:41 +0000 Subject: [PATCH] doc: Clean up Multicast RIB documentation Moved it all to PIM section and updated docs for recent changes. Signed-off-by: Nathan Bahr --- doc/developer/grpc.rst | 1 - doc/user/pim.rst | 130 +++++++++++++++++++++++++++-------------- doc/user/zebra.rst | 82 -------------------------- 3 files changed, 85 insertions(+), 128 deletions(-) diff --git a/doc/developer/grpc.rst b/doc/developer/grpc.rst index 4e81adf8b243..62d1594f4cfc 100644 --- a/doc/developer/grpc.rst +++ b/doc/developer/grpc.rst @@ -149,7 +149,6 @@ Below is how to compile and run the program, with the example output: ] }, "frr-zebra:zebra": { - "mcast-rpf-lookup": "mrib-then-urib", "workqueue-hold-timer": 10, "zapi-packets": 1000, "import-kernel-table": { diff --git a/doc/user/pim.rst b/doc/user/pim.rst index 0fe53247b05e..8bf690c63e3c 100644 --- a/doc/user/pim.rst +++ b/doc/user/pim.rst @@ -217,33 +217,14 @@ PIM Routers never do SM over. This command is vrf aware, to configure for a vrf, specify the vrf in the router pim block. +.. _pim-global-configuration: + Global Multicast ----------------- +================ These commands are valid at the top-level of the configuration (or also per vrf where indicated), instead of under the 'router pim' submode. -.. clicmd:: ip multicast rpf-lookup-mode WORD - - Modify how PIM does RPF lookups in the zebra routing table. You can use - these choices: - - longer-prefix - Lookup the RPF in both tables using the longer prefix as a match - - lower-distance - Lookup the RPF in both tables using the lower distance as a match - - mrib-only - Lookup in the Multicast RIB only - - mrib-then-urib - Lookup in the Multicast RIB then the Unicast Rib, returning first found. - This is the default value for lookup if this command is not entered - - urib-only - Lookup in the Unicast Rib only. - .. clicmd:: ip igmp generate-query-once [version (2-3)] Generate IGMP query (v2/v3) on user requirement. This will not depend on @@ -257,6 +238,88 @@ vrf where indicated), instead of under the 'router pim' submode. 'no' form of the command disables the warning generation. This command is vrf aware. To configure per vrf, enter vrf submode. + +.. _pim-multicast-rib: + +Multicast RIB Commands +---------------------- + +The Multicast RIB provides a separate table of unicast destinations which +is used for Multicast Reverse Path Forwarding decisions. It is used with +a multicast source's IP address, hence contains not multicast group +addresses but unicast addresses. + +This table is fully separate from the default unicast table. However, +RPF lookup can include the unicast table. + +.. clicmd:: ip multicast rpf-lookup-mode MODE + + MODE sets the method used to perform RPF lookups. Supported modes: + + urib-only + Performs the lookup on the Unicast RIB. The Multicast RIB is never used. + + mrib-only + Performs the lookup on the Multicast RIB. The Unicast RIB is never used. + + mrib-then-urib + Tries to perform the lookup on the Multicast RIB. If any route is found, + that route is used. Otherwise, the Unicast RIB is tried. + + lower-distance + Performs a lookup on the Multicast RIB and Unicast RIB each. The result + with the lower administrative distance is used; if they're equal, the + Multicast RIB takes precedence. + + longer-prefix + Performs a lookup on the Multicast RIB and Unicast RIB each. The result + with the longer prefix length is used; if they're equal, the + Multicast RIB takes precedence. + + The ``mrib-then-urib`` setting is the default behavior if nothing is + configured. If this is the desired behavior, it should be explicitly + configured to make the configuration immune against possible changes in + what the default behavior is. + +.. warning:: + + Unreachable routes do not receive special treatment and do not cause + fallback to a second lookup. + +.. clicmd:: show [ip|ipv6] rpf ADDR + + Performs a Multicast RPF lookup using the Multicast RIB only. + ADDR specifies the multicast source address to look up. + + :: + + > show ip rpf 192.0.2.1 + Routing entry for 192.0.2.0/24 using Multicast RIB + Known via "kernel", distance 0, metric 0, best + * 198.51.100.1, via eth0 + + + Indicates that a multicast source lookup for 192.0.2.1 against the + Multicast RIB would use an entry for 192.0.2.0/24 with a gateway of + 198.51.100.1. + +.. clicmd:: show [ip|ipv6] rpf + + Prints the entire Multicast RIB. Note that this is independent of the + configured RPF lookup mode, the Multicast RIB may be printed yet not + used at all. + +.. clicmd:: ip mroute PREFIX NEXTHOP [DISTANCE] + + Adds a static route entry to the Multicast RIB. This performs exactly as the + ``ip route`` command, except that it inserts the route in the Multicast RIB + instead of the Unicast RIB. + These routes are only used for RPF lookup and will not be used by zebra for + insertion into the kernel *or* for normal rib processing. As such it is + possible to create weird states with these commands. Use with caution. Most + of the time this will not be necessary. + + .. _pim-interface-configuration: PIM Interface Configuration @@ -374,29 +437,6 @@ is in a vrf, enter the interface command with the vrf keyword at the end. :ref:`bfd-pim-peer-config` - -.. _pim-multicast-rib: - -PIM Multicast RIB -================= - -In order to influence Multicast RPF lookup, it is possible to insert -into zebra routes for the Multicast RIB. These routes are only -used for RPF lookup and will not be used by zebra for insertion -into the kernel *or* for normal rib processing. As such it is -possible to create weird states with these commands. Use with -caution. Most of the time this will not be necessary. - -.. clicmd:: ip mroute A.B.C.D/M A.B.C.D (1-255) - - Insert into the Multicast Rib Route A.B.C.D/M with specified nexthop. The - distance can be specified as well if desired. - -.. clicmd:: ip mroute A.B.C.D/M INTERFACE (1-255) - - Insert into the Multicast Rib Route A.B.C.D/M using the specified INTERFACE. - The distance can be specified as well if desired. - .. _msdp-configuration: Multicast Source Discovery Protocol (MSDP) Configuration diff --git a/doc/user/zebra.rst b/doc/user/zebra.rst index 06a19a61394b..6f93622c7b16 100644 --- a/doc/user/zebra.rst +++ b/doc/user/zebra.rst @@ -1123,88 +1123,6 @@ and this section also helps that case. ! ... -.. _multicast-rib-commands: - -Multicast RIB Commands -====================== - -The Multicast RIB provides a separate table of unicast destinations which -is used for Multicast Reverse Path Forwarding decisions. It is used with -a multicast source's IP address, hence contains not multicast group -addresses but unicast addresses. - -This table is fully separate from the default unicast table. However, -RPF lookup can include the unicast table. - -WARNING: RPF lookup results are non-responsive in this version of FRR, -i.e. multicast routing does not actively react to changes in underlying -unicast topology! - -.. clicmd:: ip multicast rpf-lookup-mode MODE - - - MODE sets the method used to perform RPF lookups. Supported modes: - - urib-only - Performs the lookup on the Unicast RIB. The Multicast RIB is never used. - - mrib-only - Performs the lookup on the Multicast RIB. The Unicast RIB is never used. - - mrib-then-urib - Tries to perform the lookup on the Multicast RIB. If any route is found, - that route is used. Otherwise, the Unicast RIB is tried. - - lower-distance - Performs a lookup on the Multicast RIB and Unicast RIB each. The result - with the lower administrative distance is used; if they're equal, the - Multicast RIB takes precedence. - - longer-prefix - Performs a lookup on the Multicast RIB and Unicast RIB each. The result - with the longer prefix length is used; if they're equal, the - Multicast RIB takes precedence. - - The ``mrib-then-urib`` setting is the default behavior if nothing is - configured. If this is the desired behavior, it should be explicitly - configured to make the configuration immune against possible changes in - what the default behavior is. - -.. warning:: - - Unreachable routes do not receive special treatment and do not cause - fallback to a second lookup. - -.. clicmd:: show [ip|ipv6] rpf ADDR - - Performs a Multicast RPF lookup, as configured with ``ip multicast - rpf-lookup-mode MODE``. ADDR specifies the multicast source address to look - up. - - :: - - > show ip rpf 192.0.2.1 - Routing entry for 192.0.2.0/24 using Unicast RIB - Known via "kernel", distance 0, metric 0, best - * 198.51.100.1, via eth0 - - - Indicates that a multicast source lookup for 192.0.2.1 would use an - Unicast RIB entry for 192.0.2.0/24 with a gateway of 198.51.100.1. - -.. clicmd:: show [ip|ipv6] rpf - - Prints the entire Multicast RIB. Note that this is independent of the - configured RPF lookup mode, the Multicast RIB may be printed yet not - used at all. - -.. clicmd:: ip mroute PREFIX NEXTHOP [DISTANCE] - - - Adds a static route entry to the Multicast RIB. This performs exactly as the - ``ip route`` command, except that it inserts the route in the Multicast RIB - instead of the Unicast RIB. - .. _zebra-route-filtering: zebra Route Filtering