doc/session-overview.txt

   1 Session API
   2 ***********
   3
   4
   5 Connection management algorithm basics
   6 ======================================
   7
   8 The Session core uses the normal auto-connect algorithm for selecting
   9 which services will be connected or disconnected. That means only
  10 Services with AutoConnect set to true will be used. The Session
  11 core will assign a connected Service to a Session if the Service
  12 is matching the AllowedBearer filter.
  13
  14 By using the normal auto-connect algorithm, it is possible to
  15 use the Session API and the Service API at the same time.
  16
  17
  18 Session States and Transitions
  19 ==============================
  20
  21 There is only one state which is called Free Ride.
  22
  23 The Free Ride state means that a session will go online if a matching
  24 service goes online without calling Service.Connect() itself. The idea
  25 behind this is that a session doesn't request a connection for itself
  26 instead waits until another session actively requires to go online.
  27 This is comparable to piggy-backing.
  28
  29 Connect()
  30  +------+
  31  |      v
  32 +------------+
  33 |  Free Ride |
  34 +------------+
  35   |     ^
  36   +-----+
  37  Disconnect()
  38
  39
  40 If an application wants to stay offline it can set an empty
  41 AllowedBearers list.
  42
  43
  44 Session application identification
  45 ==================================
  46
  47 Application using session can be identified through different means.
  48
  49   - SELinux
  50   - UID
  51   - GID
  52
  53 ConnMan will try to identify the application in the given order above.
  54 If SELinux is not supported by the system or not configured, ConnMan
  55 will ignore it and fallback asking the D-Bus daemon about the UID of
  56 the application.
  57
  58 The identification is only useful in combination with the policy plugin.
  59
  60
  61 Policy Plugin
  62 =============
  63
  64 The policy plugin allows the administrator to provision/configure
  65 sessions. Each policy needs an application identification in order to
  66 match the policy to a session.
  67
  68 See session-policy-format.txt for more details.
  69
  70
  71 Per application routing
  72 =======================
  73
  74 For each session a policy routing table is maintained. Each policy
  75 routing table contains a default route to the selected service.
  76
  77 Per session iptables rules:
  78
  79 iptables -t mangle -A OUTPUT -m owner [--uid-owner|--gid-owner] $OWNER \
  80           -j MARK --set-mark $MARK
  81
  82 Global rules for all sessions:
  83
  84 iptables -t mangle -A INPUT -j CONNMARK --restore-mark
  85 iptables -t mangle -A POSTROUTING -j CONNMARK --save-mark
  86
  87 Per application routing is only available when policy files are
  88 used. Without the policy plugin or a valid configuration, the default
  89 session configuration is applied.
  90
  91 The default session configuration does not enable the per application
  92 routing. Sessions are still useful in this setup, because the
  93 notification of sessions is still available, e.g. the online/offline
  94 notification.
  95
  96
  97 Multiple per-session routing tables
  98 ===================================
  99
 100 Sessions can be used in an environment with multiple network interfaces,
 101 where an application needs to direct outside traffic through a selected
 102 interface(s). ConnMan can maintain multiple sessions in a connected
 103 stated, and the application can dynamically, on a per-socket basis,
 104 select which session is used to route traffic.
 105
 106 Example use cases are:
 107 - monitoring liveness of multiple connected interfaces, by sending
 108   end-to-end heartbeat traffic on all of them in parallel.
 109 - prioritising traffic - e.g. sensitive data can be transferred over a slow,
 110   but secure connection, while big, public downloads use a second session
 111
 112 By default, ConnMan maintains only one online service. So it is impossible
 113 to send external traffic (routed through a gateway) on multiple interfaces.
 114 In order to enable this functionality, an application needs to issue the
 115 following API calls:
 116 - create multiple sessions, one for each interface to be used
 117 - set each session's AllowedInterface config field to the required interface
 118   name (eth0, eth1, wlan0, ppp0, etc.)
 119 - set each session's SourceIPRule config field to true
 120 - connect each session (or the service it is using)
 121
 122 That will instruct ConnMan to create multiple routing tables, with default
 123 routes in them. After that, the application can issue a bind() call on each
 124 socket, using required interface's source IP address. The bind() call must
 125 be made before a connect() call on a socket.