Chapter 24. Manually creating NetworkManager profiles in key file format

NetworkManager supports profiles stored in the key file format. However, by default, if you use NetworkManager utilities, such as nmcli, the networking RHEL System Role, or the nmstate API to manage profiles, NetworkManager still uses profiles in the ifcfg format.

In the next major RHEL release, the key file format will be the default.

24.1. The key file format of NetworkManager profiles

NetworkManager uses the INI-style key file format when it stores connection profiles on disk.

Example of an Ethernet connection profile in key file format

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

[ipv4]
method=auto

[ipv6]
method=auto

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

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 key files have a one-to-one mapping. This means that a NetworkManager property is stored in the key file as a variable of the same name and in the same format. However, there are exceptions, mainly to make the key file 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 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 general location for persistent profiles created by the user that can also be edited. NetworkManager copies them automatically to /etc/NetworkManager/system-connections/.
  • /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 key file format, use the nmcli connection reload command to inform NetworkManager about the changes.

24.2. Creating a NetworkManager profile in key file format

This section explains a general procedure on how to manually create a NetworkManager connection profile in key file format.

Note

Manually creating or updating the configuration files can result in an unexpected or non-functional network configuration. Red Hat recommends that you use NetworkManager utilities, such as nmcli, the network RHEL System Role, or the nmstate API to manage NetworkManager connections.

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=802-3-ethernet
    autoconnect=true
    
    [ipv4]
    method=auto
    
    [ipv6]
    method=auto
    
    [802-3-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. Optional: 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
  2. Display the IP settings of the interface:

    # ip address show enp1s0

Additional resources

  • nm-settings-keyfile (5)