X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=README;h=b8154e67a7accb7b452727dd7ad81977a15d8476;hb=5479dad2b3b5f342f51ca6e7ec8a5a501820bd55;hp=37130dd7bb79e9eaa12bbe5c7d4803300380eb2a;hpb=3df7e823d4476f56b86b809c80a1dfa57f7413bf;p=platform%2Fupstream%2Fconnman.git diff --git a/README b/README old mode 100644 new mode 100755 index 37130dd..b8154e6 --- a/README +++ b/README @@ -1,7 +1,7 @@ Connection Manager ****************** -Copyright (C) 2007-2009 Intel Corporation. All rights reserved. +Copyright (C) 2007-2012 Intel Corporation. All rights reserved. Functionality and features @@ -10,18 +10,32 @@ Functionality and features The following features are built-in into Connection Manager: - Generic plugin infrastructure - Device and network abstraction (with basic storage support) - - IPv4, routing and DNS configuration + - 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 only) support - - Bluetooth 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: - - DHCP plugins (uDHCP and dhclient) - - Resolver plugins (resolvconf and DNS proxy) - - Loopback setup - - PolicyKit support + - 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 @@ -31,9 +45,10 @@ In order to compile Connection Manager you need following software packages: - GCC compiler - GLib library - D-Bus library - - udev library (optional) + - IP-Tables library (for tethering support) + - GnuTLS library (optional) - PolicyKit (optional) - - PPP support (optional) + - readline (command line client) To configure run: ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var @@ -49,92 +64,125 @@ Configuration and options For a working system, certain configuration options need to be enabled: - --enable-ethernet + --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 - Enable support for Ethernet network cards + Disable support for USB Ethernet Gadget devices - --enable-wifi + 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. - Enable support for WiFi devices (requires wpa_supplicant) + --disable-wifi + Disable support for WiFi devices - --enable-bluetooth + 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. - Enable support for Bluetooth devices (requires BlueZ) + 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. - --enable-ppp + --disable-bluetooth - Enable PPP support for dialup connections (requires pppd) + Disable support for Bluetooth devices - The location of the pppd binary is auto-detected, but it - can be overwritten via --with-pppd=. + 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. - --enable-udhcp + 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. - Enable DHCP client support for BusyBox based systems + --disable-ofono - The location of the udhcpc binary is auto-detected, but it - can be overwritten via --with-udhcpc=. + Disable support for cellular 2G/3G/4G devices - --enable-dhclient + 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. - Enable DHCP client support for ISC dhclient based systems + 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. - The location of the dhclient binary is auto-detected, but it - can be overwritten via --with-dhclient=. + --disable-dundee - At least one DHCP client option should be selected. It is - possible to select both and then uDHCP will be tried first - before falling back to dhclient. + Disable support for Bluetooth DUN devices - --enable-dnsproxy + 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. - Enable DNS proxy support for /etc/resolv.conf abstraction + 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. - The best solution for multiple connections and proper DNS - handling is a DNS proxy server. This binds a DNS proxy - server to port 53 on the loopback interface (127.0.0.1). + --enable-iwd - The /etc/resolv.conf file needs a "nameserver 127.0.0.1" - entry, but can now set the immutable bit or be on a read-only - filesystem. No further modification to that file will be made. + Enable support for Wireless daemon for Linux - It is important that this is not used together with other - DNS proxy solution like dnsmasq. + The IWD project does not have initial release so far, + therefore by default IWD support is not enabled. - --enable-resolvconf + It is safe to enable this option along WiFi support. - Enable resolvconf support for Debian/Ubuntu based systems + --disable-pacrunner - The resolvconf package from Debian can be used to handle - configuration of the /etc/resolv.conf file. + Disable support for PACrunner proxy handling - It is safe to select this option even when resolvconf is not - installed. A missing resolvconf will be detected and in that - case it falls back to modifying /etc/resolv.conf directly. + 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. - The location of the resolvconf binary is auto-detected, but it - can be overwritten via --with-resolvconf=. + 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. - --enable-loopback + --disable-loopback - Enable setup of loopback device + 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 select this option even if networking scripts - are in place. It detects an already configured loopback - device and leaves it as it is. + 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. - --enable-udev + --disable-wispr - Enable device detection support via udev + Disable support for WISPr hotspot logins - Network devices are by default detected via the builtin RTNL - functionality. This allows to detect TTY based modem devices - via udev. + 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 @@ -143,3 +191,265 @@ For a working system, certain configuration options need to be enabled: 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 + +See connman.conf(5) for the EnableOnlineCheck option, if you need to +disable the feature. + +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