summaryrefslogtreecommitdiffstats
path: root/doc/afm-system-daemon.html
blob: dac4315af3d2e3af04b6bdfec88157b62e54a719 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
<html>
<head>
  <link rel="stylesheet" type="text/css" href="doc.css">
  <meta charset="UTF-8">
</head>
<body>
<a name="The.afm-system-daemon"></a>
<h1>The afm-system-daemon</h1>

<pre><code>version: 1
Date:    15 March 2016
Author:  José Bollo
</code></pre>

<a name="Foreword"></a>
<h2>Foreword</h2>

<p>This document describes what we intend to do. It may happen that our
current implementation and the content of this document differ.</p>

<p>In case of differences, it is assumed that this document is right
and the implementation is wrong.</p>

<a name="Introduction"></a>
<h2>Introduction</h2>

<p>The daemon <strong>afm-system-daemon</strong> is in charge of installing
applications on the system. Its main tasks are:</p>

<ul>
<li><p>installs the applications and setup the security framework
to include it</p></li>
<li><p>uninstall the applications</p></li>
</ul>


<p>The <strong>afm-system-daemon</strong> takes its orders from the system
instance of D-Bus.</p>

<p>The figure below summarizes the situation of the
<strong>afm-system-daemon</strong> in the system.</p>

<pre><code>+------------------------------------------------------------+
|                          User                              |
|                                                            |
|     +-------------------------------------------------+    |
|     |                                                 |    |
|     |                  afm-user-daemon                |    |
|     |                                                 |    |
|     +----------+----------------------+----------+----+    |
|                |                      |          :         |
|                |                      |          :         |
:================|======================|==========:=========:
|                |                      |          :         |
|     +----------+----------+     +-----+-----+    :         |
|     |   D-Bus   system    +-----+  CYNARA   |    :         |
|     +----------+----------+     +-----+-----+    :         |
|                |                      |          :         |
|     +----------+---------+    +-------+----------+----+    |
|     | afm-system-daemon  +----+   SECURITY-MANAGER    |    |
|     +--------------------+    +-----------------------+    |
|                                                            |
|                          System                            |
+------------------------------------------------------------+
</code></pre>

<a name="Starting..strong.afm-system-daemon..strong."></a>
<h2>Starting <strong>afm-system-daemon</strong></h2>

<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>

<p>The options for launching <strong>afm-system-daemon</strong> are:</p>

<pre><code>-r
--root directory

     Set the root application directory.

     Note that the default root directory is defined
     to be /usr/share/afm/applications (may change).

-d
--daemon

     Daemonizes the process. It is not needed by sytemd.

-q
--quiet

     Reduces the verbosity (can be repeated).

-v
--verbose

     Increases the verbosity (can be repeated).

-h
--help

     Prints a short help.
</code></pre>

<a name="The.D-Bus.interface"></a>
<h2>The D-Bus interface</h2>

<a name="Overview.of.the.dbus.interface"></a>
<h3>Overview of the dbus interface</h3>

<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>

<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>

<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>

<p>The client and the service are using JSON serialisation to
exchange data.</p>

<p>The D-Bus interface is defined by:</p>

<ul>
<li><p>DESTINATION: <strong>org.AGL.afm.system</strong></p></li>
<li><p>PATH: <strong>/org/AGL/afm/system</strong></p></li>
<li><p>INTERFACE: <strong>org.AGL.afm.system</strong></p></li>
</ul>


<p>The signature of any member of the interface is <strong><em>string -> string</em></strong>
for <strong><em>JSON -> JSON</em></strong>.</p>

<p>This is the normal case. In case of error, the current implmentation
returns a dbus error that is a string.</p>

<p>Here is an example that use <em>dbus-send</em> to query data on
installed applications.</p>

<pre><code>dbus-send --session --print-reply \
    --dest=org.AGL.afm.system \
    /org/AGL/afm/system \
    org.AGL.afm.system.install 'string:"/tmp/appli.wgt"'
</code></pre>

<a name="The.protocol.over.D-Bus"></a>
<h3>The protocol over D-Bus</h3>

<hr />

<a name="Method.org.AGL.afm.system.install"></a>
<h4>Method org.AGL.afm.system.install</h4>

<p><strong>Description</strong>: Install an application from its widget file.</p>

<p>If an application of the same <em>id</em> and <em>version</em> exists, it is not
reinstalled except if <em>force=true</em>.</p>

<p>Applications are installed in the subdirectories of the common directory
of applications.
If <em>root</em> is specified, the application is installed under the
sub-directories of the <em>root</em> defined.</p>

<p>Note that this methods is a simple accessor to the method
<strong><em>org.AGL.afm.system.install</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p>

<p>After the installation and before returning to the sender,
<strong><em>afm-system-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p>

<p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionaly,
a flag to <em>force</em> reinstallation, and, optionaly, a <em>root</em> directory.</p>

<p>Either just a string being the absolute path of the widget file:</p>

<pre><code>"/a/path/driving/to/the/widget"
</code></pre>

<p>Or an object:</p>

<pre><code>{
  "wgt": "/a/path/to/the/widget",
  "force": false,
  "root": "/a/path/to/the/root"
}
</code></pre>

<p>&ldquo;wgt&rdquo; and &ldquo;root&rdquo; must be absolute paths.</p>

<p><strong>output</strong>: An object with the field &ldquo;added&rdquo; being the string for
the id of the added application.</p>

<pre><code>{"added":"appli@x.y"}
</code></pre>

<hr />

<a name="Method.org.AGL.afm.system.uninstall"></a>
<h4>Method org.AGL.afm.system.uninstall</h4>

<p><strong>Description</strong>: Uninstall an application from its id.</p>

<p>Note that this methods is a simple accessor to the method
<strong><em>org.AGL.afm.system.uninstall</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p>

<p>After the uninstallation and before returning to the sender,
<strong><em>afm-system-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p>

<p><strong>Input</strong>: the <em>id</em> of the application and, otpionaly, the path to
<em>root</em> of the application.</p>

<p>Either a string:</p>

<pre><code>"appli@x.y"
</code></pre>

<p>Or an object:</p>

<pre><code>{
  "id": "appli@x.y",
  "root": "/a/path/to/the/root"
}
</code></pre>

<p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
</body>
</html>