git: d87e5b28b763 - main - route.8: Describe metric modifier

The branch main has been updated by pouria:

URL: https://cgit.FreeBSD.org/src/commit/?id=d87e5b28b763f1f0d73fd0ba0ce7f4eee30a8fca

commit d87e5b28b763f1f0d73fd0ba0ce7f4eee30a8fca
Author:     Pouria Mousavizadeh Tehrani <pouria@FreeBSD.org>
AuthorDate: 2026-05-15 22:02:09 +0000
Commit:     Pouria Mousavizadeh Tehrani <pouria@FreeBSD.org>
CommitDate: 2026-05-20 20:55:09 +0000

    route.8: Describe metric modifier
    
    Describe `-metric` argument in the route manual.
    
    Discussed with: ziaee
    Differential Revision: https://reviews.freebsd.org/D57025
---
 sbin/route/route.8 | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/sbin/route/route.8 b/sbin/route/route.8
index 5cb16120c8d8..424b005ca984 100644
--- a/sbin/route/route.8
+++ b/sbin/route/route.8
@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 16, 2026
+.Dd May 17, 2026
 .Dt ROUTE 8
 .Os
 .Sh NAME
@@ -308,6 +308,26 @@ and
 .Dq Fl gateway Ar 3fff::2 Fl weight Ar 200
 will make the nexthop 3fff::2 twice as likely to be chosen as 3fff::1.
 .Pp
+The
+.Fl metric
+option sets the numeric cost associated with a route nexthop.
+The lowest metric is always preferred and routes with higher metric
+values are only used if lower-metric routes become unavailable.
+This allows routes to establish primary and backup nexthops without
+removing the primary.
+The default value for
+.Fl metric
+is 1 when not specified.
+When multiple routes to the same destination have identical metrics, the
+.Fl weight
+option determines which nexthop is selected for ECMP.
+.Pp
+For example, a destination with two nexthops defined as
+.Dq Fl gateway Ar 3fff::1 Fl metric Ar 1
+and
+.Dq Fl gateway Ar 3fff::2 Fl metric Ar 2
+will cause the nexthop 3fff::1 to be selected.
+.Pp
 Routes have associated flags which influence operation of the protocols
 when sending to destinations matched by the routes.
 These flags may be set (or sometimes cleared)