NetworkManager Dispatcher runs administrator-provided scripts when NetworkManager reports certain changes. The action name passed to each script identifies the event: pre-up and pre-down are transition hooks, while up and down report completed activation or deactivation. These events are useful for network-related automation, but they do not guarantee internet access, application readiness, or even that the reported state is still current when a script runs.
What a dispatcher action tells you
Dispatcher is a D-Bus-activated service that runs administrator-provided scripts in response to NetworkManager events. For ordinary invocations, the script receives the interface name as its first argument and the action as its second. The interface argument has exceptions: it is none for hostname, and empty for connectivity-change and dns-change. Device and VPN events can also refer to different interface variables depending on the case.
As an Amazon Associate I earn from qualifying purchases.
The official NetworkManager-dispatcher reference manual defines these actions and their environment. The key distinction is timing: a pre- event occurs before a clean transition completes; its corresponding event without the prefix describes the completed change.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Network and VPN event meanings
| Action | Meaning and timing |
|---|---|
pre-up |
The interface is connected but not yet fully activated. Scripts run late in activation, and NetworkManager waits for them before reporting the interface fully activated. |
up |
The interface has been activated. |
pre-down |
The interface is about to be deactivated but remains connected. NetworkManager waits for applicable scripts before disconnecting it. This clean-transition hook is not emitted for forced losses such as lost carrier or a fading Wi-Fi signal. |
down |
The interface has been deactivated. |
vpn-pre-up |
The VPN is connected but not yet fully activated. It uses the pre-up hook location, and NetworkManager waits before reporting the VPN fully activated. |
vpn-up |
The VPN connection has been activated. |
vpn-pre-down |
The VPN is about to be deactivated but is still connected. NetworkManager waits for applicable scripts before disconnection. Unexpected VPN termination or general connectivity loss does not emit this clean pre-down event. |
vpn-down |
The VPN connection has been deactivated. |
Other dispatcher actions
| Action | When it runs and notable detail |
|---|---|
hostname |
The system hostname has been updated. The interface argument is none, and no environment variable is set for this action. |
dhcp4-change |
The DHCPv4 lease changed, for example through renewal or rebinding. |
dhcp6-change |
The DHCPv6 lease changed. |
connectivity-change |
NetworkManager’s connectivity state changed, such as going online or losing connectivity. The interface argument is empty. |
reapply |
The connection was reapplied on the device. |
dns-change |
DNS configuration changed, including when NetworkManager is configured not to manage resolv.conf. In that case, active connection DNS settings may be found at /run/NetworkManager/resolv.conf. The interface argument is empty. |
device-add |
A special action for a generic connection whose generic.device-handler property names a handler script. Only one script runs, from dispatcher.d/device; additional interface and connection information is provided. |
When pre-up is—and is not—a readiness signal
pre-up runs late in a profile’s activation, and NetworkManager waits for its scripts before it tells applications the interface is fully activated. The NetworkManager-wait-online manual describes this timing. It does not mean a remote host is reachable, a particular application can connect, or every other startup dependency is ready. Use it as a hook for network-transition work, not as a universal test of service availability.
#1 Best Overall
How NetworkManager selects and runs scripts
Scripts are found in /{etc,usr/lib}/NetworkManager/dispatcher.d and applicable subdirectories, then run in alphabetical order. If identically named scripts exist in both locations, the /etc version takes precedence. A valid script must be a regular executable file owned by root, not writable by group or others, and not setuid.
Ordinary scripts receive useful environment values such as NM_DISPATCHER_ACTION, CONNECTION_UUID, CONNECTION_ID, CONNECTION_DBUS_PATH, CONNECTION_FILENAME, CONNECTION_EXTERNAL, DEVICE_IFACE, and DEVICE_IP_IFACE. IP configuration variables are exported where applicable; VPN invocations can include VPN-prefixed interface and address variables. Connection user settings are exposed as CONNECTION_USER_ variables after key encoding. The exact environment varies by action, so consult the reference manual for the complete action-specific list.
Scripts run one at a time and asynchronously from NetworkManager’s main process. A long-running script can be killed. If the work may take an arbitrary amount of time, start a child process and return promptly. A script symlinked into /etc/NetworkManager/dispatcher.d/no-wait.d/ runs immediately in parallel, without waiting for preceding scripts to terminate.
Choose an event and handle stale actions safely
- Use
pre-uporvpn-pre-upfor work that must finish before NetworkManager reports activation complete; useuporvpn-upfor work that follows activation. - Use
pre-downorvpn-pre-downfor cleanup that needs a clean disconnect opportunity. Do not rely on these events to handle sudden link failure or unexpected VPN termination. - Choose the VPN-specific action when the transition belongs to a VPN rather than the underlying device. Check the relevant interface argument and environment variables instead of assuming one interface name applies to every case.
- Keep ordered work short. Use
no-wait.donly when parallel execution is acceptable, or launch a child process if lengthy work should not hold up the dispatcher. - Recheck current device or connection state before taking consequential action. An event already queued can still run after a newer event has made it obsolete—for example, an
upscript may run after the interface has gone down.
The action identifies why a script was queued; it is not a guarantee that the same condition still holds at execution time.
Quick Recap
Best Value
Rank #4
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
