// 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 [:]*} 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-}. 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=.socket \endcode */