session_policy_local: Do not handle small allocation
[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
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-wifi
75
76                 Disable support for WiFi devices
77
78                 By default WiFi technology support is built-in and
79                 enabled. This option can be used to build a small daemon
80                 for a specific system if WiFi support is not required.
81
82                 It is safe to build a daemon with WiFi support and no
83                 running wpa_supplicant. The start of wpa_supplicant is
84                 automatically detected and only a runtime dependency. It
85                 is not needed to build ConnMan.
86
87         --disable-bluetooth
88
89                 Disable support for Bluetooth devices
90
91                 By default Bluetooth technology support is built-in and
92                 enabled. This option can be used to build a small daemon
93                 for a specific system if Bluetooth support is not required.
94
95                 It is safe to build a daemon with Bluetooth support and no
96                 running bluetoothd. The start of bluetoothd is automatically
97                 detected and only a runtime dependency. It is not needed to
98                 build ConnMan.
99
100         --disable-ofono
101
102                 Disable support for cellular 2G/3G/4G devices
103
104                 By default oFono technology support is built-in and
105                 enabled. This option can be used to build a small daemon
106                 for a specific system where oFono is not used.
107
108                 It is safe to build a daemon with oFono support and no
109                 running ofonod. That start of ofonod is automatically
110                 detected and only a runtime dependency. It is not needed to
111                 build ConnMan.
112
113         --disable-dundee
114
115                 Disable support for Bluetooth DUN devices
116
117                 By default Bluetooth DUN technology (dundee) support is
118                 built-in and enabled. This option can be used to build a
119                 small daemon for a specific system where dundee is not used.
120
121                 It is safe to build a daemon with dundee support and no
122                 running dundee. That start of dundee is automatically
123                 detected and only a runtime dependency. It is not needed to
124                 build ConnMan.
125
126         --disable-pacrunner
127
128                 Disable support for PACrunner proxy handling
129
130                 By default PACrunner support is built-in and enabled. This
131                 option can be used to build a small daemon for a specific
132                 system where PACrunner is not used.
133
134                 It is safe to build a daemon with PACrunner support and no
135                 pacrunner daemon. It will detect and start a PACrunner
136                 process if needed at runtime. The presence is not needed
137                 to build ConnMan.
138
139         --disable-loopback
140
141                 Disable setup of loopback device
142
143                 For distributions with a really minimal init system and no
144                 networking scripts this can take care of setting up the
145                 loopback device and enabling it.
146
147                 It is safe to leave this selected even if networking
148                 scripts are in place. It detects an already configured
149                 loopback device and leaves it as it is.
150
151         --disable-wispr
152
153                 Disable support for WISPr hotspot logins
154
155                 For systems with really minimal memory requirements, this
156                 will disable the support for WISPr hotspot logins. The code
157                 for WISPr will be still compiled into the daemon, but its
158                 requirement on GnuTLS for secure connections will be lifted.
159
160                 The missing GnuTLS support shrinks the memory requirements
161                 by about 30% and for systems that are more stationary and do
162                 not log into hotspots this might be a better trade off.
163
164                 Disabling WISPr support is not disabling the portal detection
165                 support. A portal will still be detected, but instead of being
166                 asked for login credentials, the request for a browser session
167                 will be made through the agent.
168
169         --enable-polkit
170
171                 Enable support for PolicyKit authorization
172
173                 This allows to check every D-Bus access against a security
174                 policy and so restrict access to certain functionality.
175
176         --enable-nmcompat
177
178                 Enable support for NetworkManager compatibility interfaces
179
180                 This allows to expose a minimal set of NetworkManager
181                 interfaces. It is useful for systems with applications
182                 written to use NetworkManager to detect online/offline
183                 status and have not yet been converted to use ConnMan.
184
185         --disable-client
186
187                 Disable support for the command line client
188
189                 By default the command line client is enabled and uses the
190                 readline library. For specific systems where ConnMan is
191                 configured by other means, the command line client can be
192                 disabled and the dependency on readline is removed.
193
194         --enable-selinux
195
196                 Enable support for compiling SElinux type enforcement rules
197
198                 The TE rules are needed if host environment is in enforcing
199                 mode. Without this option, the VPN client process cannot
200                 send notification to connman-vpnd via net.connman.Task
201                 interface. The compiled connman-task.pp module needs to
202                 also installed using this command
203                         # semodule -i connman-task.pp
204                 in order to enable the dbus access.
205
206
207 Activating debugging
208 ====================
209
210 One can activate debugging prints in ConnMan using -d command line option.
211 If the -d option has no parameters, then debugging is activated for all
212 source code files. If the -d option has parameters, they tell which source
213 code files have debugging activated. One can use wild cards in file names.
214 Example:
215     -d                   Activate all normal debug prints
216     -d src/service.c     This prints debugging info from src/service.c
217                          file only
218     -d src/network.c:src/ipconfig.c
219                          This activates debug prints in src/network.c
220                          and src/ipconfig.c files.
221     -d 'src/n*.c'        This would activate debug print from all the C source
222                          files starting with letter 'n' in src directory.
223                          Note the quotation marks around option, that is to
224                          prevent shell expansion.
225     -d '*/n*.c:*/i*.c'   Activate debug prints for all C source files starting
226                          with letters 'n' or 'i' in any sub-directory.
227
228 Some components of ConnMan have environment variable activated debug prints.
229 If the environment variable is set, then corresponding component will print
230 some extra debugging information.
231 Following environment variables can be used:
232     CONNMAN_DHCP_DEBUG        DHCPv4 related debug information
233     CONNMAN_DHCPV6_DEBUG      DHCPv6 related debug information
234     CONNMAN_IPTABLES_DEBUG    Extra information when iptables is used
235     CONNMAN_RESOLV_DEBUG      Name resolver debug prints. These debug prints
236                               are used when ConnMan resolves host names for
237                               its own use.
238                               Note that the DNS proxy debug prints do not
239                               use this environment variable. For that, one
240                               can use "-d src/dnsproxy.c" command line option.
241     CONNMAN_SUPPLICANT_DEBUG  Debugging prints for communication between
242                               connmand and wpa_supplicant processes.
243     CONNMAN_WEB_DEBUG         Debug information when ConnMan does Internet
244                               connectivity check in Wispr and 6to4 components.
245
246 Example:
247     CONNMAN_WEB_DEBUG=1 src/connmand -n
248
249
250 Kernel configuration
251 ====================
252
253 In order to support tethering, the following kernel configuration options
254 need to be enabled either as modules (m) or builtin (y):
255
256 CONFIG_BRIDGE
257 CONFIG_IP_NF_TARGET_MASQUERADE
258
259 In order to enable CONFIG_IP_NF_TARGET_MASQUERADE, the following options need
260 to be enabled also as modules (m) or builtin (y):
261
262 CONFIG_NETFILTER
263 CONFIG_NF_CONNTRACK_IPV4
264 CONFIG_NF_NAT_IPV4
265
266
267 wpa_supplicant configuration
268 ============================
269
270 In order to get wpa_supplicant and Connection Manager working properly
271 together you should edit wpa_supplicant .config file and set:
272
273 CONFIG_WPS=y
274 CONFIG_AP=y
275 CONFIG_CTRL_IFACE_DBUS_NEW=y
276
277 add:
278
279 CONFIG_BGSCAN_SIMPLE=y
280
281 This last option will enable the support of background scanning while being
282 connected, which is necessary when roaming on wifi.
283
284 and finally:
285
286 CONFIG_AUTOSCAN_EXPONENTIAL=y
287
288 This will enable the exact same function as bgscan but while being
289 disconnected.
290
291 It is recommended to use wpa_supplicant 1.x or later.
292
293
294 VPN
295 ===
296
297 In order to compile pptp and l2tp VPN plugins, you need ppp development
298 package.
299
300 To run l2tp you will need
301         - xl2tpd, http://www.xelerance.com/services/software/xl2tpd
302
303 To run pptp you will need
304         - pptp client, http://pptpclient.sourceforge.net
305
306 Both l2tp and pptp also need pppd.
307
308
309 OpenVPN
310 =======
311
312 Up to version 2.2 of OpenVPN, pushing additional routes from the
313 server will not always work. Some of the symptons are that additional
314 routes will not be set by ConnMan if the uplink is a cellular
315 network. While the same setup works well for a WiFi or ethernet
316 uplink.
317
318
319 Information
320 ===========
321
322 Mailing list:
323         connman@connman.net
324
325 For additional information about the project visit ConnMan web site:
326         http://www.connman.net