A NetworkManager dispatcher script that fails a permission check doesn't produce an error or a journal warning. At the default log level you get nothing at all. NetworkManager decides the file isn't safe to run, skips it, and carries on, and whatever that script was supposed to enforce never happens.
This hurts most when the script guards security. Say it forces a Tailscale exit node every time your laptop joins a Wi-Fi network. A skipped script doesn't break anything you'd notice. Your traffic just goes out over the coffee shop LAN while tailscale status reports that everything is healthy.
What I Expected
The dispatcher contract looks simple. Put an executable in /etc/NetworkManager/dispatcher.d/, and on every state change nm-dispatcher runs it with two arguments: the interface name and the action (up, down, vpn-up, dhcp4-change, connectivity-change and a few more). It also gets environment variables such as CONNECTION_ID, CONNECTION_UUID and DEVICE_IFACE. Scripts run in alphabetical order, which is why everyone uses numeric prefixes like 50-wifi-safe.
So the mental model goes: drop the file in, chmod +x, reconnect to Wi-Fi, done. If something's wrong, the journal will tell you.
The last part of that model is the broken part.
What Actually Happens
nm-dispatcher runs every candidate file through a permission check before it executes anything. A file has to meet all of these:
| Requirement | What fails it |
|---|---|
| Regular file | Directories, device nodes, broken symlinks |
| Owned by uid 0 | A file you wrote as your user and then sudo mv'd into place |
| Not writable by group or other |
chmod 777, chmod 775, chmod g+w
|
| Not setuid |
chmod u+s (rare, but it's checked) |
| Executable by owner | A missing chmod +x
|
The dispatcher also skips some filenames on purpose: editor backups ending in ~, and package manager leftovers like .rpmnew, .rpmsave and .dpkg-old. That's reasonable. You don't want 50-wifi-safe~ running next to 50-wifi-safe.
The design is sound. Any non-root user who can write to a dispatcher script gets root code execution on the next network event, so refusing those files is correct. The problem is how quietly it happens. The rejection is logged at debug level from inside the dispatcher process, and almost nobody runs it at debug level. Look at the journal and all you'll see is NetworkManager announcing the interface came up.
A few common ways to land in this state without knowing it:
-
chmod 777"to be sure." This is the classic. You make the file as permissive as possible to rule out permissions, and that's exactly what disqualifies it. A 777 script is world-writable, and the dispatcher won't touch a world-writable file. -
sudo mvinstead ofsudo cporinstall.mvkeeps the original owner. Write the script in your home directory, move it into place, and it stays owned by uid 1000. -
Git checkouts. Symlink
dispatcher.dentries into a dotfiles repo and the target belongs to your user. The dispatcher checks the target, not the link. -
A group-writable umask. Some distros give users a
002umask, so any file created in a shared workflow can pick upg+wwithout you noticing.
There are also two failure modes the permission table doesn't cover, and both are just as quiet from NetworkManager's side.
SELinux labels. On Fedora and RHEL, a script written in ~/ and moved into /etc/NetworkManager/dispatcher.d/ keeps its user_home_t context. The dispatcher's domain isn't allowed to execute that type, so the exec gets denied. The denial goes to the audit log, not to the NetworkManager journal entries you're reading. Owner and mode can both be perfect and the script still won't run.
The dispatcher service isn't running. NetworkManager-dispatcher.service is a separate unit. Fedora enables it by default. On some minimal installs and container-derived images it's disabled or masked, and then nothing in dispatcher.d runs, ever. NetworkManager doesn't complain about that either.
The Fix
Step 1: Install the script correctly
Use install, which sets owner and mode in one atomic step:
# Broken: owned by you, world-writable, ignored by nm-dispatcher
chmod 777 ~/50-wifi-safe
sudo mv ~/50-wifi-safe /etc/NetworkManager/dispatcher.d/
# Fixed: root:root, 0755, correct SELinux label
sudo install -o root -g root -m 0755 ~/50-wifi-safe \
/etc/NetworkManager/dispatcher.d/50-wifi-safe
sudo restorecon -v /etc/NetworkManager/dispatcher.d/50-wifi-safe # SELinux distros only
sudo systemctl enable --now NetworkManager-dispatcher.service
0755 is what you want. 0700 also passes. Anything with a 2, 3, 6 or 7 in the group or other position doesn't.
Step 2: Verify before you trust it
This is the checklist I run against any dispatcher script that "isn't doing anything":
f=/etc/NetworkManager/dispatcher.d/50-wifi-safe
stat -c '%U:%G %a %F' "$f" # want: root:root 755 regular file
ls -Z "$f" # want: NetworkManager_dispatcher_script_t (Fedora/RHEL)
systemctl is-enabled NetworkManager-dispatcher.service
head -n1 "$f" # want: a real shebang, e.g. #!/bin/bash
file "$f" # "with CRLF line terminators" = broken shebang
sudo ausearch -m avc -ts recent | grep -i dispatcher # SELinux denials, if any
The CRLF line is there because a script edited on Windows, or pasted out of some web editors, ends up with #!/bin/bash\r as its interpreter. That fails with "No such file or directory", which makes no sense until you remember the \r.
Step 3: Make the dispatcher tell you why
If the checklist passes and the script still doesn't fire, run the dispatcher in the foreground with debug output. That's where the skip reasons finally show up:
# Stop the D-Bus activated instance so yours handles the events
sudo systemctl stop NetworkManager-dispatcher.service
# Path is /usr/libexec/nm-dispatcher on Fedora/RHEL,
# /usr/lib/NetworkManager/nm-dispatcher on Debian/Ubuntu
sudo /usr/libexec/nm-dispatcher --debug --persist
# In another terminal, bounce the Wi-Fi connection
nmcli connection down "Example-SSID" && nmcli connection up "Example-SSID"
You'll see each event come in, which scripts it found, and the reason for any it refused, for example that a file is writable by group or other, or isn't owned by root. Press Ctrl-C when you're done and start the service again.
For the daemon's side of the conversation (did it even send the event?), turn up the DISPATCH logging domain at runtime:
sudo nmcli general logging level TRACE domains DISPATCH
journalctl -u NetworkManager -f
# Put it back when you're finished
sudo nmcli general logging level INFO domains ALL
Step 4: Write the script so it logs its own work
A dispatcher script that does nothing visible is indistinguishable from one that never ran. Have it write a line to the journal under its own tag every time it makes a decision, including the decision to do nothing. Below is the Wi-Fi exit-node enforcer I mentioned earlier. It's idempotent, so frequent roaming between access points doesn't make it churn Tailscale's routing:
#!/bin/bash
# /etc/NetworkManager/dispatcher.d/50-wifi-safe
IFACE="$1"; ACTION="$2"
EXIT_NODE="exit-a" # Tailscale name of your exit node
TS=/usr/bin/tailscale # absolute paths: don't trust PATH here
log() { /usr/bin/logger -t wifi-safe "$*"; }
[ "$ACTION" = "up" ] || exit 0
TYPE=$(/usr/bin/nmcli -g GENERAL.TYPE device show "$IFACE" 2>/dev/null)
[ "$TYPE" = "wifi" ] || exit 0 # every Wi-Fi network is untrusted
CURRENT=$("$TS" debug prefs 2>/dev/null | /usr/bin/jq -r '.ExitNodeID // ""')
if [ -n "$CURRENT" ]; then
log "$IFACE up (${CONNECTION_ID:-?}): exit node already active, no-op"
exit 0
fi
if "$TS" set --exit-node="$EXIT_NODE" --exit-node-allow-lan-access=false; then
log "$IFACE up (${CONNECTION_ID:-?}): exit node enforced"
else
log "$IFACE up (${CONNECTION_ID:-?}): FAILED to set exit node"
fi
There's a design choice in there worth calling out. The script doesn't keep an allowlist of "trusted" SSIDs. Any wireless association triggers enforcement. SSIDs are trivial to spoof, an allowlist grows forever, and when an allowlist goes wrong it fails open. Treating every Wi-Fi network as hostile is simpler, and when it goes wrong it fails secure. For the longer argument about why Tailscale's own auto-selection doesn't cover this, see Tailscale Exit Node Logic: Why Auto-Select Fails for Security.
One caveat: tailscale debug prefs is a debug subcommand, and its output format isn't a stable API. Pin your Tailscale version or re-check the field name after upgrades. Otherwise your idempotency check can quietly turn into "always set it."
Now journalctl -t wifi-safe becomes the first thing to check:
journalctl -t wifi-safe --since "1 hour ago"
# No lines after a Wi-Fi reconnect = the script never ran. Go back to Step 2.
Step 5: Give yourself a manual escape hatch
A forced exit node on a laptop has a known downside. If the exit node itself is unreachable, you lose DNS and egress together, and it looks exactly like the network is down. Keep a quick override in ~/.bashrc so you don't have to remember flags while you're offline:
# Toggle the Tailscale exit node manually (e.g. on a network you control)
exitnode() {
case "$1" in
off) sudo tailscale set --exit-node= && echo "exit node OFF" ;;
on) sudo tailscale set --exit-node=exit-a && echo "exit node ON" ;;
status) tailscale debug prefs | jq '{WantRunning, ExitNodeID}' ;;
*) echo "usage: exitnode on|off|status" ;;
esac
}
exitnode status also covers the first rung of the debugging ladder. If WantRunning is false, the dispatcher is irrelevant, because tailscaled isn't trying to connect at all.
The Related Traps in the Same Setup
Scripts like this rarely travel alone. They usually come with DNS and firewall changes, and both of those have their own "it worked until reboot" problem.
Don't sed a config file that might not exist. Recent Fedora releases don't necessarily ship /etc/systemd/resolved.conf, because the vendor defaults live under /usr/lib/systemd/. If you run sed -i 's/#DNSOverTLS=no/DNSOverTLS=yes/' against a missing file, either nothing happens or your tooling creates a near-empty file in /etc that shadows the vendor config. Use a drop-in instead:
# /etc/systemd/resolved.conf.d/10-wifi-safe.conf
[Resolve]
DNSOverTLS=opportunistic
LLMNR=no
MulticastDNS=no
Then sudo systemctl restart systemd-resolved and confirm with resolvectl status. Drop-ins extend the defaults instead of replacing them, and they survive package upgrades. I covered the wider "what's actually resolving your names" problem in Wildcard DNS + ndots:5.
Runtime firewall changes evaporate. firewall-cmd --zone=public --change-interface=wlan0 works right up until the interface flaps, and then NetworkManager reapplies the zone from the connection profile. Put the zone in the profile itself:
nmcli connection modify "Example-SSID" connection.zone public
nmcli connection up "Example-SSID"
firewall-cmd --get-zone-of-interface=wlan0 # should print: public
While you're in there, bind tailscale0 to its zone by interface, not by source CIDR. A source-based rule for 100.64.0.0/10 trusts anything that claims an address in that range, and on a hostile LAN the claim costs nothing.
The debugging order I'd follow, from the top of the stack down:
-
Daemon state:
tailscale debug prefs. IsWantRunningtrue, and is an exit node set? -
Dispatcher execution:
journalctl -t wifi-safe. Did the script run on the last association? -
Dispatcher eligibility: the Step 2 checklist, then
nm-dispatcher --debugif needed. -
Routing and DNS:
ip route get 1.1.1.1andresolvectl status. Is traffic actually going out throughtailscale0?
Most wasted time comes from starting at step 4, seeing a confusing route table, and debugging routing for an hour when the real answer was a file owned by the wrong uid.
Why This Matters
You'll hit this whenever a dispatcher script goes into place through anything other than a careful install as root: dotfile managers, config management with the wrong mode:, a quick sudo mv, or a well-meaning chmod 777. You'll also hit it on any distro that doesn't enable NetworkManager-dispatcher.service by default.
What I'd take from it:
-
Treat skipped as the default assumption. Until
journalctl -t <your-tag>shows a line from the script, assume it has never run. - Every script should log a line on every invocation, including no-ops. Silence should mean exactly one thing: it didn't execute.
-
Install with
install -o root -g root -m 0755, and on SELinux systems follow it withrestorecon. Neverchmod 777anything that runs as root, here or anywhere else. - Check enforcement from outside. A security control you can't observe isn't one you can rely on. A periodic check that the exit node is set while you're on Wi-Fi (a systemd timer works fine) catches the cases the dispatcher misses.
-
Prefer drop-ins and connection profiles over runtime commands. Anything you fix with
firewall-cmdorresolvectlat runtime is gone after the next reboot.
The dispatcher's permission checks protect you from a real privilege escalation path, and I wouldn't want them weakened. I just wish a rejected script showed up as a warning instead of a debug line. Until it does, the logging has to live in your own script. If you're designing this kind of enforcement for a fleet rather than one laptop, it's the sort of thing I help with through GuatuLabs consulting. If you want the server-side half of the Tailscale picture, Tailscale Subnet Routers covers it.
Top comments (0)