From 2595eb8cd9baff824302579848e9e0bfa95b33fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 19 Dec 2019 10:15:08 +0100 Subject: [PATCH 1/7] hwdb: make comment more precise Based on https://github.com/systemd/systemd/pull/14296#issuecomment-567159538. --- hwdb.d/60-sensor.hwdb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hwdb.d/60-sensor.hwdb b/hwdb.d/60-sensor.hwdb index 29c930e2c1..be9c8d2c4b 100644 --- a/hwdb.d/60-sensor.hwdb +++ b/hwdb.d/60-sensor.hwdb @@ -448,7 +448,7 @@ sensor:modalias:acpi:SMO8500*:dmi:*:svnMEDION:pnAkoyaE2212TMD99720:* # Medion Akoya E3222 MD62450 # and presumably all other Akoya Exxxx sensor:modalias:acpi:KIOX010A*:dmi:*:svnMEDION:pnE*:* -# Medion Akoya E3222 +# Medion Akoya E3222 MD62450 sensor:modalias:acpi:KIOX010A*:dmi:*:svnMEDION:pnMEDION*:* ACCEL_MOUNT_MATRIX=0, -1, 0; -1, 0, 0; 0, 0, 1 From 02c789f9f9665c0622d4f5fa8493fe33c010c61d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 11 Jan 2020 18:47:26 +0100 Subject: [PATCH 2/7] docs: import stability chart from wiki --- docs/PORTABILITY_AND_STABILITY.md | 100 ++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/PORTABILITY_AND_STABILITY.md diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md new file mode 100644 index 0000000000..db9763e1c1 --- /dev/null +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -0,0 +1,100 @@ +--- +title: Interface Portability and Stability Chart +category: Interfaces +layout: default +--- + +# Interface Portability And Stability Chart + +systemd provides a number of APIs to applications. Below you'll find a table detailing which APIs are considered stable and how portable they are. + +This list is intended to be useful for distribution and OS developers who are interested to maintain a certain level of compatibility with the new interfaces systemd introduced, without relying on systemd itself. + +In general it is our intention to cooperate with interfaces, not with code with other distributions and OSes. That means, that the interfaces where this applies are best reimplemented in a compatible fashion on those other operating systems. To make this easy we provide detailed interface documentation where necessary. That said, it's all Open Source, hence you have the option to a) fork our code and maintain portable versions of the parts you are interested in independently for your OS, or b) build systemd for your distro, but leave out all components but the ones you are interested in and run them without the core of systemd involved. We will try not to make this any more difficult than necessary, but we do not officially support using systemd code this way and will not accept patches for making this easier. + +Many of these interfaces are already being used by applications and 3rd party code. If you are interested in compatibility with these applications, please consider supporting these interfaces in your distribution, where possible. + + +## General Portability of systemd and its Components + +**Portability to OSes:** systemd is not portable to non-Linux systems. It makes use of a large number of Linux-specific interfaces, including many that are used by its very core. We do not consider it feasible to port systemd to other Unixes (let alone non-Unix operating systems) and will not accept patches for systemd implementing any such portability (but hey, it's git, so it's as easy as it can get to maintain your own fork...). APIs that are supposed to be used as drop-in .c files are exempted from this: it is important to us that these compile nicely on non-Linux and even non-Unix platforms, even if they might just become NOPs. + +**Portability to Architectures:** It is important to us that systemd is portable to little endian as well as big endian systems. We will make sure to provide portability with all important architectures and hardware Linux runs on and are happy to accept patches for this. + +**Portability to Distributions:** It is important to us that systemd is portable to all important Linux distributions. However, the goal is to unify many of the needless differences between the distributions, and hence will not accept patches for certain distribution-specific compatibility. Compatibility with the distribution's legacy should be maintained in the distribution's packaging, and not in the systemd source tree. + +**Compatibility with Specific Versions of Other packages:** We generally avoid adding compatibility kludges to systemd that work around bugs in certain versions of other software systemd interfaces with. We strongly encourage fixing bugs where they are, and if that's not systemd we rather not try to fix it there. (There are very few exceptions to this rule possible, and you need an exceptionally strong case for it). + + +## General Portability of systemd's APIs + +systemd's APIs are available everywhere where systemd is available. Some of the APIs we have defined are supposed to be generic enough to be implementable independently of systemd, thus allowing compatibility with systems systemd itself is not compatible with, i.e. other OSes, and distributions that are unwilling to fully adopt systemd. + +A number of systemd's APIs expose Linux or systemd-specific features that cannot sensibly be implemented elsewhere. Please consult the table below for information about which ones these are. + +Note that not all of these interfaces are our invention (but most), we just adopted them in systemd to make them more prominently implemented. For example, we adopted many Debian facilities in systemd to push it into the other distributions as well. + + + +--- + + + +And now, here's the list of (hopefully) all APIs that we have introduced with systemd: +[[!table header="no" class="mointable" data=""" +**API** | **Type** | **Covered by [[Interface Stability Promise|http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise]]** | **Fully documented** | **Known External Consumers** | **Reimplementable Independently** | **Known Other Implementations** | **systemd Implementation portable to other OSes or non-systemd distributions +[[hostnamed|http://www.freedesktop.org/wiki/Software/systemd/hostnamed]] | D-Bus | yes | yes | GNOME | yes | [[Ubuntu|https://launchpad.net/ubuntu/+source/ubuntu-system-service]], [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]], [[BSD|http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary]] | partially +[[localed|http://www.freedesktop.org/wiki/Software/systemd/localed]] | D-Bus | yes | yes | GNOME | yes | [[Ubuntu|https://launchpad.net/ubuntu/+source/ubuntu-system-service]], [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]], [[BSD|http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary]] | partially +[[timedated|http://www.freedesktop.org/wiki/Software/systemd/timedated]] | D-Bus | yes | yes | GNOME | yes | [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]], [[BSD|http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary]] | partially +[[initrd interface|http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface]] | Environment, flag files | yes | yes | dracut, [[ArchLinux|ArchLinux]] | yes | [[ArchLinux|ArchLinux]] | no +[[Container interface|http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface]] | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no +[[Boot Loader interface|http://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface]] | EFI variables | yes | yes | gummiboot | yes | - | no +[[Service bus API|http://www.freedesktop.org/wiki/Software/systemd/dbus]] | D-Bus | yes | yes | system-config-services | no | - | no +[[logind|http://www.freedesktop.org/wiki/Software/systemd/logind]] | D-Bus | yes | yes | GNOME | no | - | no +[[sd-login.h API|http://0pointer.de/public/systemd-man/sd-login.html]] | C Library | yes | yes | GNOME, [[PolicyKit|PolicyKit]], ... | no | - | no +[[sd-daemon.h API|http://0pointer.de/public/systemd-man/sd-daemon.html]] | C Library or Drop-in | yes | yes | numerous | yes | - | yes +[[sd-id128.h API|http://0pointer.de/public/systemd-man/sd-id128.html]] | C Library | yes | yes | - | yes | - | no +[[sd-journal.h API|http://0pointer.de/public/systemd-man/sd-journal.html]] | C Library | yes | yes | - | maybe | - | no +[[$XDG_RUNTIME_DIR|https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html]] | Environment | yes | yes | glib, GNOME | yes | - | no +[[$LISTEN_FDS/$LISTEN_PID FD Passing|http://0pointer.de/public/systemd-man/sd_listen_fds.html]] | Environment | yes | yes | numerous (via sd-daemon.h) | yes | - | no +[[$NOTIFY_SOCKET Daemon Notifications|http://0pointer.de/public/systemd-man/sd_notify.html]] | Environment | yes | yes | a few, including udev | yes | - | no +[[argv[0][0]='@' Logic|http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons]] | /proc marking | yes | yes | mdadm | yes | - | no +[[Unit file format|http://0pointer.de/public/systemd-man/systemd.unit.html]] | File format | yes | yes | numerous | no | - | no +[[Journal File Format|http://www.freedesktop.org/wiki/Software/systemd/journal-files]] | File format | yes | yes | - | maybe | - | no +[[Journal Export Format|http://www.freedesktop.org/wiki/Software/systemd/export]] | File format | yes | yes | - | yes | - | no +[[Cooperation in cgroup tree|http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups]] | Treaty | yes | yes | libvirt | yes | libvirt | no +[[Password Agents|http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents]] | Socket+Files | yes | yes | - | yes | - | no +[[udev multi-seat properties|http://www.freedesktop.org/wiki/Software/systemd/multiseat]] | udev Property | yes | yes | X11, gdm | no | - | no +udev session switch ACL properties | udev Property | no | no | - | no | - | no +[[CLI of systemctl,...|http://0pointer.de/public/systemd-man/systemctl.html]] | CLI | yes | yes | numerous | no | - | no +[[tmpfiles.d|https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html]] | File format | yes | yes | numerous | yes | [[ArchLinux|ArchLinux]] | partially +[[sysusers.d|https://www.freedesktop.org/software/systemd/man/sysusers.d.html]] | File format | yes | yes | unknown | yes | | partially +[[/etc/machine-id|http://0pointer.de/public/systemd-man/machine-id.html]] | File format | yes | yes | D-Bus | yes | - | no +[[binfmt.d|http://0pointer.de/public/systemd-man/binfmt.d.html]] | File format | yes | yes | numerous | yes | - | partially +[[/etc/hostname|http://0pointer.de/public/systemd-man/hostname.html]] | File format | yes | yes | numerous (it's a Debian thing) | yes | Debian, [[ArchLinux|ArchLinux]] | no +[[/etc/locale.conf|http://0pointer.de/public/systemd-man/locale.conf.html]] | File format | yes | yes | - | yes | [[ArchLinux|ArchLinux]] | partially +[[/etc/machine-info|http://0pointer.de/public/systemd-man/machine-info.html]] | File format | yes | yes | - | yes | - | partially +[[modules-load.d|http://0pointer.de/public/systemd-man/modules-load.d.html]] | File format | yes | yes | numerous | yes | - | partially +[[/usr/lib/os-release|http://0pointer.de/public/systemd-man/os-release.html]] | File format | yes | yes | some | yes | Fedora, OpenSUSE, [[ArchLinux|ArchLinux]], Angstrom, Frugalware, others... | no +[[sysctl.d|http://0pointer.de/public/systemd-man/sysctl.d.html]] | File format | yes | yes | some (it's a Debian thing) | yes | procps/Debian, [[ArchLinux|ArchLinux]] | partially +[[/etc/timezone|http://0pointer.de/public/systemd-man/timezone.html]] | File format | yes | yes | numerous (it's a Debian thing) | yes | Debian | partially +[[/etc/vconsole.conf|http://0pointer.de/public/systemd-man/vconsole.conf.html]] | File format | yes | yes | - | yes | [[ArchLinux|ArchLinux]] | partially +/run | File hierarchy change | yes | yes | numerous | yes | OpenSUSE, Debian, [[ArchLinux|ArchLinux]] | no +[[Generators|http://www.freedesktop.org/wiki/Software/systemd/Generators]] | Subprocess | yes | yes | - | no | - | no +[[System Updates|http://freedesktop.org/wiki/Software/systemd/SystemUpdates]] | System Mode | yes | yes | - | no | - | no +[[Presets|http://freedesktop.org/wiki/Software/systemd/Preset]] | File format | yes | yes | - | no | - | no +Udev rules | File format | yes | yes | numerous | no | no | partially +"""]] + + +### Explanations + +Items for which "systemd implementation portable to other OSes" is "partially" means that it is possible to run the respective tools that are included in the systemd tarball outside of systemd. Note however that this is not officially supported, so you are more or less on your own if you do this. If you are opting for this solution simply build systemd as you normally would but drop all files except those which you are interested in. + +Of course, it is our intention to eventually document all interfaces we defined. If we haven't documented them for now, this is usually because we want the flexibility to still change things, or don't want 3rd party applications to make use of these interfaces already. That said, our sources are quite readable and open source, so feel free to spelunk around in the sources if you want to know more. + +If you decide to reimplement one of the APIs for which "Reimplementable independently" is "no", then we won't stop you, but you are on your own. + +This is not an attempt to comprehensively list all users of these APIs. We are just listing the most obvious/prominent ones which come to our mind. + +Of course, one last thing I can't make myself not ask you before we finish here, and before you start reimplementing these APIs in your distribution: are you sure it's time well spent if you work on reimplementing all this code instead of just spending it on adopting systemd on your distro as well? From b8b7309778caeb0e8e17056f7307f538f659dc40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 11 Jan 2020 19:20:35 +0100 Subject: [PATCH 3/7] docs/stability: relax the stance on accepting patches a bit Instead of saying that patches for portability are not accepted, say that this is decided case-by-case. This is what happens in practice, and we tend to discuss each patch on its own merits. Some sentences are reworded a bit where they sound awkward. --- docs/PORTABILITY_AND_STABILITY.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index db9763e1c1..0bdbf661ef 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -8,20 +8,20 @@ layout: default systemd provides a number of APIs to applications. Below you'll find a table detailing which APIs are considered stable and how portable they are. -This list is intended to be useful for distribution and OS developers who are interested to maintain a certain level of compatibility with the new interfaces systemd introduced, without relying on systemd itself. +This list is intended to be useful for distribution and OS developers who are interested in maintaining a certain level of compatibility with the new interfaces systemd introduced, without relying on systemd itself. -In general it is our intention to cooperate with interfaces, not with code with other distributions and OSes. That means, that the interfaces where this applies are best reimplemented in a compatible fashion on those other operating systems. To make this easy we provide detailed interface documentation where necessary. That said, it's all Open Source, hence you have the option to a) fork our code and maintain portable versions of the parts you are interested in independently for your OS, or b) build systemd for your distro, but leave out all components but the ones you are interested in and run them without the core of systemd involved. We will try not to make this any more difficult than necessary, but we do not officially support using systemd code this way and will not accept patches for making this easier. +In general it is our intention to cooperate through interfaces and not code with other distributions and OSes. That means that the interfaces where this applies are best reimplemented in a compatible fashion on those other operating systems. To make this easy we provide detailed interface documentation where necessary. That said, it's all Open Source, hence you have the option to a) fork our code and maintain portable versions of the parts you are interested in independently for your OS, or b) build systemd for your distro, but leave out all components except the ones you are interested in and run them without the core of systemd involved. We will try not to make this any more difficult than necessary. Patches to allow systemd code to be more portable will be accepted on case-by-case basis (essentially, patches to follow well-established standards instead of e.g. glibc or linux extensions have a very high chance of being accepted, while patches which make the code ugly or exist solely to work around bugs in other projects have a low chance of being accepted). Many of these interfaces are already being used by applications and 3rd party code. If you are interested in compatibility with these applications, please consider supporting these interfaces in your distribution, where possible. ## General Portability of systemd and its Components -**Portability to OSes:** systemd is not portable to non-Linux systems. It makes use of a large number of Linux-specific interfaces, including many that are used by its very core. We do not consider it feasible to port systemd to other Unixes (let alone non-Unix operating systems) and will not accept patches for systemd implementing any such portability (but hey, it's git, so it's as easy as it can get to maintain your own fork...). APIs that are supposed to be used as drop-in .c files are exempted from this: it is important to us that these compile nicely on non-Linux and even non-Unix platforms, even if they might just become NOPs. +**Portability to OSes:** systemd is not portable to non-Linux systems. It makes use of a large number of Linux-specific interfaces, including many that are used by its very core. We do not consider it feasible to port systemd to other Unixes (let alone non-Unix operating systems) and will not accept patches for systemd core implementing any such portability (but hey, it's git, so it's as easy as it can get to maintain your own fork...). APIs that are supposed to be used as library code are exempted from this: it is important to us that these compile nicely on non-Linux and even non-Unix platforms, even if they might just become NOPs. **Portability to Architectures:** It is important to us that systemd is portable to little endian as well as big endian systems. We will make sure to provide portability with all important architectures and hardware Linux runs on and are happy to accept patches for this. -**Portability to Distributions:** It is important to us that systemd is portable to all important Linux distributions. However, the goal is to unify many of the needless differences between the distributions, and hence will not accept patches for certain distribution-specific compatibility. Compatibility with the distribution's legacy should be maintained in the distribution's packaging, and not in the systemd source tree. +**Portability to Distributions:** It is important to us that systemd is portable to all Linux distributions. However, the goal is to unify many of the needless differences between the distributions, and hence will not accept patches for certain distribution-specific work-arounds. Compatibility with the distribution's legacy should be maintained in the distribution's packaging, and not in the systemd source tree. **Compatibility with Specific Versions of Other packages:** We generally avoid adding compatibility kludges to systemd that work around bugs in certain versions of other software systemd interfaces with. We strongly encourage fixing bugs where they are, and if that's not systemd we rather not try to fix it there. (There are very few exceptions to this rule possible, and you need an exceptionally strong case for it). From e4893c6306f41a56ac3b436023a86c4d683c9ebf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 11 Jan 2020 19:34:29 +0100 Subject: [PATCH 4/7] docs: import "interface stability promise" In the wiki, this was a separate page. I don't think this split is useful, since the information about what is stable and what not seems randomly split between the two pages. Links are adjusted for our own pages. Some external links to gentoo and other projects seem to be broken, but it's a chore to fix them. --- docs/PORTABILITY_AND_STABILITY.md | 120 +++++++++++++++++++----------- 1 file changed, 75 insertions(+), 45 deletions(-) diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index 0bdbf661ef..6bc55d7177 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -1,9 +1,39 @@ --- -title: Interface Portability and Stability Chart +title: Interface Portability and Stability category: Interfaces layout: default --- +# Interface Stability Promise + +systemd provides various interfaces developers and programs might rely on. Starting with version 26 (the first version released with Fedora 15) we promise to keep a number of them stable and compatible for the future. + +The stable interfaces are: + +* **The unit configuration file format**. Unit files written now will stay compatible with future versions of systemd. Extensions to the file format will happen in a way that existing files remain compatible. +* **The command line interface** of systemctl, loginctl, journalctl. We will make sure that scripts invoking these commands will continue to work with future versions of systemd. Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page. Example: the output of "systemctl status" is not stable, but the one of "systemctl show" is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page. +* **The protocol spoken on the socket referred to by $NOTIFY_SOCKET**, as documented in (sd_notify(3))[https://www.freedesktop.org/software/systemd/man/sd_notify.html]. +* Some of the **"special" unit names** and their semantics. To be precise the ones that are necessary for normal services, and not those required only for early boot and late shutdown, with very few exceptions. To list them here: `basic.target`, `shutdown.target`, `sockets.target`, `network.target`, `getty.target`, `graphical.target`, `multi-user.target`, `rescue.target`, `emergency.target`, `poweroff.target`, `reboot.target`, `halt.target`, `runlevel[1-5].target`. +* For a more comprehensive and authoritative list, consult the chart below. + +The following interfaces will not necessarily be kept stable for now, but we will eventually make a stability promise for these interfaces too. In the meantime we will however try to keep breakage of these interfaces at a minimum: + +* **The D-Bus interfaces of the main service daemon** (!) [ An additional restriction applies here: functionality we consider legacy might not be available based on compile-time options, such as SysV support, libwrap support and similar. Apps should not assume properties and methods related to this functionality are unconditionally available in the D-Bus interfaces. ] +* **The set of states of the various state machines used in systemd**, e.g. the high-level unit states inactive, active, deactivating, and so on, as well (and in particular) the low-level per-unit states. +* **All "special" units that aren't listed above**. + +The following interfaces are considered private to systemd, and are not and will not be covered by any stability promise: + +* **Undocumented switches** to systemd, systemctl and otherwise. +* **The internal protocols** used on the various sockets such as the sockets `/run/systemd/shutdown`, `/run/systemd/private`. + +One of the main goals of systemd is to unify basic Linux configurations and service behaviors across all distributions. Systemd project does not contain any distribution-specific parts. Distributions are expected to convert over time their individual configurations to the systemd format, or they will need to carry and maintain patches in their package if they still decide to stay different. + +What does this mean for you? When developing with systemd, don't use any of the latter interfaces, or we will tell your mom, and she won't love you anymore. You are welcome to use the other interfaces listed here, but if you use any of the second kind (i.e. those where we don't yet make a stability promise), then make sure to subscribe to our mailing list, where we will announce API changes, and be prepared to update your program eventually. + +Note that this is a promise, not an eternal guarantee. These are our intentions, but if in the future there are very good reasons to change or get rid of an interface we have listed above as stable, then we might take the liberty to do so, despite this promise. However, if we do this, then we'll do our best to provide a smooth and reasonably long transition phase. + + # Interface Portability And Stability Chart systemd provides a number of APIs to applications. Below you'll find a table detailing which APIs are considered stable and how portable they are. @@ -41,50 +71,50 @@ Note that not all of these interfaces are our invention (but most), we just adop And now, here's the list of (hopefully) all APIs that we have introduced with systemd: -[[!table header="no" class="mointable" data=""" -**API** | **Type** | **Covered by [[Interface Stability Promise|http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise]]** | **Fully documented** | **Known External Consumers** | **Reimplementable Independently** | **Known Other Implementations** | **systemd Implementation portable to other OSes or non-systemd distributions -[[hostnamed|http://www.freedesktop.org/wiki/Software/systemd/hostnamed]] | D-Bus | yes | yes | GNOME | yes | [[Ubuntu|https://launchpad.net/ubuntu/+source/ubuntu-system-service]], [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]], [[BSD|http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary]] | partially -[[localed|http://www.freedesktop.org/wiki/Software/systemd/localed]] | D-Bus | yes | yes | GNOME | yes | [[Ubuntu|https://launchpad.net/ubuntu/+source/ubuntu-system-service]], [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]], [[BSD|http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary]] | partially -[[timedated|http://www.freedesktop.org/wiki/Software/systemd/timedated]] | D-Bus | yes | yes | GNOME | yes | [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]], [[BSD|http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary]] | partially -[[initrd interface|http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface]] | Environment, flag files | yes | yes | dracut, [[ArchLinux|ArchLinux]] | yes | [[ArchLinux|ArchLinux]] | no -[[Container interface|http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface]] | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no -[[Boot Loader interface|http://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface]] | EFI variables | yes | yes | gummiboot | yes | - | no -[[Service bus API|http://www.freedesktop.org/wiki/Software/systemd/dbus]] | D-Bus | yes | yes | system-config-services | no | - | no -[[logind|http://www.freedesktop.org/wiki/Software/systemd/logind]] | D-Bus | yes | yes | GNOME | no | - | no -[[sd-login.h API|http://0pointer.de/public/systemd-man/sd-login.html]] | C Library | yes | yes | GNOME, [[PolicyKit|PolicyKit]], ... | no | - | no -[[sd-daemon.h API|http://0pointer.de/public/systemd-man/sd-daemon.html]] | C Library or Drop-in | yes | yes | numerous | yes | - | yes -[[sd-id128.h API|http://0pointer.de/public/systemd-man/sd-id128.html]] | C Library | yes | yes | - | yes | - | no -[[sd-journal.h API|http://0pointer.de/public/systemd-man/sd-journal.html]] | C Library | yes | yes | - | maybe | - | no -[[$XDG_RUNTIME_DIR|https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html]] | Environment | yes | yes | glib, GNOME | yes | - | no -[[$LISTEN_FDS/$LISTEN_PID FD Passing|http://0pointer.de/public/systemd-man/sd_listen_fds.html]] | Environment | yes | yes | numerous (via sd-daemon.h) | yes | - | no -[[$NOTIFY_SOCKET Daemon Notifications|http://0pointer.de/public/systemd-man/sd_notify.html]] | Environment | yes | yes | a few, including udev | yes | - | no -[[argv[0][0]='@' Logic|http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons]] | /proc marking | yes | yes | mdadm | yes | - | no -[[Unit file format|http://0pointer.de/public/systemd-man/systemd.unit.html]] | File format | yes | yes | numerous | no | - | no -[[Journal File Format|http://www.freedesktop.org/wiki/Software/systemd/journal-files]] | File format | yes | yes | - | maybe | - | no -[[Journal Export Format|http://www.freedesktop.org/wiki/Software/systemd/export]] | File format | yes | yes | - | yes | - | no -[[Cooperation in cgroup tree|http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups]] | Treaty | yes | yes | libvirt | yes | libvirt | no -[[Password Agents|http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents]] | Socket+Files | yes | yes | - | yes | - | no -[[udev multi-seat properties|http://www.freedesktop.org/wiki/Software/systemd/multiseat]] | udev Property | yes | yes | X11, gdm | no | - | no -udev session switch ACL properties | udev Property | no | no | - | no | - | no -[[CLI of systemctl,...|http://0pointer.de/public/systemd-man/systemctl.html]] | CLI | yes | yes | numerous | no | - | no -[[tmpfiles.d|https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html]] | File format | yes | yes | numerous | yes | [[ArchLinux|ArchLinux]] | partially -[[sysusers.d|https://www.freedesktop.org/software/systemd/man/sysusers.d.html]] | File format | yes | yes | unknown | yes | | partially -[[/etc/machine-id|http://0pointer.de/public/systemd-man/machine-id.html]] | File format | yes | yes | D-Bus | yes | - | no -[[binfmt.d|http://0pointer.de/public/systemd-man/binfmt.d.html]] | File format | yes | yes | numerous | yes | - | partially -[[/etc/hostname|http://0pointer.de/public/systemd-man/hostname.html]] | File format | yes | yes | numerous (it's a Debian thing) | yes | Debian, [[ArchLinux|ArchLinux]] | no -[[/etc/locale.conf|http://0pointer.de/public/systemd-man/locale.conf.html]] | File format | yes | yes | - | yes | [[ArchLinux|ArchLinux]] | partially -[[/etc/machine-info|http://0pointer.de/public/systemd-man/machine-info.html]] | File format | yes | yes | - | yes | - | partially -[[modules-load.d|http://0pointer.de/public/systemd-man/modules-load.d.html]] | File format | yes | yes | numerous | yes | - | partially -[[/usr/lib/os-release|http://0pointer.de/public/systemd-man/os-release.html]] | File format | yes | yes | some | yes | Fedora, OpenSUSE, [[ArchLinux|ArchLinux]], Angstrom, Frugalware, others... | no -[[sysctl.d|http://0pointer.de/public/systemd-man/sysctl.d.html]] | File format | yes | yes | some (it's a Debian thing) | yes | procps/Debian, [[ArchLinux|ArchLinux]] | partially -[[/etc/timezone|http://0pointer.de/public/systemd-man/timezone.html]] | File format | yes | yes | numerous (it's a Debian thing) | yes | Debian | partially -[[/etc/vconsole.conf|http://0pointer.de/public/systemd-man/vconsole.conf.html]] | File format | yes | yes | - | yes | [[ArchLinux|ArchLinux]] | partially -/run | File hierarchy change | yes | yes | numerous | yes | OpenSUSE, Debian, [[ArchLinux|ArchLinux]] | no -[[Generators|http://www.freedesktop.org/wiki/Software/systemd/Generators]] | Subprocess | yes | yes | - | no | - | no -[[System Updates|http://freedesktop.org/wiki/Software/systemd/SystemUpdates]] | System Mode | yes | yes | - | no | - | no -[[Presets|http://freedesktop.org/wiki/Software/systemd/Preset]] | File format | yes | yes | - | no | - | no -Udev rules | File format | yes | yes | numerous | no | no | partially -"""]] + +| API | Type | Covered by Interface Stability Promise | Fully documented | Known External Consumers | Reimplementable Independently | Known Other Implementations | systemd Implementation portable to other OSes or non-systemd distributions | +| --- | ---- | ----------------------------------------------------------------------------------------- | ---------------- | ------------------------ | ----------------------------- | --------------------------- | -------------------------------------------------------------------------- | +| [hostnamed](https://www.freedesktop.org/wiki/Software/systemd/hostnamed) | D-Bus | yes | yes | GNOME | yes | [Ubuntu](https://launchpad.net/ubuntu/+source/ubuntu-system-service), [Gentoo](http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml), [BSD](http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary) | partially | +| [localed](https://www.freedesktop.org/wiki/Software/systemd/localed) | D-Bus | yes | yes | GNOME | yes | [Ubuntu](https://launchpad.net/ubuntu/+source/ubuntu-system-service), [Gentoo](http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml), [BSD](http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary) | partially | +| [timedated](https://www.freedesktop.org/wiki/Software/systemd/timedated) | D-Bus | yes | yes | GNOME | yes | [Gentoo](http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml), [BSD](http://uglyman.kremlin.cc/gitweb/gitweb.cgi?p=systembsd.git;a=summary) | partially | +| [initrd interface](https://www.freedesktop.org/wiki/Software/systemd/InitrdInterface) | Environment, flag files | yes | yes | dracut, [ArchLinux](ArchLinux) | yes | [ArchLinux](ArchLinux) | no | +| [Container interface](https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface) | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no | +| [Boot Loader interface](https://systemd.io/BOOT_LOADER_INTERFACE) | EFI variables | yes | yes | gummiboot | yes | - | no | +| [Service bus API](https://www.freedesktop.org/wiki/Software/systemd/dbus) | D-Bus | yes | yes | system-config-services | no | - | no | +| [logind](https://www.freedesktop.org/wiki/Software/systemd/logind) | D-Bus | yes | yes | GNOME | no | - | no | +| [sd-login.h API](https://www.freedesktop.org/software/systemd/man/sd-login.html) | C Library | yes | yes | GNOME, [PolicyKit](PolicyKit), ... | no | - | no | +| [sd-daemon.h API](https://www.freedesktop.org/software/systemd/man/sd-daemon.html) | C Library or Drop-in | yes | yes | numerous | yes | - | yes | +| [sd-id128.h API](https://www.freedesktop.org/software/systemd/man/sd-id128.html) | C Library | yes | yes | - | yes | - | no | +| [sd-journal.h API](https://www.freedesktop.org/software/systemd/man/sd-journal.html) | C Library | yes | yes | - | maybe | - | no | +| [$XDG_RUNTIME_DIR](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) | Environment | yes | yes | glib, GNOME | yes | - | no | +| [$LISTEN_FDS $LISTEN_PID FD Passing](https://www.freedesktop.org/software/systemd/man/sd_listen_fds.html) | Environment | yes | yes | numerous (via sd-daemon.h) | yes | - | no | +| [$NOTIFY_SOCKET Daemon Notifications](https://www.freedesktop.org/software/systemd/man/sd_notify.html) | Environment | yes | yes | a few, including udev | yes | - | no | +| [argv[0][0]='@' Logic](https://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons) | /proc marking | yes | yes | mdadm | yes | - | no | +| [Unit file format](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) | File format | yes | yes | numerous | no | - | no | +| [Journal File Format](https://www.freedesktop.org/wiki/Software/systemd/journal-files) | File format | yes | yes | - | maybe | - | no | +| [Journal Export Format](https://www.freedesktop.org/wiki/Software/systemd/export) | File format | yes | yes | - | yes | - | no | +| [Cooperation in cgroup tree](https://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups) | Treaty | yes | yes | libvirt | yes | libvirt | no | +| [Password Agents](https://www.freedesktop.org/wiki/Software/systemd/PasswordAgents) | Socket+Files | yes | yes | - | yes | - | no | +| [udev multi-seat properties](https://www.freedesktop.org/wiki/Software/systemd/multiseat) | udev Property | yes | yes | X11, gdm | no | - | no | +| udev session switch ACL properties | udev Property | no | no | - | no | - | no | +| [CLI of systemctl,...](https://www.freedesktop.org/software/systemd/man/systemctl.html) | CLI | yes | yes | numerous | no | - | no | +| [tmpfiles.d](https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html) | File format | yes | yes | numerous | yes | [ArchLinux](ArchLinux) | partially | +| [sysusers.d](https://www.freedesktop.org/software/systemd/man/sysusers.d.html) | File format | yes | yes | unknown | yes | | partially | +| [/etc/machine-id](https://www.freedesktop.org/software/systemd/man/machine-id.html) | File format | yes | yes | D-Bus | yes | - | no | +| [binfmt.d](https://www.freedesktop.org/software/systemd/man/binfmt.d.html) | File format | yes | yes | numerous | yes | - | partially | +| [/etc/hostname](https://www.freedesktop.org/software/systemd/man/hostname.html) | File format | yes | yes | numerous (it's a Debian thing) | yes | Debian, [ArchLinux](ArchLinux) | no | +| [/etc/locale.conf](https://www.freedesktop.org/software/systemd/man/locale.conf.html) | File format | yes | yes | - | yes | [ArchLinux](ArchLinux) | partially | +| [/etc/machine-info](https://www.freedesktop.org/software/systemd/man/machine-info.html) | File format | yes | yes | - | yes | - | partially | +| [modules-load.d](https://www.freedesktop.org/software/systemd/man/modules-load.d.html) | File format | yes | yes | numerous | yes | - | partially | +| [/usr/lib/os-release](https://www.freedesktop.org/software/systemd/man/os-release.html) | File format | yes | yes | some | yes | Fedora, OpenSUSE, [ArchLinux](ArchLinux), Angstrom, Frugalware, others... | no | +| [sysctl.d](https://www.freedesktop.org/software/systemd/man/sysctl.d.html) | File format | yes | yes | some (it's a Debian thing) | yes | procps/Debian, [ArchLinux](ArchLinux) | partially | +| [/etc/timezone](https://www.freedesktop.org/software/systemd/man/timezone.html) | File format | yes | yes | numerous (it's a Debian thing) | yes | Debian | partially | +| [/etc/vconsole.conf](https://www.freedesktop.org/software/systemd/man/vconsole.conf.html) | File format | yes | yes | - | yes | [ArchLinux](ArchLinux) | partially | +| /run | File hierarchy change | yes | yes | numerous | yes | OpenSUSE, Debian, [ArchLinux](ArchLinux) | no | +| [Generators](https://www.freedesktop.org/software/systemd/man/systemd.generator.html) | Subprocess | yes | yes | - | no | - | no | +| [System Updates](https://www.freedesktop.org/software/systemd/man/systemd.offline-updates.html) | System Mode | yes | yes | - | no | - | no | +| [Presets](https://freedesktop.org/wiki/Software/systemd/Preset) | File format | yes | yes | - | no | - | no | +| Udev rules | File format | yes | yes | numerous | no | no | partially | ### Explanations From b2eea3dc325e8bcf680e09e08488600380334000 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 12 Jan 2020 18:17:50 +0100 Subject: [PATCH 5/7] docs: say that all documented programs in $PATH are stable --- docs/PORTABILITY_AND_STABILITY.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index 6bc55d7177..ee771592b6 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -11,7 +11,7 @@ systemd provides various interfaces developers and programs might rely on. Start The stable interfaces are: * **The unit configuration file format**. Unit files written now will stay compatible with future versions of systemd. Extensions to the file format will happen in a way that existing files remain compatible. -* **The command line interface** of systemctl, loginctl, journalctl. We will make sure that scripts invoking these commands will continue to work with future versions of systemd. Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page. Example: the output of "systemctl status" is not stable, but the one of "systemctl show" is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page. +* **The command line interface** of `systemd`, `systemctl`, `loginctl`, `journalctl`, and all other command line utilities installed in `$PATH` and documented in a man page. We will make sure that scripts invoking these commands will continue to work with future versions of systemd. Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page. Example: the output of `systemctl status` is not stable, but that of `systemctl show` is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page. * **The protocol spoken on the socket referred to by $NOTIFY_SOCKET**, as documented in (sd_notify(3))[https://www.freedesktop.org/software/systemd/man/sd_notify.html]. * Some of the **"special" unit names** and their semantics. To be precise the ones that are necessary for normal services, and not those required only for early boot and late shutdown, with very few exceptions. To list them here: `basic.target`, `shutdown.target`, `sockets.target`, `network.target`, `getty.target`, `graphical.target`, `multi-user.target`, `rescue.target`, `emergency.target`, `poweroff.target`, `reboot.target`, `halt.target`, `runlevel[1-5].target`. * For a more comprehensive and authoritative list, consult the chart below. @@ -24,7 +24,7 @@ The following interfaces will not necessarily be kept stable for now, but we wil The following interfaces are considered private to systemd, and are not and will not be covered by any stability promise: -* **Undocumented switches** to systemd, systemctl and otherwise. +* **Undocumented switches** to `systemd`, `systemctl` and otherwise. * **The internal protocols** used on the various sockets such as the sockets `/run/systemd/shutdown`, `/run/systemd/private`. One of the main goals of systemd is to unify basic Linux configurations and service behaviors across all distributions. Systemd project does not contain any distribution-specific parts. Distributions are expected to convert over time their individual configurations to the systemd format, or they will need to carry and maintain patches in their package if they still decide to stay different. From ef0bea8cf4f1615df0ec47a7ec854862841ec2cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 12 Jan 2020 18:32:40 +0100 Subject: [PATCH 6/7] docs: say that dbus api is stable (but list various caveats) I removed the part about sysv compat, because that has already been removed and we don't make any use of conditional dbus interfaces afaict. --- docs/PORTABILITY_AND_STABILITY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index ee771592b6..ceb82dba3c 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -14,11 +14,11 @@ The stable interfaces are: * **The command line interface** of `systemd`, `systemctl`, `loginctl`, `journalctl`, and all other command line utilities installed in `$PATH` and documented in a man page. We will make sure that scripts invoking these commands will continue to work with future versions of systemd. Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page. Example: the output of `systemctl status` is not stable, but that of `systemctl show` is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page. * **The protocol spoken on the socket referred to by $NOTIFY_SOCKET**, as documented in (sd_notify(3))[https://www.freedesktop.org/software/systemd/man/sd_notify.html]. * Some of the **"special" unit names** and their semantics. To be precise the ones that are necessary for normal services, and not those required only for early boot and late shutdown, with very few exceptions. To list them here: `basic.target`, `shutdown.target`, `sockets.target`, `network.target`, `getty.target`, `graphical.target`, `multi-user.target`, `rescue.target`, `emergency.target`, `poweroff.target`, `reboot.target`, `halt.target`, `runlevel[1-5].target`. +* **The D-Bus interfaces of the main service daemon and other daemons**. We try to always preserve backwards compatiblity, and intentational breakage is never introduced. Nevertheless, when we find bugs that mean that the existing interface was not useful, or when the implementation did something different than stated by the documentation and the implemented behaviour is not useful, we will fix the implementation and thus introduce a change in behaviour. But the API (parameter counts and types) is never changed, and existing attributes and methods will not be removed. * For a more comprehensive and authoritative list, consult the chart below. The following interfaces will not necessarily be kept stable for now, but we will eventually make a stability promise for these interfaces too. In the meantime we will however try to keep breakage of these interfaces at a minimum: -* **The D-Bus interfaces of the main service daemon** (!) [ An additional restriction applies here: functionality we consider legacy might not be available based on compile-time options, such as SysV support, libwrap support and similar. Apps should not assume properties and methods related to this functionality are unconditionally available in the D-Bus interfaces. ] * **The set of states of the various state machines used in systemd**, e.g. the high-level unit states inactive, active, deactivating, and so on, as well (and in particular) the low-level per-unit states. * **All "special" units that aren't listed above**. From d89cde0994745091cee920f2fd5bd090e35fefc7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 12 Jan 2020 19:03:32 +0100 Subject: [PATCH 7/7] docs: say that various cli progs are independent of pid1 --- docs/PORTABILITY_AND_STABILITY.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/PORTABILITY_AND_STABILITY.md b/docs/PORTABILITY_AND_STABILITY.md index ceb82dba3c..1a3b821181 100644 --- a/docs/PORTABILITY_AND_STABILITY.md +++ b/docs/PORTABILITY_AND_STABILITY.md @@ -128,3 +128,26 @@ If you decide to reimplement one of the APIs for which "Reimplementable independ This is not an attempt to comprehensively list all users of these APIs. We are just listing the most obvious/prominent ones which come to our mind. Of course, one last thing I can't make myself not ask you before we finish here, and before you start reimplementing these APIs in your distribution: are you sure it's time well spent if you work on reimplementing all this code instead of just spending it on adopting systemd on your distro as well? + +## Independent operation of systemd programs + +Some programs in the systemd suite are indended to operate independently of the +running init process (or even without an init process, for example when +creating system installation chroots). They can be safely called on systems with +a different init process or for example in package installation scriptlets. + +The following programs currently and in the future will support operation +without communicating with the `systemd` process: +`systemd-escape`, +`systemd-id128`, +`systemd-path`, +`systemd-tmpfiles`, +`systemd-sysctl`, +`systemd-sysusers`. + +Many other programs support operation without the system manager except when +the specific functionality requires such communication. For example +`journalctl` operates almost independently, but will query the boot id when +`--boot` option is used. `systemd-journal-remote`, `systemd-journal-upload`, +`systemd-journal-gatewayd`, `coredumpctl`, `busctl`, `systemctl --root` also +fall into this category.