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