Crinit is an init daemon executed as PID 1 by the Linux Kernel. It reads a global configuration ("series"-file) either specified on the command line or from /etc/crinit/default.series. The series file in turn may reference further configuration files or a whole directory from which all configs shall be loaded. Each one defines a task potentially containing a set of commands and dependencies on other tasks.
The specified tasks are then started with as much parallelism as dependencies allow, i.e. tasks without any dependencies are spawned as soon as possible after Crinit has been started. Once a task is spawned, finished, or has failed, its dependent tasks are updated and spawned as necessary.
The below diagram shows the overall concept of Crinit.
Not indicated in the diagram are planned cryptographic features of the Config Parser intended to provide optional verification/integrity checking of the global and task configurations.
Crinit currently has the following features implemented:
crinit-ctl) capable ofsd_notify()In the future we also plan to support:
There are example configurations below which show how to use the currently implemented features. For detailed explanations of Crinit's inner workings please refer to the Doxygen documentation generated during build. The client API is documented in the Doxygen documentation of crinit-client.h. The API is implemented as a shared library (libcrinit-client.so).
This repository also includes an example application to generate a /etc/machine-id file, which is used to uniquely identify the system (for example by elosd). The machine-id-gen tool is supposed to be called on boot, for example from earlysetup.crinit as shown in the example configuration files contained in this repository. Its implementation either uses the value for systemd.machine_id given on the Kernel command line or – on an NXP S32G-based board – the unique ID burned to on-chip OTP memory. If the Kernel command line value is set, it always takes precedence and any physical memory OTP reads are omitted. This means that while the application has special functionality for S32G SoCs, it can work on any target as long as the Kernel command line contains the necessary value.
MIT License
Copyright (c) [2023] [emlix GmbH, Elektrobit Automotive GmbH]
The full text of the license can be found in the [LICENSE](LICENSE) file in the repository root directory.
Crinit is powered by Elektrobit Automotive GmbH.
Elektrobit is an automotive software company and developer of embedded software products for ECU, AUTOSAR, automated driving, connected vehicles and UX. Crinit is an integrated part of EB corbos Linux.
EB corbos Linux – built on Ubuntu - is an open-source operating system for high-performance computing, leveraging the rich functionality of Linux while meeting security and industry regulations.
The crinit logo is the Swallow (Hirundinidae). A quick and small bird able to fly long distances. Originator is Anja Lehwess-Litzmann (emlix GmbH). Year 2023. It is licensed under Creative Commons No Derivatives (CC-nd). It shall be used in black on white or HKS43 color.
Crinit is mainly configured via global and task-specific configuration files. There are, however, some specific options related to its behavior as a secondary init process (e.g. if crinit is started by another init process, or even itself). These options can only be changed through command-line parameters.
Specifically, those are
/dev - devtmpfs pseudo file system/dev/pts - devpts pseudo file system/proc - procfs filesystem, needed by Crinit to parse the Kernel cmdline/run - tmpfs, needed by Crinit to create its socket (default location)/sys - sysfs pseudo file system Default: Activated if Crinit is PID 1, otherwise deactivated.Crinit also respects the environment variable
CRINIT_SOCK - The path to the socket file Crinit will create for communication through libcrinit-client. Default: /run/crinit/crinit.sockNote that crinit-ctl uses the same environment variable to decide to which socket it will connect to. This makes it possible to have multiple instances of crinit running alongside each other, each controlled through a different socket.
As described above, Crinit needs a global series-file containing global configuration options as well as a list of task configurations. Examples for a local demonstration inside the build environment (see Build Instructions below) are available in config/test/ and examples to use as a starting point for a minimal system boot are available in config/example/.
The general format of crinit configuration files is INI-style KEY = value pairs. Some settings may be array-like, meaning they can be specified multiple times to append values. Leaving out the KEY = part at the start of the line in favor of at least one whitespace character is shorthand for appending to the last key, for example:
is equivalent to
An example to boot a minimal environment may look like this:
/etc/crinit.crinit.crinclYES or NO. Default: NOSTOP_COMMAND and SIGTERM as well as betweenSIGTERM and SIGKILL on shutdown/reboot. Default: 100000YES, Crinit will switch to syslog for output as soon as a task file PROVIDES the syslog feature. Ideally this should be a task file loading a syslog server such as syslogd or elosd. Default: NOYES, Crinit will allow Elos event filters as task dependencies with the @elos prefix as soon as a task file PROVIDES the elos feature. Ideally this should be a task file loading the Elos daemon elosd. Default is NO. Needs ELOS support included at build-time.127.0.0.1 Needs ELOS support included at build-time.54321 Needs ELOS support included at build-time.The network-dhcp.crinit from above could for example look like this:
network-dhcp:wait dependency is fulfilled) if the last command has successfully returned. If no COMMAND is given, the task is treated as a dependency group or "meta-task", see below. (array-like)crinit-ctl stop <TASKNAME>, crinit-ctl poweroff or crinit-ctl reboot instead of sending the regular SIGTERM. Same rules as for COMMAND apply. Additionally the variable "TASK_PID" can be used and will be expanded with the stored PID of the task. Example: STOP_COMMAND = /usr/bin/kill ${TASK_PID}. Please note that TASK_PID will expand to "-1" if the task is no longer running or has forked itself without notifying Crinit. ATTENTION: Currently STOP_COMMAND does not support IO_REDIRECT! Its output will not be redirected!<taskname>:{fail,wait,spawn}, where spawn is fulfilled when (the first command of) a task has been started, wait if it has successfully completed, and fail if it has failed somewhere along the way. Here we can see this task is only run if and after the earlysetup (setup of system directories, etc.) has fully completed and the check_qemu task has determined we are not running inside the emulator and therefore exited with an error code. This may be left out or explicitly set to empty using "" which is interpreted as "no dependencies". There is also the special @provided:feature syntax where we can define we want to depend on a specific feature another task may implement (see PROVIDES). In this case @provided:writable_var could mean that another task may have mounted a tmpfs or a writable partition there which we need for the first mkdir. That task would need to advertise the writable_var feature in its PROVIDES config value. (array-like) Additionally there is an optional feature that allows tasks to be started based on system events issued by elos. Tasks depending on an elos event can use the @elos:<filter_name> syntax to specify a task dependency that is fullfilled as soon as the specified elos filter triggers. The filters themself can be specified using the FILTER_DEFINE keyword.wait), the features ipv4_dhcp and resolvconf are provided. Another task may then depend e.g. on @provided:resolvconf. While the feature names chosen here reflect the functional intention, they can be chosen arbitrarily. (array-like)YES, the task will be restarted on failure or completion. Useful for daemons like getty. Default: NO-1 is interpreted as "unlimited". Default: -1Crinit supports setting environment variables in the global and task configurations as shown above. The variables in the global config are valid for all tasks and may be locally overriden or referenced. The above examples together would result in the following list of environment variables for the task network-dhcp (with explanatory comments).
Crinit supports an optional feature, which enables a task to depend on specific system events issued by the elos event logger. This needs ELOS support included at build-time.
In order to depend on elos events, a task uses the @elos dependency prefix in conjunction with a elos filter name. The corresponding filter has to be defined within the task itself or within the global environment. The definition follows the syntax of normal environment variables, but uses the FILTER_DEFINE prefix instead:
For example:
ENV_SET statements, each specifying a single environment variable.ENV_SET statements must be of the form ENV_SET = VARIABLE_NAME "variable content". The quotes around the variable content are mandatory and will not appear in the environment variable itself.${VARIABLE_NAME} syntax.\.\a, \b, \n, \t, \$, \\, \x<two digit hex number>.A crinit task configuration may reference multiple include files at any point in the task file. The effect is the same as manually copying the contents of the include file at exactly that point in the task config, similar to C includes. Additionally, it is possible to define an import list if not all settings in the include file should be applied.
An INCLUDE statement looks like
where <include_name> is the filename of the include without the ending and without the leading path. The imported settings are defined as a comma-separated list of possible configuration options. If omitted, everything in the include file is taken.
Currently only IO_REDIRECT, DEPENDS, and ENV_SET are supported in include files.
Example:
Imports only the ENV_SET and IO_REDIRECT settings from (assuming default values for include dir and suffix) /etc/crinit/server_settings.crincl.
server_settings.crincl could look like
In the above case, the DEPENDS setting would be ignored.
Crinit supports per-task IO redirection to/from file and between STDOUT/IN/ERR using IO_REDIRECT statements in the task configurations. Please note that currently IO redirections do not work for STOP_COMMAND. The statements are of the form
Where REDIRECT_FROM is one of { STDOUT, STDERR, STDIN }, and REDIRECT_TO may either also be one of those streams or an absolute path to a file. APPEND or TRUNCATE signify whether an existing file at that location should be appended to or truncated. Default is TRUNCATE. The special value PIPE is discussed below (see Named Pipes). OCTAL_MODE sets the permission bits if the file is newly created. Default is 0644.
Accordingly the statements in the example configuration above will result in stdout being redirected to the file /var/log/net-dhcp.log in append mode. If the file does not yet exist, it will be created with permission bits 0644. The second statement then redirects stderr to stdout, capturing both in the log.
Other examples could be
to silence stdout and log stderr, or
to read stdin from file and capture stdout to another file. Stderr will go to console as normal.
As indicated above, crinit also accepts the setting PIPE instead of APPEND or TRUNCATE. With this setting, crinit will ensure that the given path is a named pipe (also called a FIFO special file). This is useful to pipe the output of one task to another.
A common example would be redirection of output to syslog. For that we would create two task files, one as the sender and another as the receiver (using the logger utility provided by e.g. busybox and others).
Sending Task
Receiving Task
This will redirect the output of the echo command to the input of the logger utility and thereby to syslog. As is shown, it is also possible to set permissions for named pipes (default will also be 0644). It should be kept in mind to keep the permissions the same in both tasks. Setting different permissions in the sending and receiving task of a pipe creates a race condition where one of the tasks will be able to create the named pipe with its settings. The other task will take it as-is, as long as it can access the file.
By default, glibc will switch from line- to block-buffered mode when redirecting a stream to file. This may make it hard to use e.g. tail -f ... to monitor the output in parallel. To get around that problem, one may use the stdbuf utility (part of GNU coreutils).
In a crinit task, the following
will result in line-buffered output to the files which can be monitored easily. For more details, see the stdbuf man page.
A dependency group or meta-task is a task without any **COMMAND**s. The provided dependencies of the meta-task will be fulfilled immediately once its own dependencies are fulfilled. This can be used to semantically combine different dependencies into one. Reasons to do that can be semantic readability of the configs or to provide hook dependencies for third-party applications having an opaque view of their target system.
As an example a dependency group and a task using it could look like
Semantically, this would mean local_http_client only cares about the server, as a singular entity, being set up and running. This could also be delivered by a third party with only the interface knowledge "You need to wait for the
`server` dependency". How to provide this dependency, with which tasks, and in what order is then up to the system integrator who maintains dep_grp_server.
If compiled in (see Build Instructions), Crinit supports checking signatures of its task and global configuration files. The algorithm used is RSA-PSS using 4096 Bit keys and SHA256 hashing.
Crinit will use a root public key (named crinit-root as the searchable key description`) stored in the Kernel user keyring and optionally downstream signed public keys stored in the rootfs. The downstream keys need to be signed using the root key. Configuration files must then be signed either by the root key or by one of the downstream keys.
The root public key must be enrolled to the user keyring before Crinit starts. A common solution is to do this from a signed initramfs, thereby leveraging a secure boot chain to establish trust in the key.
Signature checking is configured via the Kernel command line (also part of the trusted/secure boot chain) using these two settings:
crinit.signatures={yes, no} - Activates signature checking if set to yes. Default is no.crinit.sigkeydir=<path_to_downstream_keys> - Sets the path where Crinit searches for signed public keys in the rootfs. Default is /etc/crinit/pk.For downstream keys and configuration files, Crinit expects a corresponding signature file with the .sig suffix to be present in the same directory. As an example, the task file very_valid.task would need a signature file very_valid.task.sig next to it. Key files may be in DER and PEM format with the appropriate filename extensions. The crinit-root public key stored in the user keyring should be in DER binary format.
To prepare a system for using signatures and correctly signing files, the scripts directory contains
$ crinit-genkeys.sh -o crinit-root-priv.pem # generate private root key$ crinit-genkeys.sh -f der -k crinit-root-pub.der # calculate public root key from it (destined for user keyring)$ crinit-genkeys.sh -o crinit-dwstr-priv.pem # generate downstream key$ crinit-genkeys.sh -k crinit-root-pub.pem # calculate public key from it (destined for rootfs)$ crinit-sign.sh -k crinit-root-priv.pem -o crinit-dwstr-pub.pem.sig crinit-dwstr-pub.pem # sign downstream key with root keycrinit-ctl is a CLI control program for crinit wrapping the client API functionality.
Below is its help output:
As noted above, it will also make use of the CRINIT_SOCK environment variable to know which crinit socket to connect to (Default: /run/crinit/crinit.sock).
There is a script to support smart bash completions for the crinit-ctl executable located at completion/crinit-ctl.bash. On modern distributions, this file will need to be copied and renamed to /usr/share/bash-completion/completions/crinit-ctl to be picked up automatically. The cmake installer can do this (see below). Note that a fully bash-compatible shell (bash,dash) is required to take advantage of this.
For testing purposes, it is sufficient to run source completion/crinit-ctl.bash to activate the smart completion for the current session. The script can also be sourced from .bashrc if a system-wide installation is not desired.
Once installed and loaded, crinit-ctl <TAB><TAB> will show/complete available command verbs like addtask, enable, disable, etc. For crinit-ctl addtask <TAB><TAB>, paths to \*.crinit files and specific options will be completed, similar for addseries. Verbs taking a task name as input will have completion of available tasks loaded by crinit. The script calls crinit-ctl list and parses its output in the background to achieve this.
The crinit-launch executable is a helper program to start a command as a different user and / or group. It is not meant to be executed by the user directly.
Executing
will start a Docker container for the native host architecture with all necessary programs to build Crinit and its Doxygen documentation and to run the tests.
It is possible to run the Docker container for a foreign architecture such as arm64 with the help of qemu-user-static and binfmt-support. Make sure these packages are installed on your host system if you want to use this functionality. All following commands to be run inside the container will be the same regardless of the architecture.
By default, ci/docker-run.sh will use a container based on Ubuntu Jammy. If another version is desired, it can be specified as a second parameter. For example, you can run a Lunar-based container using
Inside the container, it is sufficient to run
which will compile the release configuration for crinit, the client library and crinit-ctl as well as a suite of RPMs. The doxygen documentation is built as well. The script will copy relevant build artifacts to result/.
For debugging purposes, the debug configuration can be built with the following command. Optionally it is also possible to enable AddressSanitizer (ASAN) for additional runtime checks or static analysis using -fanalyzer at compile-time.
A clang-tidy analysis of the source can be performed using
This will also generate a compile_commands.json. The output will be saved to result/clang-tidy.
Unit tests or smoke tests can be run using the respective commands below. For the debug configuration, either of them takes an additional Debug argument.
In order to run integration tests, you can use ci/run-integration-tests.sh. This will set up two docker containers, one for the Robot test framework and one that runs Crinit and Elos, and executes all integration tests inside the robot container.
You can also manually start both containers with ci/docker-target-run.sh and ci/docker-integration-run.sh. Adapt the configuration within the robot container by changing the ip address of the target container within the robot variables (test/integration/robot_variables.py) to the current ip of the target container and run the tests by executing test/integration/scripts/run-integration-tests.sh inside the robot container.
If a manual test build is desired, running the following command sequence inside the container will setup the build system and build native binaries.
Some default paths can be configured on compile time:
-DDEFAULT_CONFIG_SERIES_FILE. Default is $CMAKE_INSTALL_SYSCONFDIR/crinit/default.series.-DDEFAULT_CRINIT_SOCKFILE=<FILEPATH>. Default is $CMAKE_INSTALL_RUNSTATEDIR/crinit/crinit.sock.-DDEFAULT_INCL_DIR=<PATH>. Default is $CMAKE_INSTALL_SYSCONFDIR/crinit.-DDEFAULT_TASK_DIR=<PATH>. Default is $CMAKE_INSTALL_SYSCONFDIR/crinit.The cmake setup supports some optional features:
-DENABLE_SIGNATURE_SUPPORT={On, Off}. If set to on, crinit will have a dependency to libmbedtls. Default is On.-DDEFAULT_SIGKEY_DIR=<PATH>. Default is $CMAKE_INSTALL_SYSCONFDIR/crinit/pk.-DENABLE_ELOS={On, Off}. If set to on, crinit will have a dependency to safu. Default is On.-DUNIT_TESTS={On, Off}. If set to on, Crinit's unit tests will be built and installed to UNIT_TEST_INSTALL_DIR. This will cause a dependency to cmocka 1.1.5 or greater. Default is On with installation path ${CMAKE_INSTALL_LIBDIR}/test/crinit/utest.-DDEFAULT_ELOS_EVENT_POLLING_TIME=<usecs>. Default is 500000.-DAPI_DOC={On, Off}. Needs doxygen. Default is On.-DMACHINE_ID_EXAMPLE={On, Off}. Default is Off.-DDEFAULT_MACHINE_ID_FILE=<FILEPATH>. Default is $CMAKE_INSTALL_SYSCONFDIR/machine-id.config/example to /etc/${EXAMPLE_TASKDIR}. Default is Off, default installation path is /etc/crinit/example.-DINSTALL_SMOKE_TESTS={On, Off}, to the SMOKE_TEST_SCRIPT_DIR and SMOKE_TEST_CONF_DIR, respectively. Default is Off and default installation paths are ${CMAKE_INSTALL_LIBDIR}/test/crinit/smoketest and ${CMAKE_INSTALL_LIBDIR}/test/crinit/smoketest/config.-DINSTALL_ROBOT_TEST_RESOURCES={On, Off} to ROBOT_TEST_RESOURCE_DIR. Default is Off and default install path is ${CMAKE_INSTALL_SYSCONFDIR}/crinit/itest.reboot and poweroff using PWR_SYMLINKS_PATH. Default is ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_SBINDIR}-DINSTALL_BASH_COMPLETION={On, Off}, to the BASH_COMPLETION_DIR. Default is On and default isntall path is ${CMAKE_INSTALL_DATADIR/bash-completion/completions.SONAME of libelos crinit will try to open at run-time. Default is auto-detection if elos is present in the build environment or libelos.so.1 if it is not.In order to build crinit, some prerequisites have to be installed.
1.9.8