From 9f87783018ca824019413132e099f696af9e44d3 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 23 Apr 2023 01:43:54 +0000 Subject: Add systemd unit conversion guide page Signed-off-by: Laurent Bercot --- doc/unit-conversion.html | 1399 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1399 insertions(+) create mode 100644 doc/unit-conversion.html (limited to 'doc') diff --git a/doc/unit-conversion.html b/doc/unit-conversion.html new file mode 100644 index 0000000..09d5670 --- /dev/null +++ b/doc/unit-conversion.html @@ -0,0 +1,1399 @@ + + + + + + s6: how to convert systemd unit files to an s6 installation + + + + + + +

+s6
+Software
+skarnet.org +

+ +

How to convert systemd unit files to an s6 installation

+ +

+ Converting a set of services managed by systemd +to a set of services managed by s6 is +a recurring question on our support channels, and having an automated conversion tool +parsing a set of systemd +unit files and outputting a set of s6 +service directories or +s6-rc service +definition directories would be extremely useful to people who want to migrate to +s6 but have an existing base of services running under systemd. +

+ +

+ Unfortunately, automating such a conversion is extremely difficult. The main +reason for this is that systemd and s6 are architectured in very different ways: +how they view a set of services, how they modelize a machine, what kind of solution +they bring to a given problem, and the extent of what they're supposed to manage +— there are few similarities between how systemd and s6 operate. As a +consequence, the way systemd maps a set of services into unit files is not +isomorphic to the way s6 does, so translating a setup between systemd and s6 +requires intelligence. It is not possible to write an automated tool that converts +a set of services accurately and idiomatically without doing a full, deep system +analysis - and writing such a tool would be a huge undertaking. +

+ +

+ Fortunately, in practice, most unit files only use a small subset of all the +theoretically supported directives: most services that run under systemd can be +converted to run under s6 without too much trouble. So, depending on the exact +nature of the set of services, it may be possible to write a reasonable converter, +that is limited in what it supports but does not require a full understanding +of systemd or s6. +

+ +

+ This document targets people who think about writing a tool to automatically +convert a set of unit files to a set of s6 services and are trying to assess +its feasability and difficulty. We analyze all the directives that may appear +in a unit file for their services, and rate the difficulty of translating the +directive, i.e. the amount of complexity that would need to go into the +converter tool if that directive were to be supported. +

+ +

+ We rate difficulty on a scale from 0 to 10. +A 0 means that the directive is irrelevant to s6 and can +be ignored. A 1 means that there is a straightforward, +one-for-one way of translating the systemd directive into s6 parlance. A +10 means that the directive is so systemd-specific that it +is impossible to express it on an s6 system and the unit file cannot be +converted as is. A 9 means that it is theoretically possible +to convert, given infinite time and manpower to write a tool that analyzes +the systemd-managed system holistically and outputs an equivalent system +managed by s6, but in practice nobody's ever going to write such a tool. +

+ +
+ + + +
+ +

Difficulty by directive

+ +

+ Use this section to answer the question: "I have this directive in my unit file, +how hard would it be to write a converter tool that processes this file?" +

+ +

+ Directives documented in systemd.unit(5) +

+ +

+ [Unit] section +

+ + + +

+ [Install] section +

+ +

+ Any directive under [Install] can be ignored, since it has no +meaning on the run-time behaviour of the service. So the difficulty is +0. However, an automatic converter would need to +analyze the whole installed service configuration, e.g. the links in +/etc/systemd/system/multi-user.target.wants/, in order to +understand the dependencies between services. systemd targets can +typically be converted into s6-rc bundles. +

+ +

+ Directives documented in systemd.service(5) +

+ +

+ [Service] section +

+ + + +

+ Directives documented in systemd.exec(5) +

+ +

+ Paths +

+ + + +

+ User/group identity +

+ + + +

+ Capabilities +

+ + + +

+ Security +

+ + + +

+ Mandatory access control +

+ + + +

+ Process properties +

+ + + +

+ Scheduling +

+ + + +

+ Sandboxing +

+ +

+ systemd gracefully turns off the sandboxing options on systems that +do not support the necessary functionality, so all these options can +be ignored (difficulty 0) and the services will still +work. However, in order to actually implementing the sandboxing, it is +necessary to pair s6 with command-line tools that perform the required +process state changes by interfacing with namespaces, cgroups, seccomp, +or any other relevant feature of the Linux kernel, so for all these +directives the difficulty is somewhere between 2, if +the tool already exists, and 8, if it requires writing +a full container implementation from scratch. The following numbers are +only a rough guess. +

+ + + +

+ System call filtering +

+ + + +

+ Environment +

+ + + +

+ Logging and standard input/output +

+ + + +

+ Credentials +

+ +

+ systemd implements its own credentials store mechanism, for no obvious +benefit. The whole credentials system needs to be reimplemented outside +of systemd in order for credentials-related directives to be supported +by s6. Consequently, all these directives are rated 6. +

+ +

+ System V compatibility +

+ +

+ The utmp directives can be made significantly easier to implement if the target +system is using utmps, +because the directives then become a single call to +utmps-write +with the relevant options. If utmps +cannot be used, then the utmp calls need to be reimplemented. +

+ + + +

+ Directives documented in systemd.kill(5) +

+ + + +

+ Directives documented in systemd.resource-control(5) +

+ +

+ All these directives relate to cgroups, so implementing them means +having access to at least some cgroups commands (difficulty at least +3. Others are even more involved, requiring tight +service integration with the system. Generally, seeing these directives +in your unit files is a bad sign; despite some of them only having +3 or 4 listed, we do not recommend +implementing systemd.resource-control(5) +without having a full holistic view of the system. +

+ + + + +

Directives rated by difficulty

+ +

+ Use this section to answer the question: "If I were to write a converter tool +from systemd to s6, what subset of the unit file syntax should I focus on +first?" +

+ +

+ Take this classification with a grain of salt: for instance, it does not +make sense to implement an easy directive if it's only used in the context +of a larger subsystem that's much harder to implement - typically, most +cgroups-related resource control directives. +

+ +

+ Difficulty: 0 — directives that can be ignored +

+ + + +

+ Difficulty: 1 — direct functionality mapping +

+ + + +

+ Difficulty: 2 — straightforward implementation +

+ + + +

+ Difficulty: 3 — requires easy additional programming +

+ + + +

+ Difficulty: 4 — requires medium additional programming +

+ + + +

+ Difficulty: 5 — requires complex additional programming +

+ + + +

+ Difficulty: 6 — requires a full independent implementation +of a Linux subsystem and/or a part of the systemd architecture +

+ + + +

+ Difficulty: 7 — requires a full independent implementation +of a complex Linux subsystem and/or a significant part of the +systemd architecture +

+ + + +

+ Difficulty: 8 — requires a complete implementation of complex +Linux-specific tooling +

+ + + +

+ Difficulty: 9 — requires a full system analysis and remodelization +

+ + + +

+ Difficulty: 10 — implementing this basically means reimplementing systemd +

+ + + + + -- cgit v1.2.3