doc: Clean up Multicast RIB documentation

Moved it all to PIM section and updated docs for recent changes. Signed-off-by: Nathan Bahr <nbahr@atcorp.com>
FRRouting · Oct 27, 2024 · 55180d7 · 55180d7
1 parent bec5b5c
commit 55180d7
Show file tree

Hide file tree

Showing 3 changed files with 85 additions and 128 deletions.
diff --git 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
@@ -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
@@ -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