NetworkManager Dispatcher Scripts Not Running: Fixes

If your NetworkManager dispatcher scripts are not running, the most common cause is missing execute permissions or a missing shebang line, and the fix is to set the executable bit and ensure the script starts with #!/bin/bash. A second common cause is placing scripts in the wrong directory or naming them without a numeric prefix, which NetworkManager requires. This article covers the exact steps to diagnose and fix these issues, plus background on how the dispatcher works, common pitfalls, and answers to frequent questions.

How NetworkManager Dispatcher Works

NetworkManager runs scripts in /etc/NetworkManager/dispatcher.d/ whenever a network interface changes state. The dispatcher calls each script with two arguments: the interface name (e.g., eth0, wlan0) and the action (e.g., up, down, vpn-up, dhcp4-change). Scripts must be owned by root, have no group or world write permissions, and be executable. NetworkManager runs them in alphabetical order, so a numeric prefix like 01-script helps control order. The dispatcher is synchronous: it waits for each script to finish before proceeding, so a hanging script can block network configuration.

Common Reasons Scripts Don’t Run

• Missing execute permission: Scripts must have the executable bit set (chmod +x).
• Wrong directory: Only /etc/NetworkManager/dispatcher.d/ is scanned (not subdirectories).
• Invalid ownership or permissions: Scripts must be owned by root and not writable by group or others (e.g., chmod 755).
• Missing shebang: Without #!/bin/bash (or another interpreter), the kernel doesn’t know how to execute the script.
• Script errors: If the script exits with a non-zero status, NetworkManager may log it but still continue; check the journal for errors.
• Dispatcher disabled: Some systems have NetworkManager-dispatcher service disabled; ensure it’s enabled.

Step-by-Step Fixes

1. Verify the script exists and is in the right place: Run ls -l /etc/NetworkManager/dispatcher.d/. If your script isn’t there, move it.
2. Check permissions: The script must be executable and not group/world writable. Run sudo chmod 755 /etc/NetworkManager/dispatcher.d/your-script.
3. Ensure correct ownership: Run sudo chown root:root /etc/NetworkManager/dispatcher.d/your-script.
4. Add a shebang: Make sure the first line is #!/bin/bash (or the interpreter you use).
5. Test the script manually: Run it with the expected arguments, e.g., sudo /etc/NetworkManager/dispatcher.d/your-script eth0 up. If it fails, fix the script.
6. Restart NetworkManager: sudo systemctl restart NetworkManager (or sudo service network-manager restart on some systems).
7. Check logs: Run journalctl -u NetworkManager-dispatcher or journalctl -u NetworkManager to see if the dispatcher ran and what errors occurred.

When to Use Dispatcher Scripts vs. Other Methods

Dispatcher scripts are ideal for reacting to network events like interface up/down, VPN connections, or DHCP changes. For simple tasks like setting DNS or routes, you might use nmcli or NetworkManager’s built-in configuration. For system-wide network policies, consider using systemd network services or NetworkManager dispatcher hooks. If you need to run a script only once at boot, a systemd service might be more appropriate. Dispatcher scripts are best for event-driven actions tied to network state changes.

Common Mistakes to Avoid

• Using spaces in filenames: NetworkManager splits arguments by spaces, so avoid spaces in script names.
• Writing to stdout/stderr: Scripts should not write to stdout; it can confuse NetworkManager. Redirect output to a log file.
• Assuming action names: Verify the exact action strings (e.g., up, down, vpn-up) by checking the NetworkManager documentation or logs.
• Not handling all actions: Your script should check the action argument and exit gracefully for unknown actions.
• Scripts that hang: Avoid long-running processes inside the script; use nohup or background them if needed.

Testing Your Script

To test a dispatcher script without waiting for a real network event, you can manually invoke it with the interface and action. For example, sudo /etc/NetworkManager/dispatcher.d/99-my-script eth0 up. Check the exit code (echo $?) to see if it succeeded. To trigger a real event, you can use nmcli device disconnect eth0 and then nmcli device connect eth0, then check your script’s log. Some users find it helpful to add a line to the script that writes to a log file, e.g., echo "$(date) - $1 $2" >> /var/log/nm-dispatcher.log.

Frequently Asked Questions

Why does my script run manually but not automatically?

The most common reason is that the script lacks the executable bit or is not owned by root with proper permissions. When you run it manually with sudo, you bypass the ownership check. Ensure the script is chmod 755 and owned by root:root.

Can I use a script in my home directory?

No, NetworkManager only scans /etc/NetworkManager/dispatcher.d/. You can place a symlink there pointing to your script, but the symlink must be owned by root and have the same permissions.

What are the valid action arguments?

Common actions include up, down, vpn-up, vpn-down, dhcp4-change, dhcp6-change, hostname, and connectivity-change. You can see the full list in the NetworkManager documentation or by reading the dispatcher scripts that come with your distribution.

How do I debug if the script still doesn’t run?

Check the system journal: journalctl -u NetworkManager-dispatcher or journalctl -u NetworkManager. Look for lines mentioning your script name. Also, add logging to your script to see if it’s being called at all. If the dispatcher service isn’t running, enable it with systemctl enable NetworkManager-dispatcher.

Does the script need to be executable if I call it with bash?

Yes, NetworkManager executes the script directly (not via bash script), so it must be executable. If you want to run it with a specific interpreter, use the shebang line.

Can I run scripts after a VPN connection?

Yes, use the vpn-up and vpn-down actions. Ensure your script checks for those actions, as they are separate from the regular up and down.

Related

• Send Anonymous SMS to Any Number: 5 Methods
• LG G6 Emojis Not Showing? Fixes That Work
• GST Refund FAQs: Timelines, Interest & Appeals