Subject: iproute2: Improve bridge documentation Package: iproute2 Version: 5.5.0-1 Severity: wishlist Tags: patch Forwarded: step...@networkplumber.org
Dear Maintainer, I have improved the documentation of man pages for bridge. Moreover state is now case insensitive. Please apply
From 04c9ce1ac1b9dc91eedb2f267766bb9682232ef0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bastien=20Roucari=C3=A8s?= <ro...@debian.org>
Date: Sun, 5 Apr 2020 11:08:11 +0200
Subject: [PATCH 6/6] State of bridge STP port are now case insensitive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Improve use experience
Signed-off-by: Bastien Roucariès <ro...@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 074edf0..3bc7af2 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 96ea482..b7b85d1 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
From 1572dd1b6143a3a542505d62b8e0ee95961e1194 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastien=20Roucari=C3=A8s?= <ro...@debian.org> Date: Sun, 5 Apr 2020 01:52:26 +0200 Subject: [PATCH 1/6] Better documentation of mcast_to_unicast option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This option is useful for Wifi bridge but need some tweak. Document it from kernel patches documentation Signed-off-by: Bastien Roucariès <ro...@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 b9bd6bc..efb8458 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
From a9332a9a9b3e693af028db77d27b98fd2814815c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastien=20Roucari=C3=A8s?= <ro...@debian.org> Date: Sun, 5 Apr 2020 02:00:45 +0200 Subject: [PATCH 2/6] Improve hairpin mode description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mention VEPA and reflective relay. Signed-off-by: Bastien Roucariès <ro...@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 efb8458..4dc8a63 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
>From 9b4deb301f17603c39f2b65118e8046e1add5282 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastien=20Roucari=C3=A8s?= <ro...@debian.org> Date: Sun, 5 Apr 2020 02:12:31 +0200 Subject: [PATCH 3/6] Document BPDU filter option 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 4dc8a63..c8e1541 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
From c6e488aa2a013f0023eaa709aca96247fa10599f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastien=20Roucari=C3=A8s?= <ro...@debian.org> Date: Sun, 5 Apr 2020 02:28:36 +0200 Subject: [PATCH 5/6] Document root_block option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Root_block is also called root guard, document it. Signed-off-by: Bastien Roucariès <ro...@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 53aebb6..96ea482 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
From 2086d388b207d5b51fe3bacc5ec75e4eeb288090 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastien=20Roucari=C3=A8s?= <ro...@debian.org> Date: Sun, 5 Apr 2020 02:19:06 +0200 Subject: [PATCH 4/6] Better documentation of BDPU guard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document that guard disable the port and how to reenable it Signed-off-by: Bastien Roucariès <ro...@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 c8e1541..53aebb6 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
signature.asc
Description: This is a digitally signed message part.
