NetworkManager: Difference between revisions

Latest revision as of 05:05, 15 June 2025

NetworkManager can be used to provide network management services in Alpine Linux. In addition to providing network management service, NetworkManager also provides a number of CLI|TUI|GUI tools compared to the inbuilt ifupdown-ng tool. Follow the steps on this page to ensure that only NetworkManager service is running and other network management services are disabled to prevent conflicts.

Prerequisites

The community repository must be enabled.
Set up eudev. Otherwise your network devices can be listed as (strictly-)unmanaged.
A non-root user account, is recommended.
Ensure that network interfaces are configured and tested.

Installation

Install the basic network management daemon of NetworkManager suite:

# apk add networkmanager

Some of the popular NetworkManager user interfaces or front ends available as sub-packages are:

TUI: networkmanager-tui, (run nmtui)
Command line: networkmanager-cli (run nmcli)
GUI: plasma-nm for Plasma integration and applet
GUI: network-manager-applet for a GTK system tray applet

Tip: Refer networkmanager-* for the list of all NetworkManager subpackages. Install the appropriate subpackages based on the required functionalities.

Configuration

To be able to use NetworkManager with your current user (i.e. non root), you need to add your user to the plugdev group created by NetworkManager:

# adduser <YourUsername> plugdev

Note: If you are already logged in, you will need to relogin for the new group to take effect.

Add the following to the /etc/NetworkManager/NetworkManager.conf file as follows:

Contents of /etc/NetworkManager/NetworkManager.conf

[main] 
dhcp=internal
plugins=ifupdown,keyfile

[ifupdown]
managed=true 

Using nm-applet

You can enable all users to edit connections in the Networkmanager gui tool i.e nm-applet without using Polkit as follows:

Create the conf.d directory for networkmanager:
# mkdir -p /etc/NetworkManager/conf.d
Add following content to /etc/NetworkManager/conf.d/any-user.conf so that
Contents of /etc/NetworkManager/conf.d/any-user.conf
[main] auth-polkit=false
Restart networkmanager:
# rc-service networkmanager restart

Wired networks

For wired networks the configuration is complete. Proceed to Service configuration section.

Wireless networks

NetworkManager supports both wireless daemons i.e iwd and wpa_supplicant. Using both daemons simulatenously leads to conflicts. Install the networkmanager-wifi package, so NetworkManager can use the WiFi device plugins to connect and manage wifi:

# apk add networkmanager-wifi

wpa_supplicant backend

wpa supplicant is the default wifi daemon in Alpine Linux. To use it as backend, retain the NetworkManager's configuration file /etc/NetworkManager/NetworkManager.conf as shown in Configuration section and add the [device] section alone as follows:

Contents of /etc/NetworkManager/NetworkManager.conf

...
[device]
wifi.scan-rand-mac-address=yes
wifi.backend=wpa_supplicant

Now you need to stop conflicting services:

# rc-service networking stop # rc-service wpa_supplicant stop

Now restart NetworkManager:

# rc-service networkmanager restart

Now connect to a network using one of the interfaces configured. If that connects and stays connected with no issues add the networkmanager service and disable the networking and wpa_supplicant boot services:

# rc-update add networkmanager default # rc-update del networking boot # rc-update del wpa_supplicant boot

iwd backend

NetworkManager supports wireless networks with iwd daemon as backend, however, consider existing issues before using it.

To use iwd as backend retain the NetworkManager's configuration file /etc/NetworkManager/NetworkManager.conf as shown in Configuration section and add the [device] section alone as follows:

Contents of /etc/NetworkManager/NetworkManager.conf

...
[device]
wifi.backend=iwd
wifi.iwd.autoconnect=yes

Ensure that wpa_supplicant and related services are stopped before continuing. Start the iwd service and restart NetworkManager:

# rc-service iwd start # rc-service networkmanager restart

Service configuration

To start|stop|restart the networkManager service, use OpenRC command:

# rc-service networkmanager start

Set the service to autostart on boot:

# rc-update add networkmanager default

VPN support

NetworkManager support for Wireguard is inbuilt, but other VPN's like OpenVPN require plugins which are found in the networkmanager-openvpn subpackage.

Plasma support

Todo: (KDE Plasma Desktop) find out if it is possible to prevent requesting the password for KDE Wallet on login

Todo: (KDE Plasma Desktop) for autoconnect to wifi network on start, it appears that the "all users may connect to this network" option must be selected in settings, as root is not a choice to allow. There are likely better workarounds

Troubleshooting

nm-applet not authorized to control networking

If you get above error message, follow the Using nm-applet section to permit all users to use nm-applet.

device is strictly unmanaged

If you get an error message like "Could not activate connection: Connection 'Ethernet connection 1' is not available on device eth0 because device is strictly unmanaged", and networks do not appear, ensure that [ifupdown] section is configured in the /etc/NetworkManager/NetworkManager.conf file as explained in Configuration section.

@@ Line 1: / Line 1: @@
-[https://networkmanager.dev/ NetworkManager] is the standard Linux network configuration tool suite. For the list of all NetworkManager subpackages refer {{pkg|networkmanager-*}}
+[https://networkmanager.dev/ NetworkManager] can be used to provide network management services in Alpine Linux. In addition to providing network management service, NetworkManager also provides a number of CLI|TUI|GUI tools compared to the inbuilt [[ifupdown-ng]] tool. Follow the steps on this page to ensure that only {{ic|NetworkManager}} service is running and other network management services are disabled to prevent conflicts.
-== Installation ==
+== Prerequisites ==
-Networkmanager needs to have [[eudev|udev]] to be setup properly. Otherwise your network devices can be listed as (strictly-)unmanaged.
+* The [[Repositories#Managing_repositories|community repository must be enabled]].
-{{:Include:Setup Device Manager}}
+* Set up [[eudev]]. Otherwise your network devices can be listed as (strictly-)unmanaged.
+* A [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]], is recommended.
+* Ensure that [[Configure Networking|network interfaces]] are configured and [[Configure_Networking#Connectivity_testing|tested]].
-Install the basic Network Management daemon of NetworkManager suite:{{Cmd|# apk add {{Pkg|networkmanager}}}}
+== Installation ==
-To be able to use NetworkManager with your current user (i.e. not root), you need to add your user to the <code>plugdev</code> group: {{Cmd|# adduser <YourUsername> plugdev}}
+Install the basic network management daemon of NetworkManager suite:{{Cmd|# apk add {{Pkg|networkmanager}}}}
-{{Note|you will need to log out for the new group to take effect}}
-There are multiple user interfaces available in NetworkManager suite. Choose the appropriate subpackage:
+Some of the popular NetworkManager user interfaces or front ends available as sub-packages are:
-* TUI: {{Pkg|networkmanager-tui}}, a curses-based interface (run <code>nmtui</code>)
+* TUI: {{Pkg|networkmanager-tui}}, (run <code>nmtui</code>)
 * Command line: {{Pkg|networkmanager-cli}} (run <code>nmcli</code>)
 * GUI: {{Pkg|plasma-nm}} for Plasma integration and applet
 * GUI: {{Pkg|network-manager-applet}} for a GTK system tray applet
+{{Tip| Refer {{pkg|networkmanager-*}} for the list of all NetworkManager subpackages. [[Install]] the appropriate subpackages based on the required functionalities.}}
-== Networkmanager service ==
+== Configuration ==
-Ensure that [[Configure Networking|network interfaces]] are configured and [[Configure_Networking#Connectivity_testing|tested]].
+To be able to use NetworkManager with your current user (i.e. non root), you need to add your user to the <code>plugdev</code> group created by NetworkManager: {{Cmd|# adduser <YourUsername> plugdev}}
-Start NetworkManager:{{Cmd|# rc-service networkmanager start}}
+{{Note|If you are already logged in, you will need to relogin for the new group to take effect.}}
-Set the service to autostart  on boot:{{Cmd|# rc-update add networkmanager default}}
-== Wired networks ==
+Add the following to the {{path|/etc/NetworkManager/NetworkManager.conf}} file as follows:{{Cat|/etc/NetworkManager/NetworkManager.conf|<nowiki>[main]
+dhcp=internal
+plugins=ifupdown,keyfile
-If wired networks do not appear or you get an error message like "Could not activate connection: Connection 'Ethernet connection 1' is not available on device eth0 because device is strictly unmanaged", add the following to {{path|/etc/NetworkManager/NetworkManager.conf}}:
+[ifupdown]
+managed=true </nowiki>}}
-{{Cat|/etc/NetworkManager/NetworkManager.conf|[ifupdown]
+=== Using nm-applet ===
-managed{{=}}true
-}}
-== Wireless networks ==
+You can enable all users to edit connections in the Networkmanager gui tool i.e {{ic|nm-applet}} without using [[Polkit]] as follows:
+# Create the <code>conf.d</code> directory for networkmanager: {{Cmd|# mkdir -p /etc/NetworkManager/conf.d}}
+# Add following content to {{path|/etc/NetworkManager/conf.d/any-user.conf}} so that {{cat|/etc/NetworkManager/conf.d/any-user.conf|[main]
+auth-polkit{{=}}false}}
+# Restart networkmanager: {{Cmd|# rc-service networkmanager restart}}
-Install {{Pkg|networkmanager-wifi}} package if you want NetworkManager to connect and manage wifi:{{Cmd|# apk add {{Pkg|networkmanager-wifi}}}}
+=== Wired networks ===
-[[NetworkManager]] supports both wireless daemons i.e [[#iwd_backend|iwd]] and [[#wpa_supplicant_backend|wpa_supplicant]]. Using both may lead to conflicts.
+For wired networks the configuration is complete. Proceed to [[#Service configuration|Service configuration]] section.
-=== wpa_supplicant backend ===
+=== Wireless networks ===
-{{Main|Wi-Fi}}
-[[Wi-Fi#wpa supplicant|wpa supplicant]] is the default in Alpine Linux and can be [[Wi-Fi#Automatic_Configuration_on_System_Boot|configured to start]] on system boot.
-{{Note|[[Wi-Fi#wpa supplicant|wpa supplicant]] might not be required, if it isn't it may be a good idea to have it setup just as a fallback.}}
+[[NetworkManager]] supports both wireless daemons i.e [[#iwd_backend|iwd]] and [[#wpa_supplicant_backend|wpa_supplicant]]. Using both daemons simulatenously leads to conflicts. Install the {{Pkg|networkmanager-wifi}} package, so NetworkManager can use the WiFi device plugins to connect and manage wifi:{{Cmd|# apk add {{Pkg|networkmanager-wifi}}}}
-Now open {{path|/etc/NetworkManager/NetworkManager.conf}} in a text editor and change it to something like this: {{Cat|/etc/NetworkManager/NetworkManager.conf|<nowiki>[main]
-dhcp=internal
-plugins=ifupdown,keyfile
-[ifupdown]
-managed=true
+==== wpa_supplicant backend ====
+{{Main|Wi-Fi}}
+[[Wi-Fi#wpa supplicant|wpa supplicant]] is the default wifi daemon in Alpine Linux. To use it as backend, retain the NetworkManager's configuration file {{Path|/etc/NetworkManager/NetworkManager.conf}} as shown in [[#Configuration|Configuration]] section and add the <code>[device]</code> section alone as follows: {{Cat|/etc/NetworkManager/NetworkManager.conf|<nowiki>...
 [device]
 wifi.scan-rand-mac-address=yes
 wifi.backend=wpa_supplicant</nowiki>}}
-{{Note|If these options dont work on your system, change them as necessary.}}
+Now you need to stop conflicting services:{{Cmd|<nowiki># rc-service networking stop
+# rc-service wpa_supplicant stop</nowiki>}}
-Now you need to stop conflicting services:
-{{Cmd|# rc-service networking stop}}
-{{Cmd|# rc-service wpa_supplicant stop}}
 Now restart NetworkManager:{{Cmd|# rc-service networkmanager restart}}
-Now connect to a network using one of the interfaces configured. If that connects and stays connected with no issues enable the <code>networkmanager</code> service and disable the <code>networking</code> and <code>wpa_supplicant</code> boot services:
+Now connect to a network using one of the interfaces configured. If that connects and stays connected with no issues add the <code>networkmanager</code> service and disable the <code>networking</code> and <code>wpa_supplicant</code> boot services:{{Cmd|<nowiki># rc-update add networkmanager default
+# rc-update del networking boot
+# rc-update del wpa_supplicant boot</nowiki>}}
-{{Cmd|# rc-update add networkmanager}}
+==== iwd backend ====
-{{Cmd|# rc-update del networking boot}}
+{{Main|iwd}}
-{{Cmd|# rc-update del wpa_supplicant boot}}
+NetworkManager supports wireless networks with [[iwd]] daemon as backend, however, consider [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues?scope=all&utf8=%E2%9C%93&state=opened&search=iwd existing issues] before using it.
-=== iwd backend ===
+To use [[iwd]] as backend retain the NetworkManager's configuration file {{Path|/etc/NetworkManager/NetworkManager.conf}} as shown in [[#Configuration|Configuration]] section and add the <code>[device]</code> section alone as follows: {{Cat|/etc/NetworkManager/NetworkManager.conf|...
-{{Main|iwd}}
+[device]
-NetworkManager supports wireless networks with [[iwd]] as backend, however, consider [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues?scope=all&utf8=%E2%9C%93&state=opened&search=iwd existing issues] before using it.
+wifi.backend{{=}}iwd
+wifi.iwd.autoconnect{{=}}yes}}
-Using both wireless daemons i.e [[Wi-Fi#wpa_supplicant|wpa_supplicant]] and [[iwd]] simultaneously lead to conflicts. Once iwd has been configured, ensure that [[Wi-Fi#Service_configuration|wpa_supplicant]] and related services are stopped before continuing. Start the iwd service and restart NetworkManager:
+Ensure that [[Wi-Fi#Service_configuration|wpa_supplicant]] and related services are stopped before continuing. Start the iwd service and restart NetworkManager:
 {{Cmd|<noWiki># rc-service iwd start
 # rc-service networkmanager restart</noWiki>}}
-To use [[iwd]] as backend edit NetworkManager's configuration because it still defaults to [[Wi-Fi#wpa_supplicant|wpa_supplicant]]. Edit the file {{Path|/etc/NetworkManager/NetworkManager.conf}} and ensure that <code>[device]</code> section appears as follows: {{Cat|/etc/NetworkManager/NetworkManager.conf|[device]
+=== Service configuration ===
-wifi.backend{{=}}iwd}}
+To start|stop|restart the {{ic|networkManager}} service, use [[OpenRC]] command:{{Cmd|# rc-service networkmanager start}}
+Set the service to autostart on boot:{{Cmd|# rc-update add networkmanager default}}
 == VPN support ==
-NetworkManager has support for Wireguard and support for other VPN's are provided by plugins in the following subpackage:
+NetworkManager support for Wireguard is inbuilt, but other VPN's like OpenVPN require plugins which are found in the {{Pkg|networkmanager-openvpn}} subpackage.
-* {{Pkg|networkmanager-openvpn}} for OpenVPN
 == Plasma support ==
@@ Line 94: / Line 95: @@
 === nm-applet not authorized to control networking ===
-You can enable all users to edit connections without adding polkit.
+If you get above error message, follow the [[#Using nm-applet|Using nm-applet]] section to permit all users to use nm-applet.
-First, make the <code>conf.d</code> directory for networkmanager:
-{{Cmd|# mkdir -p /etc/NetworkManager/conf.d}}
+=== device is strictly unmanaged ===
-Then, add following content to {{path|/etc/NetworkManager/conf.d/any-user.conf}} so that {{cat|/etc/NetworkManager/conf.d/any-user.conf|[main]
-auth-polkit{{=}}false}}
-Finally, restart networkmanager: {{Cmd|# rc-service networkmanager restart}}
+If you get an error message like "Could not activate connection: Connection 'Ethernet connection 1' is not available on device eth0 because device is strictly unmanaged", and networks do not appear, ensure that [ifupdown] section is configured in the {{path|/etc/NetworkManager/NetworkManager.conf}} file as explained in [[#Configuration|Configuration]] section.
 == See also ==