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         - IPv4 address conflict detection (ACD) according to RFC 5227
  15         - IPv6, DHCPv6 and 6to4 tunnels
  16         - Advanced routing and DNS configuration
  17         - Built-in DNS proxy and intelligent caching
  18         - Built-in WISPr hotspot logins and portal detection
  19         - Time and timezone configuration (manual and automatic with NTP)
  20         - Proxy handling (manual and automatic with WPAD)
  21         - Tethering support (USB, Bluetooth and WiFi AP mode)
  22         - Detailed statistics handling (home and roaming)
  23
  24 Various plugins can be enabled for networking support:
  25         - Ethernet plugin
  26         - WiFi plugin with WEP40/WEP128 and WPA/WPA2 (personal and enterprise)
  27         - Bluetooth plugin (using BlueZ)
  28         - 2G/3G/4G plugin (using oFono)
  29
  30 Also plugins with additional features are available:
  31         - Loopback interface setup
  32         - PACrunner proxy handling
  33         - PolicyKit authorization support
  34
  35 Note that when ConnMan starts, it clears all network interfaces that are
  36 going to be used. If this is not desired, network interfaces can be ignored
  37 either by setting NetworkInterfaceBlacklist in the main.conf config file or
  38 by using the -I command line option.
  39
  40
  41 Compilation and installation
  42 ============================
  43
  44 In order to compile Connection Manager you need following software packages:
  45         - GCC compiler
  46         - GLib library
  47         - D-Bus library
  48         - IP-Tables library (for tethering support)
  49         - GnuTLS library (optional)
  50         - PolicyKit (optional)
  51         - readline (command line client)
  52
  53 To configure run:
  54         ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
  55
  56 Configure automatically searches for all required components and packages.
  57
  58 To compile and install run:
  59         make && make install
  60
  61
  62 Configuration and options
  63 =========================
  64
  65 For a working system, certain configuration options need to be enabled:
  66
  67         --disable-ethernet
  68
  69                 Disable support for Ethernet network cards
  70
  71                 By default Ethernet technology support is built-in and
  72                 enabled. This option can be used to build a small daemon
  73                 for a specific system if Ethernet support is not required.
  74
  75         --disable-gadget
  76
  77                 Disable support for USB Ethernet Gadget devices
  78
  79                 By default USB Ethernet Gadget technology support is built-in and
  80                 enabled. This option can be used to build a small daemon
  81                 for a specific system if USB Ethernet Gadget support is not required.
  82
  83         --disable-wifi
  84
  85                 Disable support for WiFi devices
  86
  87                 By default WiFi technology support is built-in and
  88                 enabled. This option can be used to build a small daemon
  89                 for a specific system if WiFi support is not required.
  90
  91                 It is safe to build a daemon with WiFi support and no
  92                 running wpa_supplicant. The start of wpa_supplicant is
  93                 automatically detected and only a runtime dependency. It
  94                 is not needed to build ConnMan.
  95
  96         --disable-bluetooth
  97
  98                 Disable support for Bluetooth devices
  99
 100                 By default Bluetooth technology support is built-in and
 101                 enabled. This option can be used to build a small daemon
 102                 for a specific system if Bluetooth support is not required.
 103
 104                 It is safe to build a daemon with Bluetooth support and no
 105                 running bluetoothd. The start of bluetoothd is automatically
 106                 detected and only a runtime dependency. It is not needed to
 107                 build ConnMan.
 108
 109         --disable-ofono
 110
 111                 Disable support for cellular 2G/3G/4G devices
 112
 113                 By default oFono technology support is built-in and
 114                 enabled. This option can be used to build a small daemon
 115                 for a specific system where oFono is not used.
 116
 117                 It is safe to build a daemon with oFono support and no
 118                 running ofonod. That start of ofonod is automatically
 119                 detected and only a runtime dependency. It is not needed to
 120                 build ConnMan.
 121
 122         --disable-dundee
 123
 124                 Disable support for Bluetooth DUN devices
 125
 126                 By default Bluetooth DUN technology (dundee) support is
 127                 built-in and enabled. This option can be used to build a
 128                 small daemon for a specific system where dundee is not used.
 129
 130                 It is safe to build a daemon with dundee support and no
 131                 running dundee. That start of dundee is automatically
 132                 detected and only a runtime dependency. It is not needed to
 133                 build ConnMan.
 134
 135         --enable-iwd
 136
 137                 Enable support for Wireless daemon for Linux
 138
 139                 The IWD project does not have initial release so far,
 140                 therefore by default IWD support is not enabled.
 141
 142                 It is safe to enable this option along WiFi support.
 143
 144         --disable-pacrunner
 145
 146                 Disable support for PACrunner proxy handling
 147
 148                 By default PACrunner support is built-in and enabled. This
 149                 option can be used to build a small daemon for a specific
 150                 system where PACrunner is not used.
 151
 152                 It is safe to build a daemon with PACrunner support and no
 153                 pacrunner daemon. It will detect and start a PACrunner
 154                 process if needed at runtime. The presence is not needed
 155                 to build ConnMan.
 156
 157         --disable-loopback
 158
 159                 Disable setup of loopback device
 160
 161                 For distributions with a really minimal init system and no
 162                 networking scripts this can take care of setting up the
 163                 loopback device and enabling it.
 164
 165                 It is safe to leave this selected even if networking
 166                 scripts are in place. It detects an already configured
 167                 loopback device and leaves it as it is.
 168
 169         --disable-wispr
 170
 171                 Disable support for WISPr hotspot logins
 172
 173                 For systems with really minimal memory requirements, this
 174                 will disable the support for WISPr hotspot logins. The code
 175                 for WISPr will be still compiled into the daemon, but its
 176                 requirement on GnuTLS for secure connections will be lifted.
 177
 178                 The missing GnuTLS support shrinks the memory requirements
 179                 by about 30% and for systems that are more stationary and do
 180                 not log into hotspots this might be a better trade off.
 181
 182                 Disabling WISPr support is not disabling the portal detection
 183                 support. A portal will still be detected, but instead of being
 184                 asked for login credentials, the request for a browser session
 185                 will be made through the agent.
 186
 187         --enable-polkit
 188
 189                 Enable support for PolicyKit authorization
 190
 191                 This allows to check every D-Bus access against a security
 192                 policy and so restrict access to certain functionality.
 193
 194         --enable-nmcompat
 195
 196                 Enable support for NetworkManager compatibility interfaces
 197
 198                 This allows to expose a minimal set of NetworkManager
 199                 interfaces. It is useful for systems with applications
 200                 written to use NetworkManager to detect online/offline
 201                 status and have not yet been converted to use ConnMan.
 202
 203         --disable-client
 204
 205                 Disable support for the command line client
 206
 207                 By default the command line client is enabled and uses the
 208                 readline library. For specific systems where ConnMan is
 209                 configured by other means, the command line client can be
 210                 disabled and the dependency on readline is removed.
 211
 212         --enable-selinux
 213
 214                 Enable support for compiling SElinux type enforcement rules
 215
 216                 The TE rules are needed if host environment is in enforcing
 217                 mode. Without this option, the VPN client process cannot
 218                 send notification to connman-vpnd via net.connman.Task
 219                 interface. The compiled connman-task.pp module needs to
 220                 also installed using this command
 221                         # semodule -i connman-task.pp
 222                 in order to enable the dbus access.
 223
 224     --with-dns-backend=TYPE
 225
 226                 Enable support for a DNS resolving backend
 227
 228                 Select a DNS backend to use. Supported values are "internal"
 229                 and "systemd-resolved". If "internal" is selected, ConnMan
 230                 will be build with a caching DNS proxy. If "systemd-resolved"
 231                 is selected, ConnMan configures systemd-resolved to do DNS
 232                 resolving. The default value is "internal".
 233
 234
 235 Activating debugging
 236 ====================
 237
 238 One can activate debugging prints in ConnMan using -d command line option.
 239 If the -d option has no parameters, then debugging is activated for all
 240 source code files. If the -d option has parameters, they tell which source
 241 code files have debugging activated. One can use wild cards in file names.
 242 Example:
 243     -d                   Activate all normal debug prints
 244     -d src/service.c     This prints debugging info from src/service.c
 245                          file only
 246     -d src/network.c:src/ipconfig.c
 247                          This activates debug prints in src/network.c
 248                          and src/ipconfig.c files.
 249     -d 'src/n*.c'        This would activate debug print from all the C source
 250                          files starting with letter 'n' in src directory.
 251                          Note the quotation marks around option, that is to
 252                          prevent shell expansion.
 253     -d '*/n*.c:*/i*.c'   Activate debug prints for all C source files starting
 254                          with letters 'n' or 'i' in any sub-directory.
 255
 256 Some components of ConnMan have environment variable activated debug prints.
 257 If the environment variable is set, then corresponding component will print
 258 some extra debugging information.
 259 Following environment variables can be used:
 260     CONNMAN_DHCP_DEBUG        DHCPv4 related debug information
 261     CONNMAN_DHCPV6_DEBUG      DHCPv6 related debug information
 262     CONNMAN_IPTABLES_DEBUG    Extra information when iptables is used
 263     CONNMAN_RESOLV_DEBUG      Name resolver debug prints. These debug prints
 264                               are used when ConnMan resolves host names for
 265                               its own use.
 266                               Note that the DNS proxy debug prints do not
 267                               use this environment variable. For that, one
 268                               can use "-d src/dnsproxy.c" command line option.
 269     CONNMAN_SUPPLICANT_DEBUG  Debugging prints for communication between
 270                               connmand and wpa_supplicant processes.
 271     CONNMAN_WEB_DEBUG         Debug information when ConnMan does Internet
 272                               connectivity check in Wispr and 6to4 components.
 273
 274 Example:
 275     CONNMAN_WEB_DEBUG=1 src/connmand -n
 276
 277 If timing conditions are relevant then it is recommended command to
 278 get log traces as follows:
 279     connmand -d 2>&1 | ts '[%H:%M:%.S]' | tee connman.log
 280
 281 The 'ts' program is normally available in the moreutils package.
 282
 283
 284 Kernel configuration
 285 ====================
 286
 287 In order to support tethering, the following kernel configuration options
 288 need to be enabled either as modules (m) or builtin (y):
 289
 290 CONFIG_BRIDGE
 291 CONFIG_IP_NF_TARGET_MASQUERADE
 292
 293 In order to enable CONFIG_IP_NF_TARGET_MASQUERADE, the following options need
 294 to be enabled also as modules (m) or builtin (y):
 295
 296 CONFIG_NETFILTER
 297 CONFIG_NF_CONNTRACK_IPV4
 298 CONFIG_NF_NAT_IPV4
 299
 300 For routing and statistic support in Sessions, the following options
 301 need to be enabled as modules (m) or builtin (y):
 302
 303 CONFIG_IP_NF_IPTABLES
 304 CONFIG_IP_MULTIPLE_TABLES
 305 CONFIG_NETFILTER_NETLINK_ACCT
 306 CONFIG_NETFILTER_XT_MATCH_NFACCT
 307 CONFIG_NETFILTER_XT_CONNMARK
 308 CONFIG_NETFILTER_XT_TARGET_CONNMARK
 309 CONFIG_NETFILTER_XT_MATCH_CONNMARK
 310
 311 In order to support USB gadget tethering, the following kernel configuration
 312 options need to be enabled:
 313
 314 CONFIG_USB_GADGET
 315 CONFIG_USB_ETH
 316
 317
 318 wpa_supplicant configuration
 319 ============================
 320
 321 In order to get wpa_supplicant and Connection Manager working properly
 322 together you should edit wpa_supplicant .config file and set:
 323
 324 CONFIG_WPS=y
 325 CONFIG_AP=y
 326 CONFIG_CTRL_IFACE_DBUS_NEW=y
 327
 328 add:
 329
 330 CONFIG_BGSCAN_SIMPLE=y
 331
 332 This last option will enable the support of background scanning while being
 333 connected, which is necessary when roaming on wifi.
 334
 335 It is recommended to use wpa_supplicant 2.x or later.
 336
 337 If wpa_supplicant is configured to D-Bus autostart, then ConnMan will
 338 trigger the autostart of wpa_supplicant. However please keep in mind
 339 that this trigger only happens once. If wpa_supplicant stops or crashes,
 340 ConnMan does not periodically try to autostart it. It is up to systemd or
 341 similar service management tool to autostart it. In case wpa_supplicant
 342 is not started by ConnMan then make sure option "-u" is used in order
 343 to enable its D-Bus control interface and ensure ConnMan can communicate
 344 with it.
 345
 346
 347 VPN
 348 ===
 349
 350 In order to compile pptp and l2tp VPN plugins, you need ppp development
 351 package.
 352
 353 To run l2tp you will need
 354         - xl2tpd, http://www.xelerance.com/services/software/xl2tpd
 355
 356 To run pptp you will need
 357         - pptp client, http://pptpclient.sourceforge.net
 358
 359 Both l2tp and pptp also need pppd.
 360
 361
 362 OpenVPN
 363 =======
 364
 365 Up to version 2.2 of OpenVPN, pushing additional routes from the
 366 server will not always work. Some of the symptons are that additional
 367 routes will not be set by ConnMan if the uplink is a cellular
 368 network. While the same setup works well for a WiFi or ethernet
 369 uplink.
 370
 371 Up to (at least) version 2.4.5 of OpenVPN getting information about
 372 private key decryption failures via management channel is missing. This
 373 will result in attempting with the invalid key over and over as the
 374 information about failed decryprion is not delivered to OpenVPN plugin.
 375 The following patch to OpenVPN is required for the private key
 376 decryption failures to be sent:
 377 https://git.sailfishos.org/mer-core/openvpn/blob/
 378 4f4b4af116292a207416c8a990392e35a6fc41af/rpm/privatekey-passphrase-
 379 handling.diff
 380
 381 GnuTLS
 382 ======
 383
 384 When using GnuTLS be aware that depending on the configuration of
 385 GnuTLS does either an lazy or eager initialization of an internal
 386 entropy pool using /dev/urandom. On eager initialization the loading
 387 of ConnMan will be delayed by the link loader until the entropy pool
 388 is filled. On smaller system this can easily delay the startup of
 389 ConnMan by several seconds (we had reports of 25 seconds and more
 390 delay).
 391
 392 GnuTLS allows to switch back to lazy evaluation when the environment
 393 variable GNUTLS_NO_EXPLICIT_INIT. For more details please read
 394 the man page to gnutls_global_init(3).
 395
 396
 397 Online check
 398 ============
 399
 400 ConnMan tries to detect if it has Internet connection or not when
 401 a service is connected. If the online check succeeds the service
 402 enters Online state, if not it stays in Ready state. The online
 403 check is also used to detect whether ConnMan is behind a captive
 404 portal like when you are in hotel and need to pay for connectivity.
 405
 406 The online check is done by trying to fetch status.html document
 407 from ipv4.connman.net (for IPv4 connectivity) and ipv6.connman.net
 408 (for IPv6 connectivity). The used URL looks like this
 409 http://ipv{4|6}.connman.net/online/status.html
 410
 411 When an online check request fails, another one is triggered after a
 412 longer interval. The intervals follow the square series of numbers
 413 in a specific range, by default [1, 12], corresponding to the following
 414 intervals, in seconds: 1, 4, 9, 16, 25, 36, 49, 64, 81, 100, 121 and 144.
 415
 416 See connman.conf(5) for the EnableOnlineCheck option, if you need to
 417 disable the feature.
 418 It is also possible to specify other URLs via OnlineCheckIPv4URL and
 419 OnlineCheckIPv6URL options.
 420 The range of intervals between two online check requests can be fine-tuned
 421 via OnlineCheckInitialInterval and OnlineCheckMaxInterval options.
 422
 423 During the online check procedure, ConnMan will temporarily install
 424 a host route to both the ipv4.connman.net and ipv6.connman.net so that
 425 the online check query can be directed via the correct network
 426 interface which the connected service is using. This host route is
 427 automatically removed when the online check is done. Note that the server
 428 expressly does not log any connection information, including IPv4/6
 429 addresses of connecting clients. The server runtime logs cycle in RAM
 430 memory depending on amount of connections processed.
 431
 432 ConnMan sends this very minimal information in http header when doing
 433 the online check request (example):
 434         Host: ipv4.connman.net
 435         User-Agent: ConnMan/1.23 wispr
 436         Connection: close
 437
 438 Currently following information is returned from connman.net if
 439 the connection is successful (200 OK http response code is returned):
 440         Server: nginx
 441         Date: Mon, 09 Jun 2014 09:25:42 GMT
 442         Content-Type: text/html
 443         Connection: close
 444         X-ConnMan-Status: online
 445
 446 The X-ConnMan-Status field is used in portal detection, if it is missing
 447 ConnMan will call RequestBrowser method in net.connman.Agent dbus
 448 interface to handle the portal login if the portal does not support WISPr.
 449 See doc/agent-api.txt for more details.
 450
 451
 452 Information
 453 ===========
 454
 455 Mailing list:
 456         connman@lists.linux.dev
 457
 458 If you would like to subscribe to receive mail in your inbox, just
 459 send a (empty) message from your email account to
 460
 461         connman+subscribe@lists.linux.dev
 462
 463 Mailing list archive:
 464         https://lore.kernel.org/connman
 465
 466 IRC:
 467         ircs://irc.oftc.net:6697/#connman (for SSL)
 468         irc://irc.oftc.net:6667/#connman (for non-SSL)