Inspect and debug NetworkManager without guessing

You will inspect the daemon that is actually running, see the configuration it has read, and collect useful trace logs without editing a vendor file. This guide targets NetworkManager 1.46.0, the version installed with network-manager 1.46.0-1ubuntu2.8 on the reference system. Allow 15 minutes for inspection, or longer if you need to reproduce a fault.

You need a shell and a working NetworkManager installation. Reading status and configuration is normally unprivileged. Writing a configuration snippet and restarting the service requires sudo and can interrupt active connections.

1. Confirm the daemon and package

Start by proving which binary and package you are investigating. This prevents a common distraction: debugging one installation while a different binary, container or test build is in use.

$ command -v NetworkManager
/usr/sbin/NetworkManager
$ NetworkManager --version
1.46.0
$ dpkg-query -W -f='${Package} ${Version}\n' network-manager
network-manager 1.46.0-1ubuntu2.8
$ systemctl show -p ActiveState,SubState NetworkManager
ActiveState=active
SubState=running

On another distribution, the package query differs, but NetworkManager --version and systemctl remain useful checks. If the unit is not active, stop here and investigate its service status before changing configuration.

2. Read the effective configuration

Use the daemon itself to show the merged configuration:

$ NetworkManager --print-config

This command reads configuration files and exits. It does not include connection profiles, so inspect those separately with nmcli connection. On the reference system, the output shows /etc/NetworkManager/NetworkManager.conf, vendor snippets, dns=systemd-resolved, plugins=ifupdown,keyfile, and an unmanaged-devices rule that excludes most devices except Wi-Fi and mobile broadband.

That output is more useful than opening one file in isolation. NetworkManager reads vendor snippets from /usr/lib/NetworkManager/conf.d, runtime snippets from /run/NetworkManager/conf.d, the main file, then administrator snippets in /etc/NetworkManager/conf.d. Later files override earlier settings. The internal file under /var/lib/NetworkManager is read last and is not for hand editing.

Prefer a new file in /etc/NetworkManager/conf.d for an administrator change. Do not edit a distribution-owned main file: a package update may replace it. A file name such as 95-local-debug.conf also makes ordering visible when you inspect the result.

3. Check live devices and profiles

The daemon configures devices, but nmcli is the practical inspection interface for live state. Run these commands before editing anything:

$ nmcli general status
$ nmcli device status
$ nmcli connection show
$ ip link show
$ ip address show
$ ip route show

Compare the device list with the profiles and kernel addresses. An unmanaged device is not the same as a device with a broken profile. If NetworkManager says a device is unmanaged, inspect the effective configuration and udev properties before trying to force it managed.

There are two different configuration ideas here. A device rule such as device*.managed=1 can be explicitly overruled through the API. A keyfile unmanaged-devices rule is strict and cannot be overruled with nmcli device set IFNAME managed yes. That distinction explains why a seemingly correct nmcli command may appear to do nothing.

For a profile that exists on disk but is not visible to NetworkManager, use nmcli connection reload. The monitor-connection-files setting is deprecated and does not automatically reload profiles.

4. Enable temporary trace logging

For a short, reproducible fault, runtime logging avoids leaving a persistent file behind:

$ sudo nmcli general logging level TRACE domains ALL
$ nmcli general logging

Expect the second command to report LEVEL TRACE and all logging domains. Reproduce the problem, then collect only the relevant journal entries:

$ sudo journalctl -u NetworkManager --since '5 minutes ago' --no-pager

Trace output is deliberately verbose. It should not contain NetworkManager secrets, but logs can still reveal IP addresses, interface names and network layout. Review them before sharing. When you are finished, return to ordinary logging:

$ sudo nmcli general logging level INFO domains DEFAULT

This changes the running daemon only. It does not create a persistent configuration file. If your system reports a different existing level or domain set, record it first and restore that exact output instead of assuming the defaults.

5. Capture logs from daemon startup

If the failure happens during startup, runtime logging can begin too late. Create a dedicated administrator snippet:

$ sudo install -d -m 0755 /etc/NetworkManager/conf.d
$ sudo tee /etc/NetworkManager/conf.d/95-local-debug.conf > /dev/null <<'EOF'
[logging]
level=TRACE
domains=ALL
EOF
$ NetworkManager --print-config | sed -n '/^\[logging\]/,/^\[/p'

The printed section should contain level=TRACE and domains=ALL. The next action restarts the service, so warn anyone using the machine first:

$ sudo systemctl restart NetworkManager
$ systemctl show -p ActiveState,SubState NetworkManager
ActiveState=active
SubState=running
$ sudo journalctl -u NetworkManager -b --no-pager

A restart can briefly interrupt networking. Reproduce the issue, save the relevant journal output, then remove the temporary snippet and restart again:

$ sudo rm /etc/NetworkManager/conf.d/95-local-debug.conf
$ sudo systemctl restart NetworkManager

Removing this file is the undo operation. Keep it only if you deliberately want persistent trace logging and have accepted the volume and privacy implications. If the restart fails, restore connectivity through the local console or an out-of-band session, inspect journalctl -u NetworkManager -b, and do not repeatedly restart a remote host.

6. Reload the right thing

A signal is not a universal refresh button. SIGHUP reloads supported daemon configuration and can briefly interrupt name resolution because the DNS plugin may restart. It does not reload connection profiles from disk. Use nmcli connection reload for profiles, and use a service restart when a setting cannot be changed at runtime.

For a normal configuration reload, prefer the service manager so the action is visible in the journal:

$ sudo systemctl reload NetworkManager
$ sudo journalctl -u NetworkManager -n 30 --no-pager

Some settings need a restart, and the installed manual is the authority for the version on your machine. After either action, verify the effective configuration and live state again rather than trusting a successful exit status.