doc/afm-user-daemon.md

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