From ifcfg to keyfiles: modernizing NetworkManager configuration in Fedora Linux 36

Photo by Compare Fibre on Unsplash

One of the changes in Fedora Linux 36 is that new installations will no longer support the ifcfg files to configure networking. What are those and what replaces them?

A bit of history

In the good old days, connecting a Linux box to a network was easy. For each of the interface cards connected to a network, the system administrator would drop a configuration file into the /etc directory. That configuration file would describe the addressing configuration for a particular network. On Fedora Linux, the configuration file would actually be a shell script snippet like this:

$ cat /etc/sysconfig/network-scripts/ifcfg-eth0
TYPE=Ethernet
DEVICE=eth0
BOOTPROTO=dhcp

A shell script executed on startup would read the file and apply the configuration. Simple.

Towards the end of 2004, however, a change was in the air. Quite literally — the Wi-Fi has become ubiquitous. The portable computers of the day could rapidly connect to new networks and the USB bus allowed even the wired network adapters to come and go while the system was up and running. The network configuration became more dynamic than ever before, rendering the existing network configuration tooling impractical. To the rescue came NetworkManager. On a Fedora Linux system, NetworkManager uses configuration like this:

$ cat /etc/sysconfig/network-scripts/ifcfg-eth0
TYPE=Ethernet
DEVICE=eth0
BOOTPROTO=dhcp

Looks familiar? It should. From the beginning, NetworkManager was intended to work with the existing configuration formats. In fact, it ended up with plugins which would seamlessly convert between NetworkManager’s internal configuration model and the distribution’s native format. On Fedora, it would be the aforementioned ifcfg files.

Let’s take a closer look at them.

Ifcfg files

The legacy network service, now part of the network-scripts package, originally defined the ifcfg file format. Along with the package comes a file called sysconfig.txt that, quite helpfully, documents the format.

As NetworkManager gained traction it often found itself in need of expressing a configuration that was not supported by the old fashioned network service. Given the nature of configuring things with shell scripts, adding new settings is no big deal. The unknown ones are generally just silently ignored. The NetworkManager’s idea of what ifcfg files should look like is described in the nm-settings-ifcfg-rh(5) manual.

In general, NetworkManager tries hard to write ifcfg files that work well with the legacy network service. Nevertheless, sometimes it is just not possible. These days, the number of network connection types that NetworkManager supports vastly outnumber what the legacy network service can configure. . A new format is now used to express what the legacy format can not. This includes VPN connections, broadband modems and more.

Keyfiles

The new format closely resembled the NetworkManager’s native configuration model:

$ cat /etc/NetworkManager/system-connections/VPN.ovpn
[connection]
id=My VPN
uuid=c85a7cdb-973b-491f-998d-b09a590af10e
type=vpn

[vpn]
ca=/etc/pki/tls/certs/vpn-ca.pem
connection-type=password
remote=vpn.example.com
username=lkundrak
service-type=org.freedesktop.NetworkManager.openvpn

[ipv6]
method=auto
never-default=true

The actual format should be instantly familiar to everyone familiar with Linux systems. It’s the “ini file” or “keyfile” — a bunch of plain text key-value pairs, much like the ifcfg files use, grouped into sections. The nm-settings-keyfile(5) manual documents the format thoroughly.

The main advantage of using this format is that it closely resembles NetworkManager’s idea of how to express network configuration, used both internally and on the D-Bus API. It’s easier to extend without taking into consideration the quirks of the mechanism that was designed in without the benefit of foresight back when the world was young. This means less code, less surprises and less bugs.

In fact there’s nothing the keyfile format can’t express that ifcfg files can. It can express the simple wired connections just as well as the VPNs or modems.

Migrating to keyfiles

The legacy network service served us well for many years, but its days are now long over. Fedora Linux dropped it many releases ago and without it there is seemingly little reason to use the ifcfg files. That is, for new configurations. While Fedora Linux still supports the ifcfg files, it has defaulted to writing keyfiles for quite some time.

Starting with Fedora Linux 36, the ifcfg support will no longer be present in new installations. If you’re still using ifcfg files, do not worry — the existing systems will keep it on upgrades. Nevertheless, you can still decide to uninstall it and carry your configuration over to keyfiles. Keep on reading to learn how.

If you’re like me, you installed your system years ago and you have a mixture of keyfiles and ifcfg files. Here’s how can you check:

$ nmcli -f TYPE,FILENAME,NAME conn
TYPE      FILENAME                                         NAME
ethernet  /etc/sysconfig/network-scripts/ifcfg-eth0        eth0
wifi      /etc/sysconfig/network-scripts/ifcfg-Guest       Guest
wifi      /etc/NetworkManager/system-connections/Base48    Base48
vpn       /etc/NetworkManager/system-connections/VPN.ovpn  My VPN

This example shows a VPN connection that must have always used a keyfile and a Wi-Fi connection presumably created after Fedora Linux switched to writing keyfiles by default. There’s also an Ethernet connection and Wi-Fi one from back in the day that use the ifcfg plugin. Let’s see how we can convert those to keyfiles.

The NetworkManager’s command line utility, nmcli(1), acquired a new connection migrate command, that can change the configuration backend used by a connection profile.

It’s a good idea to make a backup of /etc/sysconfig/network-scripts/ifcfg-* files, in case anything goes wrong. Once you have the backup you can try migrating a single connection to a different configuration backend (keyfile by default):

$ nmcli connection migrate eth0
Connection 'eth0' (336aba93-1cd7-4cf4-8e90-e2009db3d4d0) successfully migrated.

Did it work?

$ nmcli -f TYPE,FILENAME,NAME conn
TYPE      FILENAME                                         NAME
ethernet  /etc/NetworkManager/system-connections/eth0.nmc  eth0
wifi      /etc/sysconfig/network-scripts/ifcfg-Guest       Guest
wifi      /etc/NetworkManager/system-connections/Base48    Base48
vpn       /etc/NetworkManager/system-connections/VPN.ovpn  My VPN

Cool. Can I migrate it back, for no good reason?

$ nmcli conn migrate --plugin ifcfg-rh eth0
Connection 'eth0' (336aba93-1cd7-4cf4-8e90-e2009db3d4d0) successfully migrated.

Excellent. Without specifying more options, the “connection migrate” command ensures all connections use the keyfile backend:

$ nmcli conn migrate
Connection '336aba93-1cd7-4cf4-8e90-e2009db3d4d0' (eth0) successfully migrated.
Connection '3802a9bc-6ca5-4a17-9d0b-346f7212f2d3' (Red Hat Guest) successfully migrated.
Connection 'a082d5a0-5e29-4c67-8b6b-09af1b8d55a0' (Base48) successfully migrated.
Connection 'c85a7cdb-973b-491f-998d-b09a590af10e' (Oh My VPN) successfully migrated.

And that’s all. Now that your system has no ifcfg files, the configuration backend that supports them is of no use and you can remove it:

# dnf remove NetworkManager-initscripts-ifcfg-rh

Your system now works the same as it did before, but you can rejoice, for it is now modern.

Fedora Project community

30 Comments

  1. Michael Gruber

    Excellent!
    Each time that I thought “But what if …?”, the next paragraph would answer exactly that question.
    Very concise and informative. Thanks and rejoice 🙂

  2. Jake

    Very cool. The migrate command must be quite new. In the past, I’d clone the connection.

  3. Raffael

    Thanks for the first introduction. What interests me the most is how can I now configure in the future a server with a static IP address and static DNS server entries? This was for me the main reason why I had to touch ifcfg files and it is not explained here.

    • João Rodrigues

      $ nmcli con modify eth0 ipv4.method manual
      $ nmcli con modify eth0 ipv4.addresses 10.0.0.10/8
      $ nmcli con modify eth0 ipv4.gateway 10.0.0.1
      $ nmcli con modify eth0 ipv4.dns 10.0.0.2,10.0.0.3

      or you could

      $ nmcli con edit eth0

      and modify the settings like:

      nmcli> goto ipv4
      nmcli ipv4> set method manual
      nmcli ipv4> set addresses 10.0.0.10/8
      nmcli ipv4> set gateway 10.0.0.1
      nmcli ipv4> set dns 10.0.0.2,10.0.0.3
      nmcli ipv4> back
      nmcli> save
      nmcli> quit

      For more information, check out

      $ man nmcli-examples

      and

      $ man nm-settings-nmcli
      • Raffael

        Hi João,

        If I understood your answer right then I shouldn’t modify config files anymore? Only work with commands in the shell?

    • John

      If you’re a CLI guy, like me, you can use “nmtui” to interactively walk through creating a new config for static IP addressing and DNS.

      When I really wanna show off I use this CLI instead:
      nmcli con add type ethernet conn.interface eth0 ipv4.method static ipv4.addresses 192.168.10.10/24 ipv4.dns 192.168.10.1 ipv4.gateway 192.168.10.1

  4. David Levner

    The ‘migrate’ command is not working for me:

    $ nmcli conn migrate
    Error: argument ‘migrate’ not understood. Try passing –help instead.
    $ nmcli connection migrate
    Error: argument ‘migrate’ not understood. Try passing –help instead.
    $ nmcli connection migrate enp1s0
    Error: argument ‘migrate’ not understood. Try passing –help instead.
    $ nmcli -v
    nmcli tool, version 1.32.12-2.fc35

    $ nmcli c –help
    Usage: nmcli connection { COMMAND | help }

    COMMAND := { show | up | down | add | modify | clone | edit | delete | monitor | reload | load | import | export }

    show [–active] [–order ]
    show [–active] [id | uuid | path | apath] …

    up [[id | uuid | path] ] [ifname ] [ap ] [passwd-file ]

    down [id | uuid | path | apath] …

    add COMMON_OPTIONS TYPE_SPECIFIC_OPTIONS SLAVE_OPTIONS IP_OPTIONS [– ([+|-]. )+]

    modify [–temporary] [id | uuid | path] ([+|-]. )+

    clone [–temporary] [id | uuid | path ]

    edit [id | uuid | path]
    edit [type ] [con-name ]

    delete [id | uuid | path]

    monitor [id | uuid | path] …

    reload

    load [ … ]

    import [–temporary] type file

    export [id | uuid | path] []

    • It looks like you are running the Fedora Linux 35 version of nmcli (1.32.12-2.fc35). I think this article is about the upcoming Fedora Linux 36 version.

      • ReD

        It’s the same also on Fedora Linux 36. Right now it’s available only in updates-testing. 🙂

    • Robert Redziak

      You may check on CentOS 9 Stream too.

  5. James

    Raffael: this appears to be documented in
    man nm-settings-keyfile

    • Raffael

      James: Sadly non of the examples in this man page show static IP addresses. But João’s answer gave me the right information.

  6. Robert Redziak

    Ini.files. Ugh… I wish they used something based on structured files. Like netplan or something designed after netplan. Something easy to interact with programmatically.

  7. Eric L.

    I’m still on Fedora 35 and have the following result:

    $ nmcli -f TYPE,FILENAME,NAME conn
    TYPE      FILENAME                                                    NAME      
    ethernet  /etc/sysconfig/network-scripts/ifcfg-enp0s31f6              enp0s31f6
    bridge    /run/NetworkManager/system-connections/virbr0.nmconnection  virbr0    
    bridge    /etc/sysconfig/network-scripts/ifcfg-virbr0                 virbr0

    I’m not too concerned about the ethernet connection, the migrate approach will probably take care of it, but what about the duplicate virbr0 configuration? They have different UUIDs but look very similar (coming from my libvirt setup).

  8. Antonio

    Awesome

  9. Patrick Chiang

    Easy to read, lots of example… Thank you for the post.

  10. Pavel

    I just tried nmtui:
    1. It is not installed out-of-the-box in Fedora 36 WS
    2. UI is not tto fancy but usable
    3. and it crashes on exit by esc with error at nmt-newt-form line 427.

    From my personal experience any attempt of using curses UI on Gnome 4.2 plus Wayland is wasting of time due to endless combinations in the curses-gnome-terminal gnome wayland stack. Neither application that tries to do it works. It would better to polish Setting->WiFi UI. If networkd dbus API works it will be not so complex job.

    • Vladimir

      how about nm-connection-editor from the same package? Settings wifi UI is managed by a different team and was intended to be simple and GNOME UI compliant. You should be able to set much more in nm-c-e (bands, rate, tx power, etc.. )

  11. Ivan

    Excellent explanation! Thank you a lot!

  12. Jesse Pollard

    Too bad the ” nm-settings-ifcfg-keyfile(5)” link doesn’t work.

  13. Paweł

    After disconnecting the wired interface from the USB, the DNS data in the /etc/resolve.conf file is remembered even though the connection is no longer active. These data are forgotten only after restarting NetwokManager.

  14. Alec

    Great info, love to learn about internals in such an easy to understand way!

    I’m not ready to migrate since i use podman and it automatically creates bridges in

    /run/NetworkManager/system-connections/

    and wonder where would WIFI passwords be stored in a new model (currently its in /etc/sysconfig/network-scripts/keys-*)

    • John Call

      As an example, I can reveal my WiFi passwords in either of these two ways…

      $ sudo grep "psk" /etc/NetworkManager/system-connections/MyWiFi.nmconnection
      key-mgmt=wpa-psk
      psk=myPassword1

      $ nmcli --show-secret con show MyWiFi | grep "psk"
      802-11-wireless-security.key-mgmt:      wpa-psk
      802-11-wireless-security.psk:           myPassword1
  15. Eli

    Hello,
    There is not such command “nmcli conn migrate” So what is the simple way to migrate?

  16. Dexter P.

    Really liked the article. I do have to warn about one thing before converting to keyfiles: Ensure the services you’re hosting or running will use NetworkManager without fail.

    I remember seeing the announcement about switching to keyfiles during Fedora 33 and 34. I was using kea for my DHCP server at the time. I manually changed over from the ifcfgs to keyfiles, mainly via the nmcli con edit “UUID” command. (Didn’t know about the clone option then.) It worked great. Unfortunately, kea stopped issuing out IPs, despite the service being in the active state in systemctl. Was unable to figure out why. Had to switch over from kea to dnsmasq. Haven’t had any problems with dnsmasq so far.

    That’s the only service I’ve encountered so far. Do check any other services carefully.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions

%d bloggers like this: