aboutsummaryrefslogtreecommitdiffstats
path: root/doc/afb-overview.html
blob: 839d606c4557e1e25984ba6162745f46c224657a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
<html>
<head>
  <link rel="stylesheet" type="text/css" href="doc.css">
  <meta charset="UTF-8">
</head>
<body>
<a name="Overview.of.AFB-DAEMON"></a>
<h1>Overview of AFB-DAEMON</h1>

<pre><code>version: 1
Date:    30 mai 2016
Author:  José Bollo
</code></pre>

<p><ul>
 <li><a href="#Overview.of.AFB-DAEMON">Overview of AFB-DAEMON</a>
 <ul>
  <li><a href="#Roles.of.afb-daemon">Roles of afb-daemon</a></li>
  <li><a href="#Use.cases.of.the.binder.afb-daemon">Use cases of the binder afb-daemon</a>
  <ul>
   <li><a href="#Remotely.running.application">Remotely running application</a></li>
   <li><a href="#Adding.native.features.to.HTML5.QML.applications">Adding native features to HTML5/QML applications</a></li>
   <li><a href="#Offering.services.to.the.system">Offering services to the system</a></li>
  </ul>
  </li>
  <li><a href="#The.plugins.of.the.binder.afb-daemon">The plugins of the binder afb-daemon</a></li>
  <li><a href="#Launching.the.binder.afb-daemon">Launching the binder afb-daemon</a></li>
  <li><a href="#Future.development.of.afb-daemon">Future development of afb-daemon</a></li>
 </ul>
 </li>
</ul></p>

<a name="Roles.of.afb-daemon"></a>
<h2>Roles of afb-daemon</h2>

<p>The name <strong>afb-daemon</strong> stands for <em>Application
Framework Binder Daemon</em>. That is why afb-daemon
is also named <strong><em>the binder</em></strong>.</p>

<p><strong>Afb-daemon</strong> is in charge to bind one instance of
an application to the AGL framework and AGL system.</p>

<p>On the following figure, you can use a typical use
of afb-daemon:</p>

<p><a id="binder-fig-basis"><h4>Figure: binder afb-daemon, basis</h4></a></p>

<pre><code>. . . . . . . . . . . . . . . . . . . . . . . . . .
.        Isolated security context                .
.                                                 .
.        +------------------------------+         .
.        |                              |         .
.        |    A P P L I C A T I O N     |         .
.        |                              |         .
.        +--------------+---------------+         .
.                       |                         .
.                       |                         .
.   +-------------------+----------------------+  .
.   |                            :             |  .
.   |        b i n d e r         :             |  .
.   |    A F B - D A E M O N     :   PLUGINS   |  .
.   |                            :             |  .
.   +-------------------+----------------------+  .
.                       |                         .
. . . . . . . . . . . . | . . . . . . . . . . . . .
                        |
                        v
                   AGL SYSTEM
</code></pre>

<p>The application and its companion binder run in secured and isolated
environment set for them. Applications are intended to access to AGL
system through the binder.</p>

<p>The binder afb-daemon serves multiple purposes:</p>

<ol>
<li><p>It acts as a gateway for the application to access the system;</p></li>
<li><p>It acts as an HTTP server for serving files to HTML5 applications;</p></li>
<li><p>It allows HTML5 applications to have native extensions subject
to security enforcement for accessing hardware ressources or
for speeding parts of algorithm.</p></li>
</ol>


<a name="Use.cases.of.the.binder.afb-daemon"></a>
<h2>Use cases of the binder afb-daemon</h2>

<p>This section tries to give a better understanding of the binder
usage through several use cases.</p>

<a name="Remotely.running.application"></a>
<h3>Remotely running application</h3>

<p>One of the most interresting aspect of using the binder afb-daemon
is the ability to run applications remotely. This feature is
possible because the binder afb-daemon implements native web
protocols.</p>

<p>So the <a href="#binder-fig-1">figure binder, basis</a> would become
when the application is run remotely:</p>

<p><a id="binder-fig-remote"><h4>Figure: binder afb-daemon and remotely running application</h4></a></p>

<pre><code>             +------------------------------+
             |                              |
             |    A P P L I C A T I O N     |
             |                              |
             +--------------+---------------+
                            |
                       ~ ~ ~ ~ ~ ~
                      :  NETWORK  :
                       ~ ~ ~ ~ ~ ~
                            |
. . . . . . . . . . . . . . | . . . . . . . . . . . . . .
. Isolated security         |                           .
.   context                 |                           .
.                           |                           .
.     . . . . . . . . . . . . . . . . . . . . . . . .   .
.     .                                             .   .
.     .               F I R E W A L L               .   .
.     .                                             .   .
.     . . . . . . . . . . . . . . . . . . . . . . . .   .
.                           |                           .
.       +-------------------+----------------------+    .
.       |                            :             |    .
.       |    A F B - D A E M O N     :   PLUGINS   |    .
.       |                            :             |    .
.       +-------------------+----------------------+    .
.                           |                           .
. . . . . . . . . . . . . . | . . . . . . . . . . . . . .
                            |
                            v
                       AGL SYSTEM
</code></pre>

<a name="Adding.native.features.to.HTML5.QML.applications"></a>
<h3>Adding native features to HTML5/QML applications</h3>

<p>Applications can provide with their packaged delivery a plugin.
That plugin will be instanciated for each application instance.
The methods of the plugin will be accessible by applications and
will be excuted within the security context.</p>

<a name="Offering.services.to.the.system"></a>
<h3>Offering services to the system</h3>

<p>It is possible to run the binder afb-daemon as a daemon that provides the
API of its plugins.</p>

<p>This will be used for:</p>

<ol>
<li><p>offering common APIs</p></li>
<li><p>provide application&rsquo;s services (services provided as application)</p></li>
</ol>


<p>In that case, the figure showing the whole aspects is</p>

<p><a id="binder-fig-remote"><h4>Figure: binder afb-daemon for services</h4></a></p>

<pre><code>. . . . . . . . . . . . . . . . . . . . . . 
.  Isolated security context application  . 
.                                         . 
.    +------------------------------+     . 
.    |                              |     . 
.    |    A P P L I C A T I O N     |     . 
.    |                              |     . 
.    +--------------+---------------+     .     . . . . . . . . . . . . . . . . . . . . . .
.                   |                     .     .        Isolated security context A      .
.                   |                     .     .                                         .
. +-----------------+------------------+  .     . +------------------------------------+  .
. |                        :           |  .     . |                        :           |  .
. |      b i n d e r       :           |  .     . |      b i n d e r       :  service  |  .
. |  A F B - D A E M O N   :  PLUGINS  |  .     . |  A F B - D A E M O N   :  PLUGINS  |  .
. |                        :           |  .     . |                        :     A     |  .
. +-----------------+------------------+  .     . +-----------------+------------------+  .
.                   |                     .     .                   |                     .
. . . . . . . . . . | . . . . . . . . . . .     . . . . . . . . . . | . . . . . . . . . . .
                    |                                               |
                    v                                               v
         ================================================================================
                                     D - B U S   &amp;   C Y N A R A
         ================================================================================
                    ^                                               ^
                    |                                               |
. . . . . . . . . . | . . . . . . . . . . .     . . . . . . . . . . | . . . . . . . . . . .
.                   |                     .     .                   |                     .
. +-----------------+------------------+  .     . +-----------------+------------------+  .
. |                        :           |  .     . |                        :           |  .
. |      b i n d e r       :  service  |  .     . |      b i n d e r       :  service  |  .
. |  A F B - D A E M O N   :  PLUGINS  |  .     . |  A F B - D A E M O N   :  PLUGINS  |  .
. |                        :     B     |  .     . |                        :     C     |  .
. +------------------------------------+  .     . +------------------------------------+  .
.                                         .     .                                         .
.        Isolated security context B      .     .        Isolated security context C      .
. . . . . . . . . . . . . . . . . . . . . .     . . . . . . . . . . . . . . . . . . . . . .
</code></pre>

<p>For this case, the binder afb-daemon takes care to attribute one single session
context to each client instance. It allows plugins to store and retrieve data
associated to each of its client.</p>

<a name="The.plugins.of.the.binder.afb-daemon"></a>
<h2>The plugins of the binder afb-daemon</h2>

<p>The binder can instanciate plugins. The primary use of plugins
is to add native methods that can be accessed by applications
written with any language through web technologies ala JSON RPC.</p>

<p>This simple idea is declined to serves multiple purposes:</p>

<ol>
<li><p>add native feature to applications</p></li>
<li><p>add common API available by any applications</p></li>
<li><p>provide customers services</p></li>
</ol>


<p>A specific document explains how to write an afb-daemon binder plugin:
<a href="afb-plugin-writing.html">HOWTO WRITE a PLUGIN for AFB-DAEMON</a></p>

<a name="Launching.the.binder.afb-daemon"></a>
<h2>Launching the binder afb-daemon</h2>

<p>The launch options for binder <strong>afb-daemon</strong> are:</p>

<pre><code>  --help

        Prints help with available options

  --version

        Display version and copyright

  --verbose

        Increases the verbosity, can be repeated

  --port=xxxx

        HTTP listening TCP port  [default 1234]

  --rootdir=xxxx

        HTTP Root Directory [default $AFBDIR or else $HOME/.AFB]

  --rootbase=xxxx

        Angular Base Root URL [default /opa]

        This is used for any application of kind OPA (one page application).
        When set, any missing document whose url has the form /opa/zzz
        is translated to /opa/#!zzz

  --rootapi=xxxx

        HTML Root API URL [default /api]

        The plugins are available within that url.

  --alias=xxxx

        Maps a path located anywhere in the file system to the
        a subdirectory. The syntax for mapping a PATH to the
        subdirectory NAME is: --alias=/NAME:PATH.

        Example: --alias=/icons:/usr/share/icons maps the
        content of /usr/share/icons within the subpath /icons.

        This option can be repeated.

  --apitimeout=xxxx

        Plugin API timeout in seconds [default 20]

        Defines how many seconds maximum a method is allowed to run.
        0 means no limit.

  --cntxtimeout=xxxx

        Client Session Timeout in seconds [default 3600]

  --cache-eol=xxxx

        Client cache end of live [default 100000 that is 27,7 hours]

  --sessiondir=xxxx

        Sessions file path [default rootdir/sessions]

  --session-max=xxxx

        Maximum count of simultaneous sessions [default 10]

  --ldpaths=xxxx

        Load Plugins from given paths separated by colons
        as for dir1:dir2:plugin1.so:... [default = $libdir/afb]

        You can mix path to directories and to plugins.
        The sub-directories of the given directories are searched
        recursively.

        The plugins are the files terminated by '.so' (the extension
        so denotes shared object) that contain the public entry symbol.

  --plugin=xxxx

        Load the plugin of given path.

  --token=xxxx

        Initial Secret token to authenticate.

        If not set, no client can authenticate.

        If set to the empty string, then any initial token is accepted.

  --mode=xxxx

        Set the mode: either local, remote or global.

        The mode indicate if the application is run locally on the host
        or remotely through network.

  --readyfd=xxxx

        Set the #fd to signal when ready

        If set, the binder afb-daemon will write "READY=1\n" on the file
        descriptor whose number if given (/proc/self/fd/xxx).

  --dbus-client=xxxx

        Transparent binding to a binder afb-daemon service through dbus.

        It creates an API of name xxxx that is implemented remotely
        and queried via DBUS.

  --dbus-server=xxxx

        Provides a binder afb-daemon service through dbus.

        The name xxxx must be the name of an API defined by a plugin.
        This API is exported through DBUS.

  --foreground

        Get all in foreground mode (default)

  --daemon

        Get all in background mode
</code></pre>

<a name="Future.development.of.afb-daemon"></a>
<h2>Future development of afb-daemon</h2>

<ul>
<li><p>The binder afb-daemon would launch the applications directly.</p></li>
<li><p>The current setting of mode (local/remote/global) might be reworked to a
mechanism for querying configuration variables.</p></li>
<li><p>Implements &ldquo;one-shot&rdquo; initial token. It means that after its first
authenticated use, the initial token is removed and no client can connect
anymore.</p></li>
<li><p>Creates some intrinsic APIs.</p></li>
<li><p>Make the service connection using WebSocket not DBUS.</p></li>
<li><p>Management of targetted events.</p></li>
<li><p>Securisation of LOA.</p></li>
<li><p>Integration of the protocol JSON-RPC for the websockets.</p></li>
</ul>
</body>
</html>