Mastering NetworkManager Dispatcher: Automate ‘Everything’ When Changing Networks on Linux

Why keep typing commands every time you change networks?

Familiar scenario: You take your laptop from home to the office. At home, you use a simple 192.168.1.x IP range. But as soon as you arrive at work, you have to turn on WireGuard VPN, reconfigure routing tables to access internal servers, and disable unnecessary services for security. In the afternoon, you repeat that tedious process all over again.

Doing it manually works, but it’s prone to error. NetworkManager Dispatcher Scripts are the ultimate solution to this problem. It acts as a hook system: whenever a network state change is detected, it automatically triggers the scripts you’ve set up.

I once spent a whole week debugging packet loss just because an old background script was resetting the interface every 5 minutes. From that, I learned a lesson: automation must be transparent. NetworkManager Dispatcher does this very well because it’s event-driven, giving you tighter control over your system.

Comparing Network Automation Methods

Before diving into the code, let’s see why Dispatcher Scripts are superior to traditional methods:

• Cron Job: This is a “brute force” approach. Checking the network every 1-5 minutes causes both latency and unnecessary CPU waste.
• Systemd Service: More professional but complex to configure. Capturing the exact moment an interface goes “UP” to run a command isn’t simple for beginners.
• NetworkManager Dispatcher: This is a native feature. It sits in the background waiting. Only when you plug in a LAN cable or Wi-Fi connects successfully does it execute. Fast, clean, and extremely precise.

Pros and Cons to Consider

Advantages

• Instant Response: Executes the moment the network state changes (milliseconds).
• Clear Context: The script knows exactly which interface is running and what the specific action is (up/down/vpn-up).

Disadvantages

• Security Risks: Scripts run with root privileges. A small mistake in the code can leave the system wide open.
• Hard to Monitor: If a script fails, it “dies” silently. You have to check system logs to find the cause.

How Dispatcher Scripts Work

NetworkManager scans the /etc/NetworkManager/dispatcher.d/ directory. It executes the scripts inside in alphabetical order whenever there is a connection change.

When running, NetworkManager passes in 2 input parameters:

1. $1: Interface name (e.g., eth0, wlan0, tun0).
2. $2: Action state (e.g., up, down, vpn-up, vpn-down).

Practical Implementation Guide

Step 1: Create a Basic Monitoring Script

First, create a script to log events. This helps you confirm whether the system is correctly identifying events.

sudo nano /etc/NetworkManager/dispatcher.d/99-network-log.sh

Script content:

#!/bin/bash

INTERFACE=$1
ACTION=$2

case "$ACTION" in
    up)
        echo "$(date): Interface $INTERFACE connected" >> /var/log/network-events.log
        ;;
    down)
        echo "$(date): Interface $INTERFACE disconnected" >> /var/log/network-events.log
        ;;
esac

Step 2: Set Execution Permissions

NetworkManager is very strict about permissions. If permissions are too loose, it will ignore the script for safety.

sudo chmod 755 /etc/NetworkManager/dispatcher.d/99-network-log.sh
sudo chown root:root /etc/NetworkManager/dispatcher.d/99-network-log.sh

Step 3: Automatically Configure Routes and Firewalls by SSID

Suppose when you join the office Wi-Fi with the SSID “Office-Guest”, you need to add a route to the 10.10.x.x range and open port 8080.

Leverage the available $CONNECTION_ID environment variable:

#!/bin/bash

if [ "$CONNECTION_ID" == "Office-Guest" ]; then
    case "$2" in
        up)
            # Add static route via gateway 192.168.10.1
            ip route add 10.10.0.0/16 via 192.168.10.1 dev $1
            # Open port on Firewall
            ufw allow from 10.10.0.0/16 to any port 8080 proto tcp
            ;;
        down)
            ip route del 10.10.0.0/16 dev $1
            ufw delete allow from 10.10.0.0/16 to any port 8080 proto tcp
            ;;
    esac
fi

Debugging Tips When Scripts Don’t Work

Since scripts run in the background, you won’t see errors displayed in the terminal. Use the following command to view real-time logs:

journalctl -u NetworkManager -f

For more detail, add set -x to the second line of the script. This will display every executed command in the log, helping you identify where the script is stuck.

Conclusion

NetworkManager Dispatcher Scripts are a powerful tool for Sysadmins and Linux enthusiasts. Instead of wasting 2-3 minutes manually configuring every time you change networks, let the computer handle it in 1 second. Start with small tasks like auto-mounting network drives (NFS) or sending Telegram notifications when the server changes its IP. Good luck!