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