Bureaucrats, dave_user, Administrators
8,154
edits
Changes
no edit summary
{{AppliesToAxelEsatta}}
{{AppliesToAxelLite}}
{{AppliesToAXEL Lite AN}}
{{AppliesToSMARX AN}}
{{AppliesToSBCX}}
{{AppliesToSBC Axel AN}}
{{InfoBoxBottom}}
systemd is a ''System and Service Manager'' which has enough different settings and configuration from SystemV(SysV) which was used on all XELK BSPs up to [[Axel_Embedded_Linux_Kit_(XELK)#XELK_3.0.0|XELK 3.0.0]].
{{ImportantMessage|text=This application note '''is not a complete systemd user's guide''' but collects some useful hints that can be used for getting familiar with systemd. There is a plenty of documentation and User's Guide available for systemd, but some simple example examples - that can be found here below - may simplify the systemd approach for beginners.}}
== Brief description Architecture ==systemd manages not only services but many different objects called '''Unit'''Here below, a picture (from [https://en.wikipedia. Unit are related to org/wiki/Systemd#Core_components_and_libraries wikipedia]) showing the resources that main systemd can manage. Unit configurations are defined into the ''Unit files''components: [[File: Systemd_components.png]]
== Services = Manage services ===
<code>systemctl</code> is a the main command line utility and primary tool to manage for managing the systemd daemons/services such as ''start, restart, stop, enable, disable, reload & status''.
It is possible to display all '''started''' services with the following userspace command:
systemctl -t service --all
==== 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>.
</pre>
== Targets == 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 by systemd for having a synchronization 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:
<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 targets with:
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:
This section is used for defining the metadata and relations between different ''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.
|}
==== 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:
! 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"
|}
=== Creating 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
The following paragraph shows how to create a new service called '''myservice''' <code>iperf3</code> executing a the iperf3 command (in our case ''iperf3''):server mode
/etc/systemd/system/myserviceiperf3.service
<pre>
[Unit]
Description=My Serviceiperf3 server mode
After=network.target
StartLimitIntervalSec=0
</pre>
{| class="wikitable"
|-
! Value Parameter !! Severity !! Keyword |-| 0 || Emergency || emerg |-| 1 || Alert || alert Description
|-
| 2After || Critical || crit The executed command (''iperf3'') requires the network interface to be already active, so we use <code>After</code> for this purpose.
|-
| 3Restart || Error || err This is configured with ''0'' for disabling the service after it has been run.
|-
| 4RestartSec || Warning || warning time sleep before restarting the service; default value is 100ms.
|-
| 5User || Notice || notice configures the ''user'' or ''group'' used for executing the service.
|-
| 6ExecStart || Information || info command to be executed when the service will be started (in our case ''iperf3'').
|-
| 7WantedBy || Debug || debug defines which target is used related to the service started.
|}
Starting the service at boot time:
