Improve documentation of bridge
Subsystems (2)
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
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
@@ -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
PATCH v2 2/6 Improve hairpin mode description
In reply to Bastien RoucarièsMention VEPA and reflective relay.
--- man/man8/bridge.8 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
man/man8/bridge.8 +3 -1
@@ -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
PATCH v2 3/6 Document BPDU filter option
In reply to Bastien RoucarièsDisabled state is also BPDU filter
--- man/man8/bridge.8 | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-)
man/man8/bridge.8 +19 -6
@@ -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
PATCH v2 4/6 Better documentation of BDPU guard
In reply to Bastien RoucarièsDocument 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
@@ -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
PATCH v2 5/6 Document root_block option
In reply to Bastien RoucarièsRoot_block is also called root guard, document it.
--- man/man8/bridge.8 | 5 +++++ 1 file changed, 5 insertions(+)
man/man8/bridge.8 +5 -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. + .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
Re: [PATCH iproute2 5/6] Document root_block option
Hello!
Quoted 1 line · Bastien Roucariès
Root_blockis also called root guard, document it.
^ port?
Quoted 10 lines
Signed-off-by Bastien Roucariès <[email protected]>--- man/man8/bridge.8 | 5 +++++ 1 file changed, 5 insertions(+)man/man8/bridge.8 +0
-0
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
PATCH v2 6/6 State of bridge STP port are now case insensitive
In reply to Bastien RoucarièsImprove use experience
--- bridge/link.c | 2 +- man/man8/bridge.8 | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-)
bridge/link.c +1 -1
@@ -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
@@ -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
v2 cover iproute improve documentation of bridge
In reply to Bastien RoucarièsPlease 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
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
@@ -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
Re: [PATCH 1/6] Better documentation of mcast_to_unicast option
Quoted 10 lines · On Mon, 13 Apr 2020 01:50:33 +0200 [email protected] wrote:
+.BR
mcast_to_unicastman/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)."
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
@@ -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
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
@@ -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
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
@@ -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
Re: [PATCH 4/6] Better documentation of BDPU guard
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
Signed-off-by Bastien Roucariès <[email protected]>--- man/man8/bridge.8 | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-)man/man8/bridge.8 +0
-0
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
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
@@ -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
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
@@ -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
@@ -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
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_tunnelon ?
Quoted 7 lines
[PATCH 1/6] Better documentation of
mcast_to_unicastoption [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] Documentroot_blockoption
[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.