Bureaucrats, dave_user, Administrators
8,157
edits
Changes
no edit summary
{{AppliesToAxelEsatta}}
{{AppliesToAxelLite}}
{{AppliesToAXEL Lite AN}}
{{AppliesToSMARX AN}}
{{AppliesToSBCX}}
{{AppliesToSBC Axel AN}}
{{InfoBoxBottom}}
{{ImportantMessage|text=This application note has been validated starting from the '''XELK 34.0.x0''' kit version.}}
==History==
Starting from [[Axel_Embedded_Linux_Kit_(XELK)#XELK_4.0.0|XELK 4.0.0]] the root file system generated by NXP Yocto recipes produces a root file system using [https://www.freedesktop.org/wiki/Software/systemd/ systemd].
{{ImportantMessage|text== Brief description ==Systemd, differing from SystemV, manages This application note '''is not only services a complete systemd user's guide''' but many different objects called Unitcollects some useful hints that can be used for getting familiar with systemd. Unit are related to the resources There is a plenty of documentation and User's Guide available for systemd, but some simple examples - that systemd can manage. Unit configurations are defined into be found here below - may simplify the ''Unit files''systemd approach for beginners.}}
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)with:
systemctl -t service --all
=== Other useful = service commands ====
Starting a service from userspace:
systemctl disable ''<service_name>''
==== mask a service ==== There is a third level for stopping a service other than ''stop'' and ''disable'': it is the command <code>mask</code>. It stops the service and it will not possible to start it again using ''start''. Using <code>systemctl</code> it is possbile to ''mask/unmask'' a service: <pre>root@imx6qxelk:~# systemctl mask emergencyCreated symlink /etc/systemd/system/emergency.service → /dev/null.</pre> If we will try to start it:<pre>root@imx6qxelk:~# systemctl start emergencyFailed to start emergency.service: Unit emergency.service is masked.</pre> In this way, the service will not be used as a dependency in the ''Unit'' The reverse command is <code>unmask</code>:<pre>root@imx6qxelk:~# systemctl unmask emergencyRemoved /etc/systemd/system/emergency.service.</pre> ==== Migrating from SystemV to systemd ==== ===== start ===== Considering a SystemV <code>script</code> executing the ''start()'' function as in the following example:<pre>start() { echo "Starting My Custom Service..." /usr/bin/myservice -D}</pre> The related command is executed in the custom service <code>/usr/bin/myservice</code> with the same '''-D''' parameter. It is possibile to use the <code>ExecStart=</code>: <pre>[Service]ExecStart=/usr/bin/myservice -D</pre> ===== restart ===== The same SystemV script may use special commands for restarting the service like <code>reboot()</code> function: <pre>reboot() { echo "Reloading My Custom Service..." /usr/bin/myservice reload}</pre> which is equivalent to use <code>ExecReload=</code>: <pre>[Service]ExecReload=/usr/bin/myservice reload</pre> ===== stop ===== The <code>stop()</code> function in the script will become <code>ExecStop=</code>: SystemV: <pre>stop() { echo "Stopping My Custom Service..." /usr/bin/myservice shutdown}</pre> systemd: <pre>[Service]ExecStop=/usr/bin/myservice shutdown</pre> === Configuring the network interfaces=== One of the most systemd configuration used is the '''Network configuration'''. ==== Wired interface ====systemd uses a slightly different configuration mechanism than SystemV. The configuration file is the following one with an example of configuration: /etc/systemd/network/eth0.network <pre>[Match]Name=eth0 # Prevent the interface loading if the kernel boots from nfsKernelCommandLine=!nfsroot [Network]Address=192.168.0.120Gateway=192.168.0.254DNS=192.168.0.1#DNS=8.8.8.8 </pre> '''Note:''' The DNS is used only if the <code>systemd-resolved</code> service is enabled and the <code>/etc/resolv.conf</code> has a symbolic link to <code>/run/systemd/resolve/stub-resolv.conf</code> <pre>ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf</pre> ==== Wireless interface ==== ===== wpa_supplicant =====wpa_supplicant provides different services on systemd: * <code>wpa_supplicant.service</code> uses D-Bus, recommended with the ''NetworkManager''* <code>wpa_supplicant@interface.service</code> uses the interface name (like ''wlan0'') as parameter and executes the wpa_supplicant daemon on that interface. The configuration file is <code>/etc/wpa_supplicant/wpa_supplicant-interface.conf</code> For enabling the interface at boot time it is required to ''enable'' the service: systemctl enable wpa_supplicant@interface ===== wlan configuration example ===== Assuming ''wlan0'' as the wireless interface name, the configuration file examples are the following one: /etc/systemd/network/wlan0.network <pre>[Match]Name=wlan0[Network]# Uncomment for DHCP#DHCP=yesAddress=192.168.1.120Gateway=192.168.1.254DNS=8.8.8.8 </pre> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf <pre>ctrl_interface=/var/run/wpa_supplicanteapol_version=1ap_scan=1fast_reauth=1 network={ ssid="SSID1" psk="password1" priority=1}network={ ssid="SSID2" psk="password2" priority=2}</pre> For automatically creating the network configuration, the following command can be used: wpa_passphrase <ESSID> <passphrase> >> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf Then, the service should be enabled on the ''wlan0'' interface for let systemd to start it using the (just) created configuration file <code>wpa_supplicant-wlan0.conf</code>: systemctl enable wpa_supplicant@wlan0 == Logging with systemd (<code>journalctl</code>) == systemd has its own logging process called <code>journal</code> avoiding to start the ''syslog'' daemon. For the status information it is possible to use <code>journalctl</code>. <code>journalctl</code> ha many command line switches, to customize its behavior and filter log data (a good reference can be found [https://www.digitalocean.com/community/tutorials/how-to-use-journalctl-to-view-and-manipulate-systemd-logs here] For example, to display the new log messages (similar to <code>tail -f /var/log/messages</code>) add the <code>-f</code> option With <code>-p</code> it's possible to set the log ''priority'' journalctl -p LEVEL Where <code>LEVEL</code> can be the number or keyword of the following table (sorted from higher to lower priority). Specifying a priority will display messages marked with that priority or higher {| class="wikitable"|-! Value !! Keyword |-| 0 || emerg |-| 1 || alert |-| 2|| crit |-| 3|| err |-| 4|| warning |-| 5|| notice |-| 6|| info |-| 7|| debug |}''<time>''User can filter by arbitrary time limits using the <code>--since</code> and <code>--until</code> options, which restrict the entries displayed to those after or before the given time, respectively. E.g.: <pre>root@imx6qxelk:/home# journalctl --since "20 min ago" -- Logs begin at Wed 2019-06-26 13:22:41 UTC, end at Mon 2019-07-08 13:22:01 UTC. --Jul 08 13:11:54 imx6qxelk kernel: ERROR: v4l2 capture: slave not found!Jul 08 13:11:54 imx6qxelk kernel: ERROR: v4l2 capture: slave not found!Jul 08 13:11:54 imx6qxelk kernel[551]: [ 3157.796945] ERROR: v4l2 capture: slave not found!Jul 08 13:11:54 imx6qxelk kernel[551]: [ 3157.801690] ERROR: v4l2 capture: slave not found!Jul 08 13:11:54 imx6qxelk kernel: ERROR: v4l2 capture: slave not found!Jul 08 13:11:54 imx6qxelk kernel: ERROR: v4l2 capture: slave not found!Jul 08 13:11:54 imx6qxelk kernel[551]: [ 3157.859371] ERROR: v4l2 capture: slave not found!Jul 08 13:11:54 imx6qxelk kernel[551]: [ 3157.864406] ERROR: v4l2 capture: slave not found!</pre> For displaying the log related to a specific ''Unit'', use the <code>-u</code> option, e.g.: <pre>root@imx6qxelk:/home# journalctl -u systemd-networkd -- Logs begin at Wed 2019-06-26 13:22:41 UTC, end at Mon 2019-07-08 13:25:01 UTC. --Jul 05 11:02:13 imx6qxelk systemd-networkd[572]: Enumeration completedJul 05 11:02:13 imx6qxelk systemd-networkd[572]: eth0: IPv6 enabled for interface: SuccessJul 05 11:02:15 imx6qxelk systemd-networkd[572]: eth0: Gained carrierJul 05 11:02:16 imx6qxelk systemd-networkd[572]: eth0: Gained IPv6LLJul 05 11:02:29 imx6qxelk systemd-networkd[572]: eth0: Configured</pre> For displaying the log related to a specific <code>/dev</code> device, just add it to the command line: <pre>root@imx6qxelk:~# journalctl /dev/fb0-- Logs begin at Wed 2019-06-26 13:22:41 UTC, end at Thu 2019-07-11 09:07:01 UTC. --Jun 26 13:22:41 imx6qxelk kernel: mxc_sdc_fb fb@0: registered mxc display driver ldbJun 26 13:22:41 imx6qxelk kernel: mxc_sdc_fb fb@0: using reserved memory region at 0x8e000000, size 2 MiBJun 26 13:22:41 imx6qxelk kernel: mxc_sdc_fb fb@0: assigned reserved memory node splashscreenJun 26 13:22:41 imx6qxelk kernel: mxc_sdc_fb fb@0: using memory region 0x8e000000 0x8e1fffff</pre> For displaying the log related to a user ID, use <code>_UID=</code> parameter <pre>root@imx6qxelk:~# id messagebusuid=995(messagebus) gid=993(messagebus) groups=993(messagebus)root@imx6qxelk:~# journalctl _UID=993-- Logs begin at Wed 2019-06-26 13:22:41 UTC, end at Thu 2019-07-11 09:14:01 UTC. --Jul 10 14:42:48 imx6qxelk systemd-timesyncd[423]: Network configuration changed, trying to establish connection.Jul 10 14:43:02 imx6qxelk systemd-timesyncd[423]: Network configuration changed, trying to establish connection.Jul 11 07:38:31 imx6qxelk systemd-timesyncd[423]: Synchronized to time server 216.239.35.8:123 (time3.google.com).</pre> == Analyze the boot time== Boot time analysis is one of the most important and interesting activity for an embedded system: systemd provide an userspace command called <code>systemd-analyze</code> to help in this (hard) task The <code>systemd-analyze</code> command list how many services are running on the system and how long they took for starting at the last boot. <code>systemd-analyze</code> provides a good level of boot time information for further optimizations: === time === The <code>time</code> parameter gives the total amount of seconds used for starting the kernel and reaching the userspace. <pre>root@imx6qxelk:~# systemd-analyze time Startup finished in 5.109s (kernel) + 4.771s (userspace) = 9.880s</pre> === blame ===The <code>blame</code> parameter gives the list of started services and how long they took for starting: <pre>root@imx6qxelk:~# systemd-analyze blame 3.608s dev-mmcblk0p2.device 547ms systemd-remount-fs.service 545ms systemd-vconsole-setup.service 544ms kmod-static-nodes.service 503ms systemd-udev-trigger.service 426ms systemd-journal-flush.service 407ms tmp.mount 371ms systemd-logind.service 327ms systemd-journald.service 317ms systemd-networkd.service 275ms systemd-timesyncd.service 257ms systemd-sysctl.service 204ms ofono.service 203ms systemd-modules-load.service 194ms sys-kernel-config.mount 188ms sys-kernel-debug.mount 177ms sshd.socket 161ms psplash-start.service 138ms systemd-random-seed.service 138ms sys-fs-fuse-connections.mount 129ms systemd-udevd.service 129ms systemd-update-utmp.service 128ms systemd-tmpfiles-setup-dev.service 124ms rc-local.service 98ms systemd-tmpfiles-setup.service 91ms psplash-quit.service 90ms systemd-resolved.service 89ms systemd-backlight@backlight:backlight.service 63ms dev-mmcblk0p1.device 41ms var-volatile.mount 33ms systemd-update-utmp-runlevel.service</pre> === critical-chain ===The <code>critical-chain</code> parameter shows the startup process flow and the time consumed by each service. Here below a picture showing an example of critical path: [[File:Systemd-analyze-critical-chain.png|800px]] == Services and targets ==systemd 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 interesting Units are '''services''' and '''targets'''. They will be analyzed in the following paragraphs. === Targets ===
Targets are used byt by systemd for having a synchronization point mechanism between different services at boot time or during runtime run-time 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:
{| class="wikitable"
|-
! Function Description !! SystemV (runlevel) !! Systemd systemd (target)
|-
| System halt || 0 || runlevel0.target, poweroff.target
<code>multi-user</code> target can be identified as the <code>runlevel 3</code>.
/etc/systemd/system/''<target_name>''.target.wants
For example:
</pre>
==== Active targets ====
It is possible to display all active targtes targets with:
systemctl -t target
systemctl set-default multi-user
=== Unit files ===
For a complete information on '''Unit''' please look to the [https://www.freedesktop.org/software/systemd/man/systemd.unit.html 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 behaviour:
{| class="wikitable"
|-
! Path !! Description
|-
| <code>/lib/systemd/system</code> || 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 by the user.
|-
| <code>/etc/systemd/system</code> || 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.
|-
| <code>/run/systemd/system</code> || The files present in this directory have higher priority only respect the ones on <code>/lib/systemd/system</code>.
Systemd creates these configuration files dinamically 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 options ====
This section is used for defining the metadata and relations between different ''Unit''
Please find below the main properties description:
{| class="wikitable"
|-
! Property !! Function
|-
| Description=: || Name and function
|-
| Documentation=: || URI for the documentationvv
|-
| Requires=: || List of ''Units'' dependencies. For successfully 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 executed anyway. this is the recommended method to be used.
|-
| BindsTo=: || Similar to ''Requires'' but it does a Stop 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 will 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 options ====
This section is optional but is commonly used for defining a ''Unit'' behaviour when it will be executed during ''enable'' or ''disable'' commands.
{| class="wikitable"
|-
! Property !! Function
|-
| WantedBy=: || This is similar to the <code>Wants=</code> on ''[Unit]'' section but allows to mantain the top ''Unit'' more ''clean''.
When the ''Unit'' will be enabled, a directory on <code>/etc/systemd/system</code> will be created with the ''Unit'' name adding <code>.wants</code> to the name. Inside this directoty a symbolic link to the ''Unit'' is created.
Example:
* current ''Unit'' has <code>WantedBy=multi-user.target</code>
* a directory <code>/etc/systemd/system/multi-user.target.wants</code> will be created
* the symbolic link to the ''Unit'' will be created inside the new directory
* disabling the ''Unit'' the symbolic link is deleted and the relation is then removed.
|-
| RequiredBy=: || This is similar to <code>WantedBy=</code> 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 <code>.service</code>
Please find more information at the [https://www.freedesktop.org/software/systemd/man/systemd.service.html# documentation page]
===== [Service] section =====
Used for providing configurations for the ''services''.
====== Type ======
<code>Type=</code> uses one of the (main) following values:
{| class="wikitable"
|-
! Value !! Description
|-
| simple || Default configuration for a service when specified <code>ExecStarts=</code>
|-
| forking || the process will call a <code>fork()</code> 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 <code>ExecStarts=</code> 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 ======
{| class="wikitable"
|-
! Value !! Description
|-
| 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=: || used for adding more commands to be executed before starting the main process. May be used multiple times specifying the complete path and command parameters.
|-
| 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 <code>TimeoutStartSec=</code> and <code>TimeoutStopSec=</code>
|}
== Putting it all together: create a new service ==
For creating a new service the following file has to be created:
/etc/systemd/system/''<service_name>''.service
=== Service example ===
The following paragraph shows how to create a new service called <code>iperf3</code> executing the iperf3 command in server mode
/etc/systemd/system/iperf3.service
<pre>
[Unit]
Description=iperf3 server mode
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=0
RestartSec=1
User=root
ExecStart=/usr/bin/iperf3 -s
[Install]
WantedBy=multi-user.target
</pre>
=== Basic settings ===
{| class="wikitable"
|-
! Parameter !! Description
|-
| After || The executed command (''iperf3'') requires the network interface to be already active, so we use <code>After</code> for this purpose.
|-
| Restart || This is configured with ''0'' for disabling the service after it has been run.
|-
| RestartSec || time sleep before restarting the service; default value is 100ms.
|-
| User || configures the ''user'' or ''group'' used for executing the service.
|-
| ExecStart || command to be executed when the service will be started (in our case ''iperf3'').
|-
| WantedBy || defines which target is used related to the service started.
|}
=== Running a service ===
Starting the service from userspace:
systemctl start iperf3
Starting the service at boot time:
systemctl enable iperf3
