basecamp
Switch to NetworkManager
Closes #1414, currently the issue with the most 'upvotes' in the Omarchy repo.
The only thing that stood in the way for a switch to NetworkManager was a good TUI. Thanks to the work of @Zeus-Deus, we now have a viable replacement for Impala: Gazelle. AUR: https://aur.archlinux.org/packages/gazelle-tui
In this proposal I stay as close to the current Omarchy set-up as possible. Which means:
- We stop using systemd-networkd, and start using NetworkManager instead
- We replace Impala with Gazelle
- We keep IWD as the backend for WiFi. I have tested this, and together with NetworkManager this also works for Enterprise setups like eduroam.
- We keep using systemd-resolved for DNS resolution, as Omarchy already uses it: https://github.com/basecamp/omarchy/pull/2313
The only thing that will really change for the user is that there will be a new Network TUI. The introduction of NetworkManager will not be noticeable for most users.
It might come at the cost of having to recreate a connection for some networks, we will have to test this.
Why NetworkManager?
See issue #1414 . Systemd-networkd lacks usability when it comes to VPN-connections and Enterprise (802.1x) Networks such as eduroam. NetworkManager is the de facto standard for Linux on the Desktop. It comes with practically every Desktop Environment, and therefore has a big usebase and functionality for desktop users. https://wiki.archlinux.org/title/NetworkManager
Why stick with IWD, and not use wpa_supplicant?
Omarchy already uses IWD. IWD is the modern replacement of wpa_supplicant. This is the way linux is heading, it is a mature project (in version 3.10), and it has become a proper replacement. I have tested IWD and had no issues with logging in to Enterprise Networks or connection to VPNs. https://wiki.archlinux.org/title/Iwd
To do
This PR sets the basis for a move towards NetworkManager. It makes sure we are all on the same page and we can start to test the configuration.
- ~Remove and replaces old references to systemd-networkd.~
I think this pr is really appreciated, two-three updates earlier, i was having network issues, which got fixed only in recent updates, where i noticed, iwd and nm running side by side fixed the issue, #1475 where i had mentioned it.
When looking for references to systemd-networkd I got a little confused as I was expecting a
systemctl enable systemd-network.service
line somewhere in the repo. So I don't know how systemd-networkd is enabled. The ArchLinux tells me that you have to enable it manually... See: https://wiki.archlinux.org/title/Systemd-networkd#Required_services_and_setup
The only reference to systemd-networkd in the installation that I could find was in install/config/hardware/network.sh. This is masking the wait-online.service, so we have to keep masking it? NetworkManager has a similar wait-online.service. I reckon we also need to take care of this. As: "Enabling NetworkManager.service also enables NetworkManager-wait-online.service", see: https://wiki.archlinux.org/title/NetworkManager#NetworkManager-wait-online
@ryanrhughes , I am handling the enabling of NetworkManager, and masking systemd-networkd and wpa_supplicant in /install/first-run/networkmanager.sh, but there probably was a good reason to handle this in install/config/hardware/network.sh. I will put it there now.
Apart from this, the only script that needed a change was: /bin/omarchy-setup-dns
I just stumbled upon this issue in the Impala repo: https://github.com/pythops/impala/issues/24#issuecomment-2985431339
apparently, the creator of Impala is currently working on using NetworkManager as backend for the TUI.
This would in the end be the ideal scenario, as Impala is a really nice tui. We could use Gazelle in the mean time until Impala is ready for NetworkManager.
@pythops , how is the work on implementing the NetworkManager backend going? Is it worth the wait?
@kromsam
how is the work on implementing the NetworkManager backend going? Is it worth the wait?
The work to support NetworkManager has started but it is very slow as I am the only one working on it only on my free time. I guess it will happen at some point but can not give any specific deadline.
Thanks for the PR and the mention! Really cool to see Gazelle potentially helping Omarchy users.
I'm committed to actively maintaining Gazelle and adding features based on user feedback. If there are Omarchy-specific integrations or improvements needed, I'm happy to work on them.
Let me know if you need help testing or if there are specific features needed for Omarchy integration.
Hey folks,
I've been following both of these PRs and I still don't see a compelling reason why we should adopt NetworkManager in Omarchy. Obviously this isn't just my call to make, but I wanted to lay out my perspective clearly.
The main argument I keep hearing is VPN and enterprise network support. While I get that NetworkManager has this built-in, I think we're solving for edge cases at the expense of simplicity for the majority. Most users should be able to handle VPNs through other means. Tools like wg-quick for WireGuard, OpenVPN's native tools, or even manual configuration are perfectly viable and actually give you more control and understanding of what's happening under the hood.
NetworkManager brings a massive amount of complexity that most of our users will never need or use. It's a heavyweight abstraction layer that tries to be everything to everyone, and that philosophy runs counter to what I understand Omarchy to be about. We're using systemd-networkd precisely because it's simple, transparent, and does what it needs to do without all the bells and whistles.
The argument about compatibility with "user-facing networking applications" feels like we're designing to accommodate every possible use case. If someone wants GUI-driven VPN apps, Omarchy seems to attract users who prefer direct control over abstraction layers.
That said, I do acknowledge that enterprise networks (eduroam, 802.1x) can be genuinely painful with networkd. But again—is that really the majority use case for Omarchy users? And even if it is, shouldn't we be teaching people how to handle these things properly rather than hiding the complexity behind NetworkManager's abstractions?
I'm curious to hear what others think, especially those who've actually run into real blockers with the current setup. Not theoretical "what if someone wants to use ProtonVPN GUI" scenarios, but actual pain points you've experienced.
I came across NetworkManager when trying to get the 5g modem to work in my thinkpad. Though I can not especially say if that would solve my problem as I haven't got it to work yet either way.
@jardahrazdera thanks for your two cents, let me try to respond and see if it satisfies you.
I see NetworkManager as the 'Swiss Army Knife' for networking on the Linux Desktop. Especially laptop users, that switch environment many times will love the hassle-free experience that it offers. This is the reason that NetworkManager is the tool of choice for pretty much all the big Linux desktop distros (this includes Omakub, btw).
I agree that it might be overkill for a server, or a work station: situations were networking is a matter of 'set-and-forget'. NetworkManager is the tool for users that need simplicity and something that 'just works' without having to build configuration for certain 'edge cases'.
And then about these 'edge cases'. I would say that you might underestimate how many people are using eduroam and VPNs on a daily basis. Currently the NetworkManager-issue is the one with the most 'upvotes' in the repo: #1414 .
If Omarchy is about good defaults, then we might ask ourself, what is a good default? I think that more people are switching from systemd-networkd to NetworkManager right now, then people would switch back to networkd if NM becomes the default. I truly believe this, as the majority of users will never even notice that we switched. In my opinion, that makes NM the better default. https://github.com/basecamp/omarchy/issues/1414#issuecomment-3261643934
You write:
shouldn't we be teaching people how to handle these things properly rather than hiding the complexity behind NetworkManager's abstractions?
Even if this exists, I think I will always want to switch to NetworkManager because it just works. I don't want to be in a situation where I need to sift through some documentation to connect to some Enterprise WiFi when I end up in some hotel, conference hall, university and have wondered for five minutes why my WiFi is not connecting. And above that, yes, I would like to use the VPN gui that is part of my subscription, makes sure I always connect to the fastest/up-to-date servers, without having to download configuration files every so often.
Your main argument seems to be:
NetworkManager brings a massive amount of complexity that most of our users will never need or use.
So then maybe my question to you is: how massive is the cost of using NM instead of systemd-networkd? Is this a significant difference, or is this Arch-puritanism about a negligible difference that most people won't notice? This is a genuine question, personally I never noticed any performance drawbacks from using NetworkManager
My two cents:
I'm a ProtonVPN user who absolutely needs the GUI (like many others). Using wg-quick with proton config files is definitely not a good way to use Proton. You'd need hundreds of config files to get the same functionality of the GUI.
Dhh also said that he would be open to the idea, so long as there was a viable replacement for nmtui which currently would be gazelle. It keeps the impala/omarchy aesthetics but works with NM on the backend.
To play devils advocate a bit, I also think it's not terribly hard to mask iwd, install NM/gazelle, and edit Omarchy configs to use gazelle instead of impala. However, if I didn't have to do this, that would be great too.
In the end, I totally support and am in favor of using NM in future versions instead of iwd.
Thanks for the responses, but honestly, they prove my point better than I ever could.
@kromsam You threw around buzzwords like "Swiss Army Knife" and "hassle-free experience," but completely failed to provide a single concrete technical example of something that cannot be done with networkd + iwd. Not one.
You mention eduroam and enterprise WiFi? networkd + iwd handles 802.1x authentication perfectly fine. VPNs? wg-quick, OpenVPN native client, or basic scripting all work. "Hotel WiFi that won't connect"? That's literally just captive portal detection, which has nothing to do with NetworkManager vs networkd.
Your most telling argument is "this issue has the most upvotes." That's not engineering—that's a popularity contest. If we're making technical decisions based on GitHub reactions, we might as well add Snap packages while we're at it.
@reppiz "I absolutely need the GUI" is not a technical requirement—it's a personal preference. ProtonVPN provides WireGuard configs. They have an API. The "hundreds of config files" complaint is laughable—you can write a 20-line bash script to automate that in an afternoon. You literally admit "it's not terribly hard to do manually," which completely undermines your own argument.
Here's what I'm hearing from both of you: "I don't want to use CLI tools, I prefer clicking buttons, and I don't want to learn how the underlying system works." That's fine—use whatever you want on your personal setup. But that's not a technical justification for bloating Omarchy with NetworkManager.
Neither of you has presented a single scenario where networkd + iwd is technically incapable of doing the job. Everything you've mentioned is about convenience and personal workflow preferences. Those are valid concerns, but they're not technical blockers.
So I'll ask again: can anyone provide an actual technical limitation—something that fundamentally cannot be accomplished with the current setup—that would justify the complexity overhead of NetworkManager? Because so far, I'm seeing zero evidence of that.
Do you mind explaining the "bloat" and "complex overhead" of network manager? I'm not a network manager expert but since this is the heart of the opposition, I'd like to know what exactly is meant by this.
@reppiz Fair question.
NetworkManager adds ~3.5MB binary plus dependencies (dnsmasq, plugins), runs multiple daemons, requires D-Bus, and sits as an abstraction layer on top of iwd/wpa_supplicant anyway.
In the oposite systemd-networkd is already part of systemd (zero overhead), runs as a single service, and uses simple declarative .network files.
The "complexity" is about abstraction layers and handling every possible edge case. Networkd does what most users need without the overhead. That's the tradeoff.
But look, I've made my technical case. If the decision is to go with NetworkManager based on popularity and convenience, so be it. I won't keep arguing against the tide.
Thank you for that explanation. I actually didn't know network manager just sits on top of iwd and acts as an interface. I thought it was its own thing.
Kind of makes me understand the dilemma better. I agree now that this is more of a user preference and may not be the direction Omarchy needs to go. We'll see I guess.
For what it's worth, and since RFC was asked, I came here (and have manually already made this switch) mostly for the integrated VPN support.
As others have mentioned, I think some may be missing the importance of why VPN service is necessary without the need to manually configure it. Doing so is not as straightforward as some have implied. I know. I've done it, but I had to research quite a lot beforehand, and I'm no tech slouch.
Most of us are using Omarchy, in part, because we don't want to configure everything ourselves; especially esoteric, yet vital, services like VPN. Honestly, I was shocked it wasn't already supported out-of-the-box.
Apart from the arguments I'd also like to hear some feedback on the contents of the PR itself, especially on the migrations, as they are always a bit tricky. Did other people test them yet?
Apart from the arguments I'd also like to hear some feedback on the contents of the PR itself, especially on the migrations, as they are always a bit tricky. Did other people test them yet?
to switch we just swap the omarchy repo for your PR and run update Omarchy?
Perhaps you can update with latest release.
My update at the end says:
error: target not found: gazelle-tui
Running migration (1761589246)
Install NetworkManager from official repos
resolving dependencies...
looking for conflicting packages...
Package (11) New Version Net Change Download Size
core/gpm 1.20.7.r38.ge82d1a6-6 0.38 MiB 0.13 MiB
extra/libndp 1.9-1 0.06 MiB 0.02 MiB
extra/libnewt 0.52.25-1 0.27 MiB 0.09 MiB
extra/libnm 1.54.1-1 6.23 MiB 0.87 MiB
extra/libteam 1.32-2 0.33 MiB 0.11 MiB
extra/mobile-broadband-provider-info 20250613-1 0.49 MiB 0.06 MiB
core/pcre 8.45-4 3.50 MiB 0.98 MiB
extra/pcsclite 2.4.0-3 0.30 MiB 0.10 MiB
extra/slang 2.3.3-4 3.36 MiB 0.81 MiB
core/wpa_supplicant 2:2.11-3 6.60 MiB 1.70 MiB
extra/networkmanager 1.54.1-1 15.36 MiB 3.62 MiB
Total Download Size: 8.48 MiB
Total Installed Size: 36.89 MiB
:: Proceed with installation? [Y/n]
:: Retrieving packages...
slang-2.3.3-4-x86_64 826.4 KiB 2.31 MiB/s 00:00 [------------------------------------] 100%
libnm-1.54.1-1-x86_64 894.6 KiB 2.42 MiB/s 00:00 [------------------------------------] 100%
pcre-8.45-4-x86_64 1000.8 KiB 2.66 MiB/s 00:00 [------------------------------------] 100%
networkmanager-1.54.1-1-x86_64 3.6 MiB 8.73 MiB/s 00:00 [------------------------------------] 100%
gpm-1.20.7.r38.ge82d1a6-6-x86_64 135.7 KiB 2.76 MiB/s 00:00 [------------------------------------] 100%
libteam-1.32-2-x86_64 109.9 KiB 2.56 MiB/s 00:00 [------------------------------------] 100%
wpa_supplicant-2:2.11-3-x86_64 1736.5 KiB 3.65 MiB/s 00:00 [------------------------------------] 100%
pcsclite-2.4.0-3-x86_64 99.4 KiB 1775 KiB/s 00:00 [------------------------------------] 100%
libnewt-0.52.25-1-x86_64 91.9 KiB 1294 KiB/s 00:00 [------------------------------------] 100%
mobile-broadband-provider-info-2... 62.9 KiB 740 KiB/s 00:00 [------------------------------------] 100%
libndp-1.9-1-x86_64 19.5 KiB 111 KiB/s 00:00 [------------------------------------] 100%
Total (11/11) 8.5 MiB 12.3 MiB/s 00:01 [------------------------------------] 100%
(11/11) checking keys in keyring [------------------------------------] 100%
(11/11) checking package integrity [------------------------------------] 100%
(11/11) loading package files [------------------------------------] 100%
(11/11) checking for file conflicts [------------------------------------] 100%
(11/11) checking available disk space [------------------------------------] 100%
:: Running pre-transaction hooks...
(1/1) Wait for limine-snapper-sync to finish before updating, installing or removing.
:: Processing package changes...
( 1/11) installing libndp [------------------------------------] 100%
( 2/11) installing gpm [------------------------------------] 100%
( 3/11) installing pcre [------------------------------------] 100%
( 4/11) installing slang [------------------------------------] 100%
( 5/11) installing libnewt [------------------------------------] 100%
Optional dependencies for libnewt
python: libnewt support with the _snack module [installed]
tcl: whiptcl support [installed]
( 6/11) installing libnm [------------------------------------] 100%
( 7/11) installing libteam [------------------------------------] 100%
( 8/11) installing mobile-broadband-provider-info [------------------------------------] 100%
( 9/11) installing pcsclite [------------------------------------] 100%
Optional dependencies for pcsclite
python: API call trace logging with the pcsc-spy [installed]
ccid: USB Chip/Smart Card Interface Devices driver
(10/11) installing wpa_supplicant [------------------------------------] 100%
(11/11) installing networkmanager [------------------------------------] 100%
Optional dependencies for networkmanager
bluez: Bluetooth support [installed]
dhcpcd: alternative DHCP client
dnsmasq: connection sharing
firewalld: firewall support
iptables: connection sharing [installed]
iwd: wpa_supplicant alternative [installed]
modemmanager: cellular network support
nftables: connection sharing
openresolv: alternative resolv.conf manager
pacrunner: PAC proxy support
polkit: let non-root users control networking [installed]
ppp: dialup connection support
:: Running post-transaction hooks...
(1/6) Creating system user accounts...
Creating group 'pcscd' with GID 962.
Creating user 'pcscd' (PC/SC Smart Card Daemon) with UID 962 and GID 962.
(2/6) Reloading system manager configuration...
(3/6) Reloading device manager configuration...
(4/6) Arming ConditionNeedsUpdate...
(5/6) Reloading system bus configuration...
(6/6) Updating the info directory file...
Running migration (1761591682)
Configure and enable NetworkManager, disable systemd-networkd
Created symlink '/etc/systemd/system/wpa_supplicant.service' → '/dev/null'.
Created symlink '/etc/systemd/system/systemd-networkd.socket' → '/dev/null'.
Created symlink '/etc/systemd/system/systemd-networkd-varlink.socket' → '/dev/null'.
Created symlink '/etc/systemd/system/systemd-networkd.service' → '/dev/null'.
Created symlink '/etc/systemd/system/multi-user.target.wants/NetworkManager.service' → '/usr/lib/systemd/system/NetworkManager.service'.
Created symlink '/etc/systemd/system/dbus-org.freedesktop.nm-dispatcher.service' → '/usr/lib/systemd/system/NetworkManager-dispatcher.service'.
Created symlink '/etc/systemd/system/network-online.target.wants/NetworkManager-wait-online.service' → '/usr/lib/systemd/system/NetworkManager-wait-online.service'.
Created symlink '/etc/systemd/system/NetworkManager-wait-online.service' → '/dev/null'.
Running migration (1761592263)
Replace Impala with Gazelle
checking dependencies...
Package (1) Old Version Net Change
impala 0.4.1-1 -3.59 MiB
Total Removed Size: 3.59 MiB
:: Do you want to remove these packages? [Y/n]
:: Running pre-transaction hooks...
(1/1) Wait for limine-snapper-sync to finish before updating, installing or removing.
:: Processing package changes...
(1/1) removing impala [------------------------------------] 100%
:: Running post-transaction hooks...
(1/1) Arming ConditionNeedsUpdate...
error: target not found: gazelle-tui
I manually installed it from AUR afterwards and it's fine after restarting waybar.
test results; apart from previous mentioned, all seems to work well. imported an .ovpn with networkmanager-applet and set a username/password, connected successfully and can access remote resources. gazelle sees the vpn and can connect/disconnect/show status.
system still boots and network connection still works ;)
thanks for testing
error: target not found: gazelle-tui
I used the
omarchy-pkg-add script to install gazelle-tui, but I guess it only works official repo packages, and I should use
yay -S --noconfirm gazelle-tui
instead
Likewise... PR migrations ran fine on my machine (with NetworkManager already manually installed/configured).
Running migration (1761589246)
Install NetworkManager from official repos
Running migration (1761591682)
Configure and enable NetworkManager, disable systemd-networkd
WARNING: There are other configuration files in /etc/NetworkManager/conf.d that might override Omarchy configuration:
/etc/NetworkManager/conf.d/wifi_backend.conf
Created symlink '/etc/systemd/system/wpa_supplicant.service' → '/dev/null'.
Created symlink '/etc/systemd/system/systemd-networkd.socket' → '/dev/null'.
Created symlink '/etc/systemd/system/systemd-networkd-varlink.socket' → '/dev/null'.
Created symlink '/etc/systemd/system/systemd-networkd.service' → '/dev/null'.
Created symlink '/etc/systemd/system/NetworkManager-wait-online.service' → '/dev/null'.
Running migration (1761592263)
Replace Impala with Gazelle
The WARNING is due to the way I manually installed NetworkManager, so can be safely ignored in this case.
Thanks! I'll add a check if services are already running / masked / disabled so that we don't need to run the systemctl commands if not necessary
I have installed this PR and had some issues, so I got some help from ChatGPT since I am completely new to all of this and I asked it to summarize everything so I can report it to you and here it is:
-
NetworkManager was running but showed the Wi-Fi device as unavailable.
-
The logs showed:
Couldn't initialize supplicant interface: Failed to D-Bus activate wpa_supplicant service. → This meantwpa_supplicantwas installed but masked, so NetworkManager couldn’t start it. -
We fixed it by:
sudo systemctl unmask wpa_supplicant.service sudo systemctl enable --now wpa_supplicant.service sudo systemctl restart NetworkManager
Root cause: the PR switches Omarchy’s networking stack to NetworkManager + Gazelle, but ships with wpa_supplicant.service masked. NetworkManager cannot bring up Wi-Fi without it.
Fix proposal: ensure the PR unmasks and enables wpa_supplicant automatically when NetworkManager is active.
hm, the idea here is to use iwd instead of wpa_supplicant.
can you check if the /etc/NetworkManager/conf.d/omarchy_networkmanager.conf file was correctly copied?
here is the content of omarchy_networkmanager.conf
[main]
dns=systemd-resolved
[device]
wifi.backend=iwd
I just read the commits and realized you did this on purpose 😅
Though my wifi is working smoothly now, it used to disconnect every few minutes
here is the content of omarchy_networkmanager.conf
is this is in your /etc folder? because then NM shouldnt be looking wpa_supplicant.
did you unmask wpa_supplicant or are you on the iwd backend now?
yes, it is in my /etc folder
when I checked the status of iwd it was inactive, may be that is why it falled back to wpa_supplicant? we may have a script that check the status of iwd and enable it first
Following this issue in the Impala repo: https://github.com/pythops/impala/issues/24 , I saw that pythops is considering to support NetworkManager with Impala, which is great news. But, it might take a while.
In a comment: https://github.com/pythops/impala/issues/24#issuecomment-3493044652, he suggested that, during the wait, we could also consider using wifitui, another tui that was written in Go.
I will take a look, and see if it does things differently then Gazelle. It seems to be a bit more featureful, so maybe I'll switch it around. Also I gotta say that Gazelle feels a bit slow sometimes, compared to Impala, and wifitui.
Would love to hear some thoughts on this!
@kromsam You threw around buzzwords like "Swiss Army Knife" and "hassle-free experience," but completely failed to provide a single concrete technical example of something that cannot be done with networkd + iwd. Not one.
You mention eduroam and enterprise WiFi? networkd + iwd handles 802.1x authentication perfectly fine. VPNs? wg-quick, OpenVPN native client, or basic scripting all work. "Hotel WiFi that won't connect"? That's literally just captive portal detection, which has nothing to do with NetworkManager vs networkd.
Your most telling argument is "this issue has the most upvotes." That's not engineering—that's a popularity contest. If we're making technical decisions based on GitHub reactions, we might as well add Snap packages while we're at it.
@reppiz "I absolutely need the GUI" is not a technical requirement—it's a personal preference. ProtonVPN provides WireGuard configs. They have an API. The "hundreds of config files" complaint is laughable—you can write a 20-line bash script to automate that in an afternoon. You literally admit "it's not terribly hard to do manually," which completely undermines your own argument.
Hey @jardahrazdera, the script you are mentioning to automate all of these tasks, do you think we could include that into Omarchy to make the OS work on VPNs? (within reason of course).
- If it's relatively simple we could make it work on all systems by default if it's just a matter of global non-conflicting settings updates.
- If not we could add it as part of the Omarchy menu so users can simply select the option and have these configurations done for them. Or are they too user specific?
on one of my laptops (with mt7925e) I keep getting ERR_NETWORK_CHANGED all the time,
google shows years ago this might be related to Network Manager.
Interestingly it doesn't happen on a second laptop (also mt7925e) nor on my PC (wired).
Both laptops are cloned from the same PC install.
Running ipv4 and ipv6 pings in parallel to internet and router, seem to be unaffected.
update since removing tailscale, it seems the issue has disappearing.. Will keep an eye on it..
I am probably biased here but I very much agree with @jardahrazdera .
I think it is overall better to avoid bloated software that try to do everything at once, and rather choose the ones that do one thing and do it right (unix philosophy).
NetworkManager can not handle wireless by itself, and it relies on iwd or wpa_supplicant. So why use it in the first place. systemd-networkd does manage wire connection very well already.
For the wireless, I would still choose iwd for these reasons
Potential benefits of iwd over wpa_supplicant include:
simplification of network management
faster network discovery
fast and reliable roaming
using less system resources
using features offered by the Linux kernel
support for enterprise security methods like EAP
support for kernel asymmetric key rings and TPM
support for multiple clients
source: https://wiki.gentoo.org/wiki/Iwd