Date: Mon, 13 Nov 2023 11:44:21 +0200
From: Nikolay Aleksandrov <razor@...ckwall.org>
To: Hangbin Liu <liuhangbin@...il.com>, netdev@...r.kernel.org
Cc: "David S . Miller" <davem@...emloft.net>, David Ahern
 <dsahern@...nel.org>, Eric Dumazet <edumazet@...gle.com>,
 Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
 Ido Schimmel <idosch@...sch.org>, Roopa Prabhu <roopa@...dia.com>,
 Stephen Hemminger <stephen@...workplumber.org>,
 Florian Westphal <fw@...len.de>, Andrew Lunn <andrew@...n.ch>,
 Florian Fainelli <f.fainelli@...il.com>, Vladimir Oltean
 <olteanv@...il.com>, Jiri Pirko <jiri@...nulli.us>
Subject: Re: [RFC PATCHv3 net-next 02/10] net: bridge: add document for
 IFLA_BRPORT enum

On 11/10/23 12:15, Hangbin Liu wrote:
> Add document for IFLA_BRPORT enum so we can use it in
> Documentation/networking/bridge.rst.
> 
> Signed-off-by: Hangbin Liu <liuhangbin@...il.com>
> ---
>   include/uapi/linux/if_link.h | 227 +++++++++++++++++++++++++++++++++++
>   1 file changed, 227 insertions(+)
> 
> diff --git a/include/uapi/linux/if_link.h b/include/uapi/linux/if_link.h
> index 32d6980b78d1..a196a6e4dafb 100644
> --- a/include/uapi/linux/if_link.h
> +++ b/include/uapi/linux/if_link.h
> @@ -792,11 +792,238 @@ struct ifla_bridge_id {
>   	__u8	addr[6]; /* ETH_ALEN */
>   };
>   
> +/**
> + * DOC: The bridge mode enum defination

s/defination/definition/

drop "The", Bridge mode enum definition

> + *
> + * @BRIDGE_MODE_HAIRPIN
> + *   Controls whether traffic may be send back out of the port on which it
> + *   was received. This option is also called reflective relay mode, and is
> + *   used to support basic VEPA (Virtual Ethernet Port Aggregator)
> + *   capabilities. By default, this flag is turned off and the bridge will
> + *   not forward traffic back out of the receiving port.
> + */
> +

unnecessary newline

>   enum {
>   	BRIDGE_MODE_UNSPEC,
>   	BRIDGE_MODE_HAIRPIN,
>   };
>   
> +/**
> + * DOC: The bridge port enum defination

s/defination/definition/
drop "The"

> + *
> + * @IFLA_BRPORT_STATE
> + *   The operation state of the port. Except state 0 (disable STP or BPDU
> + *   filter feature), this is primarily used by user space STP/RSTP
> + *   implementation.

This is wrong, port states are used by the kernel STP implementation as 
well.

> + *
> + *     * 0 - port is in STP *DISABLED* state. Make this port completely
> + *       inactive for STP. This is also called BPDU filter and could be used
> + *       to disable STP on an untrusted port, like a leaf virtual devices.
> + *       The traffic forwarding is also stopped on this port.
> + *     * 1 - port is in STP *LISTENING* state. Only valid if STP is enabled
> + *       on the bridge. In this state the port listens for STP BPDUs and
> + *       drops all other traffic frames.
> + *     * 2 - port is in STP *LEARNING* state. Only valid if STP is enabled on
> + *       the bridge. In this state the port will accept traffic only for the
> + *       purpose of updating MAC address tables.
> + *     * 3 - port is in STP *FORWARDING* state. Port is fully active.
> + *     * 4 - port is in STP *BLOCKING* state. Only valid if STP is enabled on
> + *       the bridge. This state is used during the STP election process.
> + *       In this state, port will only process STP BPDUs.
> + *
> + * @IFLA_BRPORT_PRIORITY
> + *   The STP port priority. The valid values are between 0 and 255.
> + *
> + * @IFLA_BRPORT_COST
> + *   The STP path cost of the port. The valid values are between 1 and 65535.
> + *
> + * @IFLA_BRPORT_MODE
> + *   Set the bridge port mode. See *BRIDGE_MODE_HAIRPIN* for more details.
> + *
> + * @IFLA_BRPORT_GUARD
> + *   Controls whether STP BPDUs will be processed by the bridge port. By
> + *   default, the flag is turned off allowed BPDU processing. Turning this

s/allowed/to allow/

> + *   flag on will disables the bridge port if a STP BPDU packet is received.

s/disables/will disable/

> + *
> + *   If running Spanning Tree on bridge, hostile devices on the network may

"If the bridge has Spanning Tree enabled..."

> + *   send BPDU on a port and cause network failure. Setting *guard on* will
> + *   detect and stop this by disabling the port. The port will be restarted
> + *   if link is brought down, or removed and reattached.
> + *
> + * @IFLA_BRPORT_PROTECT
> + *   Controls whether a given port is allowed to become root port or not.

"a root port"

> + *   Only used when STP is enabled on the bridge. By default the flag is off.
> + *
> + *   This feature is also called root port guard. If BPDU is received from a
> + *   leaf (edge) port, it should not be elected as root port. This could
> + *   be used if using STP on a bridge and the downstream bridges are not fully
> + *   trusted; this prevents a hostile guest from rerouting traffic.
> + *
> + * @IFLA_BRPORT_FAST_LEAVE
> + *   This flag allows the bridge to immediately stop multicast traffic on a

multicast traffic forwarding

> + *   port that receives IGMP Leave message. It is only used with IGMP snooping
> + *   is enabled on the bridge. By default the flag is off.

It is only used when IGMP snooping is enabled

> + *
> + * @IFLA_BRPORT_LEARNING
> + *   Controls whether a given port will learn MAC addresses from received
> + *   traffic or not. If learning if off, the bridge will end up flooding any
> + *   traffic for which it has no FDB entry. By default this flag is on.

The second sentence is not necessary, that is the default behaviour
for unknown destinations whether learning is enabled or not, it has no
effect on it. You can mention that it learns source MAC addresses
explicitly.

> + *
> + * @IFLA_BRPORT_UNICAST_FLOOD
> + *   Controls whether unicast traffic for which there is no FDB entry will
> + *   be flooded towards this given port. By default this flag is on.

"... towards this port"

> + *
> + * @IFLA_BRPORT_PROXYARP
> + *   Enable proxy ARP on this port.
> + *
> + * @IFLA_BRPORT_LEARNING_SYNC
> + *   Controls whether a given port will sync MAC addresses learned on device
> + *   port to bridge FDB.
> + *
> + * @IFLA_BRPORT_PROXYARP_WIFI
> + *   Enable proxy ARP on this port which meets extended requirements by
> + *   IEEE 802.11 and Hotspot 2.0 specifications.
> + *
> + * @IFLA_BRPORT_ROOT_ID
> + *
> + * @IFLA_BRPORT_BRIDGE_ID
> + *
> + * @IFLA_BRPORT_DESIGNATED_PORT
> + *
> + * @IFLA_BRPORT_DESIGNATED_COST
> + *
> + * @IFLA_BRPORT_ID
> + *
> + * @IFLA_BRPORT_NO
> + *
> + * @IFLA_BRPORT_TOPOLOGY_CHANGE_ACK
> + *
> + * @IFLA_BRPORT_CONFIG_PENDING
> + *
> + * @IFLA_BRPORT_MESSAGE_AGE_TIMER
> + *
> + * @IFLA_BRPORT_FORWARD_DELAY_TIMER
> + *
> + * @IFLA_BRPORT_HOLD_TIMER
> + *
> + * @IFLA_BRPORT_FLUSH
> + *   Flush bridge ports' fdb dynamic entries.
> + *
> + * @IFLA_BRPORT_MULTICAST_ROUTER
> + *   Configure the port's multicast router presence. A port with
> + *   a multicast router will receive all multicast traffic.
> + *   The valid values are:
> + *
> + *     * 0 disable multicast routers on this port
> + *     * 1 let the system detect the presence of routers (default)
> + *     * 2 permanently enable multicast traffic forwarding on this port
> + *     * 3 enable multicast routers temporarily on this port, not depending
> + *         on incoming queries.
> + *
> + * @IFLA_BRPORT_PAD
> + *
> + * @IFLA_BRPORT_MCAST_FLOOD
> + *   Controls whether a given port will flood multicast traffic for which
> + *   there is no MDB entry. By default this flag is on.
> + *
> + * @IFLA_BRPORT_MCAST_TO_UCAST
> + *   Controls whether a given port will replicate packets using unicast
> + *   instead of multicast. By default this flag is off.
> + *
> + *   This is done by copying the packet per host and changing the multicast
> + *   destination MAC to a unicast one accordingly.
> + *
> + *   *mcast_to_unicast* works on top of the multicast snooping feature of the
> + *   bridge. Which means unicast copies are only delivered to hosts which
> + *   are interested in unicast and signaled this via IGMP/MLD reports previously.
> + *
> + *   This feature is intended for interface types which have a more reliable
> + *   and/or efficient way to deliver unicast packets than broadcast ones
> + *   (e.g. WiFi).
> + *
> + *   However, it should only be enabled on interfaces where no IGMPv2/MLDv1
> + *   report suppression takes place. IGMP/MLD report suppression issue is
> + *   usually overcome by the network daemon (supplicant) enabling AP isolation
> + *   and by that separating all STAs.
> + *
> + *   Delivery of STA-to-STA IP multicast is made possible again by enabling
> + *   and utilizing the bridge hairpin mode, which considers the incoming port
> + *   as a potential outgoing port, too (see *BRIDGE_MODE_HAIRPIN* option).
> + *   Hairpin mode is performed after multicast snooping, therefore leading
> + *   to only deliver reports to STAs running a multicast router.
> + *
> + * @IFLA_BRPORT_VLAN_TUNNEL
> + *   Controls whether vlan to tunnel mapping is enabled on the port.
> + *   By default this flag is off.
> + *
> + * @IFLA_BRPORT_BCAST_FLOOD
> + *   Controls flooding of broadcast traffic on the given port. By default
> + *   this flag is on.
> + *
> + * @IFLA_BRPORT_GROUP_FWD_MASK
> + *   Set the group forward mask. This is a bitmask that is applied to
> + *   decide whether to forward incoming frames destined to link-local
> + *   addresses. The addresses of the form are 01:80:C2:00:00:0X (defaults
> + *   to 0, which means the bridge does not forward any link-local frames
> + *   coming on this port).
> + *
> + * @IFLA_BRPORT_NEIGH_SUPPRESS
> + *   Controls whether neighbor discovery (arp and nd) proxy and suppression
> + *   is enabled on the port. By default this flag is off.
> + *
> + * @IFLA_BRPORT_ISOLATED
> + *   Controls whether a given port will be isolated, which means it will be
> + *   able to communicate with non-isolated ports only. By default this
> + *   flag is off.
> + *
> + * @IFLA_BRPORT_BACKUP_PORT
> + *   Set a backup port. If the port loses carrier all traffic will be
> + *   redirected to the configured backup port. Set the value to 0 to disable
> + *   it.
> + *
> + * @IFLA_BRPORT_MRP_RING_OPEN
> + *
> + * @IFLA_BRPORT_MRP_IN_OPEN
> + *
> + * @IFLA_BRPORT_MCAST_EHT_HOSTS_LIMIT
> + *   The number of per-port EHT hosts limit. The default value is 512.
> + *   Setting to 0 is not allowed.
> + *
> + * @IFLA_BRPORT_MCAST_EHT_HOSTS_CNT
> + *   The current number of tracked hosts, read only.
> + *
> + * @IFLA_BRPORT_LOCKED
> + *   Controls whether a port will be locked, meaning that hosts behind the
> + *   port will not be able to communicate through the port unless an FDB
> + *   entry with the units MAC address is in the FDB. The common use case is that
> + *   hosts are allowed access through authentication with the IEEE 802.1X
> + *   protocol or based on whitelists. By default this flag is off.
> + *
> + * @IFLA_BRPORT_MAB
> + *
> + * @IFLA_BRPORT_MCAST_N_GROUPS
> + *
> + * @IFLA_BRPORT_MCAST_MAX_GROUPS
> + *   Sets the maximum number of MDB entries that can be registered for a
> + *   given port. Attempts to register more MDB entries at the port than this
> + *   limit allows will be rejected, whether they are done through netlink
> + *   (e.g. the bridge tool), or IGMP or MLD membership reports. Setting a
> + *   limit to 0 disables the limit. The default value is 0.

"Setting a limit of 0"

> + *
> + * @IFLA_BRPORT_NEIGH_VLAN_SUPPRESS
> + *   Controls whether neighbor discovery (arp and nd) proxy and suppression is
> + *   enabled for a given VLAN on a given port. By default this flag is off.

given VLAN? This is per-port, not per-vlan.

> + *
> + *   Note that this option only takes effect when *IFLA_BRPORT_NEIGH_SUPPRESS*
> + *   is enabled for a given port.
> + *
> + * @IFLA_BRPORT_BACKUP_NHID
> + *   The FDB nexthop object ID to attach to packets being redirected to a
> + *   backup port that has VLAN tunnel mapping enabled (via the
> + *   *IFLA_BRPORT_VLAN_TUNNEL* option). Setting a value of 0 (default) has
> + *   the effect of not attaching any ID.
> + */
> +
>   enum {
>   	IFLA_BRPORT_UNSPEC,
>   	IFLA_BRPORT_STATE,	/* Spanning tree state     */

Powered by blists - more mailing lists