Session API
***********


Connection management algorithm basics
======================================

The Session core uses the normal auto-connect algorithm for selecting
which services will be connected or disconnected. That means only
Services with AutoConnect 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
==============================

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
=======================

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.


Multiple per-session routing tables
===================================

Sessions can be used in an environment with multiple network interfaces,
where an application needs to direct outside traffic through a selected
interface(s). ConnMan can maintain multiple sessions in a connected
stated, and the application can dynamically, on a per-socket basis,
select which session is used to route traffic.

Example use cases are:
- monitoring liveness of multiple connected interfaces, by sending
  end-to-end heartbeat traffic on all of them in parallel.
- prioritising traffic - e.g. sensitive data can be transferred over a slow,
  but secure connection, while big, public downloads use a second session

By default, ConnMan maintains only one online service. So it is impossible
to send external traffic (routed through a gateway) on multiple interfaces.
In order to enable this functionality, an application needs to issue the
following API calls:
- create multiple sessions, one for each interface to be used
- set each session's AllowedInterface config field to the required interface
  name (eth0, eth1, wlan0, ppp0, etc.)
- set each session's SourceIPRule config field to true
- connect each session (or the service it is using)

That will instruct ConnMan to create multiple routing tables, with default
routes in them. After that, the application can issue a bind() call on each
socket, using required interface's source IP address. The bind() call must
be made before a connect() call on a socket.