mirror of
https://github.com/systemd/systemd.git
synced 2024-12-22 17:35:35 +03:00
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.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
b8b7309778
commit
e4893c6306
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user