summaryrefslogtreecommitdiff
path: root/README
blob: e3268c829f89ecc0f5dc6ec66a71b28c4a4cbb03 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
Connection Manager
******************

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, 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 and enterprise)
	- Bluetooth plugin (using BlueZ)
	- 2G/3G/4G plugin (using oFono)

Also plugins with additional features are available:
	- 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
============================

In order to compile Connection Manager you need following software packages:
	- GCC compiler
	- GLib library
	- D-Bus library
	- 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

Configure automatically searches for all required components and packages.

To compile and install run:
	make && make install


Configuration and options
=========================

For a working system, certain configuration options need to be enabled:

	--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

		Disable support for WiFi devices

		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.

		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

		Disable support for Bluetooth devices

		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.

		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.

	--disable-ofono

		Disable support for cellular 2G/3G/4G devices

		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.

		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.

	--disable-dundee

		Disable support for Bluetooth DUN devices

		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.

		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.

	--enable-iwd

		Enable support for Wireless daemon for Linux

		The IWD project does not have initial release so far,
		therefore by default IWD support is not enabled.

		It is safe to enable this option along WiFi support.

	--disable-pacrunner

		Disable support for PACrunner proxy handling

		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.

		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.

	--disable-loopback

		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 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

		Enable support for PolicyKit authorization

		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)