| Message ID | 20210211104502.2081443-6-olteanv@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | Clarifications to bridge man page | expand |
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 >
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.
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?
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?
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 --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