XELK-AN-008: How to use systemd on an Embedded system

Info Box Applies to Axel Ultra Applies to AXEL ESATTA Applies to Axel Lite

This application note has been validated starting from the XELK 4.0.0 kit version.

History

Version	Date	XELK version	Notes
1.0.0	Sep 2019	4.0.0

Introduction

Starting from XELK 4.0.0 the root file system generated by NXP Yocto recipes produces a root file system using systemd.

Systemd is a System and Service Manager which has enough different settings and configuration from systemV which was used on all XELK BSPs up to XELK 3.0.0.

Brief description

Systemd, differing from SystemV, manages not only services but many different objects called Unit. Unit are related to the resources that systemd can manage. Unit configurations are defined into the Unit files.

Units categoris (identified by the file extension) are:

   .service
   .target
   .socket
   .device
   .mount
   .automount
   .swap
   .path
   .timer
   .snapshot
   .slice
   .scope

Major insteresting Units are services and targets. They will be analyzed in the following paragraphs.

Services

It is possible to display all started services with the following userspace command:

systemctl -t service

It is possible to display all services (including disabled and stopped services):

systemctl -t service --all

Other useful service commands

Starting a service from userspace:

systemctl start <service_name>

Stopping a service from userspace

systemctl stop <service_name>

Starting a service at boot time:

systemctl enable <service_name>

Disabling service (already started at boot time):

systemctl disable <service_name>

Targets

Targets are used byt systemd for having a synchronization point between different services at boot time or during runtime changes.

They can be used for set the system to a new state.

All services linked to a target are linked to the modification to the same target. These can be seen in a similar way of SystemV runlevels with many other added functionalities.

Target and runlevels

Here below there is a list of power on/off targets and related SystemV runlevels:

Description	SystemV (runlevel)	Systemd (target)
System halt	0	runlevel0.target, poweroff.target
Single user mode	1, s, single	runlevel1.target, rescue.target
Multi user	2	runlevel2.target, multi-user.target
Multi user with network	3	runlevel3.target, multi-user.target
Experimental	4	runlevel4.target, multi-user.target
Multi user with network, graphical mode	5	runlevel5.target, graphical.target
Reboot	6	runlevel6.target, reboot.target

multi-user target can be identified as the runlevel 3.

On the

/etc/systemd/system/<target_name>.target.wants

directory there is a list of services related to that target.

For example:

root@imx6qxelk:~# ls /etc/systemd/system/multi-user.target.wants/
atd.service	       busybox-syslog.service  gpuconfig.service  ofono.service		systemd-networkd.service
avahi-daemon.service   connman.service	       mytest.service	  psplash-quit.service	systemd-resolved.service
busybox-klogd.service  crond.service	       ntpdate.service	  remote-fs.target

Active targets

It is possible to display all active targtes with:

systemctl -t target

Changing a target

systemctl isolate graphical

The actual target is shown with:

systemctl get-default

Changing the default target:

systemctl set-default multi-user

Unit files

For a complete information on Unit please look to the documentation page

Here below you can find an extract for the main used topics and configuration descriptions.

Location Path

Units are configured by systemd using configuration files that can be found in different directories. Each of them has different priority and bahaviour:

• /lib/systemd/system

This directory stores a copy of configuration files. This is the default destination for new installed configuration file. Typically files in this directory should not be modified bye the user.

• /etc/systemd/system

This is the directory where to store a new Unit or to modify an existing one. The files present in this directory have the highest priority.

• /run/systemd/system

The files present in this directory have higher priority only respect the ones on /lib/systemd/system. Systemd creates these configuration files dinamcally at runtime; modification on this directory can be used for testing a runtime behaviour for a Unit but all modifications will be lost at next boot.

[Unit] section

This section is used for defining the metadata and relations between different Unit

Please find below the main properties description:

Description=: 

Name and function

Documentation=: 

URI for the documentation

Requires=:

List of Units dependencies. For succesfully executing this Unit, all listed dependency should be activated without errors, otherwise this Unit return fail.

Wants=:

Similar to a Requires but weaker. If the Unit listed are not found or return fail, this Unit are in any case executed. this is the recommended method to be used.

BindsTo=:

Similar to Requires but it does a Sop for the Unit when the listed Unit are terminated.

Before=:

The Unit listed will not be executed until this Unit will not change to started. This is used for an order of Units executions.

After=:

The Unit listed wile be started before this Unit. This is used for an order of Units executions.

Conflicts=

The Unit listed cannot be executed simultaneously to this Unit.

[Install] section

This section is optional but is comonly used for defining a Unit behaviour when it will be executed at boot time with enable command.

WantedBy=:

This is similar to the Wants= on [Unit] section but allows to mantain the top Unit more clean.

Wwhen the Unit will be enabled, a directory on /etc/systemd/system will be created with the Unit name adding .wants to the name. Inside this directotya symbolic link to the Unit is created.

Example:

• current Unit has WantedBy=multi-user.target
• a directory /etc/systemd/system/multi-user.target.wants will be created
• the symbolic link to the Unit will be created inside the new directoty
• disabling the Unit the symbolic link is deleted and the relation is then removed.

RequiredBy=:

This is similar to WantedBy= but a dependency cause a fail if not satisfied. When the Unit is enabled, a directory with added .requires will be created

Also=:

When the Unit is enabled, also the listed Units are enabled too.

Specific sections

Some Unit have specific sections based on their characteristic. The most important is the section [Service] related to the Unit .service

Please find more information at the documentation page

[Service] section

Used for providing configurations for the services.

Type

Type= should be set to :

simple:

Default configuration for a service when specified ExecStarts=

forking:

the process will call a fork() when starts causing the father to exit. This informs systemd that the process is still alive even if the father has been terminated.

oneshot:

the process has a very short execution time and then systemd should wait for its termination before continuing with other Units. this is the default configuration if ExecStarts= is not specified.

dbus:

the Unit will acquire the name on the D-Bus. systemd will continue to process the other Units

notify:

the service will notify when completely initialized. Systemd will wait for the notification before continuing with the following Units

idle:

the service will not be executed until all active jobs are dispatched.

Other options

ExecStarts=: 

Specifiy the full path and parameters for executing a service. If preceded by a "-" this inform that the command failure can be accepted.

ExecStartsPre=:

Può essere utilizzata per fornire comandi aggiuntivi che dovrebbero essere eseguiti prima del processo principale. Può essere usato multiple volte, deve specificare il percorso completo del comando e può essere usato anche qui il "-" per tollerare errori.

ExecReload=:

commands to be executed for reloading the service configuration.

ExecStop=:

commands required for stopping the service. If missing, the service will be killed.

ExecStopPost=:

commands to be executed after the service has been stopped..

RestartSec=:

time to sleep (seconds) before restarting the service.

Restart=:

restart conditions for systemd to be checked before restarting the service (if terminated). Can be set to "always","on-success", "on-failure", "on-abnormal", "on-abort", or "on-watchdog".

TimeoutSec=:

time to sleep during start or stop before considering the process failed on start or stop. Start and stop timeout can be set with different values using TimeoutStartSec= nad e TimeoutStopSec=