doc/afm-user-daemon.md

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