DA: Skip initializing failed_bssids list when eapol failure case
[platform/upstream/connman.git] / README
diff --git a/README b/README
old mode 100644 (file)
new mode 100755 (executable)
index 1e3481d..b8154e6
--- a/README
+++ b/README
@@ -11,6 +11,7 @@ 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
        - 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
        - IPv6, DHCPv6 and 6to4 tunnels
        - Advanced routing and DNS configuration
        - Built-in DNS proxy and intelligent caching
@@ -31,6 +32,11 @@ Also plugins with additional features are available:
        - PACrunner proxy handling
        - PolicyKit authorization support
 
        - 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
 ============================
 
 Compilation and installation
 ============================
@@ -39,7 +45,7 @@ In order to compile Connection Manager you need following software packages:
        - GCC compiler
        - GLib library
        - D-Bus library
        - GCC compiler
        - GLib library
        - D-Bus library
-       - IP-Tables library
+       - IP-Tables library (for tethering support)
        - GnuTLS library (optional)
        - PolicyKit (optional)
        - readline (command line client)
        - GnuTLS library (optional)
        - PolicyKit (optional)
        - readline (command line client)
@@ -66,6 +72,14 @@ For a working system, certain configuration options need to be enabled:
                enabled. This option can be used to build a small daemon
                for a specific system if Ethernet support is not required.
 
                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
        --disable-wifi
 
                Disable support for WiFi devices
@@ -118,6 +132,15 @@ For a working system, certain configuration options need to be enabled:
                detected and only a runtime dependency. It is not needed to
                build ConnMan.
 
                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
        --disable-pacrunner
 
                Disable support for PACrunner proxy handling
@@ -186,6 +209,111 @@ For a working system, certain configuration options need to be enabled:
                configured by other means, the command line client can be
                disabled and the dependency on readline is removed.
 
                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
 ============================
 
 wpa_supplicant configuration
 ============================
@@ -197,14 +325,23 @@ CONFIG_WPS=y
 CONFIG_AP=y
 CONFIG_CTRL_IFACE_DBUS_NEW=y
 
 CONFIG_AP=y
 CONFIG_CTRL_IFACE_DBUS_NEW=y
 
-and, add:
+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.
 
 
 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 0.8.x or 1.x or later.
+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
 
 
 VPN
@@ -231,12 +368,88 @@ 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.
 
 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:
 
 Information
 ===========
 
 Mailing list:
-       connman@connman.net
+       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
 
 
-For additional information about the project visit ConnMan web site:
-       http://www.connman.net
+Mailing list archive:
+       https://lore.kernel.org/connman