Systemd
systemd is being added to postmarketOS (in addition to OpenRC), as announced in this blog post.
Official images
Official postmarketOS edge images from 2025-01-12 or later for GNOME (Mobile), Plasma (Mobile) and Phosh use systemd.
How to build your own systemd-based postmarketOS images
systemd has arrived in postmarketOS edge on Friday, 2025-01-10! See the announcement. |
Configure pmbootstrap for systemd
- Install pmbootstrap (make sure you have version 3.2.0 or higher via
pmbootstrap -V
, clone from git if your distribution does not ships an old version) - Make sure your pmaports are up-to-date (
pmbootstrap pull
) - Run
pmbootstrap init
, select systemd and select your device - Consider running
pmbootstrap config systemd always
/ selectingalways
whenpmbootstrap init
asks you about systemd to use it for all UIs, even where it isn't currently the default.
Build the image
Run pmbootstrap install
as usually.
Undo configuration for systemd
- Run
pmbootstrap config systemd default
Debugging
Sometimes boot-up can hang waiting for a required service to start, before any VT/console is available for login/debug. The systemd debug shell can be enabled by adding systemd.debug-shell=1
to the kernel cmdline, and a shell will be available on VT9 when systemd starts.
Reporting bugs
Bugs should be should include the systemd
gitlab label when they are filed, so that they are easy to find.
Contributing patches
Thank you for helping to improve systemd support in postmarketOS!
Merge requests should be submitted with the gitlab label systemd
so that they are easy to find for review.
For adding systemd services and other unit files, see Systemd_services
Matrix / IRC channel
We have a dedicated Matrix and IRC channel for integrating systemd with postmarketOS, feel free to join if you are interested in contributing!
Managing Services in pmaports
Summary
This describes the design for configuring and maintaining systemd service autostart preferences in pmaports. It's intended to be used by pmaports package maintainers. It may also be helpful for system admins who would like to understand how pmOS performs autostart configuration for systemd user and system services.
Goals
Users should have ultimate control in how their system is configured and pmOS maintainers need a reliable, easy, and consistent way to provide default configuration for users on all device and UI combinations that we support.
With systemd, maintainers and users have a lot more options for specifying service autostart preferences. We found that some of these options can create service autostart config conflicts between users and pmOS package maintainers. For example, users might run systemctl disable foo
and a package update might systemctl enable foo
and override the user's preferences. This has happened in the past with our openrc config. The following requirements were used to find a design that prevents (or greatly reduces) these types of conflicts:
- Allow pmOS components (such as UI and device packages) to specify default autostart preferences.
- Allow users to override preferences using well known methods (e.g.
systemctl disable
...) - Packages should not override user config
- Use something similar to other distros that also solve this problem
- Allow package managers to conditionally enable/disable autostarted services on package upgrade, useful for replacing one service with another.
Design
Systemd service autostart config is handled using systemd's preset feature. Some major distros, like Fedora, use systemd presets. A lot of the following design was inspired by how other distros use this. Presets, when used in the following way, allow us to meet all of the previously stated goals.
The general overview is:
- pmOS packages (currently
postmarketos-base-systemd
) install systemd preset config for services, for postmarketOS - packages that install systemd unit files run an install script macro to apply preset config on installation
- Those same packages also run a different macro on uninstall to clean up symlinks
Distro system and user service presets are installed by the postmarketos-base-systemd
package. Other packages may provide presets too, but care must be taken to ensure that service packages using the systemd install script macros must be installed after any package providing a preset config for that service. If this cannot be guaranteed, then the expected preset may not be applied.
Service packages that install systemd unit files should use post-install
and pre-deinstall
install script macros when those unit files include an [Install]
section. The macros are provided in the file /usr/share/systemd/systemd-apk-macros.sh
, this file is installed by the systemd package. The relevant install scripts are expected to source this file. There are two functions in this file, one for each type of install script:
systemd_service_post_install
and systemd_service_pre_deinstall.
Both scripts accept either user or system as the first param (for type of service), and then a list of services.
Example using ficticious foo
service, where foo.service
and foo@.service
unit files are installable:
$ cat foo-systemd.post-install
$!/bin/sh
. /usr/share/systemd/systemd-apk-macros.sh
systemd_service_post_install system foo foo@bar
$ cat foo-systemd.pre-deinstall
$!/bin/sh
. /usr/share/systemd/systemd-apk-macros.sh
systemd_service_pre_deinstall system foo foo@bar
Currently, if service files are added in the `systemd-services` package in pmaports, adding a new variable for the service in step 5 of the systemd-services/APKBUILD
will cause that package to generate the necessary install scripts automatically.