Build and Safely Tune NetworkManager Profiles with nmcli

By the end of this guide you will be able to create a NetworkManager connection profile, change its IP settings, add Wi-Fi security, activate it deliberately, and return to the previous configuration when needed. The examples use NetworkManager 1.46.0 and nmcli 1.46.0, as installed on Ubuntu at the time of writing.

Allow about 10 minutes for a new profile, or 5 minutes to adjust an existing one. You need NetworkManager running and a shell account allowed to manage connections. Some systems permit ordinary users to use nmcli for their own session; use sudo when nmcli reports that a policy or permission is required.

1. Find the profile and device you mean

A NetworkManager profile is saved configuration, not the device itself. Several profiles can exist for one interface, and only one may be active there at a time. Start by listing both profiles and devices.

nmcli -f NAME,UUID,TYPE,DEVICE connection show
nmcli -f DEVICE,TYPE,STATE,CONNECTION device status

Use the profile name or, preferably, its UUID when a name may be ambiguous. Keep a copy of the current values before changing a profile:

nmcli -f connection.id,connection.uuid,connection.type,connection.interface-name,connection.autoconnect,ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns,ipv6.method connection show "PROFILE_NAME"

Expected output includes one profile name and UUID, followed by properties such as ipv4.method: auto. The auto value means DHCP for IPv4. A blank address or gateway is not necessarily an error: those values can be supplied by DHCP or another setting.

2. Create a separate Wi-Fi profile

Creating a new profile is a useful low-risk way to test settings without overwriting a working connection. This command saves a profile but does not contain a password and does not activate it.

sudo nmcli connection add type wifi ifname "*" con-name "Lab Wi-Fi" ssid "EXAMPLE_SSID" autoconnect no

The asterisk means that the profile is not tied to one interface name. That is usually better for a portable Wi-Fi profile. The command prints the new connection name and UUID. Check it before adding further settings:

nmcli -f connection.id,connection.uuid,connection.type,802-11-wireless.ssid,connection.autoconnect connection show "Lab Wi-Fi"

NetworkManager calls the Wi-Fi setting 802-11-wireless; nmcli also accepts its shorter alias, wifi. The long property names are clearer in scripts and when reading output.

3. Add WPA-Personal security without exposing a real password

For a normal WPA2 or WPA3 Personal network, set wifi-sec.key-mgmt to wpa-psk and then set the key. The password is a secret, so do not put a real value in shell history, a ticket, or a public script. The following shows the property names and syntax; use the interactive editor below when entering a real password:

sudo nmcli connection modify "Lab Wi-Fi" wifi-sec.key-mgmt wpa-psk
sudo nmcli connection modify "Lab Wi-Fi" wifi-sec.psk "EXAMPLE_WIFI_PASSWORD"

For WPA-PSK, the manpage accepts an ASCII passphrase of 8 to 63 characters or a 64-character hexadecimal key. WPA3 Personal with SAE has different passphrase rules, but wpa-psk is the compatibility choice for WPA2 plus WPA3 Personal. Do not choose sae unless the access point and client policy require WPA3-only operation.

To avoid putting the secret in the command line, run the modification interactively:

sudo nmcli connection edit "Lab Wi-Fi"

At the editor prompt, enter set wifi-sec.psk, provide the value when requested, then enter save and quit. Verify the security type without printing the password:

nmcli -f 802-11-wireless.ssid,802-11-wireless-security.key-mgmt connection show "Lab Wi-Fi"

Expected output shows the SSID and wpa-psk. Treat any command that displays full connection settings as sensitive because secret values may be revealed to a privileged user.

4. Choose DHCP or a static IPv4 configuration

DHCP is the safer default on an ordinary home or office network. Set the profile back to DHCP like this:

sudo nmcli connection modify "Lab Wi-Fi" ipv4.method auto ipv4.addresses "" ipv4.gateway "" ipv4.dns ""

The empty values clear the static address, gateway, and DNS list. The profile then obtains those values automatically when activated. The corresponding verification is:

nmcli -f ipv4.method,ipv4.addresses,ipv4.gateway,ipv4.dns connection show "Lab Wi-Fi"

For a device that must keep a known address, use manual, an address with prefix length, and a gateway on the same reachable network:

sudo nmcli connection modify "Lab Wi-Fi" \
  ipv4.method manual \
  ipv4.addresses "192.0.2.50/24" \
  ipv4.gateway "192.0.2.1" \
  ipv4.dns "192.0.2.53,192.0.2.54"

The addresses are a comma-separated list, with the first address treated as primary. The gateway is meaningful when an address is also set and normally creates the default route. The documentation uses the ipv4.addresses, ipv4.gateway, and ipv4.dns properties for these values; the shorter aliases are ip4, gw4, and dns.

5. Activate the profile and verify the live result

Profile edits are saved configuration. They become the live configuration when the profile is activated:

sudo nmcli connection up id "Lab Wi-Fi"

Expected output reports that the connection was successfully activated and names the device. Check the active profile, assigned addresses, and routes separately:

nmcli -f DEVICE,TYPE,STATE,CONNECTION device status
nmcli -f IP4.ADDRESS,IP4.GATEWAY,IP4.DNS device show "INTERFACE_NAME"
ip route

If activation fails, read the error before changing more properties. Common causes are an incorrect SSID, an unsupported security mode, an address already in use, or a gateway that is not reachable from the selected prefix. A profile can be valid as saved configuration but still fail when a particular device or access point is involved.

6. Undo a test profile or restore its previous values

If you created the separate example profile, disconnect it before removing it. Deletion is irreversible from NetworkManager's point of view, so check the name first:

nmcli -f NAME,UUID,DEVICE connection show "Lab Wi-Fi"
sudo nmcli connection down id "Lab Wi-Fi"
sudo nmcli connection delete id "Lab Wi-Fi"

If you modified an existing profile, restore the values from the copy made in step 1. For example, return to DHCP with:

sudo nmcli connection modify "PROFILE_NAME" \
  ipv4.method auto ipv4.addresses "" ipv4.gateway "" ipv4.dns ""

Then activate the profile again if you need the old configuration immediately. If a remote session is at risk, make the undo command ready before applying the change.

Done means

• You changed the intended profile, identified by name and preferably UUID.
• The profile has the expected SSID, security mode, IP method, address, gateway, and DNS values.
• You activated it deliberately and checked the live device and route.
• You know whether the secret is stored by the system or supplied by a secret agent, and you have not published it in shell history.
• You can restore the saved values or remove a disposable test profile.