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
|
// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page system-integration.html
\ingroup qtappman
\title System Integration
\brief Describes the device setup to optimally run the application manager
The most likely setup for running the application manager is as a systemd system service. You can
of course use any init system you like, but the following sections describe how to set up the
application manager with systemd, as this is the most common setup.
\section1 Basic Systemd Service
This documentation assumes that you have a basic understanding of how to set up systemd services.
The application manager is "systemd notify" aware, so a basic service file should look like this:
\badcode
# /etc/systemd/system/minidesk.service
[Unit]
Description=Start the minidesk application manager example
[Service]
Type=notify
ExecStart=/usr/bin/minidesk --verbose
User=minidesk-user
Group=minidesk-group
WatchdogSec=10s
[Install]
# WantedBy=your-ui.target
\endcode
\list
\li The \c Type field should always be \c notify as is expected from a modern systemd aware service.
\li The \c ExecStart field is obviously your application manager executable with any command line
options you need.
\li The \c User and \c Group fields should be set to the user and group that will run the
application manager.
\note The application manager should not be run as root, as this is a big and unnecessary
security risk. Always create an unprivileged user to run the application manager.
\li The \c WatchdogSec field is optional, but recommended. It sets the \l{Watchdog}{watchdog timeout}
for the application manager. If the application manager does not send a systemd notification
within this timeout, systemd will assume that the application manager has crashed and will
restart it.
\li The \c WantedBy part is optional for testing, but needs to be enabled and adjusted for your
specific target setup to enable the service to start automatically on boot.
\endlist
\section1 Root Privileges for the Application Manager
Although the application manager itself should not be run with root privileges, it might still need
those privileges for some operations, such as setting extended attributes on files during
application installation, mounting application code into containers or cleaning up orphaned
application installations. This is optional and depends on your specific setup and requirements.
In order to accomplish both these opposing goals, the application manager can be started as root
user together with the \c{--setuid <user>[:<group>]*} command line option. If this is the case, the
application manager will fork off a simple server (the so called \e{sudo helper}) that talks to the
main process over a private socket and executes the aforementioned privileged operations on behalf
of the main process.
The main process will then switch itself to the specified user and group(s), and continue as the
given unprivileged user.
Please see the \l{setuid}{--setuid command line option documentation} for more details on the
expected values.
This can be done like so:
\badcode
# /etc/systemd/system/minidesk.service
[Unit]
Description=Start the minidesk application manager example
[Service]
Type=notify
ExecStart=/usr/bin/minidesk --verbose --setuid minidesk-user:minidesk-group
WatchdogSec=10s
[Install]
# WantedBy=your-ui.target
\endcode
\note Please note that on versions before 6.10 this setup was different: you had to set the owner
to \c root and the suid/'s' bit on the application manager executable.
Then, the service had to be started as the unprivileged user and the suid-root bit would take
care of starting the process initially as \e root. This was changed to the new scheme for two
reasons:
1) the suid-root scheme can be a big security hole, if the application manager executable's
execute-permissions are too liberal (as is with any suid-root executable).
2) all processes with suid-root bit set are tagged \c AT_SECURE by the Linux kernel and have
to live with restrictions forever, even after switching back to an unprivileged user (e.g.
\c secure_getenv(), \c LD_LIBRARY_PATH).
\section1 Extra Wayland Sockets
The application manager follows the basic Wayland socket setup: it always creates a Wayland socket
in the default location (\c{$XDG_RUNTIME_DIR}) that is named \c{qtam-wayland-<number>}. This socket
is owned by the user that runs the application manager, and only Wayland clients from the same
user can connect to it.
This should be sufficient for most setups, but if you have complex container setups, you might need
additional sockets that are accessible for other (e.g. container) users.
Before version 6.11, this was done by the application manager itself using the
\c wayland/extraSockets configuration field, but it needed root privileges to create the sockets.
Since version 6.11, this is instead configured via systemd \e socket units that are linked to the
application manager service unit. For every extra socket, you need to create a systemd socket unit:
\badcode
# /etc/systemd/system/extra-wayland-socket.socket
[Socket]
Accept=no
Service=minidesk.service
FileDescriptorName=wayland.custom-short-unique-ascii-id
ListenStream=/run/path/to/extra-socket
#SocketUser=
#SocketGroup=
#SocketMod=
\endcode
\list
\li The \c Accept field needs to be set to \c no.
\li The \c Service field needs to link to the application manager service unit.
\li The \c FileDescriptorName field is optional for normal systemd socket units, but required to
\b{not only} be set, but also start with the string \c{wayland.} for the application manager to
be able to use the socket.
Each one of the extra sockets must also append a short, unique identifier to this field.
\li The \c ListenStream field is the path to the socket that will be created.
\li The \c SocketUser, \c SocketGroup, and \c SocketMod fields are optional, but can be used to
set the user, group, and permissions of the socket. If not set, the socket will be owned by
\e root.
\endlist
In addition, you need to link back from the application manager service unit to the socket units,
if the sockets should also automatically be started when you start the application manager service
unit:
\badcode
# /etc/systemd/system/minidesk.service
[Service]
...
Sockets=extra-wayland-socket.socket
#Sockets=<other socket unit>.socket
\endcode
*/
|
