Configure NetworkManager Profiles Safely with nmcli

You will finish with a controlled way to inspect a NetworkManager connection profile, change its IPv4 and DNS settings, verify what was saved, and restore the previous values if the change is wrong. The examples match NetworkManager 1.46.0 and its nm-settings property names.

Allow about fifteen minutes. You need a shell, NetworkManager and an existing profile name. Reading profiles is normally unprivileged. Modifying a system connection may require sudo, depending on the profile permissions and your local policy.

1. Identify the profile before touching it

A NetworkManager profile is saved configuration, not necessarily the configuration currently applied to a device. Start by listing profiles and active connections:

$ nmcli connection show
$ nmcli connection show --active

Use the profile's NAME or, preferably, its UUID when a name is ambiguous. The UUID is the profile's unique identifier and cannot normally be changed. Replace PROFILE_NAME below with the exact name shown on your machine:

$ nmcli connection show "PROFILE_NAME"
$ nmcli -f connection.id,connection.uuid,connection.type,connection.interface-name,connection.autoconnect connection show "PROFILE_NAME"

Checkpoint: confirm that the type and interface are the ones you intend to change. A profile with no connection.interface-name can attach to any suitable interface; binding it to a name later can make it fail after interface names change.

2. Read the effective properties

The nm-settings names use a setting.property form. The useful core for an ordinary Ethernet or Wi-Fi profile is:

Ask for just those fields to make the output easier to scan:

$ nmcli -f connection.id,connection.uuid,connection.autoconnect,ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns,ipv4.dns-search,ipv4.ignore-auto-dns connection show "PROFILE_NAME"

Do not confuse an unset value with a universal default. NetworkManager can consult global configuration, a DHCP lease, or the DNS plugin. For example, ipv4.gateway only has meaning with addresses, and ipv4.never-default prevents a profile becoming the default route even if an address is present.

3. Save a reversible snapshot

Before changing anything, save the exact values you will replace. This is an ordinary read-only command:

$ nmcli -g ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns,ipv4.dns-search,ipv4.ignore-auto-dns connection show "PROFILE_NAME"

Copy that output somewhere safe and record whether the profile is currently active. If you are changing a remote host, keep an existing session open and arrange console access first. A bad address, gateway or DNS change can cut off the session.

4. Change DHCP to a static IPv4 profile

Use documentation-range values only as placeholders. Replace every value with an address that belongs to your network:

$ sudo nmcli connection modify "PROFILE_NAME" \
    ipv4.method manual \
    ipv4.addresses 192.0.2.25/24 \
    ipv4.gateway 192.0.2.1 \
    ipv4.dns "192.0.2.53,198.51.100.53" \
    ipv4.dns-search "example.invalid" \
    ipv4.ignore-auto-dns yes

ipv4.method manual is the switch that makes the address list static. The address includes its prefix length. DNS values are a list, and this command replaces the existing list; it does not append to it.

NetworkManager saves the profile, but changing the profile does not always mean the running device has already adopted every value. Check the saved profile before deciding whether to activate it:

$ nmcli -f ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns,ipv4.dns-search,ipv4.ignore-auto-dns connection show "PROFILE_NAME"

Checkpoint: the output should show manual, your chosen address and gateway, and the DNS list. If it does not, stop and correct the command before bringing the profile up.

5. Apply and verify the change

Reactivating a profile is service-disrupting. Do it only when that interruption is acceptable:

$ sudo nmcli connection up "PROFILE_NAME"

A successful activation normally reports the connection name and device. Then inspect both the active device and the profile:

$ nmcli device show <INTERFACE_NAME> | rg 'IP4.ADDRESS|IP4.GATEWAY|IP4.DNS'
$ nmcli connection show --active
$ nmcli -f connection.id,ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns connection show "PROFILE_NAME"

Replace <INTERFACE_NAME> with the device from nmcli connection show --active. The active address and gateway should match the values you selected. DNS display depends on the resolver plugin, so also test a name that should resolve in your environment; do not treat a successful ping to an IP address as proof that DNS is correct.

6. Restore DHCP if the change fails

To undo the static example, return the profile to automatic IPv4 configuration and remove the values that only made sense for the static setup:

$ sudo nmcli connection modify "PROFILE_NAME" \
    ipv4.method auto \
    ipv4.addresses "" \
    ipv4.gateway "" \
    ipv4.dns "" \
    ipv4.dns-search "" \
    ipv4.ignore-auto-dns no
$ sudo nmcli connection up "PROFILE_NAME"

In nmcli, an empty value unsets a list or property. That is different from inventing a new DNS server or leaving the old static address behind. Verify the rollback:

$ nmcli -f ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns,ipv4.ignore-auto-dns connection show "PROFILE_NAME"
ipv4.method:                            auto

If you saved different original values, restore those exact values instead. Do not delete the profile as a first response: nmcli connection delete is destructive and removes the saved profile.

Common traps

• Changing the wrong profile: names are human labels. Use the UUID when several profiles look similar.
• Expecting autoconnect to choose a profile: it only applies when resources are suitable. Among candidates, higher connection.autoconnect-priority wins; equal priorities use the most recently connected profile.
• Appending when you meant to replace: +ipv4.dns appends a DNS value. Plain ipv4.dns replaces the list.
• Showing secrets accidentally: do not add --show-secrets to routine inspection or paste its output into a ticket.
• Assuming every property fits every profile: the manpage lists all settings, but applicability depends on the connection type.