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