Jump to content

Systemd: Difference between revisions

From postmarketOS Wiki
add "reporting bugs"
E-v (talk | contribs)
m #Configure pmbootstrap for systemd: improve wording
 
(24 intermediate revisions by 8 users not shown)
Line 1: Line 1:
systemd is being added to postmarketOS (in addition to OpenRC), as announced [https://postmarketos.org/blog/2024/03/05/adding-systemd/ in this blog post].
systemd is being added to postmarketOS (in addition to [[OpenRC]]), as announced [https://postmarketos.org/blog/2024/03/05/adding-systemd/ 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 ==
== How to build your own systemd-based postmarketOS images ==
{{note|The steps here will change until it is fully integrated! See {{issue|2632|pmaports}} for details. Trying this out in the current stage is for advanced users who know what they are doing!}}
{{note|systemd has arrived in postmarketOS edge on Friday, 2025-01-10! See the [https://postmarketos.org/edge/2025/01/09/systemd-soon/ announcement].}}


=== Configure pmbootstrap for systemd ===
=== Configure pmbootstrap for systemd ===


* [[Pmbootstrap#From_git|Clone pmbootstrap from git]]
* Install [[pmbootstrap]] (make sure you have version 3.2.0 or higher via <code>pmbootstrap -V</code>, [[Pmbootstrap#From_git|clone from git]] if your distribution ships an old version)
* Go to your local [[pmaports]] clone, do git fetch and git checkout the <code>master_staging_systemd</code> branch
* Make sure your pmaports are up-to-date (<code>pmbootstrap pull</code>)
* Run <code>pmbootstrap init</code>, select systemd and select your device
* Run <code>pmbootstrap init</code>, select systemd and select your device
* Configure the systemd staging repository as mirror:
* Consider running <code>pmbootstrap config systemd always</code> / selecting <code>always</code> when <code>pmbootstrap init</code> asks you about systemd to use it for all UIs, even where it isn't currently the default.
 
<syntaxhighlight lang="shell-session">
$ pmbootstrap config mirrors_postmarketos "http://mirror.postmarketos.org/postmarketos/staging/systemd/"
</syntaxhighlight>
 
* Run <code>pmbootstrap config systemd always</code>
* (If the staging repository didn't bootstrap your device's architecture yet, run <code>pmbootstrap repo_bootstrap systemd</code>. See status at [https://build.postmarketos.org/ build.postmarketos.org]. <code>pmbootstrap install</code> will tell you that this needs to be done, if necessary.)


=== Build the image ===
=== Build the image ===
Run <code>pmbootstrap install</code> as usually.
Run <code>pmbootstrap install</code> as usually.


=== Undo configuration for systemd ===
== Undo configuration for systemd ==


* Checkout <code>master</code> again in pmaports
* Run <code>pmbootstrap config systemd default</code>
* Run <code>pmbootstrap config systemd default</code>
* Reset the mirror to the default (or select your preferred one in <code>pmbootstrap init</code>):
 
== 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 <code>systemd.debug-shell=1</code> to the kernel cmdline, and a shell will be available on VT9 when systemd starts.
 
== Reporting bugs ==
Bugs should be should include the <code>systemd</code> 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 <code>systemd</code> 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 <code>systemctl disable foo</code> and a package update might <code>systemctl enable foo</code> 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. <code>systemctl disable</code> ...)
* 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 <code>postmarketos-base-systemd</code>) 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 <code>postmarketos-base-systemd</code> 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 <code>post-install</code> and <code>pre-deinstall</code> install script macros when those unit files include an <code>[Install]</code> section. The macros are provided in the file <code>/usr/share/systemd/systemd-apk-macros.sh</code>, 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:
 
<code>systemd_service_post_install</code> and <code>systemd_service_pre_deinstall.</code> Both scripts accept either user or system as the first param (for type of service), and then a list of services.
 
Example using ficticious <code>foo</code> service, where <code>foo.service</code> and <code>foo@.service</code> unit files are installable:


<syntaxhighlight lang="shell-session">
<syntaxhighlight lang="shell-session">
$ pmbootstrap config mirrors_postmarketos http://mirror.postmarketos.org/postmarketos/
$ 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
</syntaxhighlight>
</syntaxhighlight>


== Reporting bugs ==
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 <code>systemd-services/APKBUILD</code> will cause that package to generate the necessary install scripts automatically.
Use the systemd megathread ({{issue|2632|pmaports}}) for now.
 
== Subpages ==
{{Special:PrefixIndex/Systemd/|hideredirects=yes}}
[[Category:Init]]

Latest revision as of 12:56, 10 February 2025

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

Note 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 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 / selecting always when pmbootstrap 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:

  1. pmOS packages (currently postmarketos-base-systemd) install systemd preset config for services, for postmarketOS
  2. packages that install systemd unit files run an install script macro to apply preset config on installation
  3. 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.

Subpages