-
Story
-
Resolution: Won't Do
-
Minor
-
None
-
rhel-9.1.0
-
Low
-
rhel-net-mgmt
-
ssg_networking
-
None
-
False
-
False
-
-
None
-
None
-
None
-
None
-
If docs needed, set a value
-
-
x86_64
-
None
-
0
Section Number and Name:
Chapter 7. Configuring a network bridge
Describe the issue:
A bridge has many options that can be set. The documentation currently briefly shows/explains a few of them, scattered across the examples.
Some options are shown in the docs, some appear in nm-settings man page or the bridge man page, and some in the kernel bridge documentation. It's all spread across multiple places with no complete single source. We should aim to present a single comprehensive page to your customers in our RHEL docs.
https://people.freedesktop.org/~lkundrak/nm-docs/nm-settings.html
https://wiki.linuxfoundation.org/networking/bridge
The RHV documentation has a good explanation of some of the keys and can be used as a starting point for this improvement, but we are missing the details of what values can be set.
https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/html/administration_guide/appe-custom_network_properties#Explanation_of_bridge_opts_Parameters
Suggestions for improvement:
Aim to document all bridge configuration options, detailed not just the key description, but also possible values (minimum, maximum, default) and for values that are bitmasks (i.e. group_fwd_mask) let's try to document the protocols that each represents.
Ideally document all these:
% grep DEVICE_ATTR_RW net/bridge/br_sysfs_br.c
static DEVICE_ATTR_RW(forward_delay);
static DEVICE_ATTR_RW(hello_time);
static DEVICE_ATTR_RW(max_age);
static DEVICE_ATTR_RW(ageing_time);
static DEVICE_ATTR_RW(stp_state);
static DEVICE_ATTR_RW(group_fwd_mask);
static DEVICE_ATTR_RW(priority);
static DEVICE_ATTR_RW(group_addr);
static DEVICE_ATTR_RW(multicast_router);
static DEVICE_ATTR_RW(multicast_snooping);
static DEVICE_ATTR_RW(multicast_query_use_ifaddr);
static DEVICE_ATTR_RW(multicast_querier);
static DEVICE_ATTR_RW(hash_elasticity);
static DEVICE_ATTR_RW(hash_max);
static DEVICE_ATTR_RW(multicast_igmp_version);
static DEVICE_ATTR_RW(multicast_last_member_count);
static DEVICE_ATTR_RW(multicast_startup_query_count);
static DEVICE_ATTR_RW(multicast_last_member_interval);
static DEVICE_ATTR_RW(multicast_membership_interval);
static DEVICE_ATTR_RW(multicast_querier_interval);
static DEVICE_ATTR_RW(multicast_query_interval);
static DEVICE_ATTR_RW(multicast_query_response_interval);
static DEVICE_ATTR_RW(multicast_startup_query_interval);
static DEVICE_ATTR_RW(multicast_stats_enabled);
static DEVICE_ATTR_RW(multicast_mld_version);
static DEVICE_ATTR_RW(nf_call_iptables);
static DEVICE_ATTR_RW(nf_call_ip6tables);
static DEVICE_ATTR_RW(nf_call_arptables);
static DEVICE_ATTR_RW(vlan_filtering);
static DEVICE_ATTR_RW(vlan_protocol);
static DEVICE_ATTR_RW(default_pvid);
static DEVICE_ATTR_RW(vlan_stats_enabled);
static DEVICE_ATTR_RW(vlan_stats_per_port);
Having all this well documented in a single place would be better, and RHV can then just link the RHEL docs for a complete explanation, along with any other layered product that makes use of this.