route.8: Describe metric modifier

Describe `-metric` argument in the route manual.

Discussed with:	ziaee
Differential Revision: https://reviews.freebsd.org/D57025

1 files changed, 21 insertions, 1 deletions

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)