Merge pull request #14502 from opensourcerouting/fix/document_on_how_…

…to_set_the_distance_from_linux

doc: Add an example on how to set a distance for a route from the kernel

doc/user/bgp.rst

@@ -461,6 +461,15 @@ Administrative Distance Metrics
 
    Sets the administrative distance for a particular route.
 
+   If the system has a static route configured from the kernel, it has a
+   distance of 0. In some cases, it might be useful to override the route
+   from the FRR. E.g.: Kernel has a statically configured default route,
+   and you received another default route from the BGP and want to install
+   it to be preferred over the static route. In such a case, you MUST set
+   a higher distance from the kernel.
+
+   .. seealso:: :ref:`administrative-distance`
+
 .. _bgp-requires-policy:
 
 Require policy on EBGP

doc/user/zebra.rst

@@ -374,6 +374,8 @@ outgoing interface
 
    Resolve PBR nexthop via ip neigh tracking
 
+.. _administrative-distance:
+
 Administrative Distance
 =======================
 
@@ -420,16 +422,34 @@ the same distances that other routing suites have chosen.
 +------------+-----------+
 
 An admin distance of 255 indicates to Zebra that the route should not be
-installed into the Data Plane.  Additionally routes with an admin distance
+installed into the Data Plane. Additionally routes with an admin distance
 of 255 will not be redistributed.
 
 Zebra does treat Kernel routes as special case for the purposes of Admin
-Distance.  Upon learning about a route that is not originated by FRR
-we read the metric value as a uint32_t.  The top byte of the value
+Distance. Upon learning about a route that is not originated by FRR
+we read the metric value as a uint32_t. The top byte of the value
 is interpreted as the Administrative Distance and the low three bytes
-are read in as the metric.  This special case is to facilitate VRF
+are read in as the metric. This special case is to facilitate VRF
 default routes.
 
+.. code-block:: shell
+
+   $ # Set administrative distance to 255 for Zebra
+   $ ip route add 192.0.2.0/24 metric $(( 2**32 - 2**24 )) dev lo
+   $ vtysh -c 'show ip route 192.0.2.0/24 json' | jq '."192.0.2.0/24"[] | (.distance, .metric)'
+   255
+   0
+   $ # Set administrative distance to 192 for Zebra
+   $ ip route add 192.0.2.0/24 metric $(( 2**31 + 2**30 )) dev lo
+   $ vtysh -c 'show ip route 192.0.2.0/24 json' | jq '."192.0.2.0/24"[] | (.distance, .metric)'
+   192
+   0
+   $ # Set administrative distance to 128, and metric 100 for Zebra
+   $ ip route add 192.0.2.0/24 metric $(( 2**31 + 100 )) dev lo
+   $ vtysh -c 'show ip route 192.0.2.0/24 json' | jq '."192.0.2.0/24"[] | (.distance, .metric)'
+   128
+   100
+
 Route Replace Semantics
 =======================