InterfaceStabilityPromise (original) (raw)

Back to systemd

This page has been obsoleted and replaced: https://systemd.io/PORTABILITY_AND_STABILITY/.

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).
• 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 Interface Portability And Stability Chart

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.