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.
16 The daemon **afm-user-daemon** is in charge of handling
17 applications on behalf of a user. Its main tasks are:
19 - enumerate applications that end user can run
20 and keep this list available on demand
22 - start applications on behalf of end user, set user running
23 environment, set user security context
25 - list current runnable or running applications
27 - pause, resume, terminate a running instance of a given application
29 - transfer requests for installation/uninstallation
30 of applications to the corresponding system daemon
33 The **afm-user-daemon** takes its orders from the session
36 The figure below summarizes the situation of **afm-user-daemon** in the system.
38 +------------------------------------------------------------+
40 | +---------------------+ |
41 | +---------------------+ | Smack isolated | |
42 | | D-Bus session + | APPLICATIONS | |
43 | +----------+----------+ +---------+-----------+ |
46 | +----------+--------------------------+-----------+ |
48 | | afm-user-daemon | |
50 | +----------+----------------------+----------+----+ |
53 :================|======================|==========:=========:
55 | +----------+----------+ +-----+-----+ : |
56 | | D-Bus system +-----+ CYNARA | : |
57 | +----------+----------+ +-----+-----+ : |
59 | +----------+---------+ +-------+----------+----+ |
60 | | afm-system-daemon +----+ SECURITY-MANAGER | |
61 | +--------------------+ +-----------------------+ |
64 +------------------------------------------------------------+
67 Tasks of **afm-user-daemon**
68 ----------------------------
70 ### Maintaining list of applications ###
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.
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
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
86 ### Launching application ###
88 **afm-user-daemon** launches application. Its builds a secure
89 environment for the application before starting it within a
92 Different kind of applications can be launched.
94 This is set using a configuration file that describes
95 how to launch an application of a given kind within a given
98 There is two launching modes: local or remote.
100 Launching an application locally means that
101 the application and its binder are launched together.
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)
107 Once launched, running instances of application receive
108 a runid that identify them.
110 ### Managing instances of running applications ###
112 **afm-user-daemon** manages the list of applications
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.
120 ### Installing and uninstalling applications ###
122 If the client own the right permissions,
123 **afm-user-daemon** delegates that task
124 to **afm-system-daemon**.
127 Starting **afm-user-daemon**
128 -----------------------------
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.
134 The options for launching **afm-user-daemon** are:
137 --application directory
139 Includes the given application directory to
140 the database base of applications.
147 Includes root application directory or directories when
148 passing multiple rootdir to
149 applications database.
151 Note that default root directory for
152 applications is always added. In current version
153 /usr/share/afm/applications is used as default.
156 --mode (local|remote)
158 Set the default launch mode.
159 The default value is 'local'
164 Daemonizes the process. It is not needed by sytemd.
169 Reduces the verbosity (can be repeated).
174 Increases the verbosity (can be repeated).
182 Launcher Configuration
183 -----------------------------
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.
191 This tuple mode+type allows to select the adequate rule.
193 Configuration file is **/etc/afm/afm-launch.conf**.
195 It contains sections and rules. It can also contain comments
196 and empty lines to improve readability.
198 The separators are space and tabulation, any other character
199 should have a meaning.
201 The format is line oriented.
202 The new line character separate the lines.
204 Lines having only separators are blank lines and ignored.
205 Line having character #(sharp) at first position are comment
208 Lines not starting with a separator are different
209 from lines starting with a separator character.
211 The grammar of the configuration file is defined below:
213 CONF: *COMMENT *SECTION
217 RULE: +TYPE VECTOR ?VECTOR
219 MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL
223 VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL
229 COMMENT: *SEP CMT *(SEP | NCHAR) NL
234 CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff'
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:
243 application/x-executable
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
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
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.
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.
271 Within this mode, the launchers have either one or two vectors
274 The first vector is process as a program and is executed with
275 system call 'execve'.
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.
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.
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
294 Here is the list of *%substitutions*:
298 This simply emits the percent sign %
302 Holds application Id of launched application.
304 Defined by the attribute **id** of the element **<widget>**
309 In the future should represent the list of bindings and bindings directory separated by ','.
310 Warning: not supported in current version.
314 The file within the widget directory that is the entry point.
316 For HTML applications, it represents the relative path to main
317 page (aka index.html).
319 Defined by attribute **src** of the element **<content>** within **config.xml**.
323 Path of the directory where the application runs (cwd)
326 It is equal to %h/%a.
330 Requested height for the widget.
332 Defined by the attribute **height** of the element **<widget>**
337 Path of the home directory for all applications.
339 It is generally equal to $HOME/app-data
343 Path of the directory were the icons of the applications can be found.
345 - ***%m***: mime-type
347 Mime type of the launched application.
349 Defined by the attribute **type** of the element **<content>**
354 Name of the application as defined by the content of the
355 element **<name>** of **config.xml**.
359 A port to use. It is currently a kind of random port. The precise
360 model is to be defined later.
364 Number of file descriptor to use for signaling
365 readiness of launched process.
369 Path of directory containing the widget and its data.
373 An hexadecimal number that can be used to initialize pairing of client
374 and application binder.
378 Requested width for the widget.
380 Defined by the attribute **width** of the element **<widget>**
387 ### Overview of the dbus interface
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.
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
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***.
405 D-Bus is mainly used for signaling and discovery. Its optimized
406 typed protocol is not used except for transmission of standalone strings.
408 Clients and Services are using JSON serialisation to exchange data.
410 The D-Bus interface is defined by:
412 * DESTINATION: **org.AGL.afm.user**
414 * PATH: **/org/AGL/afm/user**
416 * INTERFACE: **org.AGL.afm.user**
418 The signature of any member of the interface is ***string -> string***
419 for ***JSON -> JSON***.
421 This is the normal case. In case of error, the current implementation
422 returns a dbus error as a string.
424 Here an example using *dbus-send* to query data on
425 installed applications.
427 dbus-send --session --print-reply \
428 --dest=org.AGL.afm.user \
430 org.AGL.afm.user.runnables string:true
432 ### Using ***afm-util***
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.
439 The syntax is simple: it accept a command and when requires attached arguments.
441 Here is the summary of ***afm-util***:
443 - **afm-util runnables **:
445 list the runnable widgets installed
447 - **afm-util install wgt **:
451 - **afm-util uninstall id **:
453 remove the installed widget of id
455 - **afm-util detail id **:
457 print detail about the installed widget of id
459 - **afm-util runners **:
461 list the running instance
463 - **afm-util start id **:
465 start an instance of the widget of id
467 - **afm-util once id **:
469 run once an instance of the widget of id
471 - **afm-util terminate rid **:
473 terminate the running instance rid
475 - **afm-util pause rid **:
477 pause the running instance rid
479 - **afm-util resume rid **:
481 resume the previously paused rid
483 - **afm-util state rid **:
485 get status of the running instance rid
488 Here is how to list applications using ***afm-util***:
494 ### The protocol over D-Bus
498 * **DESTINATION**: org.AGL.afm.user
500 * **PATH**: /org/AGL/afm/user
502 * **INTERFACE**: org.AGL.afm.user
506 #### Method org.AGL.afm.user.detail
508 **Description**: Get details about an application from its id.
510 **Input**: the id of the application as below.
512 Either just a string:
516 Or an object having the field "id" of type string:
520 **Output**: A JSON object describing the application containing
521 the fields described below.
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
536 #### Method org.AGL.afm.user.runnables
538 **Description**: Get the list of applications that can be run.
540 **Input**: any valid json entry, can be anything except null.
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*.
549 #### Method org.AGL.afm.user.install
551 **Description**: Install an application from its widget file.
553 If an application of the same *id* and *version* exists, it is not
554 reinstalled except when *force=true*.
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*.
561 Note that this methods is a simple accessor to the method
562 ***org.AGL.afm.system.install*** of ***afm-system-daemon***.
564 After the installation and before returning to the sender,
565 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
567 **Input**: The *path* of widget file to be installed. Optionally,
568 a flag to *force* reinstallation and/or a *root* directory.
570 Simple form a simple string containing the absolute widget path:
572 "/a/path/driving/to/the/widget"
577 "wgt": "/a/path/to/the/widget",
579 "root": "/a/path/to/the/root"
582 "wgt" and "root" MUST be absolute paths.
584 **output**: An object containing field "added" to use as application ID.
586 {"added":"appli@x.y"}
590 #### Method org.AGL.afm.user.uninstall
592 **Description**: Uninstall an application from its id.
595 Note that this methods is a simple accessor to
596 ***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***.
598 After the uninstallation and before returning to the sender,
599 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
601 **Input**: the *id* of the application and, optionally, the path to
612 "root": "/a/path/to/the/root"
615 **output**: the value 'true'.
619 #### Method org.AGL.afm.user.start
623 **Input**: the *id* of the application and, optionally, the
624 start *mode* as below.
626 Either just a string:
630 Or an object containing field "id" of type string and
631 optionally a field mode:
633 {"id":"appli@x.y","mode":"local"}
635 The field "mode" is a string equal to either "local" or "remote".
637 **output**: The *runid* of the application launched. *runid* is an integer.
641 #### Method org.AGL.afm.user.once
645 **Input**: the *id* of the application
647 Either just a string:
651 Or an object containing field "id" of type string.
655 **output**: The *state* of the application retrieved or launched.
656 See *org.AGL.afm.user.state* to get a description of the returned
661 #### Method org.AGL.afm.user.terminate
663 **Description**: Terminates the application attached to *runid*.
665 **Input**: The *runid* (an integer) of running instance to terminate.
667 **output**: the value 'true'.
671 #### Method org.AGL.afm.user.stop
673 Obsolete since 8th November 2016 (2016/11/08).
674 Kept for compatibility.
676 Use **org.AGL.afm.user.pause** instead.
680 #### Method org.AGL.afm.user.continue
682 Obsolete since 8th November 2016 (2016/11/08).
683 Kept for compatibility.
685 Use **org.AGL.afm.user.resume** instead.
689 #### Method org.AGL.afm.user.pause
691 **Description**: Pauses the application attached to *runid* until terminate or resume.
693 **Input**: The *runid* (integer) of the running instance to pause.
695 **output**: the value 'true'.
699 #### Method org.AGL.afm.user.resume
701 **Description**: Resumes the application attached to *runid* previously paused.
703 **Input**: The *runid* (integer) of the running instance to resume.
705 **output**: the value 'true'.
709 #### Method org.AGL.afm.user.state
711 **Description**: Get informations about a running instance of *runid*.
713 **Input**: The *runid* (integer) of the running instance inspected.
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").
720 Example of returned state:
724 "pids": [ 435, 436 ],
731 #### Method org.AGL.afm.user.runners
733 **Description**: Get the list of currently running instances.
737 **output**: An array of states, one per running instance, as returned by
738 the methodd ***org.AGL.afm.user.state***.