NetworkManager Dispatcher Events: What They Mean & When They Run

NetworkManager dispatcher events are scripts that run automatically when your network connection changes state, such as connecting to Wi-Fi, losing Ethernet, or starting a VPN. They let you trigger custom actions—like updating DNS, mounting a drive, or logging connection history—at precise moments in the network lifecycle. This article explains each event, when it fires, and how to use them safely.

What Are Dispatcher Scripts?

NetworkManager is the default network management service on most Linux distributions (Ubuntu, Fedora, Debian, Arch). When a network interface changes state—connecting, disconnecting, or reconfiguring—NetworkManager runs scripts placed in the /etc/NetworkManager/dispatcher.d/ directory. These scripts receive two arguments: the interface name (e.g., eth0, wlan0) and the event name (e.g., up, down).

Dispatcher scripts are executed as the root user, so they can perform system-wide actions like modifying firewall rules or writing to protected directories. They are synchronous by default—NetworkManager waits for the script to finish before proceeding with the next step—so a slow or hanging script can delay your network setup.

The Core Events: up, down, pre-up, and post-down

The most common events are tied to the interface’s operational state. Here is what each one means and when it runs:

• up — Fires after the interface has successfully connected and been assigned an IP address. This is the most frequently used event for starting services, mounting network shares, or updating dynamic DNS.
• down — Fires after the interface has disconnected or been brought down. Use this to stop services, unmount shares, or clean up temporary routes.
• pre-up — Runs before the interface is configured with an IP address, but after the link is physically up (carrier detected). Useful for setting custom MAC addresses or VLAN tags before the IP assignment.
• post-down — Runs after the interface is fully brought down, but before the dispatcher finishes. Rarely needed; down usually suffices.

Note that up and down are the only events that fire for every connection type (Wi-Fi, Ethernet, mobile broadband). The others are specific to certain conditions.

VPN and Connectivity Events

In addition to interface events, NetworkManager dispatcher also handles VPN and overall connectivity changes:

• vpn-up — Fires when a VPN connection is established. The interface argument is the VPN interface name (e.g., tun0).
• vpn-down — Fires when a VPN connection is terminated.
• vpn-pre-up — Runs before the VPN tunnel is fully configured, but after the underlying connection is up.
• vpn-post-down — Runs after the VPN tunnel is torn down.
• connectivity-change — Fires when NetworkManager’s internet connectivity check changes (e.g., from full to none). The interface argument is empty, and the event is passed via environment variable CONNECTIVITY_STATE.

These events allow you to update routing tables, flush DNS caches, or restart dependent services when a VPN goes up or down.

How to Write a Dispatcher Script

Writing a dispatcher script is straightforward, but there are important rules:

1. Create a file in /etc/NetworkManager/dispatcher.d/ with a descriptive name (e.g., 99-custom-action).
2. Make it executable: sudo chmod +x /etc/NetworkManager/dispatcher.d/99-custom-action.
3. The script must be a valid shell script (or any executable). It receives two arguments: $1 is the interface, $2 is the event.
4. Always check the event and interface before acting. For example, only run on up for eth0.

Here is a minimal example that logs when Wi-Fi connects:

#!/bin/bash
if [ "$2" = "up" ] && [[ "$1" == wl* ]]; then
    echo "$(date): $1 connected" >> /var/log/wifi.log
fi

Remember: the script runs as root, so be careful with commands that could have side effects. Always test with a harmless action first.

Common Pitfalls and Misconceptions

One frequent mistake is assuming up means the internet is reachable. It only means the interface has an IP address—DNS, gateway, or external connectivity may still be broken. For internet-dependent actions, use connectivity-change with a check on CONNECTIVITY_STATE.

Another misconception is that scripts run in alphabetical order. They do, but the order is not guaranteed to be the same across versions. If you need strict ordering, use numeric prefixes (e.g., 10-first, 20-second) and keep dependencies minimal.

Also, dispatcher scripts run synchronously. If your script takes 30 seconds to complete, NetworkManager will block that interface’s configuration for 30 seconds. For long tasks, run them in the background with & or use a systemd timer instead.

Debugging and Testing Dispatcher Scripts

To test a dispatcher script without rebooting, you can manually trigger it by running it with the interface and event as arguments. For example:

sudo /etc/NetworkManager/dispatcher.d/99-custom-action wlan0 up

This simulates the event. However, some events like connectivity-change rely on environment variables; you can set them manually:

sudo CONNECTIVITY_STATE=full /etc/NetworkManager/dispatcher.d/99-custom-action "" connectivity-change

Check NetworkManager’s logs for dispatcher errors: journalctl -u NetworkManager or journalctl -t dispatcher (on systemd systems). If a script fails, NetworkManager logs the exit code but does not show the script’s output by default. Redirect output to a log file inside the script for debugging.

Alternatives to Dispatcher Scripts

Dispatcher is not the only way to react to network changes. Depending on your needs, consider:

• systemd networkd — If you use systemd-networkd instead of NetworkManager, it has its own .network files with ExecUp and ExecDown options.
• udev rules — For hardware-level events (e.g., cable plugged in), udev can trigger on change events, but it lacks the high-level connection state info.
• NetworkManager’s D-Bus API — Write a small daemon that listens for signals like StateChanged or DeviceStateChanged. More flexible but more complex.
• cron or systemd timers — For periodic checks (e.g., ping a server every minute), a timer is simpler and does not block network setup.

Dispatcher is best for quick, event-driven tasks that need to happen exactly at the moment of connection change. For anything more complex, a dedicated service is often cleaner.

Frequently Asked Questions

Do dispatcher scripts run on every boot?

Yes, if the network interface comes up during boot, the up event fires. However, if the interface is already up before NetworkManager starts (e.g., due to early boot), the event may not fire. In that case, use a systemd service that starts after NetworkManager to ensure your action runs.

Can I use dispatcher scripts to set DNS servers?

Yes, but it’s not recommended. NetworkManager manages DNS via its own plugins (e.g., dnsmasq, systemd-resolved). Overwriting /etc/resolv.conf in a dispatcher script can conflict with NetworkManager’s settings. Use the dns option in your connection profile instead.

What is the difference between up and pre-up?

pre-up runs before the IP address is assigned, so commands that depend on the IP (like adding a route) may fail. up runs after IP assignment, so the interface is fully usable. Use pre-up only for hardware-level tweaks like setting MTU or MAC.

Why is my script not running?

Check that the script is executable, owned by root, and has no syntax errors. Also verify the event name is spelled correctly (e.g., vpn-up not vpnup). Finally, check NetworkManager logs for errors like “dispatcher: Script execution failed”.

Can I run a script only for a specific Wi-Fi network?

Yes. The dispatcher script receives the connection’s UUID in the environment variable CONNECTION_UUID. You can compare it against the UUID of your target network (found via nmcli connection show) and act accordingly.

Is it safe to run background processes from a dispatcher script?

Yes, but be careful. If you launch a background process, it may be killed when the script exits. Use setsid or nohup to detach it fully, or better, use systemd-run to start a transient unit that survives.

Related

• Best PS5 Settings for Aim, Audio & Visibility
• How Much RAM Does a Local LLM Need?
• Page Break in Google Docs: Add, Move, Remove