Netdev List
 help / color / mirror / Atom feed
From: Stephen Hemminger <stephen@networkplumber.org>
To: Pranav Tathe <pranavtathe30@gmail.com>
Cc: netdev@vger.kernel.org, David Ahern <dsahern@kernel.org>
Subject: Re: [PATCH iproute2-next] ip-link: document BOND type options in man page
Date: Mon, 16 Nov 2026 14:35:53 -0800	[thread overview]
Message-ID: <20261116143553.1b051ab9@phoenix.local> (raw)
In-Reply-To: <20261110142527.257436-1-pranavtathe30@gmail.com>

On Tue, 10 Nov 2026 19:55:27 +0530
Pranav Tathe <pranavtathe30@gmail.com> wrote:

> The ip-link(8) man page documents master-side creation options for many
> link types but has no "BOND Type Support" section, leaving the bond master
> options (mode, miimon, arp_*, xmit_hash_policy, lacp_*, ad_*,
> coupled_control, broadcast_neighbor, lacp_strict, arp_missed_max, ...)
> undocumented, even though a "Bonding Slave Support" section already exists.
> 
> Add a "BOND Type Support" section modelled on "BRIDGE Type Support",
> describing every bond master option accepted by iplink_bond.c. Option
> descriptions are sourced from the kernel bonding documentation
> (Documentation/networking/bonding.rst).
> 
> Signed-off-by: Pranav Tathe <pranavtathe30@gmail.com>
> ---
There is a tradeoff between more complete man page and duplicating what
is already in the kernel documentation. I would rather have kernel doc
as single source of truth and keep the ip man page to a minimum.

The longer AI review is:
------------------------

Having a BOND section is welcome, and the option set you identified is
right. But the per-option prose restates bonding.rst, and that overlap is
what I would like to avoid. Documentation that is copied from the kernel
drifts from it, and the man page has no way to notice.

The miimon entry in this very patch shows how that goes:

> +.BI miimon " MIIMON "
> +- specifies the MII link monitoring frequency in milliseconds. This
> +determines how often the link state of each slave is inspected for link
> +failures. A value of zero disables MII link monitoring. A value of 100
> +is a good starting point. The default value is
> +.BR 0 .

0 is right for balance-rr, active-backup, balance-xor and broadcast, but
not for the other three. Since

  c1f897ce186a ("bonding: set default miimon value for non-arp modes if
                not set")   [v4.18-rc7]

setting the mode to 802.3ad, balance-tlb or balance-alb forces miimon to
100 when it was left unspecified:

	if (!bond_mode_uses_arp(newval->value)) {
		...
		if (!bond->params.miimon) {
			/* set miimon to default value */
			WRITE_ONCE(bond->params.miimon, BOND_DEFAULT_MIIMON);

bond_mode_uses_arp() is false only for those three modes, and
IFLA_BOND_MODE goes through __bond_opt_set(BOND_OPT_MODE), so

	ip link add bond0 type bond mode 802.3ad

comes up with miimon=100. That was the motivating case in c1f897ce186a;
802.3ad needs link monitoring to work at all.

And bonding.rst is not much better - it says

	The default value is 100 if arp_interval is not set.

which is imprecise in the other direction, since the kernel guard is on
the mode, not on arp_interval. That wording came from

  f036b97da67f ("Documentation: bonding: update miimon default to 100")

four years after the behaviour changed. So this is a detail that two
kernel doc revisions have not stated correctly, and copying it into
ip-link(8) adds a third place to get it wrong.

So for v2, I would keep the synopsis and the option list, which are the
parts a reader needs from us, and cut the descriptions back to one line
per option - roughly what it does and which modes it applies to - leaving
semantics, defaults and valid ranges to the kernel. The BRIDGE section you
modelled this on is already written that way:

	.BI hello_time " HELLO_TIME "
	- set the time in seconds between hello packets sent by the bridge,
	when it is a root bridge or a designated bridges.
	Only relevant if STP is enabled. Valid values are between 1 and 10.

For miimon that is just

	.BI miimon " MIIMON "
	- specifies the MII link monitoring frequency in milliseconds. A
	value of zero disables MII link monitoring.

with the default left out entirely, rather than stated wrongly.

Then one pointer after the synopsis covers all of it:

	The options below mirror the bonding driver parameters. For their
	full semantics, permitted values and defaults see the kernel
	bonding documentation,
	.B Documentation/networking/bonding.rst
	in the Linux kernel source tree, or
	.B https://www.kernel.org/doc/html/latest/networking/bonding.html
	\&.

tc-bpf(8) already cites Documentation/networking/ this way, so the style
is not new here.

On the rest: I checked every option in the new section against the option
list in bond_parse_opt() - the set is complete in both directions, nothing
documented that is not parsed and nothing parsed that is not documented,
and the value lists and numeric codes all match. That part is solid and
should carry over to v2 unchanged. The page also renders with no new groff
warnings.

      reply	other threads:[~2026-11-16 22:35 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-10 14:25 [PATCH iproute2-next] ip-link: document BOND type options in man page Pranav Tathe
2026-11-16 22:35 ` Stephen Hemminger [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261116143553.1b051ab9@phoenix.local \
    --to=stephen@networkplumber.org \
    --cc=dsahern@kernel.org \
    --cc=netdev@vger.kernel.org \
    --cc=pranavtathe30@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox