diff mbox series

[iproute2,5/6] man8/bridge.8: explain self vs master for "bridge fdb add"

Message ID 20210211104502.2081443-6-olteanv@gmail.com
State New
Headers show
Series Clarifications to bridge man page | expand

Commit Message

Vladimir Oltean Feb. 11, 2021, 10:45 a.m. UTC
From: Vladimir Oltean <vladimir.oltean@nxp.com>

The "usually hardware" and "usually software" distinctions make no
sense, try to clarify what these do based on the actual kernel behavior.

Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
---
 man/man8/bridge.8 | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

Comments

Alexandra Winter Feb. 15, 2021, 8:22 a.m. UTC | #1
Thank you very much Vladimir for improving this man page. I am still struggling with the meaning of the bridge attributes and sometimes
the man page has caused more confusion.

In the section about 'bridge link set' Self vs master mention physical device vs software bridge. Would it make sense to use the same
terminology here?

The attributes are listed under 'bridge fdb add' not under 'bridge fdb show'. Is it correct that the attributes displayed by 'show'
are a 1-to-1 representation of the ones set by 'add'? What about the entries that are not manually set, like bridge learned adresses?
Is it possible to add some explanation about those as well?

On 11.02.21 11:45, Vladimir Oltean wrote:
> From: Vladimir Oltean <vladimir.oltean@nxp.com>

> 

> The "usually hardware" and "usually software" distinctions make no

> sense, try to clarify what these do based on the actual kernel behavior.

> 

> Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>

> ---

>  man/man8/bridge.8 | 15 ++++++++++++---

>  1 file changed, 12 insertions(+), 3 deletions(-)

> 

> diff --git a/man/man8/bridge.8 b/man/man8/bridge.8

> index 1dc0aec83f09..d0bcd708bb61 100644

> --- a/man/man8/bridge.8

> +++ b/man/man8/bridge.8

> @@ -533,12 +533,21 @@ specified.

>  .sp

>  

>  .B self

> -- the address is associated with the port drivers fdb. Usually hardware

> -  (default).

> +- the operation is fulfilled directly by the driver for the specified network

> +device. If the network device belongs to a master like a bridge, then the

> +bridge is bypassed and not notified of this operation (and if the device does

> +notify the bridge, it is driver-specific behavior and not mandated by this

> +flag, check the driver for more details). The "bridge fdb add" command can also

> +be used on the bridge device itself, and in this case, the added fdb entries

> +will be locally terminated (not forwarded). In the latter case, the "self" flag

> +is mandatory. 

Maybe I misunderstand this sentence, but I can do a 'bridge fdb add' without 'self'
on the bridge device. And the address shows up under 'bridge fdb show'.
So what does mandatory mean here?
The flag is set by default if "master" is not specified.
>  .sp

>  

>  .B master

> -- the address is associated with master devices fdb. Usually software.

> +- if the specified network device is a port that belongs to a master device

> +such as a bridge, the operation is fulfilled by the master device's driver,

> +which may in turn notify the port driver too of the address. If the specified

> +device is a master itself, such as a bridge, this flag is invalid.

>  .sp

>  

>  .B router

>
Vladimir Oltean Feb. 15, 2021, 10:32 a.m. UTC | #2
Hi Alexandra,

On Mon, Feb 15, 2021 at 09:22:47AM +0100, Alexandra Winter wrote:
> In the section about 'bridge link set' Self vs master mention physical

> device vs software bridge. Would it make sense to use the same

> terminology here?


You mean like this?

.TP
.B self
operation is fulfilled by the driver of the specified network interface.

.TP
.B master
operation is fulfilled by the specified interface's master, for example
a bridge, which in turn may or may not notify the underlying network
interface driver. This flag is considered implicit by the kernel if
'self' was not specified.

> The attributes are listed under 'bridge fdb add' not under 'bridge fdb

> show'. Is it correct that the attributes displayed by 'show' are a

> 1-to-1 representation of the ones set by 'add'?


Bah, not quite. I'll try to summarize below.

> What about the entries that are not manually set, like bridge learned

> adresses? Is it possible to add some explanation about those as well?


Ok, challenge accepted. Here's my take on 'bridge fdb show', I haven't
used most of these options (I'm commenting solely based on code
inspection) so if anybody with more experience could chime in, I'd be
happy to adjust the wording.


.SS bridge fdb show - list forwarding entries.

This command displays the current forwarding table. By default all FDB
entries in the system are shown. The following options can be used to
reduce the number of displayed entries:

.TP
.B br
Filter the output to contain only the FDB entries of the specified
bridge, or belonging to ports of the specified bridge (optional).

.B brport
Filter the output to contain only the FDB entries present on the
specified network interface (bridge port). This flag is optional.

.B dev
Same as "brport".

.B vlan
Filter the output to contain only the FDB entries with the specified
VLAN ID (optional).

.B dynamic
Filter out the local/permanent (not forwarded) FDB entries.

.B state
Filter the output to contain only the FDB entries having the specified
state. The bridge FDB is modeled as a neighbouring protocol for
PF_BRIDGE (similar to what ARP is for IPv4 and ND is for IPv6).
Therefore, an FDB entry has a NUD ("Network Unreachability Detection")
state given by the generic neighbouring layer.

The following are the valid components of an FDB entry state (more than
one may be valid at the same time):

.B permanent
Associated with the generic NUD_PERMANENT state, which means that the L2
address of the neighbor has been statically configured by the user and
therefore there is no need for a neighbour resolution.
For the bridge FDB, it means that an FDB entry is 'local', i.e. the L2
address belongs to a local interface.

.B reachable
Associated with the generic NUD_REACHABLE state, which means that the L2
address has been resolved by the neighbouring protocol. A reachable
bridge FDB entry can have two sub-states (static and dynamic) detailed
below.

.B static
Associated with the generic NUD_NOARP state, which is used to denote a
neighbour for which no protocol is needed to resolve the mapping between
the L3 address and L2 address. For the bridge FDB, the neighbour
resolution protocol is source MAC address learning, therefore a static
FDB entry is one that has not been learnt.

.B dynamic
Is a NUD_REACHABLE entry that lacks the NUD_NOARP state, therefore has
been resolved through address learning.

.B stale
Associated with the generic NUD_STALE state. Denotes an FDB entry that
was last updated longer ago than the bridge's hold time, but not yet
removed. The hold time is equal to the forward_delay (if the STP
topology is still changing) or to the ageing_time otherwise.


.PP
In the resulting output, each FDB entry can have one or more of the
following flags:

.B self
This entry is present in the FDB of the specified network interface driver.

.B router
???

.B extern_learn
This entry has been added to the master interface's FDB by the lower
port driver, as a result of hardware address learning.

.B offload
This entry is present in the hardware FDB of a lower port and also
associated with an entry of the master interface.

.B master
This entry is present in the software FDB of the master interface of
this lower port.

.B sticky
This entry cannot be migrated to another port by the address learning
process.

.PP
With the
.B -statistics
option, the command becomes verbose. It prints out the last updated
and last used time for each entry.

> >  .B self

> > -- the address is associated with the port drivers fdb. Usually hardware

> > -  (default).

> > +- the operation is fulfilled directly by the driver for the specified network

> > +device. If the network device belongs to a master like a bridge, then the

> > +bridge is bypassed and not notified of this operation (and if the device does

> > +notify the bridge, it is driver-specific behavior and not mandated by this

> > +flag, check the driver for more details). The "bridge fdb add" command can also

> > +be used on the bridge device itself, and in this case, the added fdb entries

> > +will be locally terminated (not forwarded). In the latter case, the "self" flag

> > +is mandatory. 

> Maybe I misunderstand this sentence, but I can do a 'bridge fdb add' without 'self'

> on the bridge device. And the address shows up under 'bridge fdb show'.

> So what does mandatory mean here?


It's right in the next sentence:

> The flag is set by default if "master" is not specified.


It's mandatory and implicit if "master" is not specified, ergo 'bridge
fdb add dev br0' will work because 'master' is not specified (it is
implicitly 'bridge fdb add dev br0 self'. But 'bridge fdb add dev br0
master' will fail, because the 'self' flag is no longer implicit (since
'master' was specified) but mandatory and absent.

I'm not sure what I can do to improve this.
Alexandra Winter Feb. 15, 2021, 10:53 a.m. UTC | #3
On 15.02.21 11:32, Vladimir Oltean wrote:
> Hi Alexandra,

> 

> On Mon, Feb 15, 2021 at 09:22:47AM +0100, Alexandra Winter wrote:

>> In the section about 'bridge link set' Self vs master mention physical

>> device vs software bridge. Would it make sense to use the same

>> terminology here?

> 

> You mean like this?

> 

> .TP

> .B self

> operation is fulfilled by the driver of the specified network interface.

> 

> .TP

> .B master

> operation is fulfilled by the specified interface's master, for example

> a bridge, which in turn may or may not notify the underlying network

> interface driver. This flag is considered implicit by the kernel if

> 'self' was not specified.

> 

Actually, I found your first (more verbose) proposal more helpful. 

>> The attributes are listed under 'bridge fdb add' not under 'bridge fdb

>> show'. Is it correct that the attributes displayed by 'show' are a

>> 1-to-1 representation of the ones set by 'add'?

> 

> Bah, not quite. I'll try to summarize below.

> 

>> What about the entries that are not manually set, like bridge learned

>> adresses? Is it possible to add some explanation about those as well?

> 

> Ok, challenge accepted. Here's my take on 'bridge fdb show', I haven't

> used most of these options (I'm commenting solely based on code

> inspection) so if anybody with more experience could chime in, I'd be

> happy to adjust the wording.

> 

> 

> .SS bridge fdb show - list forwarding entries.

> 

> This command displays the current forwarding table. By default all FDB

> entries in the system are shown. The following options can be used to

> reduce the number of displayed entries:

> 

> .TP

> .B br

> Filter the output to contain only the FDB entries of the specified

> bridge, or belonging to ports of the specified bridge (optional).

> 

> .B brport

> Filter the output to contain only the FDB entries present on the

> specified network interface (bridge port). This flag is optional.

> 

> .B dev

> Same as "brport".

> 

> .B vlan

> Filter the output to contain only the FDB entries with the specified

> VLAN ID (optional).

> 

> .B dynamic

> Filter out the local/permanent (not forwarded) FDB entries.

> 

> .B state

> Filter the output to contain only the FDB entries having the specified

> state. The bridge FDB is modeled as a neighbouring protocol for

> PF_BRIDGE (similar to what ARP is for IPv4 and ND is for IPv6).

> Therefore, an FDB entry has a NUD ("Network Unreachability Detection")

> state given by the generic neighbouring layer.

> 

> The following are the valid components of an FDB entry state (more than

> one may be valid at the same time):

> 

> .B permanent

> Associated with the generic NUD_PERMANENT state, which means that the L2

> address of the neighbor has been statically configured by the user and

> therefore there is no need for a neighbour resolution.

> For the bridge FDB, it means that an FDB entry is 'local', i.e. the L2

> address belongs to a local interface.

> 

> .B reachable

> Associated with the generic NUD_REACHABLE state, which means that the L2

> address has been resolved by the neighbouring protocol. A reachable

> bridge FDB entry can have two sub-states (static and dynamic) detailed

> below.

> 

> .B static

> Associated with the generic NUD_NOARP state, which is used to denote a

> neighbour for which no protocol is needed to resolve the mapping between

> the L3 address and L2 address. For the bridge FDB, the neighbour

> resolution protocol is source MAC address learning, therefore a static

> FDB entry is one that has not been learnt.

> 

> .B dynamic

> Is a NUD_REACHABLE entry that lacks the NUD_NOARP state, therefore has

> been resolved through address learning.

> 

> .B stale

> Associated with the generic NUD_STALE state. Denotes an FDB entry that

> was last updated longer ago than the bridge's hold time, but not yet

> removed. The hold time is equal to the forward_delay (if the STP

> topology is still changing) or to the ageing_time otherwise.

> 

> 

> .PP

> In the resulting output, each FDB entry can have one or more of the

> following flags:

> 

> .B self

> This entry is present in the FDB of the specified network interface driver.

> 

> .B router

> ???

> 

> .B extern_learn

> This entry has been added to the master interface's FDB by the lower

> port driver, as a result of hardware address learning.

> 

> .B offload

> This entry is present in the hardware FDB of a lower port and also

> associated with an entry of the master interface.

> 

> .B master

> This entry is present in the software FDB of the master interface of

> this lower port.

> 

> .B sticky

> This entry cannot be migrated to another port by the address learning

> process.

> 

> .PP

> With the

> .B -statistics

> option, the command becomes verbose. It prints out the last updated

> and last used time for each entry.

> 

Thank you so much!! This will be very helpful.

>>>  .B self

>>> -- the address is associated with the port drivers fdb. Usually hardware

>>> -  (default).

>>> +- the operation is fulfilled directly by the driver for the specified network

>>> +device. If the network device belongs to a master like a bridge, then the

>>> +bridge is bypassed and not notified of this operation (and if the device does

>>> +notify the bridge, it is driver-specific behavior and not mandated by this

>>> +flag, check the driver for more details). The "bridge fdb add" command can also

>>> +be used on the bridge device itself, and in this case, the added fdb entries

>>> +will be locally terminated (not forwarded). In the latter case, the "self" flag

>>> +is mandatory. 

>> Maybe I misunderstand this sentence, but I can do a 'bridge fdb add' without 'self'

>> on the bridge device. And the address shows up under 'bridge fdb show'.

>> So what does mandatory mean here?

> 

> It's right in the next sentence:

> 

>> The flag is set by default if "master" is not specified.

> 

> It's mandatory and implicit if "master" is not specified, ergo 'bridge

> fdb add dev br0' will work because 'master' is not specified (it is

> implicitly 'bridge fdb add dev br0 self'. But 'bridge fdb add dev br0

> master' will fail, because the 'self' flag is no longer implicit (since

> 'master' was specified) but mandatory and absent.

> 

> I'm not sure what I can do to improve this.

> 

Maybe the sentence under 'master':
" If the specified
+device is a master itself, such as a bridge, this flag is invalid."
is sufficient to defien this situation. And no need to explain mandatory implicit defaults
in the first paragraph?
Vladimir Oltean Feb. 15, 2021, 12:13 p.m. UTC | #4
On Mon, Feb 15, 2021 at 11:53:42AM +0100, Alexandra Winter wrote:
> Actually, I found your first (more verbose) proposal more helpful.


Sorry, I don't understand. Do you want me to copy the whole explanation
from bridge fdb add to bridge link set?

> >> Maybe I misunderstand this sentence, but I can do a 'bridge fdb add' without 'self'

> >> on the bridge device. And the address shows up under 'bridge fdb show'.

> >> So what does mandatory mean here?

> >

> > It's right in the next sentence:

> >

> >> The flag is set by default if "master" is not specified.

> >

> > It's mandatory and implicit if "master" is not specified, ergo 'bridge

> > fdb add dev br0' will work because 'master' is not specified (it is

> > implicitly 'bridge fdb add dev br0 self'. But 'bridge fdb add dev br0

> > master' will fail, because the 'self' flag is no longer implicit (since

> > 'master' was specified) but mandatory and absent.

> >

> > I'm not sure what I can do to improve this.

> >

> Maybe the sentence under 'master':

> " If the specified

> +device is a master itself, such as a bridge, this flag is invalid."

> is sufficient to defien this situation. And no need to explain mandatory implicit defaults

> in the first paragraph?


I don't understand this either. Could you paste here how you think this
paragraph should read?
Alexandra Winter Feb. 15, 2021, 12:33 p.m. UTC | #5
On 15.02.21 13:13, Vladimir Oltean wrote:
> On Mon, Feb 15, 2021 at 11:53:42AM +0100, Alexandra Winter wrote:

>> Actually, I found your first (more verbose) proposal more helpful.

> 

> Sorry, I don't understand. Do you want me to copy the whole explanation

> from bridge fdb add to bridge link set?

> 

>>>> Maybe I misunderstand this sentence, but I can do a 'bridge fdb add' without 'self'

>>>> on the bridge device. And the address shows up under 'bridge fdb show'.

>>>> So what does mandatory mean here?

>>>

>>> It's right in the next sentence:

>>>

>>>> The flag is set by default if "master" is not specified.

>>>

>>> It's mandatory and implicit if "master" is not specified, ergo 'bridge

>>> fdb add dev br0' will work because 'master' is not specified (it is

>>> implicitly 'bridge fdb add dev br0 self'. But 'bridge fdb add dev br0

>>> master' will fail, because the 'self' flag is no longer implicit (since

>>> 'master' was specified) but mandatory and absent.

>>>

>>> I'm not sure what I can do to improve this.

>>>

>> Maybe the sentence under 'master':

>> " If the specified

>> +device is a master itself, such as a bridge, this flag is invalid."

>> is sufficient to defien this situation. And no need to explain mandatory implicit defaults

>> in the first paragraph?

> 

> I don't understand this either. Could you paste here how you think this

> paragraph should read?

> 

Sorry, I did not mean to cause confusion. Your original proposal:
 .B self
-- the address is associated with the port drivers fdb. Usually hardware
-  (default).
+- the operation is fulfilled directly by the driver for the specified network
+device. If the network device belongs to a master like a bridge, then the
+bridge is bypassed and not notified of this operation (and if the device does
+notify the bridge, it is driver-specific behavior and not mandated by this
+flag, check the driver for more details). The "bridge fdb add" command can also
+be used on the bridge device itself, and in this case, the added fdb entries
+will be locally terminated (not forwarded). In the latter case, the "self" flag
+is mandatory. The flag is set by default if "master" is not specified.
 .sp
 
 .B master
-- the address is associated with master devices fdb. Usually software.
+- if the specified network device is a port that belongs to a master device
+such as a bridge, the operation is fulfilled by the master device's driver,
+which may in turn notify the port driver too of the address. If the specified
+device is a master itself, such as a bridge, this flag is invalid.
 .sp


The above is fine with me and IMHO much better than it is today.
But if you ask me I would change it to:

 .B self
- the operation is fulfilled directly by the driver for the specified physical device. 
If the network device belongs to a master like a bridge, then the
bridge is bypassed and not notified of this operation (and if the device does
notify the bridge, it is driver-specific behavior and not mandated by this
flag, check the driver for more details). The "bridge fdb add" command can also
be used on the bridge device itself, and in this case, the added fdb entries
will be locally terminated (not forwarded). The flag is set by default if "master" 
is not specified.
 .sp
 
 .B master
- if the specified network device is a port that belongs to a master device
such as a software bridge, the operation is fulfilled by the master device's driver,
which may in turn notify the port driver too of the address. If the specified
device is a master itself, such as a bridge, this flag is invalid.
 .sp
diff mbox series

Patch

diff --git a/man/man8/bridge.8 b/man/man8/bridge.8
index 1dc0aec83f09..d0bcd708bb61 100644
--- a/man/man8/bridge.8
+++ b/man/man8/bridge.8
@@ -533,12 +533,21 @@  specified.
 .sp
 
 .B self
-- the address is associated with the port drivers fdb. Usually hardware
-  (default).
+- the operation is fulfilled directly by the driver for the specified network
+device. If the network device belongs to a master like a bridge, then the
+bridge is bypassed and not notified of this operation (and if the device does
+notify the bridge, it is driver-specific behavior and not mandated by this
+flag, check the driver for more details). The "bridge fdb add" command can also
+be used on the bridge device itself, and in this case, the added fdb entries
+will be locally terminated (not forwarded). In the latter case, the "self" flag
+is mandatory. The flag is set by default if "master" is not specified.
 .sp
 
 .B master
-- the address is associated with master devices fdb. Usually software.
+- if the specified network device is a port that belongs to a master device
+such as a bridge, the operation is fulfilled by the master device's driver,
+which may in turn notify the port driver too of the address. If the specified
+device is a master itself, such as a bridge, this flag is invalid.
 .sp
 
 .B router