route.8: Add information about ROUTE_MPATH and FIB_ALGO

Since the kernel options ROUTE_MPATH and FIB_ALGO are enabled
per default for a while, it's good to have some user facing
documetation about the general functionality of multipath
routing and fib lookup algorithms.

Reviewed by:	pauamma, Jose Luis Duran <jlduran at gmail dot com>
MFC after:	5 days
Differential Revision:	https://reviews.freebsd.org/D38783

1 files changed, 56 insertions, 1 deletions

diff --git a/sbin/route/route.8 b/sbin/route/route.8
index 161189e7a9d8..c893ae5ab4b3 100644
--- a/sbin/route/route.8
+++ b/sbin/route/route.8
@@ -28,7 +28,7 @@
 .\"     @(#)route.8	8.3 (Berkeley) 3/19/94
 .\" $FreeBSD$
 .\"
-.Dd December 15, 2021
+.Dd February 26, 2023
 .Dt ROUTE 8
 .Os
 .Sh NAME
@@ -405,6 +405,60 @@ and
 .Dv RTM_CHANGE .
 As such, only the super-user may modify
 the routing tables.
+.Pp
+.Fx provides support for scalable multipath routing.
+It is activated by default, but can be turned off by setting the
+.Va net.route.multipath
+.Xr sysctl 8
+MIB to 0.
+.Pp
+There are multiple route lookup algorithms available.
+They can be configured by setting
+.Va net.route.algo.inet.algo
+for IPv4 and
+.Va net.route.algo.inet6.algo
+for IPv6
+.Xr sysctl 8
+MIBs.
+.Pp
+A list of available algorithms can be obtained by accessing the
+following
+.Xr sysctl 8
+MIBs
+.Va net.route.algo.inet.algo_list
+for IPv4 and
+.Va net.route.algo.inet6.algo_list
+for IPv6.
+.Pp
+The following algorithms are available:
+.Bl -tag -width radix_lockless
+.It radix
+Base system radix backend.
+.It bsearch
+Lockless binary search in a special IP array, tailored for a small FIB
+with <16 routes.
+This algorithm is only available for IPv4.
+.It radix_lockless
+Lockless immutable radix, re-created on every rtable change,
+tailored for a small FIB with <1000 routes.
+.It dpdk_lpm
+DPDK DIR24-8-based lookups, lockless datastructure, optimized
+for a large FIB.
+In order to use the dpdk_lpm algorithm one or both of the
+following kernel modules must be loaded via
+.Xr loader.conf 5 :
+.Bl -tag -width dpdk_lpm6.ko -compact
+.It dpdk_lpm4.ko
+DPDK implementation for IPv4.
+.It dpdk_lpm6.ko
+DPDK implementation for IPv6.
+.El
+.El
+.Pp
+The algorithms are selected automatically based on the size of the routing
+table of the system.
+They can be changed, but not every algorithm performs best for every
+FIB size.
 .Sh EXIT STATUS
 .Ex -std
 .Sh EXAMPLES
@@ -484,6 +538,7 @@ The next-hop gateway should be reachable through a different route.
 .Xr netstat 1 ,
 .Xr netintro 4 ,
 .Xr route 4 ,
+.Xr loader.conf 5 ,
 .Xr arp 8 ,
 .Xr routed 8
 .Sh HISTORY