doc/afm-user-daemon.md

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