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
It can be useful to choose a different "ipv6.addr-gen-mode". And it can be
useful to override the default for a set of profiles.
For example, in cloud or in a data center, stable-privacy might not be
the best choice. Add a mechanism to override the default via global defaults
in NetworkManager.conf:
# /etc/NetworkManager/conf.d/90-ipv6-addr-gen-mode-override.conf
[connection-90-ipv6-addr-gen-mode-override]
match-device=type:ethernet
ipv6.addr-gen-mode=0
"ipv6.addr-gen-mode" is a special property, because its default depends on
the component that configures the profile.
- when read from disk (keyfile and ifcfg-rh), a missing addr-gen-mode
key means to default to "eui64".
- when configured via D-Bus, a missing addr-gen-mode property means to
default to "stable-privacy".
- libnm's ip6-config::addr-gen-mode property defaults to
"stable-privacy".
- when some tool creates a profile, they either can explicitly
set the mode, or they get the default of the underlying mechanisms
above.
- nm-initrd-generator explicitly sets "eui64" for profiles it creates.
- nmcli doesn' explicitly set it, but inherits the default form
libnm's ip6-config::addr-gen-mode.
- when NM creates a auto-default-connection for ethernet ("Wired connection 1"),
it inherits the default from libnm's ip6-config::addr-gen-mode.
Global connection defaults only take effect when the per-profile
value is set to a special default/unset value. To account for the
different cases above, we add two such special values: "default" and
"default-or-eui64". That's something we didn't do before, but it seams
useful and easy to understand.
Also, this neatly expresses the current behaviors we already have. E.g.
if you don't specify the "addr-gen-mode" in a keyfile, "default-or-eui64"
is a pretty clear thing.
Note that usually we cannot change default values, in particular not for
libnm's properties. That is because we don't serialize the default
values to D-Bus/keyfile, so if we change the default, we change
behavior. Here we change from "stable-privacy" to "default" and
from "eui64" to "default-or-eui64". That means, the user only experiences
a change in behavior, if they have a ".conf" file that overrides the default.
https://bugzilla.redhat.com/show_bug.cgi?id=1743161https://bugzilla.redhat.com/show_bug.cgi?id=2082682
See-also: https://github.com/coreos/fedora-coreos-tracker/issues/907https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1213
This is an interface to the Checkpoint/Restore functionality that's
available for quite some time. It runs a command with a checkpoint taken
and rolls back unless success is confirmed before the checkpoint times
out:
$ nmcli dev checkpoint eth0 -- nmcli dev dis eth0
Device 'eth0' successfully disconnected.
Type "Yes" to commit the changes: No
Checkpoint was removed.
The details about how it's used are documented in nmcli(1) and
nmcli-examples(7).
Introduction of a new setting ipv4.link-local, which enables
link-local IP addresses concurrently with other IP address assignment
implementations such as dhcp or manually.
No way is implemented to obtain a link-local address as a fallback when
dhcp does not respond (as dhcpd does, for example). This could be be
added later.
To maintain backward compatibility with ipv4.method ipv4.link-local has
lower priority than ipv4.method. This results in:
* method=link-local overrules link-local=disabled
* method=disabled overrules link-local=enabled
Furthermore, link-local=auto means that method defines whether
link-local is enabled or disabled:
* method=link-local --> link-local=enabled
* else --> link-local=disabled
The upside is, that this implementation requires no normalization.
Normalization is confusing to implement, because to get it really
right, we probably should support normalizing link-local based on
method, but also vice versa. And since the method affects how other
properties validate/normalize, it's hard to normalize that one, so that
the result makes sense. Normalization is also often not great to the
user, because it basically means to modify the profile based on other
settings.
The downside is that the auto flag becomes API and exists because
we need backward compatibility with ipv4.method.
We would never add this flag, if we would redesign "ipv4.method"
(by replacing by per-method-specific settings).
Defining a default setting for ipv4.link-local in the global
configuration is also supported.
The default setting for the new property can be "default", since old
users upgrading to a new version that supports ipv4.link-local will not
have configured the global default in NetworkManager.conf. Therefore,
they will always use the expected "auto" default unless they change
their configuration.
Co-Authored-By: Thomas Haller <thaller@redhat.com>
This adds a global "--offline" option and allows its use with "add" and
"modify" commands. The "add" looks like this:
$ nmcli --offline conn add type ethernet ens3 ipv4.dns 192.168.1.1 \
>output.nmconnection
The "modify" is essentially implementing what's been suggested by
Beniamino in bugzilla ticked (referred to below):
$ nmcli --offline connection modify ens3 ipv4.dns 192.168.1.1 \
<input.nmconnection >output.nmconnection
Other commands don't support the argument at the moment:
$ nmcli --offline c up ens3
Error: 'up' command doesn't support --offline mode.
https://bugzilla.redhat.com/show_bug.cgi?id=1361145
The "unbound" DNS plugin was very rudimentary and is deprecated since
commit 4a2fe09853 ('man: mark [main].dns=unbound as deprecated') (Jun
2021).
It is part of dnssec-trigger tool, but the dnssec-trigger tool doesn't
actually use it. Instead it installs a dispatcher script
"/usr/lib/NetworkManager/dispatcher.d/01-dnssec-trigger".
Especially, since the plugin requires "/usr/libexec/dnssec-trigger-script",
which is provided by "dnssec-trigger" package on Fedora. At the same
time, the package provides the dispatcher script. So I don't this works
or anybody is using this.
https://mail.gnome.org/archives/networkmanager-list/2022-April/msg00002.html
Follow-up commits are going color Wi-Fi networks and connections that rely
on deprecated features differently, to provide a visual cue.
Add color definitions for those.
NetworkManager-wait-online is a constant source of confusion,
as it seems to delay the boot (when it's often just the messenger
or either a network problem, a NetworkManager misconfiguration
or a misconfiguration of other systemd services).
Try to clear that up with a manual page.
https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1130
People keep reporting bugs with `level=DEBUG` or set to a certain
domains. That is generally not useful. Complete debug logs should be
collected, we can always ignore what we don't care about, but we might
miss important information by limiting what we collect.
Try to make that clearer in the manual.
