Chapter 38. NetworkManager connection profiles in keyfile format
Chapter 38. 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. 38.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: 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 . Save the connection profile with a .nmconnection suffix in the /etc/NetworkManager/system-connections/ directory. This directrory contains persistent profiles. If you modify a persistent profile by using the NetworkManager API, NetworkManager writes and overwrites files in this 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. 38.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 by 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 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 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: 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 . Set permissions to the configuration file so that only the root user can read and update it: Start the NetworkManager service: If you set the autoconnect variable in the profile to false , activate the connection: Verification Verify that the NetworkManager service is running: Verify that NetworkManager can read the profile from the configuration file: If the output does not show the newly created connection, verify that the keyfile permissions and the syntax you used are correct. Display the connection profile: Additional resources nmcli(1) , nm-settings(5) , and nm-settings-keyfile(5) man pages on your system 38.3. Manually creating a NetworkManager profile in keyfile format You can manually create a NetworkManager connection profile in keyfile format. Warning 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 Create a connection profile. For example, for a connection profile for the enp1s0 Ethernet device that uses DHCP, create the /etc/NetworkManager/system-connections/example.nmconnection file with the following content: 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. Set permissions on the configuration file so that only the root user can read and update it: Reload the connection profiles: Verify that NetworkManager read the profile from the configuration file: 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. If you set the autoconnect variable in the profile to false , activate the connection: Verification Display the connection profile: Additional resources nm-settings(5) and nm-settings-keyfile(5) man pages on your system 38.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 The /usr/lib/udev/rules.d/60-net.rules udev rule calls the /lib/udev/rename_device helper utility. The helper utility searches for the HWADDR parameter in /etc/sysconfig/network-scripts/ifcfg-* files. 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 Create a systemd link file or a udev rule to rename an interface. Use the custom interface name in the interface-name property of a NetworkManager connection profile. Additional resources How the udev device manager renames network interfaces Configuring user-defined network interface names by using udev rules Configuring user-defined network interface names by using systemd link files 38.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: Verification Optionally, you can verify that you successfully migrated all your connection profiles: Additional resources nm-settings-keyfile(5) nm-settings-ifcfg-rh(5) How the udev device manager renames network interfaces
[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 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/example.nmconnection chmod 600 /etc/NetworkManager/system-connections/example.nmconnection chown root:root /etc/NetworkManager/system-connections/example.nmconnection systemctl start NetworkManager.service nmcli connection up Example-Connection 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 nmcli -f TYPE,FILENAME,NAME connection TYPE FILENAME NAME ethernet /etc/NetworkManager/system-connections/examaple.nmconnection Example-Connection ethernet /etc/sysconfig/network-scripts/ifcfg-enp1s0 enp1s0 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 [connection] id=Example-Connection type=ethernet autoconnect=true interface-name=enp1s0 [ipv4] method=auto [ipv6] method=auto chown root:root /etc/NetworkManager/system-connections/example.nmconnection chmod 600 /etc/NetworkManager/system-connections/example.nmconnection nmcli connection reload nmcli -f NAME,UUID,FILENAME connection NAME UUID FILENAME Example-Connection 86da2486-068d-4d05-9ac7-957ec118afba /etc/NetworkManager/system-connections/example.nmconnection nmcli connection up example_connection nmcli connection show example_connection nmcli connection migrate Connection 'enp1s0' (43ed18ab-f0c4-4934-af3d-2b3333948e45) successfully migrated. Connection 'enp2s0' (883333e8-1b87-4947-8ceb-1f8812a80a9b) successfully migrated. 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