old-docs/afb-overview.md

   1
   2 Overview of AFB-DAEMON
   3 ======================
   4
   5 Roles of afb-daemon
   6 -------------------
   7
   8 The name **afb-daemon** stands for *Application
   9 Framework Binder Daemon*. That is why afb-daemon
  10 is also named ***the binder***.
  11
  12 **Afb-daemon** is in charge to bind one instance of
  13 an application to the AGL framework and AGL system.
  14
  15 On the following figure, you can use a typical use
  16 of afb-daemon:
  17
  18 <h4><a id="binder-fig-basis">Figure: binder afb-daemon, basis</a></h4>
  19
  20 ![binder-basis][binder-basis]
  21
  22 The application and its companion binder run in secured and isolated
  23 environment set for them. Applications are intended to access to AGL
  24 system through the binder.
  25
  26 The binder afb-daemon serves multiple purposes:
  27
  28 1. It acts as a gateway for the application to access the system;
  29
  30 2. It acts as an HTTP server for serving files to HTML5 applications;
  31
  32 3. It allows HTML5 applications to have native extensions subject
  33 to security enforcement for accessing hardware resources or
  34 for speeding parts of algorithm.
  35
  36 Use cases of the binder afb-daemon
  37 ----------------------------------
  38
  39 This section tries to give a better understanding of the binder
  40 usage through several use cases.
  41
  42 ### Remotely running application
  43
  44 One of the most interesting aspect of using the binder afb-daemon
  45 is the ability to run applications remotely. This feature is
  46 possible because the binder afb-daemon implements native web
  47 protocols.
  48
  49 So the [figure binder, basis](#binder-fig-basis) would become
  50 when the application is run remotely:
  51
  52 <h4><a id="binder-fig-remote">Figure: binder afb-daemon and remotely running application</a></h4>
  53
  54
  55 ### Adding native features to HTML5/QML applications
  56
  57 Applications can provide with their packaged delivery a binding.
  58 That binding will be instantiated for each application instance.
  59 The methods of the binding will be accessible by applications and
  60 will be executed within the security context.
  61
  62 ### Offering services to the system
  63
  64 It is possible to run the binder afb-daemon as a daemon that provides the
  65 API of its bindings.
  66
  67 This will be used for:
  68
  69 1. offering common APIs
  70
  71 2. provide application's services (services provided as application)
  72
  73 In that case, the figure showing the whole aspects is
  74
  75 <h4><a id="binder-fig-remote">Figure: binder afb-daemon for services</a></h4>
  76
  77 ![afb-for-services][afb-for-services]
  78
  79 For this case, the binder afb-daemon takes care to attribute one single session
  80 context to each client instance. It allows bindings to store and retrieve data
  81 associated to each of its client.
  82
  83 The bindings of the binder afb-daemon
  84 ------------------------------------
  85
  86 The binder can instantiate bindings. The primary use of bindings
  87 is to add native methods that can be accessed by applications
  88 written with any language through web technologies ala JSON RPC.
  89
  90 This simple idea is declined to serves multiple purposes:
  91
  92 1. add native feature to applications
  93
  94 2. add common API available by any applications
  95
  96 3. provide customers services
  97
  98 A specific document explains how to write an afb-daemon binder binding:
  99 [HOWTO WRITE a BINDING for AFB-DAEMON](afb-bindings-writing.html)
 100
 101
 102 Launching the binder afb-daemon
 103 -------------------------------
 104
 105 The launch options for binder **afb-daemon** are:
 106
 107           --help
 108
 109                 Prints help with available options
 110
 111           --version
 112
 113                 Display version and copyright
 114
 115           --verbose
 116
 117                 Increases the verbosity, can be repeated
 118
 119           --quiet
 120
 121                 Decreases the verbosity, can be repeated
 122
 123           --port=xxxx
 124
 125                 HTTP listening TCP port  [default 1234]
 126
 127           --workdir=xxxx
 128
 129                 Directory where the daemon must run [default: $PWD if defined
 130                 or the current working directory]
 131
 132           --uploaddir=xxxx
 133
 134                 Directory where uploaded files are temporarily stored [default: workdir]
 135
 136           --rootdir=xxxx
 137
 138                 Root directory of the application to serve [default: workdir]
 139
 140           --roothttp=xxxx
 141
 142                 Directory of HTTP served files. If not set, files are not served
 143                 but apis are still accessibles.
 144
 145           --rootbase=xxxx
 146
 147                 Angular Base Root URL [default /opa]
 148
 149                 This is used for any application of kind OPA (one page application).
 150                 When set, any missing document whose url has the form /opa/zzz
 151                 is translated to /opa/#!zzz
 152
 153           --rootapi=xxxx
 154
 155                 HTML Root API URL [default /api]
 156
 157                 The bindings are available within that url.
 158
 159           --alias=xxxx
 160
 161                 Maps a path located anywhere in the file system to the
 162                 a subdirectory. The syntax for mapping a PATH to the
 163                 subdirectory NAME is: --alias=/NAME:PATH.
 164
 165                 Example: --alias=/icons:/usr/share/icons maps the
 166                 content of /usr/share/icons within the subpath /icons.
 167
 168                 This option can be repeated.
 169
 170           --no-httpd
 171
 172                 Tells to not start the HTTP server.
 173
 174           --apitimeout=xxxx
 175
 176                 binding API timeout in seconds [default 20]
 177
 178                 Defines how many seconds maximum a method is allowed to run.
 179                 0 means no limit.
 180
 181           --cntxtimeout=xxxx
 182
 183                 Client Session Timeout in seconds [default 3600]
 184
 185           --cache-eol=xxxx
 186
 187                 Client cache end of live [default 100000 that is 27,7 hours]
 188
 189           --session-max=xxxx
 190
 191                 Maximum count of simultaneous sessions [default 10]
 192
 193           --ldpaths=xxxx
 194
 195                 Load bindings from given paths separated by colons
 196                 as for dir1:dir2:binding1.so:... [default = $libdir/afb]
 197
 198                 You can mix path to directories and to bindings.
 199                 The sub-directories of the given directories are searched
 200                 recursively.
 201
 202                 The bindings are the files terminated by '.so' (the extension
 203                 so denotes shared object) that contain the public entry symbol.
 204
 205           --binding=xxxx
 206
 207                 Load the binding of given path.
 208
 209           --token=xxxx
 210
 211                 Initial Secret token to authenticate.
 212
 213                 If not set, no client can authenticate.
 214
 215                 If set to the empty string, then any initial token is accepted.
 216
 217           --random-token
 218
 219                 Generate a random starting token. See option --exec.
 220
 221           --mode=xxxx
 222
 223                 Set the mode: either local, remote or global.
 224
 225                 The mode indicate if the application is run locally on the host
 226                 or remotely through network.
 227
 228           --readyfd=xxxx
 229
 230                 Set the #fd to signal when ready
 231
 232                 If set, the binder afb-daemon will write "READY=1\n" on the file
 233                 descriptor whose number if given (/proc/self/fd/xxx).
 234
 235           --dbus-client=xxxx
 236
 237                 Transparent binding to a binder afb-daemon service through dbus.
 238
 239                 It creates an API of name xxxx that is implemented remotely
 240                 and queried via DBUS.
 241
 242           --dbus-server=xxxx
 243
 244                 Provides a binder afb-daemon service through dbus.
 245
 246                 The name xxxx must be the name of an API defined by a binding.
 247                 This API is exported through DBUS.
 248
 249           --ws-client=xxxx
 250
 251                 Transparent binding to a binder afb-daemon service through a WebSocket.
 252
 253                 The value of xxxx is either a unix naming socket, of the form "unix:path/api",
 254                 or an internet socket, of the form "host:port/api".
 255
 256           --ws-server=xxxx
 257
 258                 Provides a binder afb-daemon service through WebSocket.
 259
 260                 The value of xxxx is either a unix naming socket, of the form "unix:path/api",
 261                 or an internet socket, of the form "host:port/api".
 262
 263           --foreground
 264
 265                 Get all in foreground mode (default)
 266
 267           --daemon
 268
 269                 Get all in background mode
 270
 271           --no-httpd
 272
 273                 Forbids HTTP serve
 274
 275           --exec
 276
 277                 Must be the last option for afb-daemon. The remaining
 278                 arguments define a command that afb-daemon will launch.
 279                 The sequences @p, @t and @@ of the arguments are replaced
 280                 with the port, the token and @.
 281
 282           --tracereq=xxxx
 283
 284                 Trace the processing of requests in the log file.
 285
 286                 Valid values are 'no' (default), 'common', 'extra' or 'all'.
 287
 288
 289
 290
 291
 292 Future development of afb-daemon
 293 --------------------------------
 294
 295 - The binder afb-daemon would launch the applications directly.
 296
 297 - The current setting of mode (local/remote/global) might be reworked to a
 298 mechanism for querying configuration variables.
 299
 300 - Implements "one-shot" initial token. It means that after its first
 301 authenticated use, the initial token is removed and no client can connect
 302 anymore.
 303
 304 - Creates some intrinsic APIs.
 305
 306 - Make the service connection using WebSocket not DBUS.
 307
 308 - Management of targeted events.
 309
 310 - Securing LOA.
 311
 312 - Integration of the protocol JSON-RPC for the websockets.
 313
 314 [binder-basis]: pictures/AFB_overview.svg
 315 [afb-for-services]: pictures/AFB_for_services.svg