networkmanager-dmenu: controlling NetworkManager from a menu

What it replaces, and the audience for it

The project exists to replace the NetworkManager applet, the small tray icon that most desktop distributions ship, with something that behaves like the rest of a keyboard-driven desktop. The script is a single Python file, and the whole interaction happens in a menu that the user already has. The feature list is longer than the idea of a menu usually implies. It connects to existing WiFi and wired connections, connects to new WiFi networks and asks for the passphrase when one is needed, connects to existing VPN, WireGuard, GSM and Bluetooth connections, and toggles WiFi, the wireless modem, Bluetooth and networking as a whole. It can launch the NetworkManager connection editor for the cases it does not handle, it supports several WiFi adapters, it can rescan for networks, it can start, stop and delete a hotspot, it can show the password and a QR code for the current network, and it sends notifications through notify-send when it is available. It is a complete replacement for the applet, not a thin front end.

Nine launchers, and how the theming works

The launcher support is wide, and the list is the reason the script is useful on more than one desktop. It works with Bemenu, Dmenu, Fuzzel, Rofi, Tofi, Walker, Wmenu, Wofi and Yofi, and the requirements list records which display server some of them need, with dmenu on X, wofi and yofi on Wayland, rofi on X or XWayland, and bemenu on X or Wayland. The important design choice is that the script does not draw anything itself. The dmenu_command setting takes the command to run, with any options you want, and the case insensitivity flag is a typical example, so the appearance and the behaviour of the menu come from the launcher rather than from the script. The configuration file warns that a literal percent sign has to be written twice, which is a consequence of the Python format string used to build the menu entries, and the highlight options in the configuration only apply to rofi and wofi, which are the two that support it.

Passphrase entry and the reason pinentry is optional

A network tool that shows a WiFi passphrase in a menu is a bad tool, so the project takes this seriously in two ways. The first is pinentry, which is optional but recommended. When it is configured, the passphrase is typed into a separate pinentry window, and the configuration records which flavour of the pinentry command to use along with its own description and prompt text, so the script is not tied to one implementation. The second is a fallback for people who do not want the extra dependency. If dmenu is used for the passphrase entry, the options in the passphrase section of the configuration set the foreground and background colours to the same value, which means the typed text is not visible, and the suckless password patch is supported when it is installed, with its option that prevents the input from being echoed. Rofi, wofi and bemenu are given their own equivalent flags instead, since they do not need the colour trick.

The configuration file and where it comes from

There is no configuration to write from scratch, because running the script generates one. On the first run it checks which launchers and which terminals are installed and asks you to choose, and it writes the result to a config file under the networkmanager-dmenu directory in your configuration folder. From then on the file is yours to edit, and an example file is shipped in the repository if you would rather start from that. A different location can be requested with a command line flag or with an environment variable, and the flag wins when both are given, which is the arrangement that keeps a system wide installation usable by more than one user. The keys under the dmenu section cover the compact display mode, the menu command, whether saved connections are listed, the pinentry program, the characters that mark the active connection and the WiFi indicator, the prompt text, and the Python style format string that builds the entries, which is where you control what each line of the menu looks like.

Permissions, and the part that catches people out

Two configuration decisions have consequences that are not obvious from the feature list. The first is whether the script runs as root or as your own user. The README is explicit that you can set PolicyKit permissions to run it as your user, and that the script remains usable for connecting to connections that already exist without doing that, but that you then cannot enable or disable networking or add new connections. So the choice is between convenience and privilege, and the permission file is where you decide it. The second is Bluetooth, which needs access to the radio device node. If the bluez package is installed and the Bluetooth service is running, there is nothing more to do. If it is not, the user needs access to the device node for radio switches, which on some distributions belongs to a group, so the user has to be added to it, and on others is handled with a udev rule that assigns the node to a group with the right permissions.

Packaging and the release discipline

Installation is deliberately minimal, because the project is one script. You copy it somewhere on the path, or you take the packaged version, since Arch Linux, a Gentoo overlay and the Nix packages all carry it. The repository also holds a Nix flake, so the Nix route is a first-class one rather than an afterthought. The release process is where the engineering effort shows, because the Makefile treats version drift as a bug. A version target reads the version string out of the script itself, and a check target compares it with the latest Git tag, failing with a message that a build from the current tree would claim a version that was never released, and the comment above it explains why: the flake derives its version from the script, so a script and its tags drifting apart produces a package that lies about itself. The release target then validates the version format, refuses to run on a dirty tree, refuses to reuse an existing tag, updates the version string, commits it and creates an annotated, signed tag with a message prefilled with the version and a bullet per commit.

Where the approach stops being the right one

A menu driven script is a good fit for a keyboard workflow and a poor fit for a mouse workflow, and the difference shows up in the everyday actions. Connecting to a network is quick, but reviewing the details of a saved profile, or changing a proxy setting, or looking at a long list of networks in order to read their signal strength, is worse in a text menu than in a window with icons. The tool also does not try to be a full network manager, it connects to the profiles that already exist, and anything beyond that is delegated to the connection editor it can launch, so a user with a complicated enterprise setup still ends up in a GUI. The honest alternative is therefore the applet itself, or the desktop panel for NetworkManager, and the choice comes down to whether the keyboard menu is worth giving up the tray and the pointer for something that is a better fit on a tiling desktop and a worse one everywhere else.

Editorial conclusion

networkmanager-dmenu fits a keyboard-driven Linux desktop, particularly a Wayland or tiling setup where a tray applet is either unavailable or in the way, and it fits a user who wants their network menu to look like the rest of their menu tooling. It does not fit a mouse-first desktop, and it does not fit a machine where the applet is already the right answer. Before installing it, decide whether you will run it as your own user or as root, because the PolicyKit permissions decide whether you can add networks or only connect to the ones that already exist, and read the Bluetooth section, where access to the device node needs a group change or a udev rule.

Frequently asked questions

Official sources

1. firecat53/networkmanager-dmenu on GitHub
2. Issues
3. License: MIT
4. README
5. Releases