`man nm-settings` and related manual pages have several shortcomings, that should be fixed.
The biggest one, is that `man nm-settings` is undecided what it wants to document.
We have
1) settings in D-Bus API
- man nm-settings
2) properties in `nmcli connection`
- man nmcli
3) NMSetting API in libnm
- gtk-doc API
4) settings in keyfile format
- man nm-settings-keyfile
5) settings in ifcfg-rh format
- man nm-settings-ifcfg-rh
Of course, all these variants are related and often similar. However, there are subtle differences.
What users are most interested in, is probably information how to use nmcli. However, `man nmcli` only details aliases. For the rest, the user would look at `man nm-settings`.
What is `man nm-settings` supposed to document? The D-Bus API? Or the properties for an nmcli user? We should make up our mind. Currently, there is no distinct manual for (1) and (2).
If we interpret `man nm-settings` as documenting nmcli settings (2), then we should add a `man nm-settings-dbus` for (1).
Otherwise, `man nmcli` should contain the entire list of settings and `man nm-settings` should clearly describe the D-Bus API.
Some differences, and note how our current man pages fail to accurately document them, depending on what you look:
- ipv4.addresses
- on D-Bus, they are called both "addresses" and "address-data"
- in nmcli, they are called "ipv4.addresses", if there are multiple
addresses, they can be added/removed with +ipv4.addresses/-ipv4.addresses.
- in keyfile, they are persisted as address1, address2.
- ethernet.cloned-mac-address
- on D-Bus, it's both "cloned-mac-address" and "assigned-mac-address"
- on nmcli and keyfile, there is only "cloned-mac-address"
- bond.options
- this is an "artificial" hash in libnm. On D-Bus and keyfile, their content
is "unpacked". E.g. we handle "bond.mode", not a nested "options"
dictionary.
- on nmcli, bond.options has a very odd usage, which is inconsistent and
inconvenient to use. That would be fixable, but well.
- either way, the manual does not explain which bond options actually exist
and which values they can take.
- user.data
- in nmcli, this is not yet supported (todo).
- on keyfile, the user data is unpacked, and stored as "user.$NAME" (good)
- on D-Bus, the user data is in a nested "user.data" setting (bad).
- ethtool.* (e.g. "ethtool.feature-lro")
- on D-Bus, keyfile, and nmcli the usage is nice (how one would expect).
However, the options are not implemented as a GObject property, so we
currently cannot generate documntation for them. The solution is not to add
GObject properties, but to extend the way how we generate documentation.
- team settings
- dunno.
- note that some properties only exist on D-Bus and vice versa. For example,
ethernet.assigned-mac-address. A nmcli user looking at `man nm-settings`
will be confused.
We should make a clear distinction which manual documents which aspect (the 5 aspects above). Second, look at above examples, and ensure they are properly document in each aspect.
Comment 2Marcelo Ricardo Leitner
2019-07-03 15:09:35 UTC
Mass-moving bugs RHEL <= 7.6.0 to 7.7.0.
As we are past RFE deadline for 7.7.0 and we should have no new features on 7.8.0, please evaluate if it's still wanted on RHEL7 and contact PM for exception. You may also move it to RHEL8 if that's wanted. Thanks!
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.
For information on the advisory (NetworkManager bug fix and enhancement update), and where to find the updated
files, follow the link below.
If the solution does not work for you, open a new bug report.
https://access.redhat.com/errata/RHBA-2020:4499
`man nm-settings` and related manual pages have several shortcomings, that should be fixed. The biggest one, is that `man nm-settings` is undecided what it wants to document. We have 1) settings in D-Bus API - man nm-settings 2) properties in `nmcli connection` - man nmcli 3) NMSetting API in libnm - gtk-doc API 4) settings in keyfile format - man nm-settings-keyfile 5) settings in ifcfg-rh format - man nm-settings-ifcfg-rh Of course, all these variants are related and often similar. However, there are subtle differences. What users are most interested in, is probably information how to use nmcli. However, `man nmcli` only details aliases. For the rest, the user would look at `man nm-settings`. What is `man nm-settings` supposed to document? The D-Bus API? Or the properties for an nmcli user? We should make up our mind. Currently, there is no distinct manual for (1) and (2). If we interpret `man nm-settings` as documenting nmcli settings (2), then we should add a `man nm-settings-dbus` for (1). Otherwise, `man nmcli` should contain the entire list of settings and `man nm-settings` should clearly describe the D-Bus API. Some differences, and note how our current man pages fail to accurately document them, depending on what you look: - ipv4.addresses - on D-Bus, they are called both "addresses" and "address-data" - in nmcli, they are called "ipv4.addresses", if there are multiple addresses, they can be added/removed with +ipv4.addresses/-ipv4.addresses. - in keyfile, they are persisted as address1, address2. - ethernet.cloned-mac-address - on D-Bus, it's both "cloned-mac-address" and "assigned-mac-address" - on nmcli and keyfile, there is only "cloned-mac-address" - bond.options - this is an "artificial" hash in libnm. On D-Bus and keyfile, their content is "unpacked". E.g. we handle "bond.mode", not a nested "options" dictionary. - on nmcli, bond.options has a very odd usage, which is inconsistent and inconvenient to use. That would be fixable, but well. - either way, the manual does not explain which bond options actually exist and which values they can take. - user.data - in nmcli, this is not yet supported (todo). - on keyfile, the user data is unpacked, and stored as "user.$NAME" (good) - on D-Bus, the user data is in a nested "user.data" setting (bad). - ethtool.* (e.g. "ethtool.feature-lro") - on D-Bus, keyfile, and nmcli the usage is nice (how one would expect). However, the options are not implemented as a GObject property, so we currently cannot generate documntation for them. The solution is not to add GObject properties, but to extend the way how we generate documentation. - team settings - dunno. - note that some properties only exist on D-Bus and vice versa. For example, ethernet.assigned-mac-address. A nmcli user looking at `man nm-settings` will be confused. We should make a clear distinction which manual documents which aspect (the 5 aspects above). Second, look at above examples, and ensure they are properly document in each aspect.