ConnMan
ConnMan is a command-line network manager designed for use with embedded devices and fast resolve times. It is modular through a plugin architecture, but has native DHCP and NTP support.[1]
Installation
Install the connman package. wpa_supplicant, bluez, and openvpn are optional dependencies required for Wi-Fi, Bluetooth, and VPN functionality respectively.
Before enabling connman.service, ensure any existing network configuration is disabled.
ConnMan comes with the connmanctl(1) CLI, there are various #Front-ends available.
Front-ends
- cmst — Qt GUI for ConnMan.
- connman-ncurses — Simple ncurses UI for ConnMan; not all of connman functionality is implemented, but usable (with X or from terminal without X), see the wiki.
- ConnMan-UI — GTK3 client applet.
- rofi-connman — rofi/dmenu-powered frontend
- Econnman — Enlightenment desktop panel applet.
- connman-gtk — GTK client, abandoned since 2021-10-25.
Usage
ConnMan comes with the connmanctl command-line interface, see connmanctl(1).
If you do not provide any commands connmanctl starts as an interactive shell.
ConnMan automatically handles wired connections.
Wi-Fi
Enabling and disabling WiFi
To check if WiFi is enabled you can run connmanctl technologies and check for the line that says Powered: True/False.
To power the WiFi on you can run connmanctl enable wifi or if you need to disable it you can run connmanctl disable wifi.
Other ways to enable WiFi could include using the Fn keys on the laptop to turn it on or running ip link set interface up.
Connecting to an open access point
To scan the network connmanctl accepts simple names called technologies. To scan for nearby Wi-Fi networks:
$ connmanctl scan wifi
To list the available networks found after a scan run (example output):
$ connmanctl services
*AO MyNetwork wifi_dc85de828967_68756773616d_managed_psk
OtherNET wifi_dc85de828967_38303944616e69656c73_managed_psk
AnotherOne wifi_dc85de828967_3257495245363836_managed_wep
FourthNetwork wifi_dc85de828967_4d7572706879_managed_wep
AnOpenNetwork wifi_dc85de828967_4d6568657272696e_managed_none
To connect to an open network, use the second field beginning with wifi_:
$ connmanctl connect wifi_dc85de828967_4d6568657272696e_managed_none
You should now be connected to the network. Check using connmanctl state or ip addr.
Connecting to a protected access point
For protected access points you will need to provide some information to the ConnMan daemon, at the very least a password or a passphrase.
The commands in this section show how to run connmanctl in interactive mode, it is required for running the agent command. To start interactive mode simply type:
$ connmanctl
You then proceed almost as above, first scan for any Wi-Fi technologies:
connmanctl> scan wifi
To list services:
connmanctl> services
Now you need to register the agent to handle user requests. The command is:
connmanctl> agent on
You now need to connect to one of the protected services. To do this easily, just use tab completion for the wifi_ service. If you were connecting to OtherNET in the example above you would type:
connmanctl> connect wifi_dc85de828967_38303944616e69656c73_managed_psk
The agent will then ask you to provide any information the daemon needs to complete the connection. The information requested will vary depending on the type of network you are connecting to. The agent will also print additional data about the information it needs as shown in the example below.
Agent RequestInput wifi_dc85de828967_38303944616e69656c73_managed_psk Passphrase = [ Type=psk, Requirement=mandatory ] Passphrase?
Provide the information requested, in this example the passphrase, and then type:
connmanctl> quit
If the information you provided is correct you should now be connected to the protected access point.
Using iwd instead of wpa_supplicant
ConnMan can use iwd to connect to wireless networks. As connman will start wpa_supplicant when it finds it, it is recommended to uninstall wpa_supplicant.
Note that ConnMan is probably unnecessary for IWD users, as IWD can handle its own network configuration, in which case connmand should be stopped.
Currently the -i-option of iwd seems to cause that the WiFi-interface gets hidden from connman.
Create the following service file which should cause connman to use iwd to connect to wireless networks, regardless if wpa_supplicant is installed.
/etc/systemd/system/connman_iwd.service
[Unit] Description=Connection service DefaultDependencies=false Conflicts=shutdown.target RequiresMountsFor=/var/lib/connman After=dbus.service network-pre.target systemd-sysusers.service iwd.service Before=network.target multi-user.target shutdown.target Wants=network.target Requires=iwd.service [Service] Type=dbus BusName=net.connman Restart=on-failure ExecStart=/usr/bin/connmand --wifi=iwd_agent -n StandardOutput=null CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_SYS_TIME CAP_SYS_MODULE ProtectHome=true ProtectSystem=true [Install] WantedBy=multi-user.target
Then enable/start the connman_iwd service.
Advantage of using iwd instead of wpa_supplicant is, that the ping times seem to be much more consistent and the connection seems to be more reliable.
Settings
Settings and profiles are automatically created for networks the user connects to often. They contain fields for the passphrase, essid and other information. Profile settings are stored in directories under /var/lib/connman/ by their service name. To view all network profiles run:
# cat /var/lib/connman/*/settings
/var/lib/connman-vpn/.Technologies
Various hardware interfaces are referred to as Technologies by ConnMan.
To list available technologies run:
$ connmanctl technologies
To get just the types by their name one can use this one liner:
$ connmanctl technologies | awk '/Type/ { print $NF }'
Type = tech_name provides the technology type used with connmanctl commandsTo interact with them one must refer to the technology by type. Technologies can be toggled on/off with:
$ connmanctl enable technology_type
and:
$ connmanctl disable technology_type
For example to toggle off wifi:
$ connmanctl disable wifi
rfkill or bluetoothctl to (un)block devices, yet hardware keys may still work.[2] Always use connmanctl enable|disable Tips and tricks
Avoid changing the hostname
By default, ConnMan changes the transient hostname (see hostnamectl(1)) on a per network basis. This can create problems with X authority: If ConnMan changes your hostname to something else than the one used to generate the xauth magic cookie, then it will become impossible to create new windows. Symptoms are error messages like No protocol specified and Can't open display: :0.0. Manually resetting the host name fixes this, but a permanent solution is to prevent ConnMan from changing your host name in the first place. This can be accomplished by adding the following to /etc/connman/main.conf:
[General] AllowHostnameUpdates=false
Make sure to restart the connman.service after changing this file.
For testing purposes it is recommended to watch the systemd journal and plug the network cable a few times to see the action.
Prefer ethernet to wireless
By default ConnMan does not prefer ethernet over wireless, which can lead to it deciding to stick with a slow wireless network even when ethernet is available. You can tell connman to prefer ethernet adding the following to /etc/connman/main.conf:
[General] PreferredTechnologies=ethernet,wifi
Exclusive connection
ConnMan allows you to be connected to both ethernet and wireless at the same time. This can be useful as it allows programs that established a connection over wifi to stay connected even after you connect to ethernet. But some people prefer to have only a single unambiguous connection active at a time. That behavior can be activated by adding the following to /etc/connman/main.conf:
[General] SingleConnectedTechnology=true
Connecting to eduroam (802.1X)
WPA2 Enterprise networks such as eduroam require a separate configuration file before connecting to the network. For example, create /var/lib/connman/eduroam.config:
eduroam.config
[service_eduroam] Type=wifi Name=eduroam EAP=peap CACertFile=/etc/ssl/certs/certificate.cer Phase2=MSCHAPV2 Identity=user@foo.edu AnonymousIdentity=anonymous@foo.edu Passphrase=password
Restart wpa_supplicant.service and connman.service to connect to the new network.
- Options are case-sensitive, e.g.
EAP = ttlsinstead ofEAP = TTLS.[3] - Consult the institution hosting the eduroam network for various settings such as username, password,
EAP,Phase2output, and needed certificates.
For more information, see connman-service.config(5) and Wireless network configuration#eduroam.
Avoiding conflicts with local DNS server
If you are running a local DNS server, it will likely have problems binding to port 53 (TCP and/or UDP) after installing Connman. This is because Connman includes its own DNS proxy which also tries to bind to those ports. If you see log messages from BIND or dnsmasq like
named[529]: could not listen on UDP socket: address in use
this could be the problem. To verify which application is listening on the ports, you can execute ss -tulpn as root.
To fix this connmand can be started with the options -r or --nodnsproxy by overriding the systemd service file. Create the folder /etc/systemd/system/connman.service.d/ and add the file disable_dns_proxy.conf:
/etc/systemd/system/connman.service.d/disable_dns_proxy.conf
[Service] ExecStart= ExecStart=/usr/bin/connmand -n --nodnsproxy
Make sure to reload the systemd daemon and restart the connman.service, and your DNS proxy, after adding this file.
DNS management
/etc/resolv.conf
If you want to know the DNS servers received from DHCP while keeping a custom /etc/resolv.conf, then append RuntimeDirectory=connman to the above file (clear the ExecStart lines if not needed). Now connman will write them to /var/run/connman/resolv.conf instead.
Using systemd-resolved
ConnMan has systemd-resolved support, which replaces its internal DNS proxy with a module that configures systemd-resolved with the correct DNS servers and search domains for the interface whenever it connects to a network. Using systemd-resolved is known to improve compatibility with Tailscale since ConnMan's internal proxy and Tailscale can fight over /etc/resolv.conf, which is better mediated by both talking to resolved instead.
To use this support, ConnMan needs to be rebuilt: checkout the package using the Arch build system, set the configure flag --with-dns-backend=systemd-resolved, rebuild the package, and install the modified version. After installing the modified package, set up the stub resolver as /etc/resolv.conf then restart connman.service, systemd-resolved.service, and (if using it) tailscale.service.
Blacklist interfaces
If something like Docker is creating virtual interfaces Connman may attempt to connect to one of these instead of your physical adapter if the connection drops. A simple way of avoiding this is to blacklist the interfaces you do not want to use. Connman will by default blacklist interfaces starting with vmnet, vboxnet, virbr and ifb, so those need to be included in the new blacklist as well.
Blacklisting interface names is also useful to avoid a race condition where connman may access eth# or wlan# before systemd/udev can change it to use a Predictable Network Interface Names like enp4s0. Blacklisting the conventional (and unpredictable) interface prefixes makes connman wait until they are renamed.
If it does not already exist, create /etc/connman/main.conf:
[General] NetworkInterfaceBlacklist=vmnet,vboxnet,virbr,ifb,docker,veth,eth,wlan
Once connman.service has been restarted this will also hide all the veth####### interfaces from GUI tools like Econnman.
Troubleshooting
Error /net/connman/technology/wifi: Not supported
Currently, connman does not support scanning for WiFi networks with iwd, at the moment this functionality is available with wpa_supplicant only (see [4][dead link 2023-09-16 ⓘ]). To connect to wifi with iwd, enable/start iwd.service and then either follow instructions in Iwd to connect to the wifi or you can also use any of the #Front-ends. In order to have Wifi Scanning support from within connman, install wpa_supplicant and then restart connman.service after you stop iwd.service.
Error /net/connman/technology/wifi: No carrier
You have enabled your wifi with:
$ connmanctl enable wifi
If wireless scanning leads to above error, this may be due to an unresolved bug. If it does not resolve even though wireless preconditions[dead link 2023-09-16 ⓘ] are met, try again after disabling competing network managers and rebooting.
This may also simply be caused by the wireless interface being blocked by rfkill, which can occur after restarting wpa_supplicant. Use rfkill list to check.
"Not registered", or "Method "Connect" with signature ... doesn't exist"
When issuing commands, you may see errors like the following:
From a connmanctl prompt:
connmanctl> connect service_id
Error /net/connman/service/SSID: Method "Connect" with signature "" on interface "net.connman.Service" doesn't exist
From the shell:
# connmanctl connect service_id
Error /net/connman/service/service_id: Not registered
These errors are produced because the agent is not running. Start the agent from a connmanctl prompt with agent on, and try again.
Error Failed to set hostname/domainname
connman can failed to set hostname or domainname due to lack of CAP_SYS_ADMIN.
You will need to edit connman.service (and other like connman-vpn.service , etc ...) to modify the CapabilityBoundingSet line to add CAP_SYS_ADMIN.
See EPERM under sethostname(2) § ERRORS or setdomainname(2) § ERRORS for more details.
Unknown route on connection
A log entry for an unknown route appears each time a connect is done. For example:
...
connmand[473]: wlp2s0 {add} route 82.165.8.211 gw 10.20.30.4 scope 0 <UNIVERSE>
connmand[473]: wlp2s0 {del} route 82.165.8.211 gw 10.20.30.4 scope 0 <UNIVERSE>
...
It likely is Connman performing a connectivity check to the ipv4.connman.net host (which resolves to the IP address 82.165.8.211 at current).[5] See the Connman README for more information on why and what - apart from the connecting IP - it transmits.
This behaviour can be prevented by adding the following to /etc/connman/main.conf:
[General] EnableOnlineCheck=false
This setting will cause that the default device will not switch to ONLINE, but stay in READY state.connman.conf(5) However, the connection will still be functional.
The connection itself is also functional (unless behind a captive portal) if the check is blocked by a firewall rule:
# ip6tables -A OUTPUT -d ipv6.connman.net -j REJECT # iptables -A OUTPUT -d ipv4.connman.net,ipv6.connman.net -j REJECT
File /proc/net/pnp doesn't exist
If you see this in your error log it is caused by bug in connman [6] and can be ignored.Bug Report
See also
- Git repository documentation — for further detailed documentation