Improve documentation of bridge

Improve documentation of bridge

[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  ? 

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 iproute2 1/6] Better documentation of mcast_to_unicast option

[Bastien Roucariès]

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

Document it from kernel patches documentation

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 man/man8/bridge.8 | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index b9bd6bc5..efb84582 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

[PATCH iproute2 2/6] Improve hairpin mode description

[Bastien Roucariès]

Mention VEPA and reflective relay.

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 man/man8/bridge.8 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index efb84582..4dc8a63c 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

[PATCH iproute2 3/6] Document BPDU filter option

[Bastien Roucariès]

Disabled state is also BPDU filter
---
 man/man8/bridge.8 | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index 4dc8a63c..c8e15416 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

[PATCH iproute2 4/6] Better documentation of BDPU guard

[Bastien Roucariès]

Document that guard disable the port and how to reenable it

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 man/man8/bridge.8 | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index c8e15416..53aebb60 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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 "
-- 
2.25.1

[PATCH iproute2 5/6] Document root_block option

[Bastien Roucariès]

Root_block is also called root guard, document it.

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 man/man8/bridge.8 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index 53aebb60..96ea4827 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

[PATCH iproute2 6/6] State of bridge STP port are now case insensitive

[Bastien Roucariès]

Improve use experience

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 bridge/link.c     | 2 +-
 man/man8/bridge.8 | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/bridge/link.c b/bridge/link.c
index 074edf00..3bc7af20 100644
--- a/bridge/link.c
+++ b/bridge/link.c
@@ -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,
diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index 96ea4827..b7b85d1e 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

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

[Sergei Shtylyov]

Hello!

On 05.04.2020 16:48, Bastien Roucariès wrote:

> Root_block is also called root guard, document it.
                                ^ port?
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
>   man/man8/bridge.8 | 5 +++++
>   1 file changed, 5 insertions(+)
> 
> diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
> index 53aebb60..96ea4827 100644
> --- a/man/man8/bridge.8
> +++ b/man/man8/bridge.8
> @@ -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

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

[roucaries.bastien]

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

[PATCH 1/6] Better documentation of mcast_to_unicast option

[roucaries.bastien]

From: Bastien Roucariès <rouca@debian.org>

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

Document it from kernel patches documentation

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 man/man8/bridge.8 | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index b9bd6bc5..ff6f6f37 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

[PATCH 2/6] Improve hairpin mode description

[roucaries.bastien]

From: Bastien Roucariès <rouca@debian.org>

Mention VEPA and reflective relay.

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 man/man8/bridge.8 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index ff6f6f37..584324b5 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

[PATCH 3/6] Document BPDU filter option

[roucaries.bastien]

From: Bastien Roucariès <rouca@debian.org>

Disabled state is also BPDU filter
---
 man/man8/bridge.8 | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index 584324b5..bd33635a 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

[PATCH 4/6] Better documentation of BDPU guard

[roucaries.bastien]

From: Bastien Roucariès <rouca@debian.org>

Document that guard disable the port and how to reenable it

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 man/man8/bridge.8 | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index bd33635a..9bfd942f 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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 "
-- 
2.25.1

[PATCH 5/6] Document root_block option

[roucaries.bastien]

From: Bastien Roucariès <rouca@debian.org>

Root_block is also called root port guard, document it.

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 man/man8/bridge.8 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index 9bfd942f..ff6a5cc9 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -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
-- 
2.25.1

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

[roucaries.bastien]

From: Bastien Roucariès <rouca@debian.org>

Improve use experience

Signed-off-by: Bastien Roucariès <rouca@debian.org>
---
 bridge/link.c     |  2 +-
 man/man8/bridge.8 | 16 ++++++++--------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/bridge/link.c b/bridge/link.c
index 074edf00..3bc7af20 100644
--- a/bridge/link.c
+++ b/bridge/link.c
@@ -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,
diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index ff6a5cc9..5efbd466 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.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
-- 
2.25.1

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

[Sergei Shtylyov]

Hello!

On 13.04.2020 2:50, roucaries.bastien@gmail.com wrote:

> From: Bastien Roucariès <rouca@debian.org>
> 
> Document that guard disable the port and how to reenable it
> 
> Signed-off-by: Bastien Roucariès <rouca@debian.org>
> ---
>   man/man8/bridge.8 | 13 ++++++++++++-
>   1 file changed, 12 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
> index bd33635a..9bfd942f 100644
> --- a/man/man8/bridge.8
> +++ b/man/man8/bridge.8
> @@ -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?

> +the bridge port if a STP BPDU packet is received.
[...]

MBR, Sergei

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

[Stephen Hemminger]

On Mon, 13 Apr 2020 01:50:33 +0200
roucaries.bastien@gmail.com wrote:

> +.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).

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)."

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

[Stephen Hemminger]

On Mon, 13 Apr 2020 01:50:32 +0200
roucaries.bastien@gmail.com 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  ? 
> 
> 
> [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.