Fedora systemd Services

Unit files for traditional services have a naming scheme of foobar.service. When considering what basename to use, keep in mind that we’d like to use the same service names for software across distributions. We’d also like to ship the .service files in the upstream packages. These desires create a few guides for naming a unit file:

For backwards compatibility you may also want to create a symlink from an older, name to the new name. In the above example, for instance, Fedora has always used httpd for the service. When creating the new apache-httpd.service file, also create a symlink named httpd.service that points at apache-httpd.service. Then end users that are used to using service httpd will have it continue to work.

The EnvironmentFiles= line in the [Service] section of .service files is used to support loading environment variables that can be used in unit files. For instance, if your sysv-initscript used a file in /etc/sysconfig to set command line options, you can use EnvironmentFiles= like so:

Example:

You may then refer to variables set in the /etc/sysconfig/httpd file with ${FOOBAR} and $FOOBAR, in the ExecStart= lines (and related lines). (${FOOBAR} expands the variable into one word, $FOOBAR splits up the variable value at whitespace into multiple words)

The - on the EnvironmentFile= line ensures that no error messages is generated if the environment file does not exist. Since many of these files were optional in sysvinit, you should include the - when using this directive.

For most services, we do not want to use requirement dependencies in the [Unit] section, such as Requires= or Wants=. Instead exclusively use ordering dependencies: Before= and After=. This is used to implement loose coupling: if someone asks two services to start at the same time, systemd will properly order their startup but not make it strictly necessary to run one if the other is started.

If you use a requirement dependency, use Wants= rather than Requires=, to make things a little bit more robust. If you use a requirement dependency in almost all cases you should also add an ordering dependency, as ordering and requirement dependencies are orthogonal in systemd.

Here’s an example of this common case:

Avoid referring to runlevelX.target units in all lines taking unit names (such as WantedBy), these are legacy names existing for compatibility with SysV only.

Avoid Names= (in the [Unit] section). Usually it is a better idea to symlink an additional name in the file system. Note that a name listed in Names= is only useful when a service file is already loaded. However, systemd loads only the service files actually referred to in another loaded service, and uses the filenames during the search. Hence a name in Names= is not useful as a search key, but a symlink in the file system is. Also do not put a (redundant) Names=foobar.service line into a file called foobar.service. We want to keep our service files short.

Unit files should avoid using StandardOutput= or StandardError=. The default is the right choice for almost all cases, and using the default allows users to change global defaults in /etc/systemd/system.conf.

This is an example systemd unit .service file for ABRT:

Hardware activation occurs when a service is installed but only turns on if a certain type of hardware is installed. Enabling of the service is normally done with a udev rule. At this time we do not have further guidance on how to write those udev rules. The service itself installs its .service files in the normal places and are installed by the normal systemd scriptlets. These services should never be enabled by the package as they will be enabled by udev.

Socket activation occurs when a service allows systemd to listen for connections to a specific socket and, when systemd receives a connection on that socket, it starts the service. To do this, the upstream source needs to have some minor coding work to let systemd listen for connections on the socket and there needs to be a .socket file in %{_lib}/systemd/system/ that tells systemd to listen to that socket and what to start when a connection is received. This is similar in function to inetd and some, but not all, services coded to work with inetd will work with socket activation.

However, socket activation can also be used to allow parallel startup of services. If a service supports systemd socket activation as described above and we additionally start it explicitly on boot, then systemd will start it but allow things that depend on it to startup at the same time. If the dependent service makes a request to the socket activatable service before it has come up, then systemd will cause the request to wait until the socket activatable service has come up and can process the request. To achieve this effect, the service must be socket activatable as described above, the .service file for the service needs to have a Wants= line for the .socket, and the service must autostart.

Note that certain socket activated services (notably network listening ones) require FESCo approval — see Default Services for details. Once you have permission, you can package the .socket file and use the systemd scriptlets that enable the service by default. You need to also check the .service file to make sure it has a Wants= entry on the .socket file as that ensures that starting the service will also inform systemd of the socket.

All packages with timed execution which already depend on systemd (for example because they contain systemd units) must use timer units instead of cron jobs, with no dependency or requirements on a crontab.

Packages which do not already depend or require systemd must not use timer units but instead depend and have requirement on crontabs, to avoid introducing unnecessary new dependencies on systemd directly.

In order to allow parallel startup of a D-Bus service and its consumers it is essential that D-Bus services can be bus activated and the D-Bus activation request is forwarded from the D-Bus system bus to systemd so that you end up with only a single instance of the service, even if a service is triggered by both boot-up and activation. If historically your D-Bus service was not bus-activated but started via a SysV init script, it should be updated to use bus activation. This may be implemented by dropping a D-Bus .service file in /usr/share/dbus-1/system-services/ and use the SystemdService= directive therein to redirect the activation to systemd.

Here’s an example for a D-Bus bus-activable service. The ConsoleKit bus activation file /usr/share/dbus-1/system-services/org.freedesktop.ConsoleKit.service:

And the matching systemd unit file /usr/lib/systemd/system/console-kit-daemon.service:

As you can see SystemdService= is used in the D-Bus activation file to bind the systemd service to the D-Bus service.

Traditionally, bus activated D-Bus services could not be disabled without uninstalling them entirely. systemd allows you to disable services by making D-Bus invoke an alias systemd service name (that can be created or removed to enable/disable activation) as an intermediary for the real service.

You can easily implement disabling by directing the D-Bus service to an alias name of the real service file (in the filesystem this shows up as a symlink placed in /etc/systemd/system to the real service file). This alias is then controlled via systemctl enable and systemctl disable. It is a good idea (though technically not necessary) to name this alias name after the D-Bus bus name of the service, prefixed with dbus-. Example for Avahi, a service that the admin might need to disable: set SystemdService=dbus-org.freedesktop.Avahi.service instead of SystemdService=avahi-daemon.service in the D-Bus activation file, and then make dbus-org.freedesktop.Avahi.service an optional alias of avahi-daemon.service that can be controlled via the Alias= directive in the [Install] section of the systemd service file. This directive is then read by systemctl enable and systemctl disable to create resp. remove a symlink to make the service available resp. unavailable under this additional name. A full example for the Avahi case:

Here is the D-Bus .service file for Avahi (/usr/share/dbus-1/system-services/org.freedesktop.Avahi.service):

Here is the Avahi systemd unit .service file (/usr/lib/systemd/system/avahi-daemon.service):

The Alias= line ensures that the existance of the /etc/systemd/system/dbus-org.freedesktop.Avahi.service symlink can be controlled by systemctl enable and systemctl disable.

Note that the creation/removal of the alias symlinks should be done with systemctl enable and systemctl disable only. You should not create these symlinks manually.

In general, it is also recommended to supply native systemd units for all services that are already bus activatable, so that these services can be controlled and supervised centrally like any other service with tools such as systemctl. A similar logic like the one shown above should apply.

See the D-Bus documentation for more information about bus activation: https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services

Packages with systemd unit files must put them into %{_unitdir} or %{_userunitdir}. %{_unitdir} evaluates to /usr/lib/systemd/system on all Fedora systems and %{_userunitdir}% evaluates to /usr/lib/systemd/user. Unit files are architecture independent (hence, not %{_lib}) and needed early in the boot process. Most systemd service files should use %{_unitdir}. However, if the service runs as part of a user session (e.g. pipewire services, gpg-agent, tracker, etc), use %{_userunitdir} instead.

Please note that in order for the %{_unitdir} or %{_userunitdir} macro to exist, your package must have:

Systemd unit .service files must not be marked as %config files.

Information on proper handling of unit files in spec file scriptlets can be found here: Scriptlets#Systemd.

tmpfiles.d is a service provided systemd for managing temporary files and directories for daemons. For more information on how to use Tmpfiles.d in Fedora Packages, please see: Tmpfiles.d.