doc/afm-system-daemon.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="doc.css">
   4   <meta charset="UTF-8">
   5 </head>
   6 <body>
   7 <a name="The.afm-system-daemon"></a>
   8 <h1>The afm-system-daemon</h1>
   9
  10 <pre><code>version: 1
  11 Date:    30 mai 2016
  12 Author:  José Bollo
  13 </code></pre>
  14
  15 <p><ul>
  16  <li><a href="#The.afm-system-daemon">The afm-system-daemon</a>
  17  <ul>
  18   <li><a href="#Foreword">Foreword</a></li>
  19   <li><a href="#Introduction">Introduction</a></li>
  20   <li><a href="#Starting..strong.afm-system-daemon..strong.">Starting <strong>afm-system-daemon</strong></a></li>
  21   <li><a href="#The.D-Bus.interface">The D-Bus interface</a>
  22   <ul>
  23    <li><a href="#Overview.of.the.dbus.interface">Overview of the dbus interface</a></li>
  24    <li><a href="#The.protocol.over.D-Bus">The protocol over D-Bus</a>
  25    <ul>
  26     <li><a href="#Method.org.AGL.afm.system.install">Method org.AGL.afm.system.install</a></li>
  27     <li><a href="#Method.org.AGL.afm.system.uninstall">Method org.AGL.afm.system.uninstall</a></li>
  28    </ul>
  29    </li>
  30   </ul>
  31   </li>
  32  </ul>
  33  </li>
  34 </ul></p>
  35
  36 <a name="Foreword"></a>
  37 <h2>Foreword</h2>
  38
  39 <p>This document describes application framework system daemon fundamentals.
  40 FCF (Fully Conform to Specification) implementation is still under development.
  41 It may happen that current implementation somehow diverges with specifications.</p>
  42
  43 <a name="Introduction"></a>
  44 <h2>Introduction</h2>
  45
  46 <p>The daemon <strong>afm-system-daemon</strong> is in charge of installing
  47 applications on AGL system. Its main tasks are:</p>
  48
  49 <ul>
  50 <li><p>installs applications and setup security framework
  51 for newly installed application.</p></li>
  52 <li><p>uninstall applications</p></li>
  53 </ul>
  54
  55
  56 <p>The <strong>afm-system-daemon</strong> takes its orders from system
  57 instance of D-Bus.</p>
  58
  59 <p>The figure below summarizes the situation of <strong>afm-system-daemon</strong> in the system.</p>
  60
  61 <pre><code>+------------------------------------------------------------+
  62 |                          User                              |
  63 |                                                            |
  64 |     +-------------------------------------------------+    |
  65 |     |                                                 |    |
  66 |     |                  afm-user-daemon                |    |
  67 |     |                                                 |    |
  68 |     +----------+----------------------+----------+----+    |
  69 |                |                      |          :         |
  70 |                |                      |          :         |
  71 :================|======================|==========:=========:
  72 |                |                      |          :         |
  73 |     +----------+----------+     +-----+-----+    :         |
  74 |     |   D-Bus   system    +-----+  CYNARA   |    :         |
  75 |     +----------+----------+     +-----+-----+    :         |
  76 |                |                      |          :         |
  77 |     +----------+---------+    +-------+----------+----+    |
  78 |     | afm-system-daemon  +----+   SECURITY-MANAGER    |    |
  79 |     +--------------------+    +-----------------------+    |
  80 |                                                            |
  81 |                          System                            |
  82 +------------------------------------------------------------+
  83 </code></pre>
  84
  85 <a name="Starting..strong.afm-system-daemon..strong."></a>
  86 <h2>Starting <strong>afm-system-daemon</strong></h2>
  87
  88 <p><strong>afm-system-daemon</strong> is launched as a <strong>systemd</strong> service
  89 attached to system. Normally, the service file is
  90 located at /lib/systemd/system/afm-system-daemon.service.</p>
  91
  92 <p>The options for launching <strong>afm-system-daemon</strong> are:</p>
  93
  94 <pre><code>-r
  95 --root directory
  96
  97  Set the root application directory.
  98
  99  Note that the default root directory is defined
 100  to be /usr/share/afm/applications (may change).
 101
 102 -d
 103 --daemon
 104
 105  Daemonizes the process. It is not needed by sytemd.
 106
 107 -q
 108 --quiet
 109
 110  Reduces the verbosity (can be repeated).
 111
 112 -v
 113 --verbose
 114
 115  Increases the verbosity (can be repeated).
 116
 117 -h
 118 --help
 119
 120  Prints a short help.
 121 </code></pre>
 122
 123 <a name="The.D-Bus.interface"></a>
 124 <h2>The D-Bus interface</h2>
 125
 126 <a name="Overview.of.the.dbus.interface"></a>
 127 <h3>Overview of the dbus interface</h3>
 128
 129 <p><strong><em>afm-system-daemon</em></strong> takes its orders from the session instance
 130 of D-Bus. The use of D-Bus is great because it allows to implement
 131 discovery and signaling.</p>
 132
 133 <p>The <strong>afm-system-daemon</strong> is listening with the destination name
 134 <strong><em>org.AGL.afm.system</em></strong> at the object of path <strong><em>/org/AGL/afm/system</em></strong>
 135 on the interface <strong><em>org.AGL.afm.system</em></strong> for the below detailed
 136 members <strong><em>install</em></strong> and <strong><em>uninstall</em></strong>.</p>
 137
 138 <p>D-Bus is mainly used for signaling and discovery. Its optimized
 139 typed protocol is not used except for transmitting only one string
 140 in both directions.</p>
 141
 142 <p>The client and the service are using JSON serialization to
 143 exchange data.</p>
 144
 145 <p>The D-Bus interface is defined by:</p>
 146
 147 <ul>
 148 <li><p>DESTINATION: <strong>org.AGL.afm.system</strong></p></li>
 149 <li><p>PATH: <strong>/org/AGL/afm/system</strong></p></li>
 150 <li><p>INTERFACE: <strong>org.AGL.afm.system</strong></p></li>
 151 </ul>
 152
 153
 154 <p>The signature of any member of the interface is <strong><em>string -> string</em></strong>
 155 for <strong><em>JSON -> JSON</em></strong>.</p>
 156
 157 <p>This is the normal case. In case of error, the current implementation
 158 returns a dbus error that is a string.</p>
 159
 160 <p>Here is an example using <em>dbus-send</em> to query data on
 161 installed applications.</p>
 162
 163 <pre><code>dbus-send --session --print-reply \
 164 --dest=org.AGL.afm.system \
 165 /org/AGL/afm/system \
 166 org.AGL.afm.system.install 'string:"/tmp/appli.wgt"'
 167 </code></pre>
 168
 169 <a name="The.protocol.over.D-Bus"></a>
 170 <h3>The protocol over D-Bus</h3>
 171
 172 <hr />
 173
 174 <a name="Method.org.AGL.afm.system.install"></a>
 175 <h4>Method org.AGL.afm.system.install</h4>
 176
 177 <p><strong>Description</strong>: Install an application from a widget file.</p>
 178
 179 <p>When an application with the same <em>id</em> and <em>version</em> already exists. Outside of
 180 using <em>force=true</em> the application is not reinstalled.</p>
 181
 182 <p>Applications are installed the subdirectories of applications common directory.
 183 If <em>root</em> is specified, the application is installed under the
 184 sub-directories of the <em>root</em> defined.</p>
 185
 186 <p>Note that this methods is a simple accessor method of
 187 <strong><em>org.AGL.afm.system.install</em></strong> from <strong><em>afm-system-daemon</em></strong>.</p>
 188
 189 <p>After the installation and before returning to the sender,
 190 <strong><em>afm-system-daemon</em></strong> sends a signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p>
 191
 192 <p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionally,
 193 a flag to <em>force</em> reinstallation, and, optionally, a <em>root</em> directory.</p>
 194
 195 <p>Either just a string being the absolute path of the widget file:</p>
 196
 197 <pre><code>"/a/path/driving/to/the/widget"
 198 </code></pre>
 199
 200 <p>Or an object:</p>
 201
 202 <pre><code>{
 203   "wgt": "/a/path/to/the/widget",
 204   "force": false,
 205   "root": "/a/path/to/the/root"
 206 }
 207 </code></pre>
 208
 209 <p>&ldquo;wgt&rdquo; and &ldquo;root&rdquo; must be absolute paths.</p>
 210
 211 <p><strong>output</strong>: An object with the field &ldquo;added&rdquo; being the string for
 212 the id of the added application.</p>
 213
 214 <pre><code>{"added":"appli@x.y"}
 215 </code></pre>
 216
 217 <hr />
 218
 219 <a name="Method.org.AGL.afm.system.uninstall"></a>
 220 <h4>Method org.AGL.afm.system.uninstall</h4>
 221
 222 <p><strong>Description</strong>: Uninstall an application from its id.</p>
 223
 224 <p>Note that this methods is a simple method accessor of
 225 <strong><em>org.AGL.afm.system.uninstall</em></strong> from <strong><em>afm-system-daemon</em></strong>.</p>
 226
 227 <p>After the uninstallation and before returning to the sender,
 228 <strong><em>afm-system-daemon</em></strong> sends a signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p>
 229
 230 <p><strong>Input</strong>: the <em>id</em> of the application and optionally the application <em>root</em> path.</p>
 231
 232 <p>Either a string:</p>
 233
 234 <pre><code>"appli@x.y"
 235 </code></pre>
 236
 237 <p>Or an object:</p>
 238
 239 <pre><code>{
 240   "id": "appli@x.y",
 241   "root": "/a/path/to/the/root"
 242 }
 243 </code></pre>
 244
 245 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 246 </body>
 247 </html>