bisdn / bisdn.github.io Goto Github PK

In the port mirroring section, the instructions do not mention how the port mirroring can be validated after being configured.

Suggested modifications:

• Figure with example of the mirroring scenario
• Mention that traffic needs to be captured on the interfaces that is connected to the mirrored switch port

Assuming the ofdpa MPLS PW extensions for ryu are in BISDN Linux, we should let users know how to use them.

In Basebox/OpenFlow, it is listed that table type specification guidelines are available, but there is no link or additional information on where to find them. Adding such link would make it more clear on these guidelines.

Similarly, a link for OF-DPA could be nice to have here when mentioning "Broadcom OF-DPA".

The introduction to bridging could first provide an overview of bridging, followed by the requirement of having the vlan_filtering flag set to 1.

In addition, the supported types of configuring bridging (iproute2 and systemd-networkd) could be listed before iproute2, so the user can know the possibilities in advance.

When searching for BISDN Linux in at least google, the first hit is our docs, and not even the official page.

So it would be good if the main page would be a bit more welcoming, and link to the official site, and talk about what this (docs.) page is about.

There is a "Networking Configuration" subsection under Getting Started and another section on the side pane.

On the Networking Configuration subsection from Getting Started, it is also mentioned:

To configure more complex scenarios, please refer to the Network Configuration section.

The Networking Configuration subsection under Getting Started could be renamed to e.g. Basic Networking, or Basic Network Connectivity, to avoid confusion and avoid repeating section names.

In Install BISDN Linux via ONIE, the post-installation instructions are listed within the previous Get the image via DHCP option 60 subsection.

A separated subsection, e.g. Post image installation can make these instructions more clear, as they are also applied to the CLI image download instructions.

In addition, it can also be relevant to state here that the switch can now be accessed through SSH as well, if a management network port is set.

In https://docs.bisdn.de/setup/install_switch_image.html#install-bisdn-linux-via-onie :

The available image download alternatives could be listed before Get the image via the CLI with links to the respective section. This would allow the user to go straight to its preferred download option.

The QinQ configuration instructions only have iproute2 listed. The new 802.1ad instructions with systemd-networkd should be added here.

https://docs.bisdn.de/network_configuration/static_routing.html#iproute2-1, https://docs.bisdn.de/network_configuration/ospf.html#ospfv3 and https://docs.bisdn.de/network_configuration/bgp.html#bgp-for-ipv6-networks configure networks with ipv6 address a 2003 prefix. This prefix seems to be meant for reservation (Telekom has 2003:: /19 for example.

Should these be changed to a private range like

In Configure a local or remote controller, the part about "the integration of system networking events" should be more clear regarding what kind of events are not integrated. In this case, replacing

system networking events

with

Linux networking events

would make this more clear, for example.

In Configure a local or remote controller , the basebox-change-config commands won't work without super user permissions. Adding sudo before each command would make this clear.

Similar to that, all commands in this documentation that require super user permissions should also have sudo before.

Overall I like the documentation for basebox.
However, in the transition between the 'Getting-Started->Basic Networking' and the 'Network-Configuration' part, I still miss a section that picks up old-fashioned network users like me.
When one of these people hears the term 'switch', he/she thinks of a simple MAC-learning switch, like a Cisco 2960, on which all interfaces are active by default and forward traffic. But the basebox config is more oriented to virtual switching in a host VM of a Linux system.
Would it be possible to add a chapter under 'Getting Started', which explains the basic differences in the approach (interfaces disabled, no traffic-forwarding out of the box) and present a minimal example for the configuration of a simple MAC-learning switch? The rest with VLANs, STP is well explained, but I find the conceptual gap quite high for someone who wants to configure and use such a system for the first time and possibly brings a CCNA to the table, but has never done any Linux networking...

In: https://github.com/bisdn/bisdn.github.io/blob/master/setup/install_switch_image.md#connect-to-the-switch-console :

CLI running instructions for ckermit should be provided, preferably with a link with its documentation, e.g.:

Usage: kermit [filename]

Alternatively, instructions for minicom could also be added, by first stating that the user can connect to the switch through a serial connection using a software of its choice.

In Configure a local or remote controller, the list of supported local controllers would clarify more the user about its controller configuration possibilities.

When describing Ryu or other internal controllers different than basebox, the involved main limitation could also be stated (for example, no integration with Linux networking events from the switch).

The OSPF configuration and BGP configuration pages are missing an introductory text, as it can be found in the other network configuration subsections.

To make these documentations more consistent, an overview of the routing protocols could be provided in the introductory texts from these sections, for example.

Listed among the tools bundled with the switch image is FRR
https://docs.bisdn.de/setup/setup_standalone.html#frrouting

Our revised-docs seems to be missing this. This would belong in the 'Tools' section.

In Local controller (BISDN Linux), the example for opkg info has service-name written as a normal parameter of the command. Suggested modification could be [SERVICE_NAME] or equivalent.

In the first paragraph of Persisting network configuration, there is a broken reference for systemd-networkd, i.e.:

:ref:”systemd-networkd”

Both first and second paragraphs should be rewritten, in addition to fixing the broken link.

The bisdn-change-config subsection is misspelled, as the bisdn-change-config command does not exist. Title should be changed to basebox-change-config.