* [PATCH iproute2-next] ip-link: document BOND type options in man page
@ 2026-11-10 14:25 Pranav Tathe
2026-11-16 22:35 ` Stephen Hemminger
0 siblings, 1 reply; 2+ messages in thread
From: Pranav Tathe @ 2026-11-10 14:25 UTC (permalink / raw)
To: netdev; +Cc: David Ahern, Stephen Hemminger, pranavtathe30
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>
---
man/man8/ip-link.8.in | 392 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 392 insertions(+)
diff --git a/man/man8/ip-link.8.in b/man/man8/ip-link.8.in
index 719781bd..5fa7c6f8 100644
--- a/man/man8/ip-link.8.in
+++ b/man/man8/ip-link.8.in
@@ -1764,6 +1764,398 @@ Redundancy Protocol (PRP).
.
.in -8
+.TP
+BOND Type Support
+For a link of type
+.I BOND
+the following additional arguments are supported:
+
+.BI "ip link add " DEVICE " type bond "
+[
+.BI mode " BONDMODE "
+] [
+.BI active_slave " SLAVE_DEV "
+] [
+.B clear_active_slave
+] [
+.BI miimon " MIIMON "
+] [
+.BI updelay " UPDELAY "
+] [
+.BI downdelay " DOWNDELAY "
+] [
+.BI peer_notify_delay " DELAY "
+] [
+.BI use_carrier " USE_CARRIER "
+] [
+.BI arp_interval " ARP_INTERVAL "
+] [
+.BI arp_validate " ARP_VALIDATE "
+] [
+.BI arp_all_targets " ARP_ALL_TARGETS "
+] [
+.BI arp_ip_target " [ ARP_IP_TARGET, ... ] "
+] [
+.BI ns_ip6_target " [ NS_IP6_TARGET, ... ] "
+] [
+.BI primary " SLAVE_DEV "
+] [
+.BI primary_reselect " PRIMARY_RESELECT "
+] [
+.BI fail_over_mac " FAIL_OVER_MAC "
+] [
+.BI xmit_hash_policy " XMIT_HASH_POLICY "
+] [
+.BI resend_igmp " RESEND_IGMP "
+] [
+.BI num_grat_arp|num_unsol_na " NUM_PEER_NOTIF "
+] [
+.BI all_slaves_active " ALL_SLAVES_ACTIVE "
+] [
+.BI min_links " MIN_LINKS "
+] [
+.BI lp_interval " LP_INTERVAL "
+] [
+.BI packets_per_slave " PACKETS_PER_SLAVE "
+] [
+.BI tlb_dynamic_lb " TLB_DYNAMIC_LB "
+] [
+.BI lacp_rate " LACP_RATE "
+] [
+.BI lacp_active " LACP_ACTIVE "
+] [
+.BI coupled_control " COUPLED_CONTROL "
+] [
+.BI broadcast_neighbor " BROADCAST_NEIGHBOR "
+] [
+.BI ad_select " AD_SELECT "
+] [
+.BI ad_user_port_key " PORTKEY "
+] [
+.BI ad_actor_sys_prio " SYSPRIO "
+] [
+.BI ad_actor_system " LLADDR "
+] [
+.BI lacp_strict " LACP_STRICT "
+] [
+.BI arp_missed_max " MISSED_MAX "
+]
+
+.in +8
+.sp
+.BI mode " BONDMODE "
+- specifies one of the bonding policies. Possible values are
+.BR balance-rr " (0), " active-backup " (1), " balance-xor " (2), "
+.BR broadcast " (3), " 802.3ad " (4), " balance-tlb " (5) and "
+.BR balance-alb " (6). "
+The default is
+.BR balance-rr .
+
+.BI active_slave " SLAVE_DEV "
+- specifies the new active slave for modes that support it
+.RB ( active-backup ", " balance-alb " and " balance-tlb ). "
+.I SLAVE_DEV
+is the name of an existing slave interface.
+
+.B clear_active_slave
+- clears the active slave, letting the bonding driver select the active
+slave on its own.
+
+.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 .
+
+.BI updelay " UPDELAY "
+- specifies the time, in milliseconds, to wait before enabling a slave
+after a link recovery has been detected. This option is only valid for
+the
+.I miimon
+link monitor. The
+.I updelay
+value should be a multiple of the
+.I miimon
+value; if it is not, it will be rounded down to the nearest multiple. The
+default value is
+.BR 0 .
+
+.BI downdelay " DOWNDELAY "
+- specifies the time, in milliseconds, to wait before disabling a slave
+after a link failure has been detected. This option is only valid for
+the
+.I miimon
+link monitor. The
+.I downdelay
+value should be a multiple of the
+.I miimon
+value; if it is not, it will be rounded down to the nearest multiple. The
+default value is
+.BR 0 .
+
+.BI peer_notify_delay " DELAY "
+- specifies the delay, in milliseconds, between each peer notification
+(gratuitous ARP and unsolicited IPv6 Neighbor Advertisement) when they
+are issued after a failover event. This delay should be a multiple of the
+.I miimon
+value. The valid range is 0 - 300000. The default value is
+.BR 0 ,
+which means to match the value of the MII link monitor interval.
+
+.BI use_carrier " USE_CARRIER "
+- obsolete option that previously selected between MII/ETHTOOL ioctls and
+.BR netif_carrier_ok ()
+to determine link state. All link state checks are now done with
+.BR netif_carrier_ok ().
+For backwards compatibility the value may still be inspected or set; the
+only valid setting is
+.BR 1 .
+
+.BI arp_interval " ARP_INTERVAL "
+- specifies the ARP link monitoring frequency in milliseconds. A value of
+0 disables ARP monitoring. ARP monitoring should not be used in
+conjunction with
+.IR miimon .
+The default value is
+.BR 0 .
+
+.BI arp_validate " ARP_VALIDATE "
+- specifies whether or not ARP probes and replies should be validated, or
+whether non-ARP traffic should be filtered (disregarded) for link
+monitoring purposes. Possible values are
+.BR none " (0), " active " (1), " backup " (2), " all " (3), "
+.BR filter " (4), " filter_active " (5) and " filter_backup " (6). "
+The default value is
+.BR none .
+
+.BI arp_all_targets " ARP_ALL_TARGETS "
+- specifies the quantity of
+.I arp_ip_target
+addresses that must be reachable in order for the ARP monitor to consider
+a slave as being up. This option affects only
+.B active-backup
+mode for slaves with
+.I arp_validate
+enabled. Possible values are
+.B any
+(0), consider the slave up when any of the targets is reachable, and
+.B all
+(1), consider the slave up only when all of the targets are reachable.
+
+.BI arp_ip_target " [ ARP_IP_TARGET, ... ] "
+- specifies the IPv4 addresses to use as ARP monitoring peers when
+.I arp_interval
+is greater than 0. These are the targets of the ARP requests sent to
+determine the health of the link. Multiple addresses must be separated by
+a comma. At least one address must be given for ARP monitoring to
+function, and a maximum of 16 targets may be specified.
+
+.BI ns_ip6_target " [ NS_IP6_TARGET, ... ] "
+- specifies the IPv6 addresses to use as NS/NA monitoring peers when
+.I arp_interval
+is greater than 0. These are the targets of the NS requests sent to
+determine the health of the link. Multiple addresses must be separated by
+a comma. At least one address must be given for NS/NA monitoring to
+function, and a maximum of 16 targets may be specified.
+
+.BI primary " SLAVE_DEV "
+- specifies which slave is the primary device.
+.I SLAVE_DEV
+is the name of an existing slave interface. The specified device will
+always be the active slave while it is available; only when it is off-line
+will alternate devices be used. This option is only valid for
+.BR active-backup ", " balance-tlb " and " balance-alb " modes. "
+
+.BI primary_reselect " PRIMARY_RESELECT "
+- specifies the reselection policy for the primary slave. This affects how
+the primary slave is chosen to become the active slave when failure of the
+active slave or recovery of the primary slave occurs. This option is
+designed to prevent flip-flopping between the primary slave and other
+slaves. Possible values are
+.BR always " (0), " better " (1) and " failure " (2). "
+The default value is
+.BR always .
+
+.BI fail_over_mac " FAIL_OVER_MAC "
+- specifies whether
+.B active-backup
+mode should set all slaves to the same MAC address at enslavement (the
+traditional behavior), or, when enabled, perform special handling of the
+bond's MAC address in accordance with the selected policy. Possible values
+are
+.BR none " (0), " active " (1) and " follow " (2). "
+The default policy is
+.BR none ,
+unless the first slave cannot change its MAC address, in which case the
+.B active
+policy is selected by default.
+
+.BI xmit_hash_policy " XMIT_HASH_POLICY "
+- selects the transmit hash policy to use for slave selection in
+.BR balance-xor ", " 802.3ad " and " tlb " modes. "
+Possible values are
+.BR layer2 ", " layer2+3 ", " layer3+4 ", " encap2+3 ", " encap3+4
+and
+.BR vlan+srcmac .
+The default value is
+.BR layer2 .
+
+.BI resend_igmp " RESEND_IGMP "
+- specifies the number of IGMP membership reports to be issued after a
+failover event. The valid range is 0 - 255; the default value is
+.BR 1 .
+A value of 0 prevents the IGMP membership report from being issued. This
+option is useful for
+.BR balance-rr ", " active-backup ", " balance-tlb " and " balance-alb
+modes.
+
+.BI num_grat_arp|num_unsol_na " NUM_PEER_NOTIF "
+- specifies the number of peer notifications (gratuitous ARPs and
+unsolicited IPv6 Neighbor Advertisements) to be issued after a failover
+event. The valid range is 0 - 255; the default value is
+.BR 1 .
+Both names set the same underlying value and cannot be set independently.
+
+.BI all_slaves_active " ALL_SLAVES_ACTIVE "
+- specifies that duplicate frames (received on inactive ports) should be
+dropped (0) or delivered (1). The default value is
+.BR 0 .
+
+.BI min_links " MIN_LINKS "
+- specifies the minimum number of links that must be active before
+asserting carrier. It is similar to the Cisco EtherChannel min-links
+feature. This option only affects
+.B 802.3ad
+mode. The default value is
+.BR 0 .
+
+.BI lp_interval " LP_INTERVAL "
+- specifies the number of seconds between instances where the bonding
+driver sends learning packets to each slave's peer switch. The valid range
+is 1 - 0x7fffffff; the default value is
+.BR 1 .
+This option has effect only in
+.B balance-tlb
+and
+.B balance-alb
+modes.
+
+.BI packets_per_slave " PACKETS_PER_SLAVE "
+- specifies the number of packets to transmit through a slave before
+moving to the next one. When set to 0 a slave is chosen at random. The
+valid range is 0 - 65535; the default value is
+.BR 1 .
+This option has effect only in
+.B balance-rr
+mode.
+
+.BI tlb_dynamic_lb " TLB_DYNAMIC_LB "
+- specifies if dynamic shuffling of flows is enabled in
+.B balance-tlb
+or
+.B balance-alb
+mode. Set to 1 to enable flow shuffling (the default) or 0 to disable it
+and rely on the hash distribution. The value has no effect on any other
+modes.
+
+.BI lacp_rate " LACP_RATE "
+- specifies the rate at which the link partner is asked to transmit LACPDU
+packets in
+.B 802.3ad
+mode. Possible values are
+.B slow
+(0), request partner to transmit LACPDUs every 30 seconds, and
+.B fast
+(1), request partner to transmit LACPDUs every 1 second. The default is
+.BR slow .
+
+.BI lacp_active " LACP_ACTIVE "
+- specifies whether to send LACPDU frames periodically. Possible values
+are
+.B off
+(0), LACPDU frames act as "speak when spoken to", and
+.B on
+(1), LACPDU frames are sent along the configured links periodically. The
+default is
+.BR on .
+
+.BI coupled_control " COUPLED_CONTROL "
+- specifies whether the LACP state machine's MUX in
+.B 802.3ad
+mode should have separate Collecting and Distributing states. Possible
+values are
+.B off
+and
+.BR on .
+The default is
+.BR on ,
+which keeps the Collecting and Distributing states coupled.
+
+.BI broadcast_neighbor " BROADCAST_NEIGHBOR "
+- specifies whether to broadcast ARP/ND packets to all active slaves.
+Possible values are
+.B off
+and
+.BR on .
+This option has no effect in modes other than
+.B 802.3ad
+mode. The default is
+.BR off .
+
+.BI ad_select " AD_SELECT "
+- specifies the
+.B 802.3ad
+aggregation selection logic to use. Possible values are
+.BR stable " (0), " bandwidth " (1), " count " (2) and " actor_port_prio " (3). "
+The default value is
+.BR stable .
+
+.BI ad_user_port_key " PORTKEY "
+- in an
+.B 802.3ad
+system, this defines the upper 10 bits of the port key. The valid range is
+0 - 1023; the default value is
+.BR 0 .
+
+.BI ad_actor_sys_prio " SYSPRIO "
+- in an
+.B 802.3ad
+system, this specifies the system priority. The valid range is 1 - 65535;
+the default value is
+.BR 65535 .
+
+.BI ad_actor_system " LLADDR "
+- in an
+.B 802.3ad
+system, this specifies the MAC address for the actor in protocol packet
+exchanges (LACPDUs). The value cannot be a multicast address. If the
+all-zeroes MAC is specified, bonding will internally use the MAC of the
+bond itself.
+
+.BI lacp_strict " LACP_STRICT "
+- specifies the fallback behavior of a bond when LACP negotiation fails on
+all slave links. Possible values are
+.B off
+(0), one interface is selected to be active in order to facilitate
+communication with peer devices that do not implement LACP, and
+.B on
+(1), interfaces are only permitted to be made active if they have an
+active LACP partner. This option is only applicable to
+.B 802.3ad
+mode. The default value is
+.BR off .
+
+.BI arp_missed_max " MISSED_MAX "
+- specifies the number of
+.I arp_interval
+monitor checks that must fail in order for an interface to be marked down
+by the ARP monitor. The default value is
+.BR 2 ,
+and the allowable range is 1 - 255.
+
+.in -8
+
.TP
BRIDGE Type Support
For a link of type
--
2.56.0
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH iproute2-next] ip-link: document BOND type options in man page
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
0 siblings, 0 replies; 2+ messages in thread
From: Stephen Hemminger @ 2026-11-16 22:35 UTC (permalink / raw)
To: Pranav Tathe; +Cc: netdev, David Ahern
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.
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2026-11-16 22:35 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
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 is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox