When starting to work with ConnMan, the README file https://git.kernel.org/cgit/network/connman/connman.git/tree/README is a very useful starting point. It describes compilation, compile time switches, logging and contains other very useful information. When working with ConnMan, the main.conf file contains a good set of tunable knobs, see https://git.kernel.org/cgit/network/connman/connman.git/tree/src/main.conf. If there is a need to pre-configure services or VPNs, see https://git.kernel.org/cgit/network/connman/connman.git/tree/doc/config-format.txt and https://git.kernel.org/cgit/network/connman/connman.git/tree/doc/vpn-config-format.txt , respectively.
In addition to the README and main.conf documentation above, up to date D-Bus and service configuration file documentation for ConnMan is always found with the ConnMan source code in git, see https://git.kernel.org/cgit/network/connman/connman.git/tree/doc.
ConnMan contains a very useful command line tool, connmanctl, which will be used in the examples below.
ConnMan supports the following nework technologies:
- ethernet, using a built-in card, connected via host or client side USB
- WiFi using wpa_supplicant
- Celluar connectivity using oFono
- Bluetooth connectivity using Bluez
ConnMan will remember the state of the network technologies over reboots. By default all technologies are disabled at the very first startup in order to prevent unwanted wireless or wired communication from happening. Technologies can be enabled and disabled with:
> connmanctl enable wifi Enabled wifi > connmanctl disable wifi Disabled wifi
ConnMan can tether an uplink connection via all of the above networking technologies except cellular. ConnMan does this by adding all tethered network interfaces to a bridge and runs a DHCP server on the bridge interface. This forms a device wide network where all connected devices have IP connectivity between each other. Tethering does not depend on the uplink Internet connection as ConnMan keeps the tethered network running until told otherwise.
By default ethernet is not allowed to be tethered. This behavior is intentional, as to avoid mistakes when connecting to a already set up LAN and starting another DHCP server on it. Should the need to tether ethernet arise, ethernet tethering can be enabled withTetheringTechnologies in http://git.kernel.org/cgit/network/connman/connman.git/tree/src/main.conf. In the same file it is also possible to specify whether the tethering state is to be preserved over reboots by setting the PersistentTetheringMode configuration option.
ConnMan presents network connections as services. The existing services can be shown using the ConnMan command line utility connmanctl:
> connmanctl services *AO Wired ethernet_3d871eafa37e_cable *AR eca wifi_38502dce5bcf_656361_managed_psk * Guest wifi_38502dce5bcf_4775657374_managed_none * ABC Phone bluetooth_5C886ED67C1D_327100D49DFA
The symbols in the output above are: '*' favorite (saved) network, 'A' autoconnectable, 'O' online and 'R' ready. If no letter is shown in the O/R column, the network is not connected. In addition, temporary states include 'a' for association, 'c' configuration and 'd' disconnecting. When any of these three letters are showing, the network is in the process of connecting or disconnecting.
A network is in state 'ready' once it has obtained an IPv4 or IPv6 address or both. The addresses can be acquired via DHCPv4 or DHCPv6, IPv6 address autoconfiguration, IPv4 link local assignment or statically configured for IPv4 or IPv6. A network is in state 'online' if ConnMan has verified connectivity to Internet, i.e. it has managed to look up and connect to ipv4.connman.net or ipv6.connman.net. For all practical purposes 'ready' and 'online' are usually equivalent for the intended connectivity experience. The 'ready' state gives and indication that the network might need a proxy set up to get connected from a company intranet, airport WiFi or similar. In the worst case the network really has limited outside connectivity for one or another reason.
ConnMan can connect as many services as the hardware allows. The default route is assinged to the first service in the list. ConnMan will have only one service at a time in state 'online' while the other services are kept in state 'ready'.
Favorite (saved) networks that have autoconnect enabled are considered when autoconnecting services. These services are marked with '*' and 'A' in connmanctl, respectively. By default ConnMan autoconnects these in the order they are shown in the list of services until one of them gets connected. After that the autoconnected service is in use and ConnMan won't select a new one until the network goes out of range. When the service goes out of range or gets disconnected from the network infrastructure side, autoconnect is re-run and another favorite autoconnectable service is selected.
Ethernet networks are handled a bit different from the wireless ones. Starting from ConnMan 1.29 ethernet connection behavior now properly follows the documentation which states that once an ethernet network cable is plugged in, it will be connected immediately.
The order in which services are considered can be modified by the PreferredTechnologies configuration in main.conf. Once present, this configuration entry also modifies the autoconnect behavior slightly. Say /etc/connman/main.conf file contains the following:
[General] PreferredTechnologies = ethernet,wifi,cellular
This configuration causes the following two things to happen:
- the autoconnect order is modified such that ethernet services are considered first, then WiFi and then cellular services with any remaining ones left unsorted
- once a new services become available, the technology type of the already connected service is compared with the technology type of the new service, if the new service has a type listed earlier than the one of the connected service, the new service will be autoconnected
There are two additional twists to this story. The first one is that if the new service will end up with a better connectivity state than the already connected one, i.e. the new service can reach state 'online' while the already connected service is in state 'ready', the new service will be selected. The second twist is that if both the new and the already connected service end up in the same state, i.e. both end up in state 'ready' or 'online', and the technology type of the new service precedes the technology type of the already connected service, the new service will be selected.
With PreferredTechnologies enabled, the autoconnected services depend on the order in which they are created. Let's say there is one service for ethernet and another one for WiFi. If the WiFi service is detected before the ethernet one, both will get connected as ethernet, connected later, is preferred over WiFi. And as described above, WiFi can still have the default route if it goes to state 'online' while the ethernet one stays in 'ready'. If the ordering is the opposite with ethernet discovered first, the WiFi service will never be considered as ethernet is preferred over WiFi and already connected. When all possible services or certain specific subset of them need to be connected at any one time, the services need to be connected individually through the D-Bus Service API.