4 Copyright (C) 2007-2012 Intel Corporation. All rights reserved.
7 Functionality and features
8 ==========================
10 The following features are built-in into Connection Manager:
11 - Generic plugin infrastructure
12 - Device and network abstraction (with basic storage support)
13 - IPv4, IPv4-LL (link-local) and DHCP
14 - IPv6, DHCPv6 and 6to4 tunnels
15 - Advanced routing and DNS configuration
16 - Built-in DNS proxy and intelligent caching
17 - Built-in WISPr hotspot logins and portal detection
18 - Time and timezone configuration (manual and automatic with NTP)
19 - Proxy handling (manual and automatic with WPAD)
20 - Tethering support (USB, Bluetooth and WiFi AP mode)
21 - Detailed statistics handling (home and roaming)
23 Various plugins can be enabled for networking support:
25 - WiFi plugin with WEP40/WEP128 and WPA/WPA2 (personal and enterprise)
26 - Bluetooth plugin (using BlueZ)
27 - 2G/3G/4G plugin (using oFono)
29 Also plugins with additional features are available:
30 - Loopback interface setup
31 - PACrunner proxy handling
32 - PolicyKit authorization support
34 Note that when ConnMan starts, it clears all network interfaces that are
35 going to be used. If this is not desired, network interfaces can be ignored
36 either by setting NetworkInterfaceBlacklist in the main.conf config file or
37 by using the -I command line option.
40 Compilation and installation
41 ============================
43 In order to compile Connection Manager you need following software packages:
47 - IP-Tables library (for tethering support)
48 - GnuTLS library (optional)
49 - PolicyKit (optional)
50 - readline (command line client)
53 ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
55 Configure automatically searches for all required components and packages.
57 To compile and install run:
61 Configuration and options
62 =========================
64 For a working system, certain configuration options need to be enabled:
68 Disable support for Ethernet network cards
70 By default Ethernet technology support is built-in and
71 enabled. This option can be used to build a small daemon
72 for a specific system if Ethernet support is not required.
76 Disable support for USB Ethernet Gadget devices
78 By default USB Ethernet Gadget technology support is built-in and
79 enabled. This option can be used to build a small daemon
80 for a specific system if USB Ethernet Gadget support is not required.
84 Disable support for WiFi devices
86 By default WiFi technology support is built-in and
87 enabled. This option can be used to build a small daemon
88 for a specific system if WiFi support is not required.
90 It is safe to build a daemon with WiFi support and no
91 running wpa_supplicant. The start of wpa_supplicant is
92 automatically detected and only a runtime dependency. It
93 is not needed to build ConnMan.
97 Disable support for Bluetooth devices
99 By default Bluetooth technology support is built-in and
100 enabled. This option can be used to build a small daemon
101 for a specific system if Bluetooth support is not required.
103 It is safe to build a daemon with Bluetooth support and no
104 running bluetoothd. The start of bluetoothd is automatically
105 detected and only a runtime dependency. It is not needed to
110 Disable support for cellular 2G/3G/4G devices
112 By default oFono technology support is built-in and
113 enabled. This option can be used to build a small daemon
114 for a specific system where oFono is not used.
116 It is safe to build a daemon with oFono support and no
117 running ofonod. That start of ofonod is automatically
118 detected and only a runtime dependency. It is not needed to
123 Disable support for Bluetooth DUN devices
125 By default Bluetooth DUN technology (dundee) support is
126 built-in and enabled. This option can be used to build a
127 small daemon for a specific system where dundee is not used.
129 It is safe to build a daemon with dundee support and no
130 running dundee. That start of dundee is automatically
131 detected and only a runtime dependency. It is not needed to
136 Enable support for Wireless daemon for Linux
138 The IWD project does not have initial release so far,
139 therefore by default IWD support is not enabled.
141 It is safe to enable this option along WiFi support.
145 Disable support for PACrunner proxy handling
147 By default PACrunner support is built-in and enabled. This
148 option can be used to build a small daemon for a specific
149 system where PACrunner is not used.
151 It is safe to build a daemon with PACrunner support and no
152 pacrunner daemon. It will detect and start a PACrunner
153 process if needed at runtime. The presence is not needed
158 Disable setup of loopback device
160 For distributions with a really minimal init system and no
161 networking scripts this can take care of setting up the
162 loopback device and enabling it.
164 It is safe to leave this selected even if networking
165 scripts are in place. It detects an already configured
166 loopback device and leaves it as it is.
170 Disable support for WISPr hotspot logins
172 For systems with really minimal memory requirements, this
173 will disable the support for WISPr hotspot logins. The code
174 for WISPr will be still compiled into the daemon, but its
175 requirement on GnuTLS for secure connections will be lifted.
177 The missing GnuTLS support shrinks the memory requirements
178 by about 30% and for systems that are more stationary and do
179 not log into hotspots this might be a better trade off.
181 Disabling WISPr support is not disabling the portal detection
182 support. A portal will still be detected, but instead of being
183 asked for login credentials, the request for a browser session
184 will be made through the agent.
188 Enable support for PolicyKit authorization
190 This allows to check every D-Bus access against a security
191 policy and so restrict access to certain functionality.
195 Enable support for NetworkManager compatibility interfaces
197 This allows to expose a minimal set of NetworkManager
198 interfaces. It is useful for systems with applications
199 written to use NetworkManager to detect online/offline
200 status and have not yet been converted to use ConnMan.
204 Disable support for the command line client
206 By default the command line client is enabled and uses the
207 readline library. For specific systems where ConnMan is
208 configured by other means, the command line client can be
209 disabled and the dependency on readline is removed.
213 Enable support for compiling SElinux type enforcement rules
215 The TE rules are needed if host environment is in enforcing
216 mode. Without this option, the VPN client process cannot
217 send notification to connman-vpnd via net.connman.Task
218 interface. The compiled connman-task.pp module needs to
219 also installed using this command
220 # semodule -i connman-task.pp
221 in order to enable the dbus access.
227 One can activate debugging prints in ConnMan using -d command line option.
228 If the -d option has no parameters, then debugging is activated for all
229 source code files. If the -d option has parameters, they tell which source
230 code files have debugging activated. One can use wild cards in file names.
232 -d Activate all normal debug prints
233 -d src/service.c This prints debugging info from src/service.c
235 -d src/network.c:src/ipconfig.c
236 This activates debug prints in src/network.c
237 and src/ipconfig.c files.
238 -d 'src/n*.c' This would activate debug print from all the C source
239 files starting with letter 'n' in src directory.
240 Note the quotation marks around option, that is to
241 prevent shell expansion.
242 -d '*/n*.c:*/i*.c' Activate debug prints for all C source files starting
243 with letters 'n' or 'i' in any sub-directory.
245 Some components of ConnMan have environment variable activated debug prints.
246 If the environment variable is set, then corresponding component will print
247 some extra debugging information.
248 Following environment variables can be used:
249 CONNMAN_DHCP_DEBUG DHCPv4 related debug information
250 CONNMAN_DHCPV6_DEBUG DHCPv6 related debug information
251 CONNMAN_IPTABLES_DEBUG Extra information when iptables is used
252 CONNMAN_RESOLV_DEBUG Name resolver debug prints. These debug prints
253 are used when ConnMan resolves host names for
255 Note that the DNS proxy debug prints do not
256 use this environment variable. For that, one
257 can use "-d src/dnsproxy.c" command line option.
258 CONNMAN_SUPPLICANT_DEBUG Debugging prints for communication between
259 connmand and wpa_supplicant processes.
260 CONNMAN_WEB_DEBUG Debug information when ConnMan does Internet
261 connectivity check in Wispr and 6to4 components.
264 CONNMAN_WEB_DEBUG=1 src/connmand -n
266 If timing conditions are relevant then it is recommended command to
267 get log traces as follows:
268 connmand -d 2>&1 | ts '[%H:%M:%.S]' | tee connman.log
270 The 'ts' program is normaly avialable in the moreutils package.
276 In order to support tethering, the following kernel configuration options
277 need to be enabled either as modules (m) or builtin (y):
280 CONFIG_IP_NF_TARGET_MASQUERADE
282 In order to enable CONFIG_IP_NF_TARGET_MASQUERADE, the following options need
283 to be enabled also as modules (m) or builtin (y):
286 CONFIG_NF_CONNTRACK_IPV4
289 For routing and statistic support in Sessions, the following options
290 need to be enabled as modules (m) or builtin (y):
292 CONFIG_IP_NF_IPTABLES
293 CONFIG_IP_MULTIPLE_TABLES
294 CONFIG_NETFILTER_NETLINK_ACCT
295 CONFIG_NETFILTER_XT_MATCH_NFACCT
296 CONFIG_NETFILTER_XT_CONNMARK
297 CONFIG_NETFILTER_XT_TARGET_CONNMARK
298 CONFIG_NETFILTER_XT_MATCH_CONNMARK
300 In order to support USB gadget tethering, the following kernel configuration
301 options need to be enabled:
307 wpa_supplicant configuration
308 ============================
310 In order to get wpa_supplicant and Connection Manager working properly
311 together you should edit wpa_supplicant .config file and set:
315 CONFIG_CTRL_IFACE_DBUS_NEW=y
319 CONFIG_BGSCAN_SIMPLE=y
321 This last option will enable the support of background scanning while being
322 connected, which is necessary when roaming on wifi.
324 It is recommended to use wpa_supplicant 2.x or later.
326 If wpa_supplicant is configured to D-Bus autostart, then ConnMan will
327 trigger the autostart of wpa_supplicant. However please keep in mind
328 that this trigger only happens once. If wpa_supplicant stops or crashes,
329 ConnMan does not periodically try to autostart it. It is up to systemd or
330 similar service management tool to autostart it.
336 In order to compile pptp and l2tp VPN plugins, you need ppp development
339 To run l2tp you will need
340 - xl2tpd, http://www.xelerance.com/services/software/xl2tpd
342 To run pptp you will need
343 - pptp client, http://pptpclient.sourceforge.net
345 Both l2tp and pptp also need pppd.
351 Up to version 2.2 of OpenVPN, pushing additional routes from the
352 server will not always work. Some of the symptons are that additional
353 routes will not be set by ConnMan if the uplink is a cellular
354 network. While the same setup works well for a WiFi or ethernet
361 When using GnuTLS be aware that depending on the configuration of
362 GnuTLS does either an lazy or eager initialization of an internal
363 entropy pool using /dev/urandom. On eager initialization the loading
364 of ConnMan will be delayed by the link loader until the entropy pool
365 is filled. On smaller system this can easily delay the startup of
366 ConnMan by several seconds (we had reports of 25 seconds and more
369 GnuTLS allows to switch back to lazy evaluation when the environment
370 variable GNUTLS_NO_EXPLICIT_INIT. For more details please read
371 the man page to gnutls_global_init(3).
377 ConnMan tries to detect if it has Internet connection or not when
378 a service is connected. If the online check succeeds the service
379 enters Online state, if not it stays in Ready state. The online
380 check is also used to detect whether ConnMan is behind a captive
381 portal like when you are in hotel and need to pay for connectivity.
383 The online check is done by trying to fetch status.html document
384 from ipv4.connman.net (for IPv4 connectivity) and ipv6.connman.net
385 (for IPv6 connectivity). The used URL looks like this
386 http://ipv{4|6}.connman.net/online/status.html
388 See connman.conf(5) for the EnableOnlineCheck option, if you need to
391 During the online check procedure, ConnMan will temporarily install
392 a host route to both the ipv4.connman.net and ipv6.connman.net so that
393 the online check query can be directed via the correct network
394 interface which the connected service is using. This host route is
395 automatically removed when the online check is done. Note that the server
396 expressly does not log any connection information, including IPv4/6
397 addresses of connecting clients. The server runtime logs cycle in RAM
398 memory depending on amount of connections processed.
400 ConnMan sends this very minimal information in http header when doing
401 the online check request (example):
402 Host: ipv4.connman.net
403 User-Agent: ConnMan/1.23 wispr
406 Currently following information is returned from connman.net if
407 the connection is successfull (200 OK http response code is returned):
409 Date: Mon, 09 Jun 2014 09:25:42 GMT
410 Content-Type: text/html
412 X-ConnMan-Status: online
414 The X-ConnMan-Status field is used in portal detection, if it is missing
415 ConnMan will call RequestBrowser method in net.connman.Agent dbus
416 interface to handle the portal login if the portal does not support WISPr.
417 See doc/agent-api.txt for more details.
426 For additional information about the project visit ConnMan web site:
427 https://01.org/connman
428 http://www.connman.net
430 You can report bugs at https://01.org/jira/browse/CM