This commit fixes the build process for the documentation that was previously
unable to build separately via meson due to a dependency issue.
Previously, trying to build the API documentation via `ninja NetworkManager-doc`
failed due to missing dependencies (for example, `nm-dbus-types.xml` was not built).
I believe this happens due to some different handling of static paths vs. custom_target
by meson in this case.
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1801
Fixes: 03637ad8b5 ('build: add initial support for meson build system')
README.md:
As this document is mainly for normal users, and in Gitlab it's
displayed by default, it's the main entry point to get information when
someone get into the repo, either via web or cloned.
Added explanations about how to install and use NM and how to find the
documentation for users. Added brief info about how to report issues
and ask for help, with links to CONTRIBUTING.md to get more details.
Added brief link for potential contributors to read CONTRIBUTING.md.
People not familiar with open source projects might not be aware of it.
Deleted the "moved to freedesktop" message. After 15 years, people might
know yet.
Added brief explanation about the free software license.
CONTRIBUTING.md:
Added a link to the list of all communication channels, only mailing
list and IRC were listed.
Added detailed explanation about how to report issues and attach logs.
It also references the new tool anonymize-logs.py.
Added brief guidelines about how to start contributing choosing issues
from the tracker.
Fixed some small formatting issues and added a reference to nm-in-vm,
fixing the link to nm-in-container too.
MAINTAINERS.md:
Added explanation about how to triage and properly label the issues.
This is basically based on the kind-of-workflow that we already have,
but maybe it's a good time to check that it's correct or to propose
small changes (so, please propose changes in review).
If ID_NET_MANAGED_BY= attribute is set, we have an indication who is
responsible for the device. If this is set to anything but
"org.freedesktop.NetworkManager", then the device is unmanaged.
The effect is the same as setting NM_UNMANAGED= attribute. NM_UNMANAGED=
takes precedence over this setting.
See-also: https://github.com/systemd/systemd/issues/29768
See-also: https://github.com/systemd/systemd/pull/29782
We honored "NM_AUTO_DEFAULT_LINK_LOCAL_ONLY" udev property, for when we
generate a "Wired connection 1" (aka the "auto-default connection").
Systemd now also honors and may set ID_NET_AUTO_LINK_LOCAL_ONLY for
a similar purpose. Honore that too.
The NM specific variable still is preferred, also because "NM_AUTO_DEFAULT_LINK_LOCAL_ONLY"
is about something very NetworkManager specific (controlling "Wired connection 1").
Maybe one day, we should drop "data/90-nm-thunderbolt.rules" and only
rely on what systemd provides. But not yet.
See-also: https://github.com/systemd/systemd/pull/29767https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/1413
An empty value NO_COLOR= should not be treated to disable colors.
This is also what [1] says (changed a while ago [2]).
[1] https://no-color.org/
[2] 99f90e27d0
Addition of list and string is allowed but only from version 0.60 of
meson. We claim to support building with meson 0.47, and there are
distributions like Debian and CentOS Stream 8 that uses versions older
than 0.60. Fix it by converting the offending string to a single item
list.
On newer versions, we get this warning only:
Project targets '>= 0.47.2' but uses feature introduced in
'0.60.0': list.<plus>. The right hand operand was not a list.
Fixes: 984642e33f ('build: meson: fix some missing dependencies')
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1737
Some targets related to documentation generation had missing
dependencies, like xsl templates or the python generator. If these files
are changed, their output changes too, but as they were not listed as
dependencies (custom_target's input), meson wasn't aware.
In Makefile.am they already were correctly listed as dependencies.
Gtkdoc comments are used, among other things, to generate the various
nm-setting-* manual pages. When a constant is referenced in a gtkdoc
comment (i.e. `%NM_IP_TUNNEL_MODE_IPIP`) it is expanded to show the C name
and the value (i.e. `NM_IP_TUNNEL_MODE_IPIP (1)`). To generate the
nm-setting-* manual pages, we don't use gtkdoc, but we process this data
with the custom script tools/generate-docs-nm-settings-docs-gir.py.
This script was expanding the constants in the same way than gtkdoc.
Showing the constants in that way in nm-setting-* manual pages makes
little sense, because users are not going to use the C identifiers.
Let's show them with a more appropriate format.
Additionally, the different nm-setting-* pages might require different
formats than the other. For example, for nm-setting-nmcli a format like
`"ipip" (1)` is prefered, but for nm-setting-dbus it's better
`1 (ipip)`. Let's generate different nm-settings-docs-gir-*.xml files for
nmcli, dbus, keyfile and ifcfg-rh, using the right format for each one.
If there are properties that accept special values apart from the
normally accepted values, or any of those values has an special meaning,
it can be shown as "Special value", indicating the nicknames and numbers
that can be used to select it.
Show a new field called "Valid values" in those properties that only
accept a limited set of values, like enums, ints with a valid range of
values, etc.
As there is some complex logic behind getting this information, this
logic has been put in nm-meta-setting-desc and nm-enum-utils so they can
be re-used, avoiding duplicity and errors. Some refactor has been done
in nm-meta-setting-desc in this direction, too.
Separate the explanation of the format in various paragraphs so it is
better structured and easier to follow and understand.
Add a note about the properties that, instead of using a semicolon
separated list, use individual key-value pairs per list element
(addresses, routes and routing-rules), since this is also a relevant
difference from the standard key file format and from the settings
specification format.
The default behavior is not to rename profiles. I guess, that makes
sense, as renaming a file when changing the "connection.id" could break
users who rely on the name.
My use case is the following. When I connect a Wi-Fi hotspot I use
`nmcli device wifi connect $SSID`, which -- as expected -- persists the
profile to "/etc/NetworkManager/system-connections/$SSID.nmconnection".
Later, I always update the profile's name to "w_$SSID" so I can see on
the name that this is wireless profile. I also want the filename to
reflect that change of name.
Add a configuration option for that. All the infrastructure
("force_rename" parameter) already exists.
Fail to save a connection with a 'link' setting instead of just
ignoring it. Now:
$ nmcli connection add type ethernet ifname foobar
Connection 'ethernet-foobar' (c3f6f067-e1d5-4bb1-8d67-e09109253a79) successfully added.
$ nmcli connection modify ethernet-foobar link.tx-queue-length 1234
Error: Failed to modify connection 'ethernet-foobar': failed to update connection: The ifcfg-rh plugin doesn't support setting 'link'. If you are modifying an existing connection profile saved in ifcfg-rh format, please migrate the connection to keyfile using 'nmcli connection migrate c3f6f067-e1d5-4bb1-8d67-e09109253a79' or via the Update2() D-Bus API and try again.
$ nmcli connection migrate c3f6f067-e1d5-4bb1-8d67-e09109253a79
Connection 'ethernet-foobar' (c3f6f067-e1d5-4bb1-8d67-e09109253a79) successfully migrated.
$ nmcli connection modify ethernet-foobar link.tx-queue-length 1234
$
Fixes: 39bfcf7aab ('all: add "link" setting')
<description> is now an XML element, no longer an attribute. Fix the
style sheets.
Fixes: 89abede3df ('docs: rework generating property infos to use <description> element')
"generate-docs-nm-settings-docs-merge.py" merges properties from
multiple XMLs. It supported an argument "--only-from-first", to
only select properties that were in the first of the provided XMLs.
The idea is that the first XML would be "src/nmcli/gen-metadata-nm-settings-nmcli.xml"
which is generated from nmcli meta-data and exactly describes the
supported properties. For example, "connection.read-only", "user.data"
or "wireless.tx-power" exist as properties somewhere, but not supported
by nmcli.
Change that, to not tie the selected property to the first XML.
"gen-metadata-nm-settings-nmcli.xml" is the XML that contains which
properties to select from, but "src/libnm-client-impl/nm-property-infos-nmcli.xml"
contains hand crafted descriptions. The latter descriptions are
preferred. As the order of the XML is already relevant for which
description is preferred, the selection is orthogonal to that.
With this, prefer descriptions from "src/libnm-client-impl/nm-property-infos-nmcli.xml"
but still select properties from "src/nmcli/gen-metadata-nm-settings-nmcli.xml".
Note that the argument is only used to generate "man/nm-settings-docs-nmcli.xml",
and with the current input, there is no actual change in behavior.
When we generate the manual page for nm-settings-nmcli, we run:
"/usr/bin/python" \
./tools/generate-docs-nm-settings-docs-merge.py \
--only-from-first \
man/nm-settings-docs-nmcli.xml \
src/nmcli/gen-metadata-nm-settings-nmcli.xml \
src/libnm-client-impl/nm-property-infos-nmcli.xml \
src/libnm-client-impl/nm-settings-docs-gir.xml
If "gen-metadata-nm-settings-nmcli.xml" contains either a <description>
or a <description-docbook>, then we must not continue searching the
other XML documents. The user provided an explicit override, and
fallback (search further) is wrong. Previously, we might take
<description> from the first file, and <description-docbook> from the
second file. As "man/nm-settings-nmcli.xsl" prefers
<description-docbook>, it takes the wrong text. Instead, as we search
the files during merge, we must prefer the first one.
Note that the change doesn't really matter anymore, because each XML
now must also contain both <description> and <description-docbook>.
There is an assertion for that.
Also, stop generating <deprecated-docbook>. First, it lacked the
important "since=" attribute and was necessary. Also, it's redundant and
does not contain anything interesting. So far, we don't need special
formatting for the deprecated message, and we likely never will.
Also, stop accepting or generating the "description=" attribute. This
should always be an XML element now.
The input always actually has a <description-docbook> field, so the secret-flags
hint was never shown.
Move it. It's indepenent from <description> and <description-docbook> anyway.
With this we see the expected messages
See the section called “Secret flag types:” for flag values.
The manual page is large. When you search for a properties, then it's
not immediately clear to which setting it belongs. You would have to
scroll up for the setting name.
This also makes sense for the nmcli manual page, because on the command
line you have to specify the full name.
Now the settings in the [global-dns] section are used *in addition* to
connection-specific ones. Only the global domains sections, when
valid, override connection settings. Update the man page to clarify
that.
Fixes: 1f0d1d78d2 ('dns-manager: always apply options from [global-dns]')
NetworkManager dispatcher will now run dispatcher scripts with 'reapply'
as action as well. Each time the connection is reapplied on a device,
this action is triggered. Document this action in the documentation.
(cherry picked from commit 0e3d2c367c)
Support managing the loopback interface through NM as the users want to
set the proper mtu for loopback interface when forwarding the packets.
Additionally, the IP addresses, DNS, route and routing rules are also
allowed to configure for the loopback connection profiles.
https://bugzilla.redhat.com/show_bug.cgi?id=2060905
This is the better name, becuse this is not in particular about "docs".
It's about generating an XML with the information from the settings
meta data for nmcli.
We will do something similar with the libnm-core meta data.
1) The "enabled-on-global-iface" flag was odd. Instead, have only
and "enabled" flag and skip (by default) endpoints on interface
that have no default route. With the new flag "also-without-default-route",
this can be overruled. So previous "enabled-on-global-default" now is
the same as "enabled", and "enabled" from before behaves now like
"enabled,also-without-default-route".
2) What was also odd, as that the fallback default value for the flags
depends on "/proc/sys/net/mptcp/enabled". There was not one fixed
fallback default, instead the used fallback value was either
"enabled-on-global-iface,subflow" or "disabled".
Usually that is not a problem (e.g. the default value for
"ipv6.ip6-privacy" also depends on use_tempaddr sysctl). In this case
it is a problem, because the mptcp-flags (for better or worse) encode
different things at the same time.
Consider that the mptcp-flags can also have their default configured in
"NetworkManager.conf", a user who wants to switch the address flags
could previously do:
[connection.mptcp]
connection.mptcp-flags=0x32 # enabled-on-global-iface,signal,subflow
but then the global toggle "/proc/sys/net/mptcp/enabled" was no longer
honored. That means, MPTCP handling was always on, even if the sysctl was
disabled. Now, "enabled" means that it's only enabled if the sysctl
is enabled too. Now the user could write to "NetworkManager.conf"
[connection.mptcp]
connection.mptcp-flags=0x32 # enabled,signal,subflow
and MPTCP handling would still be disabled unless the sysctl
is enabled.
There is now also a new flag "also-without-sysctl", so if you want
to really enable MPTCP handling regardless of the sysctl, you can.
The point of that might be, that we still can configure endpoints,
even if kernel won't do anything with them. Then you could just flip
the sysctl, and it would start working (as NetworkManager configured
the endpoints already).
Fixes: eb083eece5 ('all: add NMMptcpFlags and connection.mptcp-flags property')
(cherry picked from commit c00873e08f)
When NetworkManager runs in initrd, it can be cumbersome to enable debug logging.
Granted, when using dracut, the NetworkManager dracut module will honor "rd.debug".
However, a user may use NetworkManager in initrd without dracut. Then,
the only way to enable debug logging would be by changing
"NetworkManager.conf" and rebuild the initrd (or having some script in
place, that allows to more conveniently enable debug logging for
NetworkManager).
To make it easier for debugging, honor "nm.debug" on the kernel command
line.
Note that if "nm.debug" is set on the kernel command line, it always overrides
both the command line arguments and the configuration from NetworkManager.conf.
That is intentional. The only way to override that is by overriding the
kernel command line with a file "/run/NetworkManager/proc-cmdline".
https://bugzilla.redhat.com/show_bug.cgi?id=2102313
Improve documentation by preserving paragraphs in the
nm-settings-nmcli man pages.
To do that structure of src/libnm-client-impl/nm-settings-docs-gir.xml
was changed to have "description" as subnode to property node instead
of attribute of property node. Another subnode "description-docbook"
was added - this node is then used when generating man pages.
tools/generate-docs-nm-settings-docs-gir.py and man/nm-settings-dbus.xsl
were also changed to accomodate for changes mentioned above.
Replace xsltproc tool with python script when generating
./src/libnmc-setting/settings-docs.h.
Deleted settings-docs.xsl since it was replaced by python script.
Change src/libnmc-setting/settings-docs.h.in accodring to newly
generated src/libnmc-setting/settings-docs.h
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/661https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1260
