From b01a12a13531c56a336a399456cb71709bb1a549 Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Thu, 27 Apr 2023 17:30:05 +0200 Subject: manuals: expand init manager documentation - Add details about INIT_MANAGER Correct the fact that "none" currently generates an image with "sysvinit", at least on Poky. This behaviour should probably be changed. - Expand the "Selecting an Initialization Manager" section. - Stop mentioning "rescue image" generation, as this is not detailed anywhere else. (From yocto-docs rev: fd99f2753b50b7ad6133b787b90331fcb3a35152) Signed-off-by: Michael Opdenacker CC: Paul Eggleton Signed-off-by: Richard Purdie --- documentation/dev-manual/device-manager.rst | 2 + documentation/dev-manual/init-manager.rst | 108 ++++++++++++++++++---------- 2 files changed, 74 insertions(+), 36 deletions(-) (limited to 'documentation/dev-manual') diff --git a/documentation/dev-manual/device-manager.rst b/documentation/dev-manual/device-manager.rst index 4248c23b44..0343d19b9c 100644 --- a/documentation/dev-manual/device-manager.rst +++ b/documentation/dev-manual/device-manager.rst @@ -1,5 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK +.. _device-manager: + Selecting a Device Manager ************************** diff --git a/documentation/dev-manual/init-manager.rst b/documentation/dev-manual/init-manager.rst index 10c4754e62..fd8747b9b0 100644 --- a/documentation/dev-manual/init-manager.rst +++ b/documentation/dev-manual/init-manager.rst @@ -1,71 +1,107 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK +.. _init-manager: + Selecting an Initialization Manager *********************************** -By default, the Yocto Project uses SysVinit as the initialization -manager. However, there is also support for systemd, which is a full -replacement for init with parallel starting of services, reduced shell -overhead and other features that are used by many distributions. +By default, the Yocto Project uses :wikipedia:`SysVinit ` as +the initialization manager. There is also support for BusyBox init, a simpler +implementation, as well as support for :wikipedia:`systemd `, which +is a full replacement for init with parallel starting of services, reduced +shell overhead, increased security and resource limits for services, and other +features that are used by many distributions. + +Within the system, SysVinit and BusyBox init treat system components as +services. These services are maintained as shell scripts stored in the +``/etc/init.d/`` directory. -Within the system, SysVinit treats system components as services. These -services are maintained as shell scripts stored in the ``/etc/init.d/`` -directory. Services organize into different run levels. This -organization is maintained by putting links to the services in the -``/etc/rcN.d/`` directories, where `N/` is one of the following options: -"S", "0", "1", "2", "3", "4", "5", or "6". +SysVinit is more elaborate than BusyBox init and organizes services in +different run levels. This organization is maintained by putting links +to the services in the ``/etc/rcN.d/`` directories, where `N/` is one +of the following options: "S", "0", "1", "2", "3", "4", "5", or "6". .. note:: Each runlevel has a dependency on the previous runlevel. This dependency allows the services to work properly. +Both SysVinit and BusyBox init are configured through the ``/etc/inittab`` +file, with a very similar syntax, though of course BusyBox init features +are more limited. + In comparison, systemd treats components as units. Using units is a broader concept as compared to using a service. A unit includes several -different types of entities. Service is one of the types of entities. +different types of entities. ``Service`` is one of the types of entities. The runlevel concept in SysVinit corresponds to the concept of a target in systemd, where target is also a type of supported unit. -In a SysVinit-based system, services load sequentially (i.e. one by one) -during init and parallelization is not supported. With systemd, services -start in parallel. Needless to say, the method can have an impact on -system startup performance. +In systems with SysVinit or BusyBox init, services load sequentially (i.e. one +by one) during init and parallelization is not supported. With systemd, services +start in parallel. This method can have an impact on the startup performance +of a given service, though systemd will also provide more services by default, +therefore increasing the total system boot time. systemd also substantially +increases system size because of its multiple components and the extra +dependencies it pulls. -If you want to use SysVinit, you do not have to do anything. But, if you -want to use systemd, you must take some steps as described in the -following sections. +On the contrary, BusyBox init is the simplest and the lightest solution and +also comes with BusyBox mdev as device manager, a lighter replacement to +:wikipedia:`udev `, which SysVinit and systemd both use. -Using systemd Exclusively +The ":ref:`device-manager`" chapter has more details about device managers. + +Using SysVinit with udev ========================= -Set the :term:`INIT_MANAGER` variable in your distribution configuration -file as follows:: +SysVinit with the udev device manager corresponds to the +default setting in Poky. This corresponds to setting:: + + INIT_MANAGER = "sysvinit" + +Using BusyBox init with BusyBox mdev +==================================== + +BusyBox init with BusyBox mdev is the simplest and lightest solution +for small root filesystems. All you need is BusyBox, which most systems +have anyway:: + + INIT_MANAGER = "mdev-busybox" + +Using systemd +============= + +The last option is to use systemd together with the udev device +manager. This is the most powerful and versatile solution, especially +for more complex systems:: INIT_MANAGER = "systemd" This will enable systemd and remove sysvinit components from the image. -See ``meta/conf/distro/include/init-manager-systemd.inc`` for exact +See :yocto_git:`meta/conf/distro/include/init-manager-systemd.inc +` for exact details on what this does. -Using systemd for the Main Image and Using SysVinit for the Rescue Image -======================================================================== - -Set these variables in your distribution configuration file as follows:: +Controling systemd from the target command line +----------------------------------------------- - DISTRO_FEATURES:append = " systemd" - VIRTUAL-RUNTIME_init_manager = "systemd" +Here is a quick reference for controling systemd from the command line on the +target. Instead of opening and sometimes modifying files, most interaction +happens through the ``systemctl`` and ``journalctl`` commands: -Doing so causes your main image to use the -``packagegroup-core-boot.bb`` recipe and systemd. The rescue/minimal -image cannot use this package group. However, it can install SysVinit -and the appropriate packages will have support for both systemd and -SysVinit. +- ``systemctl status``: show the status of all services +- ``systemctl status ``: show the status of one service +- ``systemctl [start|stop] ``: start or stop a service +- ``systemctl [enable|disable] ``: enable or disable a service at boot time +- ``systemctl list-units``: list all available units +- ``journalctl -a``: show all logs for all services +- ``journalctl -f``: show only the last log entries, and keep printing updates as they arrive +- ``journalctl -u``: show only logs from a particular service Using systemd-journald without a traditional syslog daemon -========================================================== +---------------------------------------------------------- Counter-intuitively, ``systemd-journald`` is not a syslog runtime or provider, -and the proper way to use systemd-journald as your sole logging mechanism is to +and the proper way to use ``systemd-journald`` as your sole logging mechanism is to effectively disable syslog entirely by setting these variables in your distribution configuration file:: @@ -73,5 +109,5 @@ configuration file:: VIRTUAL-RUNTIME_base-utils-syslog = "" Doing so will prevent ``rsyslog`` / ``busybox-syslog`` from being pulled in by -default, leaving only ``journald``. +default, leaving only ``systemd-journald``. -- cgit v1.2.3-54-g00ecf