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         --enable-iwd
 135
 136                 Enable support for Wireless daemon for Linux
 137
 138                 The IWD project does not have initial release so far,
 139                 therefore by default IWD support is not enabled.
 140
 141                 It is safe to enable this option along WiFi support.
 142
 143         --disable-pacrunner
 144
 145                 Disable support for PACrunner proxy handling
 146
 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.
 150
 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
 154                 to build ConnMan.
 155
 156         --disable-loopback
 157
 158                 Disable setup of loopback device
 159
 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.
 163
 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.
 167
 168         --disable-wispr
 169
 170                 Disable support for WISPr hotspot logins
 171
 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.
 176
 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.
 180
 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.
 185
 186         --enable-polkit
 187
 188                 Enable support for PolicyKit authorization
 189
 190                 This allows to check every D-Bus access against a security
 191                 policy and so restrict access to certain functionality.
 192
 193         --enable-nmcompat
 194
 195                 Enable support for NetworkManager compatibility interfaces
 196
 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.
 201
 202         --disable-client
 203
 204                 Disable support for the command line client
 205
 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.
 210
 211         --enable-selinux
 212
 213                 Enable support for compiling SElinux type enforcement rules
 214
 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.
 222
 223
 224 Activating debugging
 225 ====================
 226
 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.
 231 Example:
 232     -d                   Activate all normal debug prints
 233     -d src/service.c     This prints debugging info from src/service.c
 234                          file only
 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.
 244
 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
 254                               its own use.
 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.
 262
 263 Example:
 264     CONNMAN_WEB_DEBUG=1 src/connmand -n
 265
 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
 269
 270 The 'ts' program is normaly avialable in the moreutils package.
 271
 272
 273 Kernel configuration
 274 ====================
 275
 276 In order to support tethering, the following kernel configuration options
 277 need to be enabled either as modules (m) or builtin (y):
 278
 279 CONFIG_BRIDGE
 280 CONFIG_IP_NF_TARGET_MASQUERADE
 281
 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):
 284
 285 CONFIG_NETFILTER
 286 CONFIG_NF_CONNTRACK_IPV4
 287 CONFIG_NF_NAT_IPV4
 288
 289 For routing and statistic support in Sessions, the following options
 290 need to be enabled as modules (m) or builtin (y):
 291
 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
 299
 300 In order to support USB gadget tethering, the following kernel configuration
 301 options need to be enabled:
 302
 303 CONFIG_USB_GADGET
 304 CONFIG_USB_ETH
 305
 306
 307 wpa_supplicant configuration
 308 ============================
 309
 310 In order to get wpa_supplicant and Connection Manager working properly
 311 together you should edit wpa_supplicant .config file and set:
 312
 313 CONFIG_WPS=y
 314 CONFIG_AP=y
 315 CONFIG_CTRL_IFACE_DBUS_NEW=y
 316
 317 add:
 318
 319 CONFIG_BGSCAN_SIMPLE=y
 320
 321 This last option will enable the support of background scanning while being
 322 connected, which is necessary when roaming on wifi.
 323
 324 It is recommended to use wpa_supplicant 2.x or later.
 325
 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.
 331
 332
 333 VPN
 334 ===
 335
 336 In order to compile pptp and l2tp VPN plugins, you need ppp development
 337 package.
 338
 339 To run l2tp you will need
 340         - xl2tpd, http://www.xelerance.com/services/software/xl2tpd
 341
 342 To run pptp you will need
 343         - pptp client, http://pptpclient.sourceforge.net
 344
 345 Both l2tp and pptp also need pppd.
 346
 347
 348 OpenVPN
 349 =======
 350
 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
 355 uplink.
 356
 357
 358 GnuTLS
 359 ======
 360
 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
 367 delay).
 368
 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).
 372
 373
 374 Online check
 375 ============
 376
 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.
 382
 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
 387
 388 See connman.conf(5) for the EnableOnlineCheck option, if you need to
 389 disable the feature.
 390
 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.
 399
 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
 404         Connection: close
 405
 406 Currently following information is returned from connman.net if
 407 the connection is successfull (200 OK http response code is returned):
 408         Server: nginx
 409         Date: Mon, 09 Jun 2014 09:25:42 GMT
 410         Content-Type: text/html
 411         Connection: close
 412         X-ConnMan-Status: online
 413
 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.
 418
 419
 420 Information
 421 ===========
 422
 423 Mailing list:
 424         connman@connman.net
 425
 426 For additional information about the project visit ConnMan web site:
 427         https://01.org/connman
 428         http://www.connman.net
 429
 430 You can report bugs at https://01.org/jira/browse/CM