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
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
/****************************************************************************
**
** Copyright (C) 2018 Pelagicore AG
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Pelagicore Application Manager.
**
** $QT_BEGIN_LICENSE:FDL-QTAS$
** Commercial License Usage
** Licensees holding valid commercial Qt Automotive Suite licenses may use
** this file in accordance with the commercial license agreement provided
** with the Software or, alternatively, in accordance with the terms
** contained in a written agreement between you and The Qt Company. For
** licensing terms and conditions see https://www.qt.io/terms-conditions.
** For further information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page containers.html
\title Containers
A \b container in the application-manager world describes an execution environment for an
executable (either an app's binary or its runtime binary) in multi-process mode. This does not have
to be something sophisticated like a Docker container, but can be as simple as an Unix process.
\section1 Predefined Containers
The application-manager comes with a single type of container built-in: the \c process container,
which simply spawns a new Unix process to execute the requested binary.
In addition, a very basic integration of Pelagicore's
\l{https://github.com/Pelagicore/softwarecontainer}{software-containers} is provided in \c
examples/softwarecontainers. This can be used as a blueprint to either create a customer-specific
production version of a softwarecontainers plugin, or to integrate another container solution.
\section1 Extending with Container Plugins
Custom container solution can easily be added via plugins.
These plugins need not to be built as part of the application-manager, but
they need to be built against a private Qt module to get the interface
definition:
\badcode
TEMPLATE = lib
CONFIG += plugin
TARGET = mycontainer-plugin
QT = appman_plugininterfaces-private
\endcode
The only thing you have to then implement are two classes that derive from \c ContainerInterface
and from ContainerManagerInterface respectively, e.g.:
\code
#include <QtAppManPluginInterfaces/containerinterface.h>
class SoftwareContainer : public ContainerInterface
{
// ...
};
class SoftwareContainerManager : public QObject, public ContainerManagerInterface
{
Q_OBJECT
Q_PLUGIN_METADATA(IID AM_ContainerManagerInterface_iid)
Q_INTERFACES(ContainerManagerInterface)
// ....
};
\endcode
Please be aware that your container plugin has to support a few basic requirements in order to
support UI clients in multi-process mode:
\list 1
\li The plugin has to be able to forward Unix local sockets into the container. This is needed for
both the Wayland socket as well as for the private peer-to-peer D-Bus connection. If the plugin
is not able to map these sockets to the exact same location within the container, it needs to
alter the environment variables for the respective locations before passing them into the
container. See below for a list of relevant environment variables.
\li In order to support hardware OpenGL acceleration, the container needs to have access to the
necessary devices: for GPUs following Linux standards (e.g. Intel), you have to make sure to
have /c{/dev/dri/*} available within the container.
\li If you want to make use of the application-manager's security features, you also have to
implement PID mapping in your plugin (this is unnecessary if your container solution shares its
PID namespace with the rest of the system). Every connection coming into the application-manager
via the Wayland or D-Bus Unix local sockets is queried for the PID of the application requesting
the connection. The application-manager will verify these PIDs against the PIDs of all running
applications via ContainerInterface::processId(). Connections that will not match a PID will
not be accepted. This behavior can be disable though by use of the \l{no-security}{\c{--no-security}}
command line option.
\endlist
The application-manager will use these environment variables to communicate various settings to the
application. A custom container plugin has to make sure to forward these or adjust them accordingly:
\table
\header
\li Name
\li Description
\row
\li \c{WAYLAND_DISPLAY}
\li The path to the Wayland server socket. If your container uses its own filesystem namespace,
you need to make sure that this socket gets forwarded accordingly.
\row
\li \c{QT_QPA_PLATFORM}
\li Always set to \c{wayland}.
\row
\li \c{QT_IM_MODULE}
\li Not really set, but explicitly unset by the application-manager. Make sure to not set it, if
the automatic Wayland input method implementation should be used.
\row
\li \c{DBUS_SESSION_BUS_ADDRESS}
\li The standard D-Bus session bus
\row
\li \c{AM_DBUS_PEER_ADDRESS}
\li This variable holds the D-Bus socket identifier for the private peer-to-peer bus between the
application-manager and the application. If your container uses its own filesystem namespace,
you need to make sure that this socket gets forwarded accordingly.
\row
\li \c{AM_DBUS_NOTIFICATION_BUS_ADDRESS}
\li Since the \c{org.freedesktop.Notifications} interface could be on a different bus as the rest
of the D-Bus interfaces, the application-manager needs to tell the application explicitly
where to look for this interface.
\row
\li \c{AM_BASE_DIR}
\li The current directory of the application-manager.
\row
\li \c{AM_RUNTIME_SYSTEM_PROPERTIES}
\li The public part of the \l{system-properties}{system properties}, encoded as an YAML document.
\row
\li \c{AM_NO_DLT_LOGGING}
\li Tells the application to not use DLT for logging.
\endtable
\section1 Configuration
There are three parts to the container configuration:
\list 1
\li Configure which containers are available at all.
\li Add specific settings for each available container integration.
\li Configure which container solution is selected to run a specific application.
\endlist
\section1 Load Container Plugins
In order to activate an existing container plugin for use in the application-manager, you need to
add its full path to the list of plugins to load in the application-manager's config file:
\badcode
plugins:
container: [ "/full/path/to/softwarecontainers.so", "/another/plugin.so" ]
\endcode
Please note that the application-manager does \b not load plugins automatically if they are placed
in a specific directory, since container plugins control the central security mechanism for
separating applications.
\section1 Container Integration Configuration
Each container integration has an unique id, which can be used to add settings to the
application-manager's config file, e.g.
\badcode
containers:
process:
defaultControlGroup: "foo"
softwarecontainers:
bar: [ 1, 2, 3 ]
\endcode
The \c process container accepts the following configuration settings:
\table
\header
\li Name
\li Type
\li Description
\row
\target control group mapping
\li \c controlGroups
\li object
\li A two-stage mapping object to allow for more readable code when dealing with cgroups from the
System-UI via Container::controlGroup. The top-level keys are readable group names
that are used to interface Container::controlGroup, while the values are themselves
maps between multiple low-level cgroup sub-system names and the actual cgroup names within
those sub-systems, e.g.:
\badcode
controlGroups:
foreGround:
memory: mem1
cpu: cpu_full
backGround:
memory: mem2
cpu: cpu_minimal
\endcode
\row
\li \c defaultControlGroup
\li string
\li The default control group for an application when it is first launched.
\endtable
For other container plugins, please consult the respective documentation.
\section1 Container Selection Configuration
There are multiple ways to control which container integration is used when
starting an application from within the application-manager:
\list 1
\li If the config file does not contain the key \c containers/selection, the container integration
id will default to \c process
\li If the aforementioned key exists, its contents will be parsed as a list of maps, where each map
only has a single mapping (this is a bit awkward, but needed to preserve the order of the
mappings). Each key is interpreted as a standard Unix wildcard expression that will be matched
against the application id.
The first match will stop this algorithm and the mapping's value will be used as the container
integration id. If no matches are found, the resulting containter integration id will be the
empty string.
\badcode
containers:
selection:
- com.pelagicore.*: "process"
- com.navigation: "special-container"
- '*': "softwarecontainers" # a single asterisk needs to be quoted
\endcode
\li Afterwards, if the System-UI did set the ApplicationManager::containerSelectionFunction property
to a valid JavaScript function, this function will be called with the first parameter set to the
application's id and the second parameter set to the container integration id that resulted from
step 1 and 2.
\badcode
ApplicationManager.containerSelectionFunction = function(appId, containerId) {
var app = ApplicationManager.application(appId)
if (app.capabilities.indexOf("non-secure") != -1)
return "process"
else
return containerId
}
\endcode
\endlist
*/
|
