SupportConsoleDevelopersStart a trialContact

Chapter 38. NetworkManager connection profiles in keyfile format

By default, NetworkManager stores connection profiles in ifcfg format, but you can also use profiles in keyfile format. Unlike the deprecated ifcfg format, the keyfile format supports all connection settings that NetworkManager provides.

In the Red Hat Enterprise Linux 9, the keyfile format will be the default.

The keyfile format is an INI-like configuration for network connections.

For example, the following is an Ethernet connection profile in keyfile format: 

[connection]
id=example_connection
uuid=82c6272d-1ff7-4d56-9c7c-0eb27c300029
type=ethernet
autoconnect=true

[ipv4]
method=auto

[ipv6]
method=auto

[ethernet]
mac-address=00:53:00:8f:fa:66
Warning

Typos or incorrect placements of parameters can lead to unexpected behavior. Therefore, do not manually edit or create NetworkManager profiles.

Use the nmcli utility, the network RHEL system role, or the nmstate API to manage NetworkManager connections. For example, you can use the nmcli utility in offline mode to create connection profiles.

Each section corresponds to a NetworkManager setting name as described in the nm-settings(5) man page. Each key-value-pair in a section is one of the properties listed in the settings specification of the man page.

Most variables in NetworkManager keyfiles have a one-to-one mapping. This means that a NetworkManager property is stored in the keyfile as a variable of the same name and in the same format. However, there are exceptions, mainly to make the keyfile syntax easier to read. For a list of these exceptions, see the nm-settings-keyfile(5) man page on your system.

Important

For security reasons, because connection profiles can contain sensitive information, such as private keys and passphrases, NetworkManager uses only configuration files owned by the root user and that are only readable and writable by root.

If you modify a persistent connection profile by using the NetworkManager API, NetworkManager writes and overwrites the corresponding *.nmconnection file in the /etc/NetworkManager/system-connections/ directory.

NetworkManager does not automatically reload profiles from disk. When you create or update a connection profile in keyfile format, use the nmcli connection reload command to inform NetworkManager about the changes.

You can use the nmcli utility in offline mode to create and manage NetworkManager connection profiles. In this mode, nmcli operates without the NetworkManager service to produce keyfile connection profiles through standard output.

Creating connection profiles offline can be useful in the following scenarios:

  • You want to create your connection profiles that need to be pre-deployed somewhere. For example in a container image or as an RPM package.
  • You want to create your connection profiles in an environment where the NetworkManager service is not available, for example, when you want to use the chroot utility. Alternatively, when you want to create or modify the network configuration of the RHEL system to be installed through the Kickstart %post script.

Procedure

  1. Create a new connection profile in the keyfile format. For example, for a connection profile of an Ethernet device that does not use DHCP, run a similar nmcli command: 

    # nmcli --offline connection add type ethernet con-name Internal-LAN ipv4.addresses 192.0.2.1/24 ipv4.dns 192.0.2.200 ipv4.method manual > /etc/NetworkManager/system-connections/int-lan.nmconnection
    Note

    The connection name you specified with the con-name key is saved into the id variable of the generated profile. When you use the nmcli command to manage this connection later, specify the connection as follows:

    • When the id variable is not omitted, use the connection name, for example Internal-LAN.
    • When the id variable is omitted, use the file name without the .nmconnection suffix, for example int-lan.

  2. Set permissions to the configuration file so that only the root user can read and update it: 

    # chmod 600 /etc/NetworkManager/system-connections/int-lan.nmconnection
# chown root:root /etc/NetworkManager/system-connections/int-lan.nmconnection

  3. Start the NetworkManager service: 

    # systemctl start NetworkManager.service

  4. If you set the autoconnect variable in the profile to false, activate the connection: 

    # nmcli connection up Internal-LAN

Verification

  1. Verify that the NetworkManager service is running: 

    # systemctl status NetworkManager.service
● NetworkManager.service - Network Manager
   Loaded: loaded (/usr/lib/systemd/system/NetworkManager.service; enabled; vendor preset: enabled)
   Active: active (running) since Wed 2022-08-03 13:08:32 CEST; 1min 40s ago
...

  2. Verify that NetworkManager can read the profile from the configuration file: 

    # nmcli -f TYPE,FILENAME,NAME connection
TYPE      FILENAME                                                     NAME
ethernet /etc/NetworkManager/system-connections/int-lan.nmconnection Internal-LAN
ethernet  /etc/sysconfig/network-scripts/ifcfg-enp1s0                  enp1s0
...

    If the output does not show the newly created connection, verify that the keyfile permissions and the syntax you used are correct.

  3. Display the connection profile: 

    # nmcli connection show Internal-LAN
connection.id:                          Internal-LAN
connection.uuid:                        232290ce-5225-422a-9228-cb83b22056b4
connection.stable-id:                   --
connection.type:                        802-3-ethernet
connection.interface-name:              --
connection.autoconnect:                 yes
...

You can define custom network interface names, such as lan to make interface names more descriptive. In this case, the udev service renames the interfaces. The renaming process works differently depending on whether you use connection profiles in ifcfg or keyfile format.

The interface renaming process when using a profile in ifcfg format
  1. The udev rule file /usr/lib/udev/rules.d/60-net.rules calls the /lib/udev/rename_device helper utility.
  2. The helper utility searches for the HWADDR parameter in /etc/sysconfig/network-scripts/ifcfg-* files.
  3. If the value set in the variable matches the MAC address of an interface, the helper utility renames the interface to the name set in the DEVICE parameter of the file.
The interface renaming process when using a profile in keyfile format
  1. Create a systemd link file or a udev rule to rename an interface.
  2. Use the custom interface name in the interface-name property of a NetworkManager connection profile.

If you use connection profiles in ifcfg format, you can convert them to the keyfile format to have all profiles in the preferred format and in one location.

Note

If an ifcfg file contains the NM_CONTROLLED=no setting, NetworkManager does not control this profile and, consequently, the migration process ignores it.

Prerequisites

  • You have connection profiles in ifcfg format in the /etc/sysconfig/network-scripts/ directory.
  • If the connection profiles contain a DEVICE variable that is set to a custom device name, such as provider or lan, you created a systemd link file or a udev rule for each of the custom device names.

Procedure

  • Migrate the connection profiles: 

    # nmcli connection migrate
Connection 'enp1s0' (43ed18ab-f0c4-4934-af3d-2b3333948e45) successfully migrated.
Connection 'enp2s0' (883333e8-1b87-4947-8ceb-1f8812a80a9b) successfully migrated.
...

Verification

  • Optional: You can verify that you successfully migrated all your connection profiles: 

    # nmcli -f TYPE,FILENAME,NAME connection
TYPE      FILENAME                                                           NAME
ethernet  /etc/NetworkManager/system-connections/enp1s0.nmconnection         enp1s0
ethernet  /etc/NetworkManager/system-connections/enp2s0.nmconnection         enp2s0
...
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top