Edit NetworkManager Keyfiles Safely and Reload Them

You will create a small NetworkManager connection profile in the native keyfile format, install it with safe permissions, ask NetworkManager to reload it, and verify the resulting connection. The example uses DHCP on an ethernet interface, so replace the example interface and profile name with values from your host.

Allow about fifteen minutes. You need NetworkManager, nmcli, a shell, and sudo access for the installation and reload steps. The commands were checked against NetworkManager 1.46.0, installed here as package version 1.46.0-1ubuntu2.8. Key names and accepted values can differ between releases, so check the local manual before adapting this to a more specialised connection.

1. Find the interface and existing profiles

Start with read-only checks. This shows interfaces that NetworkManager knows about and the profiles already present:

$ nmcli device status
$ nmcli connection show

Record the interface name you intend to manage, such as enp1s0. Do not guess it from a tutorial: predictable interface names vary between machines. Also choose a new profile name, such as Office DHCP (keyfile), rather than silently replacing an existing profile.

Checkpoint: confirm that NetworkManager is running and that the interface is listed before creating a file:

$ nmcli general status
$ nmcli -f GENERAL.DEVICE,GENERAL.STATE device show enp1s0

Replace enp1s0 in the second command. This step needs no elevated privileges.

2. Write a keyfile in a temporary directory

A keyfile is an INI-style document. Sections use NetworkManager setting names, and properties are normally written with the same names as the settings specification. The keyfile plugin also accepts these shorter section aliases: ethernet for 802-3-ethernet, wifi for 802-11-wireless, and wifi-security for 802-11-wireless-security.

Create the file as your ordinary user in /tmp. Keeping the draft outside NetworkManager's search paths lets you check it before it can affect a live connection:

$ umask 077
$ nano /tmp/office-dhcp.nmconnection

Paste this example, then change enp1s0 and the connection ID:

[connection]
id=Office DHCP (keyfile)
type=ethernet
interface-name=enp1s0
autoconnect=false

[ethernet]

[ipv4]
method=auto

[ipv6]
method=auto

The connection section identifies the profile and binds it to one interface. autoconnect=false is deliberate: the profile will not take over automatically while you are testing it. The empty [ethernet] section is valid and makes the connection type explicit. DHCP is selected by method=auto in the IPv4 and IPv6 sections.

Do not put a real password or private key in a temporary draft unless you have a specific reason. Keyfiles can contain secrets in plaintext. If you do handle one, keep the file root-readable only and remove temporary copies after checking them.

3. Install the profile with root-only permissions

NetworkManager searches system keyfiles in /etc/NetworkManager/system-connections/, /usr/lib/NetworkManager/system-connections/, and /run/NetworkManager/system-connections/. For a manually managed persistent profile, use the /etc directory. The plugin ignores a file that is readable or writable by a user or group other than root because connection files may contain passphrases and private keys.

This is the first state-changing step and needs elevated privileges. Check the destination first, then copy the draft with a new filename:

$ sudo install -o root -g root -m 600 /tmp/office-dhcp.nmconnection \
    /etc/NetworkManager/system-connections/office-dhcp.nmconnection
$ sudo stat -c '%U:%G %a %n' \
    /etc/NetworkManager/system-connections/office-dhcp.nmconnection

Expected output ends with root:root 600 /etc/NetworkManager/system-connections/office-dhcp.nmconnection. The exact spacing and path are host-specific. If the mode or ownership is wrong, stop and fix it before reloading.

Warning: do not overwrite an existing profile file merely to reuse its name. If you are replacing a working profile, save a root-owned backup first and make sure you know how to restore it. A bad network profile can disconnect a remote machine.

4. Tell NetworkManager about the file

NetworkManager does not promise to notice a manually edited keyfile immediately. Inform it explicitly with nmcli connection reload:

$ sudo nmcli connection reload
$ nmcli -f NAME,UUID,TYPE,DEVICE connection show

The reload command normally prints nothing on success. The second command should now include Office DHCP (keyfile) with type ethernet. The device column can be blank because autoconnect=false means the profile is not active.

Checkpoint: if the new profile is absent, check the filename, root-only mode, section spelling and NetworkManager's journal before changing anything else:

$ sudo journalctl -u NetworkManager -b --no-pager -n 40
$ sudo ls -l /etc/NetworkManager/system-connections/

Do not make a file world-readable as a diagnostic shortcut. That can cause NetworkManager to ignore it and exposes any stored secrets.

5. Activate and verify the connection

Activation changes network state and may interrupt an existing connection. On a local test system, activate the new profile explicitly:

$ sudo nmcli connection up 'Office DHCP (keyfile)'

On success, nmcli reports that the connection was successfully activated and normally names the device. Verify the state and the addresses separately:

$ nmcli -f NAME,TYPE,DEVICE connection show --active
$ nmcli -f GENERAL.STATE,IP4.ADDRESS,IP4.GATEWAY,IP4.DNS device show enp1s0

Replace enp1s0 with the interface you recorded earlier. Expect a connected state and an address supplied by DHCP. The exact address, gateway and DNS values depend on the network. A successful activation does not prove that routing or name resolution suits your application, so test the actual service that needs this connection.

If activation fails, read the error and inspect the journal. Do not repeatedly bring a profile up on a production link while guessing at settings. The profile is still available for correction because the file was installed separately from the old configuration.

6. Recover by disabling or removing your test profile

To stop the active test connection without deleting its definition, use:

$ sudo nmcli connection down 'Office DHCP (keyfile)'

To make it unavailable for later activation, move the file to a root-only backup outside the keyfile directory, then reload. Moving is reversible and preserves the exact text:

$ sudo mv /etc/NetworkManager/system-connections/office-dhcp.nmconnection \
    /root/office-dhcp.nmconnection.disabled
$ sudo nmcli connection reload

Restore it with the inverse sudo mv, check mode 600, and run sudo nmcli connection reload again. Do not use rm until you have confirmed that the profile and any secrets are no longer needed.

7. Know the keyfile format traps

Most properties map directly to their setting names, but several useful values have keyfile-specific syntax. DNS servers are a semicolon-separated list, for example dns=1.1.1.1;9.9.9.9;. Static addresses use numbered keys such as address1=192.0.2.20/24, not one repeated addresses key. Routes use route1=198.51.100.0/24,192.0.2.1,50, where the optional fields are gateway and metric. IPv6 uses the same numbered pattern with IPv6 values.

Do not copy the visual examples into a different setting without checking nm-settings-nmcli(5). Secret flags are decimal bit values: 0 means NetworkManager owns the secret, 1 asks a user-session secret agent, 2 means ask each time rather than save it, and 4 marks a secret as not required. These values can be added when a setting supports more than one flag. A stored password may still be visible in the keyfile, so treat the file as sensitive.