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 two 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
				      and try to connect

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.


Session States and Transitions
==============================

There is only one state which is called Free Ride.

The Free Ride state means that a session will go online if a matching
service goes online without calling Service.Connect() itself. The idea
behind this is that a session doesn't request a connection for itself
instead waits until another session actively requires to go online.
This is comparable to piggy-backing.

Connnect()
 +------+
 |      v
+------------+
|  Free Ride |
+------------+
  |     ^
  +-----+
 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 and statistics
======================================

For each session a policy routing table is maintained. Each
policy routing table contains a default route to the
selected service.

Furthermore a few iptables rules inserted into the kernel to gather
statistics via NFACCT.

Per session iptables rules:

iptables -t mangle -A OUTPUT -m owner [--uid-owner|--gid-owner] $OWNER \
	  -j MARK --set-mark $MARK

iptables -t filter -A INPUT -m mark --mark $MARK \
	 -m nfacct --nfacct-name session-input-$MARK
iptables -t filter -A OUTPUT -m mark --mark $MARK \
	 -m nfacct --nfacct-name session-output-$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 and statistics 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 and statistics. Sessions are still useful in this setup,
because the notification of sessions is still available, e.g. the
online/offline notification.
