Connection Manager
******************
-Copyright (C) 2007-2010 Intel Corporation. All rights reserved.
+Copyright (C) 2007-2012 Intel Corporation. All rights reserved.
Functionality and features
The following features are built-in into Connection Manager:
- Generic plugin infrastructure
- Device and network abstraction (with basic storage support)
- - IPv4, routing and DNS configuration
+ - IPv4, IPv4-LL (link-local) and DHCP
+ - IPv4 address conflict detection (ACD) according to RFC 5227
+ - IPv6, DHCPv6 and 6to4 tunnels
+ - Advanced routing and DNS configuration
+ - Built-in DNS proxy and intelligent caching
+ - Built-in WISPr hotspot logins and portal detection
+ - Time and timezone configuration (manual and automatic with NTP)
+ - Proxy handling (manual and automatic with WPAD)
+ - Tethering support (USB, Bluetooth and WiFi AP mode)
+ - Detailed statistics handling (home and roaming)
Various plugins can be enabled for networking support:
- Ethernet plugin
- - WiFi plugin with WEP40/WEP128 and WPA/WPA2 (personal only) support
- - Bluetooth plugin
+ - WiFi plugin with WEP40/WEP128 and WPA/WPA2 (personal and enterprise)
+ - Bluetooth plugin (using BlueZ)
+ - 2G/3G/4G plugin (using oFono)
Also plugins with additional features are available:
- - DHCP plugins (uDHCP and dhclient)
- - Resolver plugins (resolvconf and DNS proxy)
- - Loopback setup
- - PolicyKit support
+ - Loopback interface setup
+ - PACrunner proxy handling
+ - PolicyKit authorization support
+
+Note that when ConnMan starts, it clears all network interfaces that are
+going to be used. If this is not desired, network interfaces can be ignored
+either by setting NetworkInterfaceBlacklist in the main.conf config file or
+by using the -I command line option.
Compilation and installation
- GCC compiler
- GLib library
- D-Bus library
- - udev library (optional)
+ - IP-Tables library (for tethering support)
+ - GnuTLS library (optional)
- PolicyKit (optional)
+ - readline (command line client)
To configure run:
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
For a working system, certain configuration options need to be enabled:
- --enable-ethernet
+ --disable-ethernet
+
+ Disable support for Ethernet network cards
+
+ By default Ethernet technology support is built-in and
+ enabled. This option can be used to build a small daemon
+ for a specific system if Ethernet support is not required.
+
+ --disable-gadget
+
+ Disable support for USB Ethernet Gadget devices
+
+ By default USB Ethernet Gadget technology support is built-in and
+ enabled. This option can be used to build a small daemon
+ for a specific system if USB Ethernet Gadget support is not required.
+
+ --disable-wifi
- Enable support for Ethernet network cards
+ Disable support for WiFi devices
- --enable-wifi
+ By default WiFi technology support is built-in and
+ enabled. This option can be used to build a small daemon
+ for a specific system if WiFi support is not required.
- Enable support for WiFi devices (requires wpa_supplicant)
+ It is safe to build a daemon with WiFi support and no
+ running wpa_supplicant. The start of wpa_supplicant is
+ automatically detected and only a runtime dependency. It
+ is not needed to build ConnMan.
+ --disable-bluetooth
- --enable-bluetooth
+ Disable support for Bluetooth devices
- Enable support for Bluetooth devices (requires BlueZ)
+ By default Bluetooth technology support is built-in and
+ enabled. This option can be used to build a small daemon
+ for a specific system if Bluetooth support is not required.
- --enable-udhcp
+ It is safe to build a daemon with Bluetooth support and no
+ running bluetoothd. The start of bluetoothd is automatically
+ detected and only a runtime dependency. It is not needed to
+ build ConnMan.
- Enable DHCP client support for BusyBox based systems
+ --disable-ofono
- The location of the udhcpc binary is auto-detected, but it
- can be overwritten via --with-udhcpc=<path-to-binary>.
+ Disable support for cellular 2G/3G/4G devices
- --enable-dhclient
+ By default oFono technology support is built-in and
+ enabled. This option can be used to build a small daemon
+ for a specific system where oFono is not used.
- Enable DHCP client support for ISC dhclient based systems
+ It is safe to build a daemon with oFono support and no
+ running ofonod. That start of ofonod is automatically
+ detected and only a runtime dependency. It is not needed to
+ build ConnMan.
- The location of the dhclient binary is auto-detected, but it
- can be overwritten via --with-dhclient=<path-to-binary>.
+ --disable-dundee
- At least one DHCP client option should be selected. It is
- possible to select both and then uDHCP will be tried first
- before falling back to dhclient.
+ Disable support for Bluetooth DUN devices
- --enable-dnsproxy
+ By default Bluetooth DUN technology (dundee) support is
+ built-in and enabled. This option can be used to build a
+ small daemon for a specific system where dundee is not used.
- Enable DNS proxy support for /etc/resolv.conf abstraction
+ It is safe to build a daemon with dundee support and no
+ running dundee. That start of dundee is automatically
+ detected and only a runtime dependency. It is not needed to
+ build ConnMan.
- The best solution for multiple connections and proper DNS
- handling is a DNS proxy server. This binds a DNS proxy
- server to port 53 on the loopback interface (127.0.0.1).
+ --enable-iwd
- The /etc/resolv.conf file needs a "nameserver 127.0.0.1"
- entry, but can now set the immutable bit or be on a read-only
- filesystem. No further modification to that file will be made.
+ Enable support for Wireless daemon for Linux
- It is important that this is not used together with other
- DNS proxy solution like dnsmasq.
+ The IWD project does not have initial release so far,
+ therefore by default IWD support is not enabled.
- --enable-resolvconf
+ It is safe to enable this option along WiFi support.
- Enable resolvconf support for Debian/Ubuntu based systems
+ --disable-pacrunner
- The resolvconf package from Debian can be used to handle
- configuration of the /etc/resolv.conf file.
+ Disable support for PACrunner proxy handling
- It is safe to select this option even when resolvconf is not
- installed. A missing resolvconf will be detected and in that
- case it falls back to modifying /etc/resolv.conf directly.
+ By default PACrunner support is built-in and enabled. This
+ option can be used to build a small daemon for a specific
+ system where PACrunner is not used.
- The location of the resolvconf binary is auto-detected, but it
- can be overwritten via --with-resolvconf=<path-to-binary>.
+ It is safe to build a daemon with PACrunner support and no
+ pacrunner daemon. It will detect and start a PACrunner
+ process if needed at runtime. The presence is not needed
+ to build ConnMan.
- --enable-loopback
+ --disable-loopback
- Enable setup of loopback device
+ Disable setup of loopback device
For distributions with a really minimal init system and no
networking scripts this can take care of setting up the
loopback device and enabling it.
- It is safe to select this option even if networking scripts
- are in place. It detects an already configured loopback
- device and leaves it as it is.
+ It is safe to leave this selected even if networking
+ scripts are in place. It detects an already configured
+ loopback device and leaves it as it is.
+
+ --disable-wispr
+
+ Disable support for WISPr hotspot logins
+
+ For systems with really minimal memory requirements, this
+ will disable the support for WISPr hotspot logins. The code
+ for WISPr will be still compiled into the daemon, but its
+ requirement on GnuTLS for secure connections will be lifted.
+
+ The missing GnuTLS support shrinks the memory requirements
+ by about 30% and for systems that are more stationary and do
+ not log into hotspots this might be a better trade off.
+
+ Disabling WISPr support is not disabling the portal detection
+ support. A portal will still be detected, but instead of being
+ asked for login credentials, the request for a browser session
+ will be made through the agent.
--enable-polkit
This allows to check every D-Bus access against a security
policy and so restrict access to certain functionality.
+ --enable-nmcompat
+
+ Enable support for NetworkManager compatibility interfaces
+
+ This allows to expose a minimal set of NetworkManager
+ interfaces. It is useful for systems with applications
+ written to use NetworkManager to detect online/offline
+ status and have not yet been converted to use ConnMan.
+
+ --disable-client
+
+ Disable support for the command line client
+
+ By default the command line client is enabled and uses the
+ readline library. For specific systems where ConnMan is
+ configured by other means, the command line client can be
+ disabled and the dependency on readline is removed.
+
+ --enable-selinux
+
+ Enable support for compiling SElinux type enforcement rules
+
+ The TE rules are needed if host environment is in enforcing
+ mode. Without this option, the VPN client process cannot
+ send notification to connman-vpnd via net.connman.Task
+ interface. The compiled connman-task.pp module needs to
+ also installed using this command
+ # semodule -i connman-task.pp
+ in order to enable the dbus access.
+
+ --with-dns-backend=TYPE
+
+ Enable support for a DNS resolving backend
+
+ Select a DNS backend to use. Supported values are "internal"
+ and "systemd-resolved". If "internal" is selected, ConnMan
+ will be build with a caching DNS proxy. If "systemd-resolved"
+ is selected, ConnMan configures systemd-resolved to do DNS
+ resolving. The default value is "internal".
+
+
+Activating debugging
+====================
+
+One can activate debugging prints in ConnMan using -d command line option.
+If the -d option has no parameters, then debugging is activated for all
+source code files. If the -d option has parameters, they tell which source
+code files have debugging activated. One can use wild cards in file names.
+Example:
+ -d Activate all normal debug prints
+ -d src/service.c This prints debugging info from src/service.c
+ file only
+ -d src/network.c:src/ipconfig.c
+ This activates debug prints in src/network.c
+ and src/ipconfig.c files.
+ -d 'src/n*.c' This would activate debug print from all the C source
+ files starting with letter 'n' in src directory.
+ Note the quotation marks around option, that is to
+ prevent shell expansion.
+ -d '*/n*.c:*/i*.c' Activate debug prints for all C source files starting
+ with letters 'n' or 'i' in any sub-directory.
+
+Some components of ConnMan have environment variable activated debug prints.
+If the environment variable is set, then corresponding component will print
+some extra debugging information.
+Following environment variables can be used:
+ CONNMAN_DHCP_DEBUG DHCPv4 related debug information
+ CONNMAN_DHCPV6_DEBUG DHCPv6 related debug information
+ CONNMAN_IPTABLES_DEBUG Extra information when iptables is used
+ CONNMAN_RESOLV_DEBUG Name resolver debug prints. These debug prints
+ are used when ConnMan resolves host names for
+ its own use.
+ Note that the DNS proxy debug prints do not
+ use this environment variable. For that, one
+ can use "-d src/dnsproxy.c" command line option.
+ CONNMAN_SUPPLICANT_DEBUG Debugging prints for communication between
+ connmand and wpa_supplicant processes.
+ CONNMAN_WEB_DEBUG Debug information when ConnMan does Internet
+ connectivity check in Wispr and 6to4 components.
+
+Example:
+ CONNMAN_WEB_DEBUG=1 src/connmand -n
+
+If timing conditions are relevant then it is recommended command to
+get log traces as follows:
+ connmand -d 2>&1 | ts '[%H:%M:%.S]' | tee connman.log
+
+The 'ts' program is normally available in the moreutils package.
+
+
+Kernel configuration
+====================
+
+In order to support tethering, the following kernel configuration options
+need to be enabled either as modules (m) or builtin (y):
+
+CONFIG_BRIDGE
+CONFIG_IP_NF_TARGET_MASQUERADE
+
+In order to enable CONFIG_IP_NF_TARGET_MASQUERADE, the following options need
+to be enabled also as modules (m) or builtin (y):
+
+CONFIG_NETFILTER
+CONFIG_NF_CONNTRACK_IPV4
+CONFIG_NF_NAT_IPV4
+
+For routing and statistic support in Sessions, the following options
+need to be enabled as modules (m) or builtin (y):
+
+CONFIG_IP_NF_IPTABLES
+CONFIG_IP_MULTIPLE_TABLES
+CONFIG_NETFILTER_NETLINK_ACCT
+CONFIG_NETFILTER_XT_MATCH_NFACCT
+CONFIG_NETFILTER_XT_CONNMARK
+CONFIG_NETFILTER_XT_TARGET_CONNMARK
+CONFIG_NETFILTER_XT_MATCH_CONNMARK
+
+In order to support USB gadget tethering, the following kernel configuration
+options need to be enabled:
+
+CONFIG_USB_GADGET
+CONFIG_USB_ETH
+
+
+wpa_supplicant configuration
+============================
+
+In order to get wpa_supplicant and Connection Manager working properly
+together you should edit wpa_supplicant .config file and set:
+
+CONFIG_WPS=y
+CONFIG_AP=y
+CONFIG_CTRL_IFACE_DBUS_NEW=y
+
+add:
+
+CONFIG_BGSCAN_SIMPLE=y
+
+This last option will enable the support of background scanning while being
+connected, which is necessary when roaming on wifi.
+
+It is recommended to use wpa_supplicant 2.x or later.
+
+If wpa_supplicant is configured to D-Bus autostart, then ConnMan will
+trigger the autostart of wpa_supplicant. However please keep in mind
+that this trigger only happens once. If wpa_supplicant stops or crashes,
+ConnMan does not periodically try to autostart it. It is up to systemd or
+similar service management tool to autostart it. In case wpa_supplicant
+is not started by ConnMan then make sure option "-u" is used in order
+to enable its D-Bus control interface and ensure ConnMan can communicate
+with it.
+
+
+VPN
+===
+
+In order to compile pptp and l2tp VPN plugins, you need ppp development
+package.
+
+To run l2tp you will need
+ - xl2tpd, http://www.xelerance.com/services/software/xl2tpd
+
+To run pptp you will need
+ - pptp client, http://pptpclient.sourceforge.net
+
+Both l2tp and pptp also need pppd.
+
+
+OpenVPN
+=======
+
+Up to version 2.2 of OpenVPN, pushing additional routes from the
+server will not always work. Some of the symptons are that additional
+routes will not be set by ConnMan if the uplink is a cellular
+network. While the same setup works well for a WiFi or ethernet
+uplink.
+
+Up to (at least) version 2.4.5 of OpenVPN getting information about
+private key decryption failures via management channel is missing. This
+will result in attempting with the invalid key over and over as the
+information about failed decryprion is not delivered to OpenVPN plugin.
+The following patch to OpenVPN is required for the private key
+decryption failures to be sent:
+https://git.sailfishos.org/mer-core/openvpn/blob/
+4f4b4af116292a207416c8a990392e35a6fc41af/rpm/privatekey-passphrase-
+handling.diff
+
+GnuTLS
+======
+
+When using GnuTLS be aware that depending on the configuration of
+GnuTLS does either an lazy or eager initialization of an internal
+entropy pool using /dev/urandom. On eager initialization the loading
+of ConnMan will be delayed by the link loader until the entropy pool
+is filled. On smaller system this can easily delay the startup of
+ConnMan by several seconds (we had reports of 25 seconds and more
+delay).
+
+GnuTLS allows to switch back to lazy evaluation when the environment
+variable GNUTLS_NO_EXPLICIT_INIT. For more details please read
+the man page to gnutls_global_init(3).
+
+
+Online check
+============
+
+ConnMan tries to detect if it has Internet connection or not when
+a service is connected. If the online check succeeds the service
+enters Online state, if not it stays in Ready state. The online
+check is also used to detect whether ConnMan is behind a captive
+portal like when you are in hotel and need to pay for connectivity.
+
+The online check is done by trying to fetch status.html document
+from ipv4.connman.net (for IPv4 connectivity) and ipv6.connman.net
+(for IPv6 connectivity). The used URL looks like this
+http://ipv{4|6}.connman.net/online/status.html
+
+When an online check request fails, another one is triggered after a
+longer interval. The intervals follow the square series of numbers
+in a specific range, by default [1, 12], corresponding to the following
+intervals, in seconds: 1, 4, 9, 16, 25, 36, 49, 64, 81, 100, 121 and 144.
+
+See connman.conf(5) for the EnableOnlineCheck option, if you need to
+disable the feature.
+It is also possible to specify other URLs via OnlineCheckIPv4URL and
+OnlineCheckIPv6URL options.
+The range of intervals between two online check requests can be fine-tuned
+via OnlineCheckInitialInterval and OnlineCheckMaxInterval options.
+
+During the online check procedure, ConnMan will temporarily install
+a host route to both the ipv4.connman.net and ipv6.connman.net so that
+the online check query can be directed via the correct network
+interface which the connected service is using. This host route is
+automatically removed when the online check is done. Note that the server
+expressly does not log any connection information, including IPv4/6
+addresses of connecting clients. The server runtime logs cycle in RAM
+memory depending on amount of connections processed.
+
+ConnMan sends this very minimal information in http header when doing
+the online check request (example):
+ Host: ipv4.connman.net
+ User-Agent: ConnMan/1.23 wispr
+ Connection: close
+
+Currently following information is returned from connman.net if
+the connection is successful (200 OK http response code is returned):
+ Server: nginx
+ Date: Mon, 09 Jun 2014 09:25:42 GMT
+ Content-Type: text/html
+ Connection: close
+ X-ConnMan-Status: online
+
+The X-ConnMan-Status field is used in portal detection, if it is missing
+ConnMan will call RequestBrowser method in net.connman.Agent dbus
+interface to handle the portal login if the portal does not support WISPr.
+See doc/agent-api.txt for more details.
+
+
+Information
+===========
+
+Mailing list:
+ connman@lists.linux.dev
+
+If you would like to subscribe to receive mail in your inbox, just
+send a (empty) message from your email account to
+
+ connman+subscribe@lists.linux.dev
+
+Mailing list archive:
+ https://lore.kernel.org/connman
+
+IRC:
+ ircs://irc.oftc.net:6697/#connman (for SSL)
+ irc://irc.oftc.net:6667/#connman (for non-SSL)
projects / platform / upstream / connman.git / blobdiff