doc/afm-user-daemon.md

   1
   2 The afm-user-daemon
   3 ===================
   4
   5     version: 1
   6     Date:    30 mai 2016
   7     Author:  José Bollo
   8
   9 TABLE-OF-CONTENT-HERE
  10
  11 Foreword
  12 --------
  13
  14 This document describes application framework user daemon fundamentals.
  15 FCF (Fully Conform to Specification) implementation is still under development.
  16 It may happen that current implementation somehow diverges with specifications.
  17
  18
  19 Introduction
  20 ------------
  21
  22 The daemon **afm-user-daemon** is in charge of handling
  23 applications on behalf of a user. Its main tasks are:
  24
  25  - enumerate applications that end user can run
  26    and keep this list available on demand
  27
  28  - start applications on behalf of end user, set user running
  29    environment, set user security context
  30
  31  - list current runnable or running applications
  32
  33  - stop (aka pause), continue (aka resume), terminate
  34    a running instance of a given application
  35
  36  - transfer requests for installation/uninstallation
  37    of applications to the corresponding system daemon
  38    **afm-system-daemon**
  39
  40 The **afm-user-daemon** takes its orders from the session
  41 instance of D-Bus.
  42
  43 The figure below summarizes the situation of **afm-user-daemon** in the system.
  44
  45     +------------------------------------------------------------+
  46     |                          User                              |
  47     |                                 +---------------------+    |
  48     |     +---------------------+     |   Smack isolated    |    |
  49     |     |   D-Bus   session   +     |    APPLICATIONS     |    |
  50     |     +----------+----------+     +---------+-----------+    |
  51     |                |                          |                |
  52     |                |                          |                |
  53     |     +----------+--------------------------+-----------+    |
  54     |     |                                                 |    |
  55     |     |                  afm-user-daemon                |    |
  56     |     |                                                 |    |
  57     |     +----------+----------------------+----------+----+    |
  58     |                |                      |          :         |
  59     |                |                      |          :         |
  60     :================|======================|==========:=========:
  61     |                |                      |          :         |
  62     |     +----------+----------+     +-----+-----+    :         |
  63     |     |   D-Bus   system    +-----+  CYNARA   |    :         |
  64     |     +----------+----------+     +-----+-----+    :         |
  65     |                |                      |          :         |
  66     |     +----------+---------+    +-------+----------+----+    |
  67     |     | afm-system-daemon  +----+   SECURITY-MANAGER    |    |
  68     |     +--------------------+    +-----------------------+    |
  69     |                                                            |
  70     |                          System                            |
  71     +------------------------------------------------------------+
  72
  73
  74 Tasks of **afm-user-daemon**
  75 ----------------------------
  76
  77 ### Maintaining list of applications ###
  78
  79 At start **afm-user-daemon** scans the directories containing
  80 applications and load in memory a list of avaliable applications
  81 accessible by current user.
  82
  83 When **afm-system-daemon** installs or removes an application.
  84 On success it sends the signal *org.AGL.afm.system.changed*.
  85 When receiving such a signal, **afm-user-daemon** rebuilds its
  86 applications list.
  87
  88 **afm-user-daemon** provides the data it collects about
  89 applications to its clients. Clients may either request the full list
  90 of avaliable applications or a more specific information about a
  91 given application.
  92
  93 ### Launching application ###
  94
  95 **afm-user-daemon** launches application. Its builds a secure
  96 environment for the application before starting it within a
  97 secured environment.
  98
  99 Different kind of applications can be launched.
 100
 101 This is set using a configuration file that describes
 102 how to launch an application of a given kind within a given
 103 mode.
 104
 105 There is two launching modes: local or remote.
 106
 107 Launching an application locally means that
 108 the application and its binder are launched together.
 109
 110 Launching application remotely translates in only launching
 111 the application binder. The UI by itself has to be activated
 112 remotely by the requested (ie: HTML5 homescreen in a browser)
 113
 114 Once launched, running instances of application receive
 115 a runid that identify them.
 116
 117 ### Managing instances of running applications ###
 118
 119 **afm-user-daemon** manages the list of applications
 120 that it launched.
 121
 122 When owning the right permissions, a client can get the list
 123 of running instances and details about a specific
 124 running instance. It can also terminates, stops or
 125 continues a given application.
 126
 127 ### Installing and uninstalling applications ###
 128
 129 If the client own the right permissions,
 130 **afm-user-daemon** delegates that task
 131 to **afm-system-daemon**.
 132
 133
 134 Starting **afm-user-daemon**
 135 -----------------------------
 136
 137 **afm-user-daemon** is launched as a **systemd** service
 138 attached to user sessions. Normally, the service file is
 139 located at /usr/lib/systemd/user/afm-user-daemon.service.
 140
 141 The options for launching **afm-user-daemon** are:
 142
 143     -a
 144     --application directory
 145
 146          Includes the given application directory to
 147          the database base of applications.
 148
 149          Can be repeated.
 150
 151     -r
 152     --root directory
 153
 154          Includes root application directory or directories when
 155          passing multiple rootdir to
 156          applications database.
 157
 158          Note that default root directory for
 159          applications is always added. In current version
 160          /usr/share/afm/applications is used as default.
 161
 162     -m
 163     --mode (local|remote)
 164
 165          Set the default launch mode.
 166          The default value is 'local'
 167
 168     -d
 169     --daemon
 170
 171          Daemonizes the process. It is not needed by sytemd.
 172
 173     -q
 174     --quiet
 175
 176          Reduces the verbosity (can be repeated).
 177
 178     -v
 179     --verbose
 180
 181          Increases the verbosity (can be repeated).
 182
 183     -h
 184     --help
 185
 186          Prints a short help.
 187
 188
 189 Launcher Configuration
 190 -----------------------------
 191
 192 It contains rules for launching applications.
 193 When **afm-user-daemon** has to launch an application,
 194 it looks for launch mode (local or remote), as well as
 195 for the type of application describe in ***config.xml***
 196 widget configuration file.
 197
 198 This tuple mode+type allows to select the adequate rule.
 199
 200 Configuration file is **/etc/afm/afm-launch.conf**.
 201
 202 It contains sections and rules. It can also contain comments
 203 and empty lines to improve readability.
 204
 205 The separators are space and tabulation, any other character
 206 should have a meaning.
 207
 208 The format is line oriented.
 209 The new line character separate the lines.
 210
 211 Lines having only separators are blank lines and ignored.
 212 Line having character #(sharp) at first position are comment
 213 lines and ignored.
 214
 215 Lines not starting with a separator are different
 216 from lines starting with a separator character.
 217
 218 The grammar of the configuration file is defined below:
 219
 220     CONF: *COMMENT *SECTION
 221
 222     SECTION: MODE *RULE
 223
 224     RULE: +TYPE VECTOR ?VECTOR
 225
 226     MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL
 227
 228     TYPE: DATA *SEP EOL
 229
 230     VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL
 231
 232     DATA: CHAR *NCHAR
 233     NDATA: +NCHAR
 234
 235     EOL: NL *COMMENT
 236     COMMENT: *SEP CMT *(SEP | NCHAR) NL
 237
 238     NL: '\x0a'
 239     SEP: '\x20' | '\x09'
 240     CMT: '#'
 241     CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff'
 242     NCHAR: CMT | CHAR
 243
 244 Here is a sample of configuration file for defining how
 245 to launch an application of types *application/x-executable*,
 246 *text/x-shellscript* and *text/html* in local mode:
 247
 248     mode local
 249
 250     application/x-executable
 251     text/x-shellscript
 252         %r/%c
 253
 254     text/html
 255         /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
 256         /usr/bin/web-runtime http://localhost:%P/%c?token=%S
 257
 258 This shows that:
 259
 260  - within a section, several rules can be defined
 261  - within a rule, several types can be defined
 262  - within a rule, one or two vectors can be defined
 263  - vectors are using %substitution
 264  - launched binaries must be defined with their full path
 265
 266 ### mode local
 267
 268 Within this mode, the launchers have either one or two description vectors.
 269 All of those vectors are treated as programs
 270 and are executed with 'execve' system call.
 271
 272 The first vector is the leader vector and it defines the process
 273 group. The second vector (if any) is attached to the group
 274 defined by this first vector.
 275
 276 ### mode remote
 277
 278 Within this mode, the launchers have either one or two vectors
 279 describing them.
 280
 281 The first vector is process as a program and is executed with
 282 system call 'execve'.
 283
 284 The second vector (if any) defines a text that is returned
 285 to the caller. This mechanism can be used to return a uri
 286 for remote UI to connect on the newly launched application.
 287
 288 The daemon ***afm-user-daemon*** allocates a port for each
 289 new remote application.
 290 The current implementation port allocation is incremental.
 291 A smarter (cacheable and discoverable) allocation should be defined.
 292
 293 ### %substitutions
 294
 295 Vectors can include sequences of 2 characters that have a special
 296 meaning. These sequences are named *%substitution* because their
 297 first character is the percent sign (%) and because each occurrence
 298 of the sequence is replaced, at launch time, by the value associated
 299 to sequences.
 300
 301 Here is the list of *%substitutions*:
 302
 303  - ***%%***: %.
 304
 305    This simply emits the percent sign %
 306
 307  - ***%a***: appid
 308
 309    Holds application Id of launched application.
 310
 311    Defined by the attribute **id** of the element **<widget>**
 312    of **config.xml**.
 313
 314  - ***%c***: content
 315
 316    The file within the widget directory that is the entry point.
 317
 318    For HTML applications, it represents the relative path to main
 319    page (aka index.html).
 320
 321    Defined by attribute **src** of the element **<content>** within **config.xml**.
 322
 323  - ***%D***: datadir
 324
 325    Path of the directory where the application runs (cwd)
 326    and stores its data.
 327
 328    It is equal to %h/%a.
 329
 330  - ***%H***: height
 331
 332    Requested height for the widget.
 333
 334    Defined by the attribute **height** of the element **<widget>**
 335    of **config.xml**.
 336
 337  - ***%h***: homedir
 338
 339    Path of the home directory for all applications.
 340
 341    It is generally equal to $HOME/app-data
 342
 343  - ***%I***: icondir
 344
 345    Path of the directory were the icons of the applications can be found.
 346
 347  - ***%m***: mime-type
 348
 349    Mime type of the launched application.
 350
 351    Defined by the attribute **type** of the element **<content>**
 352    of **config.xml**.
 353
 354  - ***%n***: name
 355
 356    Name of the application as defined by the content of the
 357    element **<name>** of **config.xml**.
 358
 359  - ***%p***: plugins
 360
 361    In the future should represent the list of plugins and plugins directory separated by ','.
 362    Warning: not supported in current version.
 363
 364  - ***%P***: port
 365
 366    A port to use. It is currently a kind of random port. The precise
 367    model is to be defined later.
 368
 369  - ***%R***: readyfd
 370
 371    Number of file descriptor to use for signaling
 372    readiness of launched process.
 373
 374  - ***%r***: rootdir
 375
 376    Path of directory containing the widget and its data.
 377
 378  - ***%S***: secret
 379
 380    An hexadecimal number that can be used to initialize pairing of client
 381    and application binder.
 382
 383  - ***%W***: width
 384
 385    Requested width for the widget.
 386
 387    Defined by the attribute **width** of the element **<widget>**
 388    of **config.xml**.
 389
 390
 391 The D-Bus interface
 392 -------------------
 393
 394 ### Overview of the dbus interface
 395
 396 ***afm-user-daemon*** takes its orders from the session instance
 397 of D-Bus. D-Bus is nice to use in this context because it allows
 398 discovery and signaling.
 399
 400 The dbus session is by default addressed by environment
 401 variable ***DBUS_SESSION_BUS_ADDRESS***. Using **systemd**
 402 variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for
 403 user sessions.
 404
 405 The **afm-user-daemon** is listening on destination name
 406 ***org.AGL.afm.user*** at object path ***/org/AGL/afm/user***
 407 on interface ***org.AGL.afm.user*** for following members:
 408  ***runnables***, ***detail***, ***start***, ***terminate***,
 409 ***stop***, ***continue***, ***runners***, ***state***,
 410 ***install*** and ***uninstall***.
 411
 412 D-Bus is mainly used for signaling and discovery. Its optimized
 413 typed protocol is not used except for transmission of standalone strings.
 414
 415 Clients and Services are using JSON serialisation to exchange data.
 416
 417 The D-Bus interface is defined by:
 418
 419  * DESTINATION: **org.AGL.afm.user**
 420
 421  * PATH: **/org/AGL/afm/user**
 422
 423  * INTERFACE: **org.AGL.afm.user**
 424
 425 The signature of any member of the interface is ***string -> string***
 426 for ***JSON -> JSON***.
 427
 428 This is the normal case. In case of error, the current implementation
 429 returns a dbus error as a string.
 430
 431 Here an example using *dbus-send* to query data on
 432 installed applications.
 433
 434     dbus-send --session --print-reply \
 435         --dest=org.AGL.afm.user \
 436         /org/AGL/afm/user \
 437         org.AGL.afm.user.runnables string:true
 438
 439 ### Using ***afm-util***
 440
 441 The command line tool ***afm-util*** uses dbus-send to send
 442 orders to **afm-user-daemon**. This small scripts allows to
 443 send command to ***afm-user-daemon*** either interactively
 444 at shell prompt or scriptically.
 445
 446 The syntax is simple: it accept a command and when requires attached arguments.
 447
 448 Here is the summary of ***afm-util***:
 449
 450  - **afm-util runnables      **:
 451
 452    list the runnable widgets installed
 453
 454  - **afm-util install    wgt **:
 455
 456    install the wgt file
 457
 458  - **afm-util uninstall  id  **:
 459
 460    remove the installed widget of id
 461
 462  - **afm-util detail     id  **:
 463
 464    print detail about the installed widget of id
 465
 466  - **afm-util runners        **:
 467
 468    list the running instance
 469
 470  - **afm-util start      id  **:
 471
 472    start an instance of the widget of id
 473
 474  - **afm-util terminate  rid **:
 475
 476    terminate the running instance rid
 477
 478  - **afm-util stop       rid **:
 479
 480    stop the running instance rid
 481
 482  - **afm-util continue   rid **:
 483
 484    continue the previously rid
 485
 486  - **afm-util state      rid **:
 487
 488    get status of the running instance rid
 489
 490
 491 Here is how to list applications using ***afm-util***:
 492
 493     afm-util runnables
 494
 495 ---
 496
 497 ### The protocol over D-Bus
 498
 499 Recall:
 500
 501  * **DESTINATION**: org.AGL.afm.user
 502
 503  * **PATH**: /org/AGL/afm/user
 504
 505  * **INTERFACE**: org.AGL.afm.user
 506
 507 ---
 508
 509 #### Method org.AGL.afm.user.detail
 510
 511 **Description**: Get details about an application from its id.
 512
 513 **Input**: the id of the application as below.
 514
 515 Either just a string:
 516
 517     "appli@x.y"
 518
 519 Or an object having the field "id" of type string:
 520
 521     {"id":"appli@x.y"}
 522
 523 **Output**: A JSON object describing the application containing
 524 the fields described below.
 525
 526     {
 527       "id":          string, the application id (id@version)
 528       "version":     string, the version of the application
 529       "width":       integer, requested width of the application
 530       "height":      integer, resqueted height of the application
 531       "name":        string, the name of the application
 532       "description": string, the description of the application
 533       "shortname":   string, the short name of the application
 534       "author":      string, the author of the application
 535     }
 536
 537 ---
 538
 539 #### Method org.AGL.afm.user.runnables
 540
 541 **Description**: Get the list of applications that can be run.
 542
 543 **Input**: any valid json entry, can be anything except null.
 544
 545 **output**: An array of description of the runnable applications.
 546 Each item of the array contains an object containing the detail of
 547 an application as described above for the method
 548 *org.AGL.afm.user.detail*.
 549
 550 ---
 551
 552 #### Method org.AGL.afm.user.install
 553
 554 **Description**: Install an application from its widget file.
 555
 556 If an application of the same *id* and *version* exists, it is not
 557 reinstalled except when *force=true*.
 558
 559 Applications are installed in the subdirectories of the common directory
 560 reserved for applications.
 561 If *root* is specified, the application is installed under
 562 sub-directories of defined *root*.
 563
 564 Note that this methods is a simple accessor to the method
 565 ***org.AGL.afm.system.install*** of ***afm-system-daemon***.
 566
 567 After the installation and before returning to the sender,
 568 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
 569
 570 **Input**: The *path* of widget file to be installed. Optionally,
 571 a flag to *force* reinstallation and/or a *root* directory.
 572
 573 Simple form a simple string containing the absolute widget path:
 574
 575     "/a/path/driving/to/the/widget"
 576
 577 Or an object:
 578
 579     {
 580       "wgt": "/a/path/to/the/widget",
 581       "force": false,
 582       "root": "/a/path/to/the/root"
 583     }
 584
 585 "wgt" and "root" MUST be absolute paths.
 586
 587 **output**: An object containing field "added" to use as application ID.
 588
 589     {"added":"appli@x.y"}
 590
 591 ---
 592
 593 #### Method org.AGL.afm.user.uninstall
 594
 595 **Description**: Uninstall an application from its id.
 596
 597
 598 Note that this methods is a simple accessor to
 599 ***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***.
 600
 601 After the uninstallation and before returning to the sender,
 602 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
 603
 604 **Input**: the *id* of the application and, optionally, the path to
 605 application *root*.
 606
 607 Either a string:
 608
 609     "appli@x.y"
 610
 611 Or an object:
 612
 613     {
 614       "id": "appli@x.y",
 615       "root": "/a/path/to/the/root"
 616     }
 617
 618 **output**: the value 'true'.
 619
 620 ---
 621
 622 #### Method org.AGL.afm.user.start
 623
 624 **Description**:
 625
 626 **Input**: the *id* of the application and, optionally, the
 627 start *mode* as below.
 628
 629 Either just a string:
 630
 631     "appli@x.y"
 632
 633 Or an object containing field "id" of type string and
 634 optionally a field mode:
 635
 636     {"id":"appli@x.y","mode":"local"}
 637
 638 The field "mode" is a string equal to either "local" or "remote".
 639
 640 **output**: The *runid* of the application launched. *runid* is an integer.
 641
 642 ---
 643
 644 #### Method org.AGL.afm.user.terminate
 645
 646 **Description**: Terminates the application attached to *runid*.
 647
 648 **Input**: The *runid* (an integer) of running instance to terminate.
 649
 650 **output**: the value 'true'.
 651
 652 ---
 653
 654 #### Method org.AGL.afm.user.stop
 655
 656 **Description**: Stops the application attached to *runid* until terminate or continue.
 657
 658 **Input**: The *runid* (integer) of the running instance to stop.
 659
 660 **output**: the value 'true'.
 661
 662 ---
 663
 664 #### Method org.AGL.afm.user.continue
 665
 666 **Description**: Continues the application attached to *runid* previously stopped.
 667
 668 **Input**: The *runid* (integer) of the running instance to continue.
 669
 670 **output**: the value 'true'.
 671
 672 ---
 673
 674 #### Method org.AGL.afm.user.state
 675
 676 **Description**: Get informations about a running instance of *runid*.
 677
 678 **Input**: The *runid* (integer) of the running instance inspected.
 679
 680 **output**: An object describing instance state. It contains:
 681 the runid (integer), the id of the running application (string),
 682 the state of the application (string either: "starting", "running", "stopped").
 683
 684 Example of returned state:
 685
 686     {
 687       "runid": 2,
 688       "state": "running",
 689       "id": "appli@x.y"
 690     }
 691
 692 ---
 693
 694 #### Method org.AGL.afm.user.runners
 695
 696 **Description**: Get the list of currently running instances.
 697
 698 **Input**: anything.
 699
 700 **output**: An array of states, one per running instance, as returned by
 701 the methodd ***org.AGL.afm.user.state***.
 702