doc/afm-system-daemon.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta charset="utf-8">
   5   <meta name="generator" content="pandoc">
   6   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
   7   <meta name="author" content="José Bollo">
   8   <meta name="author" content="Fulup Ar Foll">
   9   <title>The afm-system-daemon</title>
  10   <style type="text/css">code{white-space: pre;}</style>
  11   <!--[if lt IE 9]>
  12     <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
  13   <![endif]-->
  14   <link rel="stylesheet" href="doc.css">
  15 </head>
  16 <body>
  17 <header>
  18 <h1 class="title">The afm-system-daemon</h1>
  19 <h2 class="author">José Bollo</h2>
  20 <h2 class="author">Fulup Ar Foll</h2>
  21 <h3 class="date">30 mai 2016</h3>
  22 </header>
  23 <nav id="TOC">
  24 <ul>
  25 <li><a href="#the-afm-system-daemon">The afm-system-daemon</a><ul>
  26 <li><a href="#foreword">Foreword</a></li>
  27 <li><a href="#introduction">Introduction</a></li>
  28 <li><a href="#starting-afm-system-daemon">Starting <strong>afm-system-daemon</strong></a></li>
  29 <li><a href="#the-d-bus-interface">The D-Bus interface</a><ul>
  30 <li><a href="#overview-of-the-dbus-interface">Overview of the dbus interface</a></li>
  31 <li><a href="#the-protocol-over-d-bus">The protocol over D-Bus</a></li>
  32 </ul></li>
  33 </ul></li>
  34 </ul>
  35 </nav>
  36 <h1 id="the-afm-system-daemon">The afm-system-daemon</h1>
  37 <pre><code>version: 1
  38 Date:    30 mai 2016
  39 Author:  José Bollo</code></pre>
  40 <p>TABLE-OF-CONTENT-HERE</p>
  41 <h2 id="foreword">Foreword</h2>
  42 <p>This document describes application framework system daemon fundamentals. FCF (Fully Conform to Specification) implementation is still under development. It may happen that current implementation somehow diverges with specifications.</p>
  43 <h2 id="introduction">Introduction</h2>
  44 <p>The daemon <strong>afm-system-daemon</strong> is in charge of installing applications on AGL system. Its main tasks are:</p>
  45 <ul>
  46 <li><p>installs applications and setup security framework for newly installed application.</p></li>
  47 <li><p>uninstall applications</p></li>
  48 </ul>
  49 <p>The <strong>afm-system-daemon</strong> takes its orders from system instance of D-Bus.</p>
  50 <p>The figure below summarizes the situation of <strong>afm-system-daemon</strong> in the system.</p>
  51 <pre><code>+------------------------------------------------------------+
  52 |                          User                              |
  53 |                                                            |
  54 |     +-------------------------------------------------+    |
  55 |     |                                                 |    |
  56 |     |                  afm-user-daemon                |    |
  57 |     |                                                 |    |
  58 |     +----------+----------------------+----------+----+    |
  59 |                |                      |          :         |
  60 |                |                      |          :         |
  61 :================|======================|==========:=========:
  62 |                |                      |          :         |
  63 |     +----------+----------+     +-----+-----+    :         |
  64 |     |   D-Bus   system    +-----+  CYNARA   |    :         |
  65 |     +----------+----------+     +-----+-----+    :         |
  66 |                |                      |          :         |
  67 |     +----------+---------+    +-------+----------+----+    |
  68 |     | afm-system-daemon  +----+   SECURITY-MANAGER    |    |
  69 |     +--------------------+    +-----------------------+    |
  70 |                                                            |
  71 |                          System                            |
  72 +------------------------------------------------------------+</code></pre>
  73 <h2 id="starting-afm-system-daemon">Starting <strong>afm-system-daemon</strong></h2>
  74 <p><strong>afm-system-daemon</strong> is launched as a <strong>systemd</strong> service attached to system. Normally, the service file is located at /lib/systemd/system/afm-system-daemon.service.</p>
  75 <p>The options for launching <strong>afm-system-daemon</strong> are:</p>
  76 <pre><code>-r
  77 --root directory
  78
  79      Set the root application directory.
  80
  81      Note that the default root directory is defined
  82      to be /usr/share/afm/applications (may change).
  83
  84 -d
  85 --daemon
  86
  87      Daemonizes the process. It is not needed by sytemd.
  88
  89 -q
  90 --quiet
  91
  92      Reduces the verbosity (can be repeated).
  93
  94 -v
  95 --verbose
  96
  97      Increases the verbosity (can be repeated).
  98
  99 -h
 100 --help
 101
 102      Prints a short help.</code></pre>
 103 <h2 id="the-d-bus-interface">The D-Bus interface</h2>
 104 <h3 id="overview-of-the-dbus-interface">Overview of the dbus interface</h3>
 105 <p><strong><em>afm-system-daemon</em></strong> takes its orders from the session instance of D-Bus. The use of D-Bus is great because it allows to implement discovery and signaling.</p>
 106 <p>The <strong>afm-system-daemon</strong> is listening with the destination name <strong><em>org.AGL.afm.system</em></strong> at the object of path <strong><em>/org/AGL/afm/system</em></strong> on the interface <strong><em>org.AGL.afm.system</em></strong> for the below detailed members <strong><em>install</em></strong> and <strong><em>uninstall</em></strong>.</p>
 107 <p>D-Bus is mainly used for signaling and discovery. Its optimized typed protocol is not used except for transmitting only one string in both directions.</p>
 108 <p>The client and the service are using JSON serialization to exchange data.</p>
 109 <p>The D-Bus interface is defined by:</p>
 110 <ul>
 111 <li><p>DESTINATION: <strong>org.AGL.afm.system</strong></p></li>
 112 <li><p>PATH: <strong>/org/AGL/afm/system</strong></p></li>
 113 <li><p>INTERFACE: <strong>org.AGL.afm.system</strong></p></li>
 114 </ul>
 115 <p>The signature of any member of the interface is <strong><em>string -&gt; string</em></strong> for <strong><em>JSON -&gt; JSON</em></strong>.</p>
 116 <p>This is the normal case. In case of error, the current implementation returns a dbus error that is a string.</p>
 117 <p>Here is an example using <em>dbus-send</em> to query data on installed applications.</p>
 118 <pre><code>dbus-send --session --print-reply \
 119     --dest=org.AGL.afm.system \
 120     /org/AGL/afm/system \
 121     org.AGL.afm.system.install &#39;string:&quot;/tmp/appli.wgt&quot;&#39;</code></pre>
 122 <h3 id="the-protocol-over-d-bus">The protocol over D-Bus</h3>
 123 <hr />
 124 <h4 id="method-org.agl.afm.system.install">Method org.AGL.afm.system.install</h4>
 125 <p><strong>Description</strong>: Install an application from a widget file.</p>
 126 <p>When an application with the same <em>id</em> and <em>version</em> already exists. Outside of using <em>force=true</em> the application is not reinstalled.</p>
 127 <p>Applications are installed the subdirectories of applications common directory. If <em>root</em> is specified, the application is installed under the sub-directories of the <em>root</em> defined.</p>
 128 <p>Note that this methods is a simple accessor method of <strong><em>org.AGL.afm.system.install</em></strong> from <strong><em>afm-system-daemon</em></strong>.</p>
 129 <p>After the installation and before returning to the sender, <strong><em>afm-system-daemon</em></strong> sends a signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p>
 130 <p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionally, a flag to <em>force</em> reinstallation, and, optionally, a <em>root</em> directory.</p>
 131 <p>Either just a string being the absolute path of the widget file:</p>
 132 <pre><code>&quot;/a/path/driving/to/the/widget&quot;</code></pre>
 133 <p>Or an object:</p>
 134 <pre><code>{
 135   &quot;wgt&quot;: &quot;/a/path/to/the/widget&quot;,
 136   &quot;force&quot;: false,
 137   &quot;root&quot;: &quot;/a/path/to/the/root&quot;
 138 }</code></pre>
 139 <p>&quot;wgt&quot; and &quot;root&quot; must be absolute paths.</p>
 140 <p><strong>output</strong>: An object with the field &quot;added&quot; being the string for the id of the added application.</p>
 141 <pre><code>{&quot;added&quot;:&quot;appli@x.y&quot;}</code></pre>
 142 <hr />
 143 <h4 id="method-org.agl.afm.system.uninstall">Method org.AGL.afm.system.uninstall</h4>
 144 <p><strong>Description</strong>: Uninstall an application from its id.</p>
 145 <p>Note that this methods is a simple method accessor of <strong><em>org.AGL.afm.system.uninstall</em></strong> from <strong><em>afm-system-daemon</em></strong>.</p>
 146 <p>After the uninstallation and before returning to the sender, <strong><em>afm-system-daemon</em></strong> sends a signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p>
 147 <p><strong>Input</strong>: the <em>id</em> of the application and optionally the application <em>root</em> path.</p>
 148 <p>Either a string:</p>
 149 <pre><code>&quot;appli@x.y&quot;</code></pre>
 150 <p>Or an object:</p>
 151 <pre><code>{
 152   &quot;id&quot;: &quot;appli@x.y&quot;,
 153   &quot;root&quot;: &quot;/a/path/to/the/root&quot;
 154 }</code></pre>
 155 <p><strong>output</strong>: the value 'true'.</p>
 156 </body>
 157 </html>