NetworkManager Dispatcher Scripts for Linux Automation

NetworkManager dispatcher scripts provide an automated, event-driven mechanism for executing custom commands and programs whenever network state changes occur in a Linux operating system. This article explains the purpose of these scripts, how they function, their execution environment, and how administrators use them to streamline network operations, manage system services, and enforce dynamic security policies.

What Are NetworkManager Dispatcher Scripts?

NetworkManager dispatcher scripts are executable files placed in the /etc/NetworkManager/dispatcher.d/ directory. NetworkManager executes these scripts automatically in response to specific network events, such as an interface establishing a connection, disconnecting, or changing IP configurations. Rather than manually running commands or relying on continuous background polling, administrators use dispatcher scripts to trigger actions only when an actual state transition happens.

How Dispatcher Scripts Function

When a network transition occurs, the nm-dispatcher daemon executes the scripts within the directory in alphabetical order. To execute safely, each script must be owned by root, have execute permissions (chmod 755), and must not be writable by any user other than root.

NetworkManager passes two primary positional parameters to each script:

1. $1 (Interface Name): The name of the network interface involved (e.g., eth0, wlan0).
2. $2 (Action/Event): The specific event that triggered the script (e.g., up, down, pre-up, vpn-up, vpn-down).

In addition to positional arguments, NetworkManager exposes dynamic connection details through environment variables, including CONNECTION_UUID, CONNECTION_ID, IP4_ADDRESS_0, and DEVICE_IP_IFACE. These variables allow scripts to identify specific Wi-Fi networks, VPN profiles, or Ethernet ports and act accordingly.

Core Automation Use Cases

• Dynamic Firewall Configuration: Administrators can adapt firewall profiles depending on the connected network. For example, a laptop connecting to a home Wi-Fi network can trigger a script to open local file-sharing ports, while switching to an untrusted public network can automatically switch the firewall to a restrictive profile.
• Mounting and Unmounting Network Storage: Dispatcher scripts can automatically mount Network File System (NFS) or Server Message Block (SMB) network drives when an office local area network (LAN) connects, and cleanly unmount them before the connection completely terminates to prevent hung filesystem processes.
• Dynamic DNS and Routing Updates: When an interface obtains a new public or private IP address via DHCP, a script can notify an external Dynamic DNS (DDNS) provider or inject custom routing table entries required for complex split-tunnel environments.
• Service Control: Specific system daemons—such as synchronization tools, backups, or proprietary monitoring agents—can be started when a high-speed wired connection is active and stopped when switching to mobile broadband or metered connections.
• Compliance and Logging: Organizations use scripts to log connection metadata, verify system compliance, and push alerts to centralized logging servers upon network connection.

By leveraging dispatcher scripts, Linux administrators achieve low-overhead, precise automation that reacts instantly to changing network topologies without requiring user intervention.