This bug has been migrated to another issue tracking site. It has been closed here and may no longer be being monitored.

If you would like to get updates for this issue, or to participate in it, you may do so at Red Hat Issue Tracker .
Bug 2048853 - nm-settings-keyfile confusion
Summary: nm-settings-keyfile confusion
Keywords:
Status: CLOSED MIGRATED
Alias: None
Product: Red Hat Enterprise Linux 9
Classification: Red Hat
Component: NetworkManager
Version: 9.0
Hardware: Unspecified
OS: Unspecified
medium
medium
Target Milestone: rc
: ---
Assignee: NetworkManager Development Team
QA Contact: Vladimir Benes
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2022-02-01 01:14 UTC by Patrick Donnelly
Modified: 2023-08-17 09:59 UTC (History)
9 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2023-08-17 09:58:53 UTC
Type: Bug
Target Upstream Version:
Embargoed:

Attachments (Terms of Use)


Links
System ID Private Priority Status Summary Last Updated
Red Hat Issue Tracker NMT-83 0 None None None 2023-01-22 14:13:05 UTC
Red Hat Issue Tracker   RHEL-1407 0 None None None 2023-08-17 09:58:52 UTC
Red Hat Issue Tracker RHELPLAN-110482 0 None None None 2022-02-01 01:16:18 UTC

Description Patrick Donnelly 2022-02-01 01:14:11 UTC 
Document URL: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_networking/assembly_manually-creating-networkmanager-profiles-in-key-file-format_configuring-and-managing-networking

Section Number and Name: all 

Describe the issue: 

- I'm using the "keyfile" description for NetworkManager (a network technology I'm new to) which is supposed to be the "new" way to configure networking in the next version of RHEL according to the above document. However, the way to write these files is not always clear with a given nmcli command. Some fields are unspecified, such as:

"ipv4.route1", "ipv4.route2", ... being the equivalent to an array of routes specified via:

nmcli connection modify ... +ipv4.routes foo

The man page (nm-settings-keyfile) **kinda** touches on weirdness to route specification but it's not at all clear.

"routing-rules" is another example.

Also note, the man page (nm-settings-keyfile) confuses things further:

> More information of the generic key file format can be found at GLib key file format[1] (Lines beginning with a '#' are comments, lists are separated by character ; etc.).

which would lead one to think that a list field like "routes" could be specified like:

routes=x.x.x.x/24,x.x.x.1;y.y.y.y/24,y.y.y.1

but this is not accepted.

I have found that the only way to discover this information is to continue using nmcli for configuring connections but modify /etc/NetworkManager/NetworkManager.conf to use keyfile format:

> [main]
> plugins=keyfile

and then inspect how it encodes commands in the keyfile.
Comment 5 Thomas Haller 2022-04-15 16:52:44 UTC 
> Thomas, if the man pages are wrong/incomplete, should we change this to a NetworkManager bug?

IMO this bug is mostly about `man nm-settings-keyfile`. We could reassign to NetworkManager.
That manual page is pretty bad, and (no doubt) should be improved.

> I think the documentation should be clear on whether customers should try to "get ahead of the curve" by using keyfile format **today** in RHEL 8. If they should, then the RHEL docs should recommend 

I think we should not recommend the user to do work, unless upgrading to the next major version. Even on RHEL9, ifcfg files will work just fine. Likewise, on RHEL8, keyfile will work fine.


> If I remember correctly, RHEL 8.5 added support for keyfiles, but it's not planned to change the default. 

keyfile are supported for a very long time already. The difference is that before RHEL9, the default in NetworkManager.conf is `[main].plugins=ifcfg-rh,keyfile`, while on RHEL9 it will be `[main].plugins=keyfile,ifcfg-rh`. Otherwise, RHEL8 and RHEL9 have a very(!) similar NetworkManager. The user could always have configured the plugin explicitly, and for NetworkManager either is fine (note that tools like anaconda (on RHEL8), /usr/lib/udev/rename_device might expect to find ifcfg-files, so changing the backend could have other effects).



I think the Guide should not go too much into detail about the actual format of keyfiles. For the individual keys, it should refer to `man nm-settings-keyfile` (which needs improvement). The Guide can however explain the larger picture, like how to edit a file. For example, inform to take care of the file owner/permissions, how to reload after modification (`nmcli connection load|reload`), that ifcfg files are also parsed by initscripts' /usr/lib/udev/rename_device (and migrating to keyfile requires to user to rename files via .link files or udev rules). Etc.


Marc, let's reassign or clone?


---

Btw, using nmcli seems much more convenient. I would always recommend that over editing keyfiles.
Also, 1.40 will bring an "--offline" option to nmcli, then you can generate/modify keyfile with nmcli (https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1183).
And 1.38 will bring a `nmcli connection migrate` command to convert from ifcfg to keyfile (online, done by the daemon) (https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1146)
Comment 6 Marc Muehlfeld 2022-04-19 07:01:01 UTC 
(In reply to Thomas Haller from comment #5)
> I think the Guide should not go too much into detail about the actual format
> of keyfiles. For the individual keys, it should refer to `man
> nm-settings-keyfile` (which needs improvement).

We have an example of a key file in
https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9-beta/html/configuring_and_managing_networking/assembly_manually-creating-networkmanager-profiles-in-key-file-format_configuring-and-managing-networking#con_the-key-file-format-of-networkmanager-profiles_assembly_manually-creating-networkmanager-profiles-in-key-file-format
and it refers to nm-settings-keyfile(5) for details.


> The Guide can however
> explain the larger picture, like how to edit a file. For example, inform to
> take care of the file owner/permissions, how to reload after modification
> (`nmcli connection load|reload`),...

This is covered in:
https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9-beta/html/configuring_and_managing_networking/assembly_manually-creating-networkmanager-profiles-in-key-file-format_configuring-and-managing-networking#proc_creating-a-networkmanager-profile-in-key-file-format_assembly_manually-creating-networkmanager-profiles-in-key-file-format



> that ifcfg files are also parsed by
> initscripts' /usr/lib/udev/rename_device (and migrating to keyfile requires
> to user to rename files via .link files or udev rules). Etc.

This is not covered yet.
You mentioned that NM 1.38 will introduce a migration tool. Is this info then still relevant.


> Marc, let's reassign or clone?

Reassigned.


> Btw, using nmcli seems much more convenient. I would always recommend that
> over editing keyfiles.
> Also, 1.40 will bring an "--offline" option to nmcli, then you can
> generate/modify keyfile with nmcli
> (https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/
> merge_requests/1183).
> And 1.38 will bring a `nmcli connection migrate` command to convert from
> ifcfg to keyfile (online, done by the daemon)
> (https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/
> merge_requests/1146)

That's a great info. I'll open doc tickets for both topics and add them to the next doc plan (will 1.40 be in 9.1 and/or 8.7)?
Note You need to log in before you can comment on or make changes to this bug.