Re: [PATCH] rtnetlink.7: Document metrics attributes (RTAX_*).

[Guillaume Nault <gnault@redhat.com>]

On Thu, Oct 02, 2025 at 11:33:09PM +0200, Alejandro Colomar wrote:
> Hi Guillaume,
> 
> On Fri, Sep 19, 2025 at 12:53:55PM +0200, Guillaume Nault wrote:
> > Add a brief explanation of the RTAX attributes that can be used in
> > RTA_METRICS.
> > 
> > Signed-off-by: Guillaume Nault <gnault@redhat.com>
> > ---
> >  man/man7/rtnetlink.7 | 49 +++++++++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 48 insertions(+), 1 deletion(-)
> > 
> > diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
> > index cb9f5155f..a04edce79 100644
> > --- a/man/man7/rtnetlink.7
> > +++ b/man/man7/rtnetlink.7
> > @@ -342,7 +342,11 @@ RTA_OIF:int:Output interface index
> >  RTA_GATEWAY:protocol address:The gateway of the route
> >  RTA_PRIORITY:int:Priority of route
> >  RTA_PREFSRC:protocol address:Preferred source address
> > -RTA_METRICS:int:Route metric
> > +RTA_METRICS::T{
> > +Route metrics
> > +.br
> > +(see below).
> > +T}
> >  RTA_MULTIPATH::T{
> >  Multipath nexthop data
> >  .br
> > @@ -384,6 +388,49 @@ routes (in seconds)
> >  T}
> >  .TE
> >  .IP
> > +.B RTA_METRICS
> > +contains an array of
> > +.I struct rtattr
> > +with their corresponding attributes:
> > +.IP
> > +.in +4n
> 
> I would use
> 
> 	.RS
> 	.IP
> 
> and get rid of the .in +4n.

I have no preference, I was just following the commands used elsewhere
in this man page.

> > +.TS
> > +tab(:);
> > +c s s
> > +lb l l.
> > +Attributes
> > +rta_type:Value type:Description
> > +_
> > +RTAX_UNSPEC:-:unspecified
> > +RTAX_LOCK:__u32:Bit field indicating which RTAX_* attributes are locked
> > +RTAX_MTU:__u32:Maximum Transmission Unit for this route
> > +RTAX_WINDOW:__u32:Maximum size of the receive window for this route
> > +RTAX_RTT:__u32:Estimated round-trip time for this route
> > +RTAX_RTTVAR:__u32:Estimated round-trip time variation for this route
> > +RTAX_SSTHRESH:__u32:Slow start threshold to use for this route
> > +RTAX_CWND:__u32:Maximum size of the congestion window for this route
> > +RTAX_ADVMSS:__u32:Maximum Segment Size to advertise for this route
> > +RTAX_REORDERING:__u32:Initial reordering level of packets for this route
> > +RTAX_HOPLIMIT:__u32:Hop limit (TTL) to use for this route
> > +RTAX_INITCWND:__u32:Initial congestion window to use for this route
> > +RTAX_FEATURES:__u32:Features to enable for this route specifically
> > +RTAX_RTO_MIN:__u32:Minimum Retransmission TimeOut to use for this route
> > +RTAX_INITRWND:__u32:Initial size of the receive window for this route
> > +RTAX_QUICKACK:__u32:Use quick ack for this route
> > +RTAX_CC_ALGO:asciiz string:Congestion Control algorithm to use for this route
> > +RTAX_FASTOPEN_NO_COOKIE:__u32:Allow TCP Fast Open without cookie
> > +.TE
> 
> And here use .RE.

Okay, I'll use .RS/.RE in v2.

> > +.IP
> > +Metrics that are locked with
> > +.B RTAX_LOCK
> > +take precedence over the values normally used by the kernel
> > +(computed or assigned by a sysctl or setsockopt(2)).
> > +Therefore, some metrics, like
> > +.BR RTAX_RTO_MIN ,
> > +have no effect unless their bit is set in
> > +.BR RTAX_LOCK .
> > +.in
> 
> I find this placement of .in weird.  The preceding paragraph isn't
> indented by it.  I think I prefer using .RS/.RE, and then you'd have to
> put .RE before this paragraph to get the same indentation.
> 
> Here's how your patch looks like:
> 
> 	$ MANWIDTH=72 diffman-git HEAD 2>/dev/null
> 	--- HEAD^:man/man7/rtnetlink.7
> 	+++ HEAD:man/man7/rtnetlink.7
> 	@@ -218,7 +218,8 @@ DESCRIPTION
> 		     RTA_GATEWAY     protocol address      The gateway of the route
> 		     RTA_PRIORITY    int                   Priority of route
> 		     RTA_PREFSRC     protocol address      Preferred source address
> 	-            RTA_METRICS     int                   Route metric
> 	+            RTA_METRICS                           Route metrics
> 	+                                                  (see below).
> 		     RTA_MULTIPATH                         Multipath nexthop data
> 							   (see below).
> 		     RTA_PROTOINFO                         No longer used
> 	@@ -242,6 +243,37 @@ DESCRIPTION
> 		     RTA_EXPIRES     int                   Expire time for IPv6
> 							   routes (in seconds)
> 	 
> 	+            RTA_METRICS contains an array of struct rtattr with their
> 	+            corresponding attributes:
> 	+
> 	+                                                           Attributes
> 	+                rta_type                  Value type      Description
> 	+                ──────────────────────────────────────────────────────────────────────────────────────────────────
> 	+                RTAX_UNSPEC               ‐               unspecified
> 	+                RTAX_LOCK                 __u32           Bit field indicating which RTAX_* attributes are locked
> 	+                RTAX_MTU                  __u32           Maximum Transmission Unit for this route
> 	+                RTAX_WINDOW               __u32           Maximum size of the receive window for this route
> 	+                RTAX_RTT                  __u32           Estimated round‐trip time for this route
> 	+                RTAX_RTTVAR               __u32           Estimated round‐trip time variation for this route
> 	+                RTAX_SSTHRESH             __u32           Slow start threshold to use for this route
> 	+                RTAX_CWND                 __u32           Maximum size of the congestion window for this route
> 	+                RTAX_ADVMSS               __u32           Maximum Segment Size to advertise for this route
> 	+                RTAX_REORDERING           __u32           Initial reordering level of packets for this route
> 	+                RTAX_HOPLIMIT             __u32           Hop limit (TTL) to use for this route
> 	+                RTAX_INITCWND             __u32           Initial congestion window to use for this route
> 	+                RTAX_FEATURES             __u32           Features to enable for this route specifically
> 	+                RTAX_RTO_MIN              __u32           Minimum Retransmission TimeOut to use for this route
> 	+                RTAX_INITRWND             __u32           Initial size of the receive window for this route
> 	+                RTAX_QUICKACK             __u32           Use quick ack for this route
> 	+                RTAX_CC_ALGO              asciiz string   Congestion Control algorithm to use for this route
> 	+                RTAX_FASTOPEN_NO_COOKIE   __u32           Allow TCP Fast Open without cookie
> 	+
> 	+            Metrics that are locked with RTAX_LOCK take precedence over
> 	+            the values normally used by the kernel (computed or as‐
> 	+            signed by a sysctl or setsockopt(2)).  Therefore, some met‐
> 	+            rics, like RTAX_RTO_MIN, have no effect unless their bit is
> 	+            set in RTAX_LOCK.
> 	+
> 		     RTA_MULTIPATH contains several packed instances of struct
> 		     rtnexthop together with nested RTAs (RTA_GATEWAY):
> 	 
> Is this indentation what you intended?

Yes. Is that indentation confusing? I can change it if necessary.

> 
> Have a lovely night!
> Alex
> 
> > +.IP
> >  .B RTA_MULTIPATH
> >  contains several packed instances of
> >  .I struct rtnexthop
> > -- 
> > 2.47.3
> > 
> 
> -- 
> <https://www.alejandro-colomar.es>
> Use port 80 (that is, <...:80/>).