[Question] Any plan to write/update the bridge doc?

[Question] Any plan to write/update the bridge doc?

[Hangbin Liu]

Hi,

Maybe someone already has asked. The only official Linux bridge document I
got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are
many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
document about each parameter? The parameter showed in ip link page seems
a little brief.

I'd like to help do this work. But apparently neither my English nor my
understanding of the code is good enough. Anyway, if you want, I can help
write a draft version first and you (bridge maintainers) keep working on this.

[1] https://wiki.linuxfoundation.org/networking/bridge
[2] https://man7.org/linux/man-pages/man8/bridge.8.html
[3] https://man7.org/linux/man-pages/man8/ip-link.8.html

Thanks
Hangbin

Re: [Question] Any plan to write/update the bridge doc?

[Ido Schimmel]

On Mon, Apr 24, 2023 at 05:25:08PM +0800, Hangbin Liu wrote:
> Hi,
> 
> Maybe someone already has asked. The only official Linux bridge document I
> got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are
> many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
> document about each parameter? The parameter showed in ip link page seems
> a little brief.

I suggest improving the man pages instead of adding kernel
documentation. The man pages are the most up to date resource and
therefore the one users probably refer to the most. Also, it's already
quite annoying to patch both "ip-link" and "bridge" man pages when
adding bridge port options. Adding a third document and making sure all
three resources are patched would be a nightmare...

> 
> I'd like to help do this work. But apparently neither my English nor my
> understanding of the code is good enough. Anyway, if you want, I can help
> write a draft version first and you (bridge maintainers) keep working on this.

I can help reviewing man page patches if you want. I'm going to send
some soon. Will copy you.

> 
> [1] https://wiki.linuxfoundation.org/networking/bridge
> [2] https://man7.org/linux/man-pages/man8/bridge.8.html
> [3] https://man7.org/linux/man-pages/man8/ip-link.8.html
> 
> Thanks
> Hangbin

Re: [Question] Any plan to write/update the bridge doc?

[Stephen Hemminger]

On Mon, 24 Apr 2023 18:46:53 +0300
Ido Schimmel <idosch@nvidia.com> wrote:

> On Mon, Apr 24, 2023 at 05:25:08PM +0800, Hangbin Liu wrote:
> > Hi,
> > 
> > Maybe someone already has asked. The only official Linux bridge document I
> > got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are
> > many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
> > document about each parameter? The parameter showed in ip link page seems
> > a little brief.  
> 
> I suggest improving the man pages instead of adding kernel
> documentation. The man pages are the most up to date resource and
> therefore the one users probably refer to the most. Also, it's already
> quite annoying to patch both "ip-link" and "bridge" man pages when
> adding bridge port options. Adding a third document and making sure all
> three resources are patched would be a nightmare...
> 
> > 
> > I'd like to help do this work. But apparently neither my English nor my
> > understanding of the code is good enough. Anyway, if you want, I can help
> > write a draft version first and you (bridge maintainers) keep working on this.  
> 
> I can help reviewing man page patches if you want. I'm going to send
> some soon. Will copy you.
> 
> > 
> > [1] https://wiki.linuxfoundation.org/networking/bridge
> > [2] https://man7.org/linux/man-pages/man8/bridge.8.html
> > [3] https://man7.org/linux/man-pages/man8/ip-link.8.html
> > 
> > Thanks
> > Hangbin  

Yes, please update the iproute2 man pages.
From there, I can make the old wiki just be a reference to them.
And Michael will pickup the man7.org versions from the current iproute2.

The iproute2 git tree is single source of current documentation please.

Re: [Question] Any plan to write/update the bridge doc?

[Jakub Kicinski]

On Mon, 24 Apr 2023 17:25:08 +0800 Hangbin Liu wrote:
> Maybe someone already has asked. The only official Linux bridge document I
> got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are
> many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
> document about each parameter? The parameter showed in ip link page seems
> a little brief.
> 
> I'd like to help do this work. But apparently neither my English nor my
> understanding of the code is good enough. Anyway, if you want, I can help
> write a draft version first and you (bridge maintainers) keep working on this.
> 
> [1] https://wiki.linuxfoundation.org/networking/bridge
> [2] https://man7.org/linux/man-pages/man8/bridge.8.html
> [3] https://man7.org/linux/man-pages/man8/ip-link.8.html

Sounds like we have 2 votes for the CLI man pages but I'd like to
register a vote for in-kernel documentation.

I work at a large company so my perspective may differ but from what 
I see:

 - users who want to call the kernel API should not have to look at 
   the CLI's man
 - man pages use archaic and arcane markup, I'd like to know how many
   people actually know how it works and how many copy / paste / look;
   ReST is prevalent, simple and commonly understood
 - in-kernel docs are rendered on the web as soon as they hit linux-next
 - we can make sure documentation is provided with the kernel changes,
   in an ideal world it doesn't matter but in practice the CLI support
   may never happen (no to mention that iproute does not hold all CLI)

Obviously if Stephen and Ido prefer to document the bridge CLI that's
perfectly fine, it's their call :) For new sections of uAPI, however,
I personally find in-kernel docs superior.

Re: [Bridge] [Question] Any plan to write/update the bridge doc?

[Stephen Hemminger]

On Mon, 24 Apr 2023 14:28:00 -0700
Jakub Kicinski <kuba@kernel.org> wrote:

> On Mon, 24 Apr 2023 17:25:08 +0800 Hangbin Liu wrote:
> > Maybe someone already has asked. The only official Linux bridge document I
> > got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are
> > many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
> > document about each parameter? The parameter showed in ip link page seems
> > a little brief.
> > 
> > I'd like to help do this work. But apparently neither my English nor my
> > understanding of the code is good enough. Anyway, if you want, I can help
> > write a draft version first and you (bridge maintainers) keep working on this.
> > 
> > [1] https://wiki.linuxfoundation.org/networking/bridge
> > [2] https://man7.org/linux/man-pages/man8/bridge.8.html
> > [3] https://man7.org/linux/man-pages/man8/ip-link.8.html  
> 
> Sounds like we have 2 votes for the CLI man pages but I'd like to
> register a vote for in-kernel documentation.
> 
> I work at a large company so my perspective may differ but from what 
> I see:
> 
>  - users who want to call the kernel API should not have to look at 
>    the CLI's man

Internal Kernel API's are not stable. So documentation is only the auto
generated kernel docs.

There is an effort to cover netlink API's with YAML. Bridge could/should
be part of that.

>  - man pages use archaic and arcane markup, I'd like to know how many
>    people actually know how it works and how many copy / paste / look;
>    ReST is prevalent, simple and commonly understood

Yes, but that is what distributions want.

>  - in-kernel docs are rendered on the web as soon as they hit linux-next
>  - we can make sure documentation is provided with the kernel changes,
>    in an ideal world it doesn't matter but in practice the CLI support
>    may never happen (no to mention that iproute does not hold all CLI)
> 
> Obviously if Stephen and Ido prefer to document the bridge CLI that's
> perfectly fine, it's their call :) For new sections of uAPI, however,
> I personally find in-kernel docs superior.


The in-kernel documents usually only cover the architecture and motivation.
What/why/how... Not the user visible public API's.

Re: [Question] Any plan to write/update the bridge doc?

[Hangbin Liu]

On Mon, Apr 24, 2023 at 02:28:00PM -0700, Jakub Kicinski wrote:
> On Mon, 24 Apr 2023 17:25:08 +0800 Hangbin Liu wrote:
> > Maybe someone already has asked. The only official Linux bridge document I
> > got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are
> > many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
> > document about each parameter? The parameter showed in ip link page seems
> > a little brief.
> > 
> > I'd like to help do this work. But apparently neither my English nor my
> > understanding of the code is good enough. Anyway, if you want, I can help
> > write a draft version first and you (bridge maintainers) keep working on this.
> > 
> > [1] https://wiki.linuxfoundation.org/networking/bridge
> > [2] https://man7.org/linux/man-pages/man8/bridge.8.html
> > [3] https://man7.org/linux/man-pages/man8/ip-link.8.html
> 
> Sounds like we have 2 votes for the CLI man pages but I'd like to
> register a vote for in-kernel documentation.
> 
> I work at a large company so my perspective may differ but from what 
> I see:
> 
>  - users who want to call the kernel API should not have to look at 
>    the CLI's man
>  - man pages use archaic and arcane markup, I'd like to know how many
>    people actually know how it works and how many copy / paste / look;
>    ReST is prevalent, simple and commonly understood

+1 for the obscure man page syntax. I can only do copy/paste when update it..

>  - in-kernel docs are rendered on the web as soon as they hit linux-next
>  - we can make sure documentation is provided with the kernel changes,
>    in an ideal world it doesn't matter but in practice the CLI support
>    may never happen (no to mention that iproute does not hold all CLI)

Yes. I saw bpf code add the doc in the header file (include/uapi/linux/bpf.h)
and generate to syscall page[1] or man page[2] directly. Another example is the
statistics.rst document, which takes *struct rtnl_link_stats64* description
drectly from the if_link.h. This should save a lot works to maintain another
file in Documentation. Maybe we can strive in this direction?

For example, we can just add descriptions for the enum in if_bridge.h and
if_link.h when add new features.
> 
> Obviously if Stephen and Ido prefer to document the bridge CLI that's
> perfectly fine, it's their call :) For new sections of uAPI, however,
> I personally find in-kernel docs superior.

I understand the hard work to maintain docs in 3 different places with
different syntax (ip-link, bridge, in-kernel). Since we will sync the uapi
headers from kernel to iproute2. Can we use the similar way like kernel does
in iproute2. i.e. Link the header file's description in a document and
convert it to man page via rst2man? With this way we only need to maintain
the doc in 1 place, the kernel uapi headers.

NOTE: there may still need some adjustment in the iproute2 man page when add
new arguments.

[1] https://docs.kernel.org/userspace-api/ebpf/syscall.html
[2] https://man7.org/linux/man-pages/man7/bpf-helpers.7.html
[3] https://docs.kernel.org/networking/statistics.html

Thanks
Hangbin

Re: [Question] Any plan to write/update the bridge doc?

[Nikolay Aleksandrov]

On 24/04/2023 18:46, Ido Schimmel wrote:
> On Mon, Apr 24, 2023 at 05:25:08PM +0800, Hangbin Liu wrote:
>> Hi,
>>
>> Maybe someone already has asked. The only official Linux bridge document I
>> got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are
>> many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
>> document about each parameter? The parameter showed in ip link page seems
>> a little brief.
> 
> I suggest improving the man pages instead of adding kernel
> documentation. The man pages are the most up to date resource and
> therefore the one users probably refer to the most. Also, it's already
> quite annoying to patch both "ip-link" and "bridge" man pages when
> adding bridge port options. Adding a third document and making sure all
> three resources are patched would be a nightmare...
> 
>>
>> I'd like to help do this work. But apparently neither my English nor my
>> understanding of the code is good enough. Anyway, if you want, I can help
>> write a draft version first and you (bridge maintainers) keep working on this.
> 
> I can help reviewing man page patches if you want. I'm going to send
> some soon. Will copy you.
> 
>>
>> [1] https://wiki.linuxfoundation.org/networking/bridge
>> [2] https://man7.org/linux/man-pages/man8/bridge.8.html
>> [3] https://man7.org/linux/man-pages/man8/ip-link.8.html
>>
>> Thanks
>> Hangbin

Always +1 for keeping the man pages up-to-date, but I tend to agree with Jakub as well
that it'd be nice to have an in-kernel doc which explains the uapi and potentially
at least some more obscure internals (if not all), we can insist on updating it
for new changes

I'd be happy to help fill such doc, but at the moment I don't have the
time to write the basis for it. As Hangbin nicely offered, I think we can start
there. For a start it'd be nice to make an initial outline of the different sections
and go on filling them from there.

E.g. as a starter something like (feel free to edit):
Introduction
Bridge internals (fdb, timers, MTU handling, fwding decisions, ports, synchronization)
STP (mst, rstp, timers, user-space stp etc)
Multicast (mdb, igmp, eht, vlan-mcast etc)
VLAN (filtering, options, tunnel...)
Switchdev
Netfilter
MRP/CFM (?)
FAQ

Each of these having uapi sections with descriptions. We can include references
to the iproute2 docs for cmd explanations and examples, but in this doc we'll have
the uapi descriptions and maybe some helpful information about internal implementation
that would save future contributors time.

At the very least we can do the uapi part for each section so options are described
and uapi nl attribute structures are explained.

Cheers,
 Nik

Re: [Question] Any plan to write/update the bridge doc?

[Hangbin Liu]

On Tue, Apr 25, 2023 at 11:04:47AM +0300, Nikolay Aleksandrov wrote:
> Always +1 for keeping the man pages up-to-date, but I tend to agree with Jakub as well
> that it'd be nice to have an in-kernel doc which explains the uapi and potentially
> at least some more obscure internals (if not all), we can insist on updating it
> for new changes
> 
> I'd be happy to help fill such doc, but at the moment I don't have the
> time to write the basis for it. As Hangbin nicely offered, I think we can start
> there. For a start it'd be nice to make an initial outline of the different sections
> and go on filling them from there.
> 
> E.g. as a starter something like (feel free to edit):
> Introduction
> Bridge internals (fdb, timers, MTU handling, fwding decisions, ports, synchronization)
> STP (mst, rstp, timers, user-space stp etc)
> Multicast (mdb, igmp, eht, vlan-mcast etc)
> VLAN (filtering, options, tunnel...)
> Switchdev
> Netfilter
> MRP/CFM (?)
> FAQ
> 
> Each of these having uapi sections with descriptions. We can include references
> to the iproute2 docs for cmd explanations and examples, but in this doc we'll have
> the uapi descriptions and maybe some helpful information about internal implementation
> that would save future contributors time.
> 
> At the very least we can do the uapi part for each section so options are described
> and uapi nl attribute structures are explained.

OK, I will try start a draft version after the Labor holiday.

Hangbin