Imported Upstream version 1.24

[platform/upstream/connman.git] / doc / session-overview.txt

diff --git a/doc/session-overview.txt b/doc/session-overview.txt
index d42c6d1..9af6a67 100644 (file)
--- a/doc/session-overview.txt
+++ b/doc/session-overview.txt
@@ -5,55 +5,14 @@ Session API
 Connection management algorithm basics
 ======================================
 
-When a session is created, a sorted list of services is added to the
-session. The services are filtered and sorted according AllowedBearers.
-
-There are three triggers which lead to evaluate the connect
-algorithm:
-
- - Session.Connect()
- - Offline
-
-Connect algorithm:
-
-              Session.Connect()
-                       |
-                +------+-------+
-          +-----+ECall Session ?+-----+
-       Yes|     +--------------+      |No
-          |                           |
-        Connect to            +--------------+
-        first available   +---+AvoidHandover?+---+
-        Service           |   +--------------+   |
-                       Yes|                      |No
-                 +----------------+              |
-             +---+In service_list +---+          |
-          Yes|   |and online?     |   |No        |
-             |   +----------------+   |          |
-             |                        |          |
-         Take that one                Take first in
-                                      the service list
-
-Disconnect algorithm
-
- - Session.Disconnect()
-
-Disconnect algorithm:
-
-  Session.Disconnect()
-       |
-       +--- Session.Change()
-       |
-+-----------------+    Yes
-|service not used +-------------+
-|by other session?|             |
-+------.----------+             |
-       |No                      |
-       |                        |
-    Service.Disconnect()   Do nothing
-
-Session.Disconnect() will be blocked whenever a ongoing
-emergency call is active.
+The Session core uses the normal auto-connect algorithm for selecting
+which services will be connected or disconnected. That means only
+Services with AutoConnect to set to true will be used. The Session
+core will assign a connected Service to a Session if the Service
+is matching the AllowedBearer filter.
+
+By using the normal auto-connect algorithm, it is possible to
+use the Session API and the Service API at the same time.
 
 
 Session States and Transitions
@@ -76,3 +35,60 @@ Connnect()
   |     ^
   +-----+
  Disconnect()
+
+
+If an application wants to stay offline it can set an empty
+AllowedBearers list.
+
+
+Session application identification
+==================================
+
+Application using session can be identified through different means.
+
+  - SELinux
+  - UID
+  - GID
+
+ConnMan will try to identify the application in the given order above.
+If SELinux is not supported by the system or not configured, ConnMan
+will ignore it and fallback asking the D-Bus daemon about the UID of
+the application.
+
+The identification is only useful in combination with the policy plugin.
+
+
+Policy Plugin
+=============
+
+The policy plugin allows the administrator to provision/configure
+sessions. Each policy needs an application identification in order to
+match the policy to a session.
+
+See session-policy-format.txt for more details.
+
+
+Per application routing
+=======================
+
+For each session a policy routing table is maintained. Each policy
+routing table contains a default route to the selected service.
+
+Per session iptables rules:
+
+iptables -t mangle -A OUTPUT -m owner [--uid-owner|--gid-owner] $OWNER \
+         -j MARK --set-mark $MARK
+
+Global rules for all sessions:
+
+iptables -t mangle -A INPUT -j CONNMARK --restore-mark
+iptables -t mangle -A POSTROUTING -j CONNMARK --save-mark
+
+Per application routing is only available when policy files are
+used. Without the policy plugin or a valid configuration, the default
+session configuration is applied.
+
+The default session configuration does not enable the per application
+routing. Sessions are still useful in this setup, because the
+notification of sessions is still available, e.g. the online/offline
+notification.