Skip to contentSkip to conversation

Improve documentation of bridge

PATCH In review Bastien Roucariès 3 participants 18 messages Apr 5, 2020 – Apr 20, 2020

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

Please found a serie improving documentation of bridge device.

Please review and apply

I could not understand some options in this page:
- vlan_tunnel on ?

According to https://vincent.bernat.ch/en/blog/2017-linux-bridge-isolation
I need echo 1 > /sys/class/net/br0/bridge/vlan_filtering to enable vlan filtering

Do we need the echo 1 ? Or could be implemented by ip bridge (better for user experience) ?

Bastien

#1 lore raw

PATCH v2 1/6 Better documentation of mcast_to_unicast option

This option is useful for Wifi bridge but need some tweak.

Document it from kernel patches documentation

---
 man/man8/bridge.8 | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)
man/man8/bridge.8 +28 -0
index b9bd6bc5..efb84582 100644
@@ -383,6 +383,34 @@ there is no MDB entry. By default this flag is on.
 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.
+
+.BR 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 it and signalized 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 mulitcast is made possible again by
+enabling and utilizing the bridge hairpin mode, which considers the
+incoming port as a potential outgoing port, too (see
+.B hairpin
+option)
+
+Hairpin mode is performed after multicast snooping, therefore leading to
+only deliver reports to STAs running a multicast router.
+
 .TP
 .BR "neigh_suppress on " or " neigh_suppress off "
 Controls whether neigh discovery (arp and nd) proxy and suppression is
Signature · 1 line
2.25.1
#2 lore raw

PATCH v2 2/6 Improve hairpin mode description

In reply to Bastien Roucariès

Mention VEPA and reflective relay.

---
 man/man8/bridge.8 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
man/man8/bridge.8 +3 -1
index efb84582..4dc8a63c 100644
@@ -332,7 +332,9 @@ cause the port to stop processing STP BPDUs.
 .TP
 .BR "hairpin on " or " hairpin off "
 Controls whether traffic may be send back out of the port on which it was
-received. By default, this flag is turned off and the bridge will not forward
+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.
 
 .TP
Signature · 1 line
2.25.1
#3 lore raw

PATCH v2 3/6 Document BPDU filter option

In reply to Bastien Roucariès

Disabled state is also BPDU filter

---
 man/man8/bridge.8 | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)
man/man8/bridge.8 +19 -6
index 4dc8a63c..c8e15416 100644
@@ -293,32 +293,45 @@ droot port selectio algorithms.
 
 .TP
 .BI state " STATE "
-the operation state of the port. This is primarily used by user space STP/RSTP
+the operation state of the port. Except state 0 (disabled),
+this is primarily used by user space STP/RSTP
 implementation. One may enter a lowercased port state name, or one of the
 numbers below. Negative inputs are ignored, and unrecognized names return an
 error.
 
 .B 0
-- port is DISABLED. Make this port completely inactive.
+- port is in
+.B DISABLED
+state. Make this port completely inactive. This is also called
+BPDU filter and could be used to disable STP on an untrusted port, like
+a leaf virtual devices.
 .sp
 
 .B 1
-- STP LISTENING state. Only valid if STP is enabled on the bridge. In this
+- STP
+.B 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.
 .sp
 
 .B 2
-- STP LEARNING state. Only valid if STP is enabled on the bridge. In this
+- STP
+.B 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.
 .sp
 
 .B 3
-- STP FORWARDING state. Port is fully active.
+- STP
+.B FORWARDING
+state. Port is fully active.
 .sp
 
 .B 4
-- STP BLOCKING state. Only valid if STP is enabled on the bridge. This state
+- STP
+.B 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.
 .sp
Signature · 1 line
2.25.1
#4 lore raw

PATCH v2 4/6 Better documentation of BDPU guard

In reply to Bastien Roucariès

Document that guard disable the port and how to reenable it

---
 man/man8/bridge.8 | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)
man/man8/bridge.8 +12 -1
index c8e15416..53aebb60 100644
@@ -340,7 +340,18 @@ STP BPDUs.
 .BR "guard on " or " guard off "
 Controls whether STP BPDUs will be processed by the bridge port. By default,
 the flag is turned off allowed BPDU processing. Turning this flag on will
-cause the port to stop processing STP BPDUs.
+disables
+the bridge port if a STP BPDU packet is received.
+
+If running Spanning Tree on bridge, hostile devices on the network
+may send BPDU on a port and cause network failure. Setting
+.B 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.  For example if guard is enable on
+eth0:
+
+.B ip link set dev eth0 down; ip link set dev eth0 up
 
 .TP
 .BR "hairpin on " or " hairpin off "
Signature · 1 line
2.25.1
#5 lore raw

PATCH v2 5/6 Document root_block option

In reply to Bastien Roucariès

Root_block is also called root guard, document it.

---
 man/man8/bridge.8 | 5 +++++
 1 file changed, 5 insertions(+)
man/man8/bridge.8 +5 -0
index 53aebb60..96ea4827 100644
@@ -372,6 +372,11 @@ enabled on the bridge. By default the flag is off.
 Controls whether a given port is allowed to become root port or not. 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 for rerouting traffic.
+
 .TP
 .BR "learning on " or " learning off "
 Controls whether a given port will learn MAC addresses from received traffic or
Signature · 1 line
2.25.1
#7 lore raw

PATCH v2 6/6 State of bridge STP port are now case insensitive

In reply to Bastien Roucariès

Improve use experience

---
 bridge/link.c     | 2 +-
 man/man8/bridge.8 | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)
bridge/link.c +1 -1
index 074edf00..3bc7af20 100644
@@ -378,7 +378,7 @@ static int brlink_modify(int argc, char **argv)
 			state = strtol(*argv, &endptr, 10);
 			if (!(**argv != '\0' && *endptr == '\0')) {
 				for (state = 0; state < nstates; state++)
-					if (strcmp(port_states[state], *argv) == 0)
+					if (strcasecmp(port_states[state], *argv) == 0)
 						break;
 				if (state == nstates) {
 					fprintf(stderr,
man/man8/bridge.8 +4 -4
index 96ea4827..b7b85d1e 100644
@@ -293,16 +293,16 @@ droot port selectio algorithms.
 
 .TP
 .BI state " STATE "
-the operation state of the port. Except state 0 (disabled),
+the operation state of the port. Except state 0 (disable STP),
 this is primarily used by user space STP/RSTP
-implementation. One may enter a lowercased port state name, or one of the
+implementation. One may enter port state name (case insensitive), or one of the
 numbers below. Negative inputs are ignored, and unrecognized names return an
 error.
 
 .B 0
-- port is in
+- port is in STP
 .B DISABLED
-state. Make this port completely inactive. This is also called
+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.
 .sp
Signature · 1 line
2.25.1
#6 lore raw

Re: [PATCH iproute2 5/6] Document root_block option

In reply to Bastien Roucariès

Hello!

Quoted 1 line · Bastien Roucariès

Root_block is also called root guard, document it.

                               ^ port?
Quoted 10 lines
---
  man/man8/bridge.8 | 5 +++++
  1 file changed, 5 insertions(+)
man/man8/bridge.8 +0 -0
index 53aebb60..96ea4827 100644

man/man8/bridge.8 enabled on the bridge. By default the flag is off. · line 378

Quoted 7 lines
man/man8/bridge.8 +4 -0
@@ -372,6 +372,11 @@ enabled on the bridge. By default the flag is off.
  Controls whether a given port is allowed to become root port or not. 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 for rerouting traffic.

s/for/from/?

[...]

MBR, Sergei

#8 lore raw

v2 cover iproute improve documentation of bridge

In reply to Bastien Roucariès

Please found a serie improving documentation of bridge device.

Please review and apply

I could not understand some options in this page:
- vlan_tunnel on ?

[PATCH 1/6] Better documentation of mcast_to_unicast option [PATCH 2/6] Improve hairpin mode description
[PATCH 3/6] Document BPDU filter option
[PATCH 4/6] Better documentation of BDPU guard [PATCH 5/6] Document root_block option
[PATCH 6/6] State of bridge STP port are now case insensitive

#9 lore raw

PATCH v2 1/6 Better documentation of mcast_to_unicast option

From: Bastien Roucariès <[email protected]>

This option is useful for Wifi bridge but need some tweak.

Document it from kernel patches documentation

---
 man/man8/bridge.8 | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
man/man8/bridge.8 +26 -0
index b9bd6bc5..ff6f6f37 100644
@@ -383,6 +383,32 @@ there is no MDB entry. By default this flag is on.
 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.
+
+.BR 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 it and signalized 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 mulitcast is made possible again by
+enabling and utilizing the bridge hairpin mode, which considers the
+incoming port as a potential outgoing port, too (see
+.B hairpin
+option).
+Hairpin mode is performed after multicast snooping, therefore leading to
+only deliver reports to STAs running a multicast router.
+
 .TP
 .BR "neigh_suppress on " or " neigh_suppress off "
 Controls whether neigh discovery (arp and nd) proxy and suppression is
Signature · 1 line
2.25.1
#11 lore raw

PATCH v2 2/6 Improve hairpin mode description

In reply to [email protected]

From: Bastien Roucariès <[email protected]>

Mention VEPA and reflective relay.

---
 man/man8/bridge.8 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
man/man8/bridge.8 +3 -1
index ff6f6f37..584324b5 100644
@@ -332,7 +332,9 @@ cause the port to stop processing STP BPDUs.
 .TP
 .BR "hairpin on " or " hairpin off "
 Controls whether traffic may be send back out of the port on which it was
-received. By default, this flag is turned off and the bridge will not forward
+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.
 
 .TP
Signature · 1 line
2.25.1
#12 lore raw

PATCH v2 3/6 Document BPDU filter option

In reply to [email protected]

From: Bastien Roucariès <[email protected]>

Disabled state is also BPDU filter

---
 man/man8/bridge.8 | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)
man/man8/bridge.8 +19 -6
index 584324b5..bd33635a 100644
@@ -293,32 +293,45 @@ droot port selectio algorithms.
 
 .TP
 .BI state " STATE "
-the operation state of the port. This is primarily used by user space STP/RSTP
+the operation state of the port. Except state 0 (disabled),
+this is primarily used by user space STP/RSTP
 implementation. One may enter a lowercased port state name, or one of the
 numbers below. Negative inputs are ignored, and unrecognized names return an
 error.
 
 .B 0
-- port is DISABLED. Make this port completely inactive.
+- port is in
+.B DISABLED
+state. Make this port completely inactive. This is also called
+BPDU filter and could be used to disable STP on an untrusted port, like
+a leaf virtual devices.
 .sp
 
 .B 1
-- STP LISTENING state. Only valid if STP is enabled on the bridge. In this
+- STP
+.B 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.
 .sp
 
 .B 2
-- STP LEARNING state. Only valid if STP is enabled on the bridge. In this
+- STP
+.B 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.
 .sp
 
 .B 3
-- STP FORWARDING state. Port is fully active.
+- STP
+.B FORWARDING
+state. Port is fully active.
 .sp
 
 .B 4
-- STP BLOCKING state. Only valid if STP is enabled on the bridge. This state
+- STP
+.B 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.
 .sp
Signature · 1 line
2.25.1
#13 lore raw

PATCH v2 4/6 Better documentation of BDPU guard

In reply to [email protected]

From: Bastien Roucariès <[email protected]>

Document that guard disable the port and how to reenable it

---
 man/man8/bridge.8 | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)
man/man8/bridge.8 +12 -1
index bd33635a..9bfd942f 100644
@@ -340,7 +340,18 @@ STP BPDUs.
 .BR "guard on " or " guard off "
 Controls whether STP BPDUs will be processed by the bridge port. By default,
 the flag is turned off allowed BPDU processing. Turning this flag on will
-cause the port to stop processing STP BPDUs.
+disables
+the bridge port if a STP BPDU packet is received.
+
+If running Spanning Tree on bridge, hostile devices on the network
+may send BPDU on a port and cause network failure. Setting
+.B 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.  For example if guard is enable on
+eth0:
+
+.B ip link set dev eth0 down; ip link set dev eth0 up
 
 .TP
 .BR "hairpin on " or " hairpin off "
Signature · 1 line
2.25.1
#15 lore raw

PATCH v2 5/6 Document root_block option

In reply to [email protected]

From: Bastien Roucariès <[email protected]>

Root_block is also called root port guard, document it.

---
 man/man8/bridge.8 | 5 +++++
 1 file changed, 5 insertions(+)
man/man8/bridge.8 +5 -0
index 9bfd942f..ff6a5cc9 100644
@@ -372,6 +372,11 @@ enabled on the bridge. By default the flag is off.
 Controls whether a given port is allowed to become root port or not. 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.
+
 .TP
 .BR "learning on " or " learning off "
 Controls whether a given port will learn MAC addresses from received traffic or
Signature · 1 line
2.25.1
#16 lore raw

PATCH v2 6/6 State of bridge STP port are now case insensitive

In reply to [email protected]

From: Bastien Roucariès <[email protected]>

Improve use experience

---
 bridge/link.c     |  2 +-
 man/man8/bridge.8 | 16 ++++++++--------
 2 files changed, 9 insertions(+), 9 deletions(-)
bridge/link.c +1 -1
index 074edf00..3bc7af20 100644
@@ -378,7 +378,7 @@ static int brlink_modify(int argc, char **argv)
 			state = strtol(*argv, &endptr, 10);
 			if (!(**argv != '\0' && *endptr == '\0')) {
 				for (state = 0; state < nstates; state++)
-					if (strcmp(port_states[state], *argv) == 0)
+					if (strcasecmp(port_states[state], *argv) == 0)
 						break;
 				if (state == nstates) {
 					fprintf(stderr,
man/man8/bridge.8 +8 -8
index ff6a5cc9..5efbd466 100644
@@ -293,29 +293,29 @@ droot port selectio algorithms.
 
 .TP
 .BI state " STATE "
-the operation state of the port. Except state 0 (disabled),
+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. One may enter a lowercased port state name, or one of the
+implementation. One may enter port state name (case insensitive), or one of the
 numbers below. Negative inputs are ignored, and unrecognized names return an
 error.
 
 .B 0
-- port is in
+- port is in STP
 .B DISABLED
-state. Make this port completely inactive. This is also called
+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.
 .sp
 
 .B 1
-- STP
+- port is in STP
 .B 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.
 .sp
 
 .B 2
-- STP
+- port is in STP
 .B 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
@@ -323,13 +323,13 @@ address tables.
 .sp
 
 .B 3
-- STP
+- port is in STP
 .B FORWARDING
 state. Port is fully active.
 .sp
 
 .B 4
-- STP
+- port is in STP
 .B 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
Signature · 1 line
2.25.1
#14 lore raw

Re: [PATCH 4/6] Better documentation of BDPU guard

In reply to [email protected]

Hello!

Quoted 14 lines · On 13.04.2020 2:50, [email protected] wrote:

From: Bastien Roucariès <[email protected]>

Document that guard disable the port and how to reenable it

---
  man/man8/bridge.8 | 13 ++++++++++++-
  1 file changed, 12 insertions(+), 1 deletion(-)
man/man8/bridge.8 +0 -0
index bd33635a..9bfd942f 100644

man/man8/bridge.8 STP BPDUs. · line 343

Quoted 5 lines
man/man8/bridge.8 +1 -1
@@ -340,7 +340,18 @@ STP BPDUs.
  .BR "guard on " or " guard off "
  Controls whether STP BPDUs will be processed by the bridge port. By default,
  the flag is turned off allowed BPDU processing. Turning this flag on will
-cause the port to stop processing STP BPDUs.
+disables

Disable. And why break the line here?

man/man8/bridge.8 STP BPDUs. · line 344

Quoted 1 line
man/man8/bridge.8 +1 -0
+the bridge port if a STP BPDU packet is received.

[...]

MBR, Sergei

#10 lore raw

Re: [PATCH 1/6] Better documentation of mcast_to_unicast option

In reply to [email protected]
Quoted 10 lines · On Mon, 13 Apr 2020 01:50:33 +0200 [email protected] wrote:

+.BR mcast_to_unicast

man/man8/bridge.8 +9 -0
+works on top of the multicast snooping feature of
+the bridge. Which means unicast copies are only delivered to hosts which
+are interested in it and signalized 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).
+

man/man8/bridge.8 there is no MDB entry. By default this flag is on. · line 408

Quoted 10 lines
man/man8/bridge.8 +10 -0
+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 mulitcast is made possible again by
+enabling and utilizing the bridge hairpin mode, which considers the
+incoming port as a potential outgoing port, too (see
+.B hairpin
+option).

It probably doesn't make difference but seems like inconsistent usage of Bold and BoldRoman macros

.B mcast_to_unicast
works on top of the multicast snooping feature of

.BR hairpin "option)."

#17 lore raw

Re: [V2][PATH 0/6] iproute improve documentation of bridge

In reply to [email protected]
Quoted 8 lines · On Mon, 13 Apr 2020 01:50:32 +0200 [email protected] wrote:

Please found a serie improving documentation of bridge device.

Please review and apply

I could not understand some options in this page:
- vlan_tunnel on ?

Quoted 7 lines

[PATCH 1/6] Better documentation of mcast_to_unicast option [PATCH 2/6] Improve hairpin mode description
[PATCH 3/6] Document BPDU filter option
[PATCH 4/6] Better documentation of BDPU guard [PATCH 5/6] Document root_block option
[PATCH 6/6] State of bridge STP port are now case insensitive

Applied all these and fixed some old spelling errors on the man page.