Change a Saved Network Profile Without Breaking It

The nm-settings manual lists every property a NetworkManager profile understands, which is exactly what you need to change one without guessing. This guide inspects a profile, changes its IPv4 and DNS settings, verifies what saved, and rolls back if it was 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 need sudo, depending on the profile's permissions and your local policy.

1. Identify the profile before touching it

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

$ nmcli connection show
$ nmcli connection show --active

Use the profile's NAME, or better, 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 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"

2. Read the effective properties

nm-settings names use a setting.property form. For an ordinary Ethernet or Wi-Fi profile, this is the useful core:

Ask for just those fields to keep the output scannable:

$ 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 instead. For example, ipv4.gateway only means anything alongside an address, and ipv4.never-default stops a profile becoming the default route even when an address is present.

3. Save a reversible snapshot

Before changing anything, save the exact values you are about to 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 note 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 you are working in.

4. Change DHCP to a static IPv4 profile

Use documentation-range values only as placeholders, then 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 carries its own prefix length.
• DNS values are a list, and replace, not append. This command overwrites the existing list entirely.

NetworkManager saves the profile straight away, but a saved change does not always mean the running device has adopted every value yet. 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"

5. Apply and verify the change

Reactivating a profile is service-disrupting. Only do it 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 what you set. DNS display depends on the resolver plugin, so also test a real name that should resolve in your environment; a successful ping to a bare IP address is not proof that DNS is correct.

6. Restore DHCP if the change fails

To undo the static example, put the profile back to automatic IPv4 and remove the values that only made sense for a 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 not the same as inventing a new DNS server or leaving the old static address in place. 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 for good.

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, a higher connection.autoconnect-priority wins, and 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 whole list.
• Showing secrets accidentally. Do not add --show-secrets to routine inspection, and never paste its output into a ticket.
• Assuming every property fits every profile. The manpage lists all settings, but applicability depends on the connection type.