Make better documentation for nmcli, NetworkManager Keyfiles
tl;dnr: If you want people to adopt new tech that is WILDLY different from old tech, document the bajeebus out of it with lots of examples...
Do a page search for 'keyfile' on the RHEL 7 networking guide. You'll get one hit, and not a relevant one.
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html-single/Networking_Guide/index.html
The guide only discusses ifcfg-rh which is a legacy transition tool at best - the official docs should do better than that.
The Fedora docs have a bit better coverage of keyfiles:
http://fedoraproject.org/wiki/Networking/Bridging#Using_configuration_files_.28keyfile.29
...but if you want to be real about it, even that documentation kind of sucks because it doesn't provide a solid practical example. Had to find one in the comments of a bugreport of all places (via google):
https://bugzilla.redhat.com/show_bug.cgi?id=1080643#c1
Just a complaint about the state of RHEL 7 docs in a couple places.
Responses
Guru
6603 points
I had similar thoughts on the nmcli documentation and posted comments here:
https://access.redhat.com/discussions/644133
Posting your concerns/issues in that thread may get some visibility as it was actively monitored at the time.
Hello
Could you give me some examples of when you would want to use a keyfile?
I try to document tasks a typical subscriber might reasonably be expected to perform, so use cases would help me.
Thank you
Expert
1004 points
Hi Stephen!
So what I was working on last night was trying to set up bridging on a workstation (see https://access.redhat.com/support/cases/01184536/).
So basically what I believe needs documented for that one would be:
1. Enabling the keyfile plugin (since 'plugins=ifcfg-rh, keyfile' didn't work)
2. Defining a bridge in nmcli (if necessary which I'd hope isn't if you're doing keyfiles)
3. Creating an arbitrary UUID for the bridge if necessary
4. Setting keyfiles up for the bridge and slave iface with a static IP.
5. Activating the keyfile definitions as the running config (restarting/reloading NetworkManager didn't help)
I think the above is a pretty common need since that's par for the course prior to setting up KVM guests with direct access to the wire.
Other tasks we do with legacy networking might be defining secondary IPs for a port, creating ISCSI ports, etc.
It would be nice if there were clear guidance on how to move away from /etc/sysconfig/network-scripts since that seems to be the intent with NetworkManager, nmcli, and NM keyfiles.
Thanks!
Hello Kodiak
As NetworkManager has a RHEL specific plugin, ifcfg-rh, there should be no need to use the generic keyfile plugin. (I thought you should not have to edit or use any plugin yourself for that matter).
Could you take a look at the bridging chapter in the Networking Guide and tell me if that helps you achieve your task in some other way?
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/ch-Configure_Network_Bridging.html
Thank you
Expert
1004 points
Hi Stephen,
Apologies if this sounds like a harsh criticism of the documentation but what you linked is exemplar to the issue I have with the state of NetworkManager docs.
The doc discusses nmtui (which should probably be considered the least common use case over GTK and console). Further even that example is incomplete.
The docs should walk someone through either using keyfiles as a replacement for /etc/sysconfig/network-scripts/ifcfg-{br0,em1}, or if ifcfg-rh is to be the permanent replacement for the old way, and still utilizes (what I believed to be) legacy files in /etc/sysconfig/network-scripts, then that should be clearly laid out on the docs and probably should still cover setting up a bridge via ifcfg-{br0,em1} files, then activating them with ifcfg-rh.
Basically my point is that it seems as though the networking guide is missing a lot of parts that prior guides documented from a network service standpoint (rather than NetworkManager), and that this should be remedied by fleshing out all these missing parts in the current EL7 docs if you want people to stop approaching NetworkManager by simply disabling it.
Thanks!
Hello Kodiak
How do you feel about using the nmcli tool?
The guide was planned to promote the use of nmcli rather than editing config files {covered in the Using the Command Line Interface (CLI) section}.
The instructions for nmcli and editing ifcfg files were recently tested by a colleague. Not saying they could not be improved of course.
The style of the guide is different to older guides. We try to describe tasks rather than things and I was never asked to document the direct editing of keyfiles or changing the ifcfg-rh plugin. So that is why I asked about use cases. Trying to understand if that is easier or better than the other methods.
Thank you
Expert
1004 points
Hi Stephen,
Does using nmcli result in the placement of text files anywhere? I think it would be foolish for the state of the network to be completely hidden from the filesystem and was hoping if you are moving away from /etc/sysconfig/network-scripts, that it only means the files go somewhere else like /etc/NetworkManager/system-connections.
If the networking configs / state is no longer being captured to human readable text files I think that's a crying shame.
Thanks!
Red Hat
Guru
3853 points
"Does using nmcli result in the placement of text files anywhere? I think it would be foolish for the state of the network to be completely hidden from the filesystem and was hoping if you are moving away from /etc/sysconfig/network-scripts, that it only means the files go somewhere else like /etc/NetworkManager/system-connections."
Using any of the nm-tools (like nmcli) leads to changes to /etc/sysconfig/network-scripts/ ... As far as I'm aware (and I teach RHEL7 classes), there is no plan to "move away from" use of that directory in RHEL7.
Expert
1004 points
Well I'll be dipped - it does put them there. I guess I don't know what the heck /etc/NetworkManager/system-connections is for then. I thought this was DNF all over again with the moving of the config files to a separate parallel folder hierarchy...
Have you read this introductory section explaining about the use of the Command Line Interface (CLI)?
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/sec-Network_Config_Using_CLI.html
It is followed by two sections also related to your questions.
But please do try one of the methods in the bridging chapter.
From the guide "The file /etc/sysconfig/network is for global settings. Information for VPNs, mobile broadband and PPPoE connections is stored in /etc/NetworkManager/system-connections/. " and NetworkManager uses the ifcfg-rh plug-in to read and write the traditional files in /etc/sysconfig/network-scripts/
Expert
1004 points
Sure but the guide didn't make it clear that it also creates files in there so when I read NetworkManager documentation talking about /etc/NetworkManager/system-connections and keyfiles I went on a snipe hunt in that direction.
Anyhow I understand it better now I think. I'll take another shot at setting up that bridge.
Expert
1004 points
Or maybe I should back up a bit and ask if keyfiles are indeed meant to eventually depricate /etc/sysconfig/network-scripts. It seems like that's the intent but I suppose I should be sure before wasting a bunch of my time messing with those over network-scripts and using ifcfg-rh.