Merge branch 'upstream' into tizen
[platform/upstream/connman.git] / README
1 Connection Manager
2 ******************
3
4 Copyright (C) 2007-2012  Intel Corporation. All rights reserved.
5
6
7 Functionality and features
8 ==========================
9
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)
22
23 Various plugins can be enabled for networking support:
24         - Ethernet plugin
25         - WiFi plugin with WEP40/WEP128 and WPA/WPA2 (personal and enterprise)
26         - Bluetooth plugin (using BlueZ)
27         - 2G/3G/4G plugin (using oFono)
28
29 Also plugins with additional features are available:
30         - Loopback interface setup
31         - PACrunner proxy handling
32         - PolicyKit authorization support
33
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.
38
39
40 Compilation and installation
41 ============================
42
43 In order to compile Connection Manager you need following software packages:
44         - GCC compiler
45         - GLib library
46         - D-Bus library
47         - IP-Tables library (for tethering support)
48         - GnuTLS library (optional)
49         - PolicyKit (optional)
50         - readline (command line client)
51
52 To configure run:
53         ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
54
55 Configure automatically searches for all required components and packages.
56
57 To compile and install run:
58         make && make install
59
60
61 Configuration and options
62 =========================
63
64 For a working system, certain configuration options need to be enabled:
65
66         --disable-ethernet
67
68                 Disable support for Ethernet network cards
69
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.
73
74         --disable-gadget
75
76                 Disable support for USB Ethernet Gadget devices
77
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.
81
82         --disable-wifi
83
84                 Disable support for WiFi devices
85
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.
89
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.
94
95         --disable-bluetooth
96
97                 Disable support for Bluetooth devices
98
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.
102
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
106                 build ConnMan.
107
108         --disable-ofono
109
110                 Disable support for cellular 2G/3G/4G devices
111
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.
115
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
119                 build ConnMan.
120
121         --disable-dundee
122
123                 Disable support for Bluetooth DUN devices
124
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.
128
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
132                 build ConnMan.
133
134         --disable-pacrunner
135
136                 Disable support for PACrunner proxy handling
137
138                 By default PACrunner support is built-in and enabled. This
139                 option can be used to build a small daemon for a specific
140                 system where PACrunner is not used.
141
142                 It is safe to build a daemon with PACrunner support and no
143                 pacrunner daemon. It will detect and start a PACrunner
144                 process if needed at runtime. The presence is not needed
145                 to build ConnMan.
146
147         --disable-loopback
148
149                 Disable setup of loopback device
150
151                 For distributions with a really minimal init system and no
152                 networking scripts this can take care of setting up the
153                 loopback device and enabling it.
154
155                 It is safe to leave this selected even if networking
156                 scripts are in place. It detects an already configured
157                 loopback device and leaves it as it is.
158
159         --disable-wispr
160
161                 Disable support for WISPr hotspot logins
162
163                 For systems with really minimal memory requirements, this
164                 will disable the support for WISPr hotspot logins. The code
165                 for WISPr will be still compiled into the daemon, but its
166                 requirement on GnuTLS for secure connections will be lifted.
167
168                 The missing GnuTLS support shrinks the memory requirements
169                 by about 30% and for systems that are more stationary and do
170                 not log into hotspots this might be a better trade off.
171
172                 Disabling WISPr support is not disabling the portal detection
173                 support. A portal will still be detected, but instead of being
174                 asked for login credentials, the request for a browser session
175                 will be made through the agent.
176
177         --enable-polkit
178
179                 Enable support for PolicyKit authorization
180
181                 This allows to check every D-Bus access against a security
182                 policy and so restrict access to certain functionality.
183
184         --enable-nmcompat
185
186                 Enable support for NetworkManager compatibility interfaces
187
188                 This allows to expose a minimal set of NetworkManager
189                 interfaces. It is useful for systems with applications
190                 written to use NetworkManager to detect online/offline
191                 status and have not yet been converted to use ConnMan.
192
193         --disable-client
194
195                 Disable support for the command line client
196
197                 By default the command line client is enabled and uses the
198                 readline library. For specific systems where ConnMan is
199                 configured by other means, the command line client can be
200                 disabled and the dependency on readline is removed.
201
202         --enable-selinux
203
204                 Enable support for compiling SElinux type enforcement rules
205
206                 The TE rules are needed if host environment is in enforcing
207                 mode. Without this option, the VPN client process cannot
208                 send notification to connman-vpnd via net.connman.Task
209                 interface. The compiled connman-task.pp module needs to
210                 also installed using this command
211                         # semodule -i connman-task.pp
212                 in order to enable the dbus access.
213
214
215 Activating debugging
216 ====================
217
218 One can activate debugging prints in ConnMan using -d command line option.
219 If the -d option has no parameters, then debugging is activated for all
220 source code files. If the -d option has parameters, they tell which source
221 code files have debugging activated. One can use wild cards in file names.
222 Example:
223     -d                   Activate all normal debug prints
224     -d src/service.c     This prints debugging info from src/service.c
225                          file only
226     -d src/network.c:src/ipconfig.c
227                          This activates debug prints in src/network.c
228                          and src/ipconfig.c files.
229     -d 'src/n*.c'        This would activate debug print from all the C source
230                          files starting with letter 'n' in src directory.
231                          Note the quotation marks around option, that is to
232                          prevent shell expansion.
233     -d '*/n*.c:*/i*.c'   Activate debug prints for all C source files starting
234                          with letters 'n' or 'i' in any sub-directory.
235
236 Some components of ConnMan have environment variable activated debug prints.
237 If the environment variable is set, then corresponding component will print
238 some extra debugging information.
239 Following environment variables can be used:
240     CONNMAN_DHCP_DEBUG        DHCPv4 related debug information
241     CONNMAN_DHCPV6_DEBUG      DHCPv6 related debug information
242     CONNMAN_IPTABLES_DEBUG    Extra information when iptables is used
243     CONNMAN_RESOLV_DEBUG      Name resolver debug prints. These debug prints
244                               are used when ConnMan resolves host names for
245                               its own use.
246                               Note that the DNS proxy debug prints do not
247                               use this environment variable. For that, one
248                               can use "-d src/dnsproxy.c" command line option.
249     CONNMAN_SUPPLICANT_DEBUG  Debugging prints for communication between
250                               connmand and wpa_supplicant processes.
251     CONNMAN_WEB_DEBUG         Debug information when ConnMan does Internet
252                               connectivity check in Wispr and 6to4 components.
253
254 Example:
255     CONNMAN_WEB_DEBUG=1 src/connmand -n
256
257 If timing conditions are relevant then it is recommended command to
258 get log traces as follows:
259     connmand -d 2>&1 | ts '[%H:%M:%.S]' | tee connman.log
260
261 The 'ts' program is normaly avialable in the moreutils package.
262
263
264 Kernel configuration
265 ====================
266
267 In order to support tethering, the following kernel configuration options
268 need to be enabled either as modules (m) or builtin (y):
269
270 CONFIG_BRIDGE
271 CONFIG_IP_NF_TARGET_MASQUERADE
272
273 In order to enable CONFIG_IP_NF_TARGET_MASQUERADE, the following options need
274 to be enabled also as modules (m) or builtin (y):
275
276 CONFIG_NETFILTER
277 CONFIG_NF_CONNTRACK_IPV4
278 CONFIG_NF_NAT_IPV4
279
280 For routing and statistic support in Sessions, the following options
281 need to be enabled as modules (m) or builtin (y):
282
283 CONFIG_IP_NF_IPTABLES
284 CONFIG_IP_MULTIPLE_TABLES
285 CONFIG_NETFILTER_NETLINK_ACCT
286 CONFIG_NETFILTER_XT_MATCH_NFACCT
287 CONFIG_NETFILTER_XT_CONNMARK
288 CONFIG_NETFILTER_XT_TARGET_CONNMARK
289 CONFIG_NETFILTER_XT_MATCH_CONNMARK
290
291 In order to support USB gadget tethering, the following kernel configuration
292 options need to be enabled:
293
294 CONFIG_USB_GADGET
295 CONFIG_USB_ETH
296
297
298 wpa_supplicant configuration
299 ============================
300
301 In order to get wpa_supplicant and Connection Manager working properly
302 together you should edit wpa_supplicant .config file and set:
303
304 CONFIG_WPS=y
305 CONFIG_AP=y
306 CONFIG_CTRL_IFACE_DBUS_NEW=y
307
308 add:
309
310 CONFIG_BGSCAN_SIMPLE=y
311
312 This last option will enable the support of background scanning while being
313 connected, which is necessary when roaming on wifi.
314
315 It is recommended to use wpa_supplicant 2.x or later.
316
317 If wpa_supplicant is configured to D-Bus autostart, then ConnMan will
318 trigger the autostart of wpa_supplicant. However please keep in mind
319 that this trigger only happens once. If wpa_supplicant stops or crashes,
320 ConnMan does not periodically try to autostart it. It is up to systemd or
321 similar service management tool to autostart it.
322
323
324 VPN
325 ===
326
327 In order to compile pptp and l2tp VPN plugins, you need ppp development
328 package.
329
330 To run l2tp you will need
331         - xl2tpd, http://www.xelerance.com/services/software/xl2tpd
332
333 To run pptp you will need
334         - pptp client, http://pptpclient.sourceforge.net
335
336 Both l2tp and pptp also need pppd.
337
338
339 OpenVPN
340 =======
341
342 Up to version 2.2 of OpenVPN, pushing additional routes from the
343 server will not always work. Some of the symptons are that additional
344 routes will not be set by ConnMan if the uplink is a cellular
345 network. While the same setup works well for a WiFi or ethernet
346 uplink.
347
348
349 Online check
350 ============
351
352 ConnMan tries to detect if it has Internet connection or not when
353 a service is connected. If the online check succeeds the service
354 enters Online state, if not it stays in Ready state. The online
355 check is also used to detect whether ConnMan is behind a captive
356 portal like when you are in hotel and need to pay for connectivity.
357
358 The online check is done by trying to fetch status.html document
359 from ipv4.connman.net (for IPv4 connectivity) and ipv6.connman.net
360 (for IPv6 connectivity). The used URL looks like this
361 http://ipv{4|6}.connman.net/online/status.html
362
363 During the online check procedure, ConnMan will temporarily install
364 a host route to both the ipv4.connman.net and ipv6.connman.net so that
365 the online check query can be directed via the correct network
366 interface which the connected service is using. This host route is
367 automatically removed when the online check is done.
368
369 ConnMan sends this very minimal information in http header when doing
370 the online check request (example):
371         Host: ipv4.connman.net
372         User-Agent: ConnMan/1.23 wispr
373         Connection: close
374
375 Currently following information is returned from connman.net if
376 the connection is successfull (200 OK http response code is returned):
377         Server: nginx
378         Date: Mon, 09 Jun 2014 09:25:42 GMT
379         Content-Type: text/html
380         Connection: close
381         X-ConnMan-Status: online
382
383 The X-ConnMan-Status field is used in portal detection, if it is missing
384 ConnMan will call RequestBrowser method in net.connman.Agent dbus
385 interface to handle the portal login if the portal does not support WISPr.
386 See doc/agent-api.txt for more details.
387
388
389 Information
390 ===========
391
392 Mailing list:
393         connman@connman.net
394
395 For additional information about the project visit ConnMan web site:
396         https://01.org/connman
397         http://www.connman.net
398
399 You can report bugs at https://01.org/jira/browse/CM