Chapter 37. NetworkManager connection profiles in keyfile format

By default, NetworkManager in Red Hat Enterprise Linux 9 and later stores connection profiles in keyfile format. Unlike the deprecated ifcfg format, the keyfile format supports all connection settings that NetworkManager provides.

37.1. The keyfile format of NetworkManager profiles

The keyfile format is similar to the INI format. 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) and nm-settings-keyfile(5) man pages. 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.

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.

Depending on the purpose of the connection profile, save it in one of the following directories:

  • /etc/NetworkManager/system-connections/: The location of persistent profiles. If you modify a persistent profile by using the NetworkManager API, NetworkManager writes and overwrites files in this directory.
  • /run/NetworkManager/system-connections/: For temporary profiles that are automatically removed when you reboot the system.
  • /usr/lib/NetworkManager/system-connections/: For pre-deployed immutable profiles. When you edit such a profile using the NetworkManager API, NetworkManager copies this profile to either the persistent or temporary storage.

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.

37.2. Using nmcli to create keyfile connection profiles in offline mode

Use NetworkManager utilities, such as nmcli, the network RHEL system role, or the nmstate API to manage NetworkManager connections, to create and update configuration files. However, you can also create various connection profiles in the keyfile format in offline mode using the nmcli --offline connection add command.

The offline mode ensures that nmcli operates without the NetworkManager service to produce keyfile connection profiles through standard output. This feature can be useful if:

  • 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.

You can create the following connection profile types:

  • static Ethernet connection
  • dynamic Ethernet connection
  • network bond
  • network bridge
  • VLAN or any kind of supported connections

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 Example-Connection ipv4.addresses 192.0.2.1/24 ipv4.dns 192.0.2.200 ipv4.method manual > /etc/NetworkManager/system-connections/output.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 Example-Connection.
    • When the id variable is omitted, use the file name without the .nmconnection suffix, for example output.

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

    # chmod 600 /etc/NetworkManager/system-connections/output.nmconnection
# chown root:root /etc/NetworkManager/system-connections/output.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 Example-Connection

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/output.nmconnection Example-Connection
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 Example-Connection
connection.id:                          Example-Connection
connection.uuid:                        232290ce-5225-422a-9228-cb83b22056b4
connection.stable-id:                   --
connection.type:                        802-3-ethernet
connection.interface-name:              --
connection.autoconnect:                 yes
...

Additional resources

37.3. Manually creating a NetworkManager profile in keyfile format

You can manually create a NetworkManager connection profile in keyfile format.

Note

Manually creating or updating the configuration files can result in an unexpected or non-functional network configuration. As an alternative, you can use nmcli in offline mode. See Using nmcli to create keyfile connection profiles in offline mode

Procedure

  1. If you create a profile for a hardware interface, such as Ethernet, display the MAC address of this interface: 

    # ip address show enp1s0
2: enp1s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 00:53:00:8f:fa:66 brd ff:ff:ff:ff:ff:ff

  2. Create a connection profile. For example, for a connection profile of an Ethernet device that uses DHCP, create the /etc/NetworkManager/system-connections/example.nmconnection file with the following content: 

    [connection]
id=example_connection
type=ethernet
autoconnect=true

[ipv4]
method=auto

[ipv6]
method=auto

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

    You can use any file name with a .nmconnection suffix. However, when you later use nmcli commands to manage the connection, you must use the connection name set in the id variable when you refer to this connection. When you omit the id variable, use the file name without the .nmconnection to refer to this connection.

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

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

  4. Reload the connection profiles: 

    # nmcli connection reload

  5. Verify that NetworkManager read the profile from the configuration file: 

    # nmcli -f NAME,UUID,FILENAME connection
NAME                UUID                                  FILENAME
example-connection  86da2486-068d-4d05-9ac7-957ec118afba  /etc/NetworkManager/system-connections/example.nmconnection
...

    If the command does not show the newly added connection, verify that the file permissions and the syntax you used in the file are correct.

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

    # nmcli connection up example_connection

Verification

  1. Display the connection profile: 

    # nmcli connection show example_connection

Additional resources

  • nm-settings-keyfile (5)

37.4. The differences in interface renaming with profiles in ifcfg and keyfile format

You can define custom network interface names, such as provider or 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 /usr/lib/udev/rules.d/60-net.rules udev rule 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.

Additional resources

37.5. Migrating NetworkManager profiles from ifcfg to keyfile format

If you still use connection profiles in the deprecated ifcfg format, you can convert them to the keyfile format.

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

  • Optionally, 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
...

Additional resources