Debugging

Since NetworkManager runs in the background except for the configuration work, you cannot easily check your own dispatcher scripts for errors. If something goes wrong, don't expect a window with helpful error messages. If there is a bug in the script, simply nothing happens. To find programming errors, check out the system logs.

On the one hand, nmcli monitor lets you trace what NetworkManager is doing in real time. You can see the network device names and what actions are currently running. To view the NetworkManager logs, you need to read the system journal with journalctl. The following command:

journalctl -f -u NetworkManager

lets you have a look at the log in real time and filter the output from NetworkManager (Listing 9).

$ journalctl -f -u NetworkManager
[...]
May 22 23:21:45 ontario NetworkManager[485]: <warn> [1590182505.2987] dispatcher:
(44) /etc/NetworkManager/dispatcher.d/30-mount-diskstation failed (failed):
Script '/etc/NetworkManager/dispatcher.d/30-mount-diskstation'
exited with error status 2.
$ nmcli monitor
enp0s31f6: Connection "LAN1" is used
enp0s31f6: is connected (being prepared)
NetworkManager is now in the state "being connected
[...]
NetworkManager is now in "connected" state
Connection state is now "complete

These commands give you a general overview of NetworkManager's actions. However, in order to search for an error, it is recommended that you send content to the systemd log yourself at critical points using logger. For an example, as shown in Listing 10, you can use the $0 (script name), $1 (network device), and $2 (action) variables also used by NetworkManager for dispatching, as well as the environment variables provided by the dispatcher function, such as $CONNECTION_UUUID or $IP4_DOMAINS (Listing 11).

#!/bin/bash
logger "Logger: Run script $0."
if [ "$2" = "up" ]; then
  logger "LOGGER: network device: $1, action: $2"
  logger "LOGGER: Environment: CONNECTION_UUUID=$CONNECTION_UUID, IP4_DOMAINS=$IP4_DOMAINS"
fi

$ journalctl -f | grep LOGGER
[...]
May 22 23:36:47 root [16135]: LOGGER: Run script /etc/NetworkManager/dispatcher.d/30-mount-diskstation
May 22 23:36:47 root [16136]: LOGGER: network device: enp0s31f6, action: up
May 22 23:50:31 oroot[18811]: LOGGER: Environment: CONNECTION_UUUID=2911db45-3eff-3b74-9c87-4c36e0290693,
IP4_DOMAINS=fritz.box

Conclusion

A meaningful dispatcher script will not automatically write itself. It takes some time to get everything working as desired. But once you work through all the details, you can get a dispatcher script to do almost anything you can do on the system at the file level. The biggest difficulty is extracting log output or viewing the environment variables populated during dispatching. But if you know the tricks, you can quickly overcome these hurdles.