Systemd

Switching init systems is a non trivial operation that has implications for how the system is configured, and sometimes for what software can be installed or not. Generally, an init system will be chosen at installation time (i.e. by downloading either a systemd or an openrc stage3 tarball), and only changed if necessary. In true Gentoo style, in addition to systemd and OpenRC, several init systems are supported.

If systemd is being unwantedly pulled in as a dependency, see Gentoo without systemd.

The core around which all distributions are built is the Linux kernel. It is the layer between the user programs and the system hardware. Gentoo provides its users several possible kernel sources. A full listing with description is available at the Kernel overview page.

For amd64-based systems, Gentoo recommends the sys-kernel/gentoo-sources package.

Choose an appropriate kernel source and install it using emerge:

systemd makes use of many modern Linux kernel features. Right now, the lower bound on kernel version is set in the ebuild to 2.6.39. In recent versions of sys-kernel/gentoo-sources, there is a convenient way of selecting the mandatory and optional kernel options for systemd (see Kernel/Configuration for further details):

To configure the kernel options manually (which is the only option when not using sys-kernel/gentoo-sources), the following kernel configuration options are required or recommended:

For an UEFI system also enable the following:

If the system is using the BFQ scheduler, it's recommended by BFQ upstream to enable hierarchical scheduling support:

For an up-to-date list, see section "REQUIREMENTS" in the upstream README file.

Ensure /usr is present at boot time

For a split /usr configuration, use an initramfs to mount /usr before starting systemd. For now, this means using sys-kernel/dracut or sys-kernel/genkernel version 4.1 or greater. Set aside time now to migrate:

When using dracut, enable the usrmount module if it is not automatically enabled to mount /usr automatically.

When genkernel is used, before rebuilding the kernel, be sure to set the /usr in genkernel's configuration file /etc/initramfs.mounts. This will mount /usr during the initramfs process:

See the Initramfs guide for more alternatives.

Using LVM and initramfs

When LVM is used and the system is booted using an initramfs, the initramfs will have to be created using sys-kernel/genkernel by running:

<target> is either initramfs or one of the other genkernel targets which imply the creation of an initramfs. For more information, look at the output of genkernel --help:

USE flags

Profile

Enable the systemd USE flag globally (in make.conf). The elogind USE flag should also be disabled to prevent conflicts with the systemd-logind service. It is also possible to switch to a systemd subprofile to use saner USE flags defaults in which case it is not necessary to change make.conf:

Finally update the system with the new profile:

Dependency problems

When replacing OpenRC with systemd, several dependency problems may occur.

If sys-apps/sysvinit blocks sys-apps/systemd, try disabling the netifrc USE flag for sys-apps/openrc. Then rebuild OpenRC temporarily to break the dependency with net-misc/netifrc followed by a depclean operation:

If sys-apps/sysvinit is still blocking sys-apps/systemd, make sure it and sys-apps/openrc are not contained in the world file:

If sys-fs/udev blocks sys-apps/systemd, sys-fs/udev might be registered in the world file. Try to resolve this by deselecting it:

sys-apps/systemd contains udev. Once installed, sys-fs/udev can be removed as systemd will be the provider for the virtual/udev requirement.

If the @system set provides sys-fs/eudev, virtual/udev and virtual/libudev may be preventing systemd. To make portage resolve the problem, after setting the USE flag, try to reinstall the virtuals:

Bootloader

In order to run systemd, switch the init that the executable kernel (or the initramfs) uses.

The following subsections document how to switch the init in one of the boot managers or the kernel.

GRUB Legacy (0.x)

The init=/lib/systemd/systemd argument should be added to the kernel command-line. An example excerpt from grub.conf would look like so:

Should the system boot using OpenRC, try using real_init instead of init.

GRUB

When grub-mkconfig is used, add the init option to GRUB_CMDLINE_LINUX:

When the GRUB configuration file is written by hand (experts only), append the init= parameter to the linux or linux16 command.

YABOOT

Yaboot is a boot loader for PowerPC-based hardware running Linux, particularly New World ROM Macintosh systems.

The init=/lib/systemd/systemd argument should be added directly after the kernel command-line. An example from yaboot.conf:

For the changes to take effect, the ybin command must be run each time the yaboot.conf file is modified.

In-kernel config

The init configuration can also be hard-coded in the kernel configuration. See Processor type and features -> Built-in kernel command line. Note that this technique works for both GRUB Legacy and GRUB.

Upgrades

systemd has the ability to update in-place on a running system (no reboot necessary). After an upgrade to systemd has emerged, run the following command:

Configuration

systemd supports a few system configuration files to set the most basic system details.

After installing systemd, run the following:

Machine ID

Create a machine ID for journaling to work. This can be done through the following command:

Hostname

To set the hostname, create/edit /etc/hostname and simply provide the desired hostname.

When booted using systemd, a tool called hostnamectl exists for editing /etc/hostname and /etc/machine-info. To change the hostname, run:

Refer to man hostnamectl for more options.

Locale

Usually, locales will be properly migrated from OpenRC when installing systemd. When required, the locale can be set in /etc/locale.conf as per the Gentoo handbook instructions:

Once booted with systemd, the tool localectl is used to set locale and console or X11 keymaps. To change the system locale, run the following command:

To change the virtual console keymap:

And finally, to set the X11 layout:

If needed the model, variant and options can be specified as well:

After doing any of the above, update the environment so the changes will take effect:

Time and date

Time, date, and timezone can be set using the timedatectl utility. That will also allow users to set up synchronization without needing to rely on net-misc/ntp or other providers than systemd's own implementation.

To learn how to use timedatectl simply run:

Automatic module loading

Automatic module loading is configured in a different file, or rather directory of files. The configuration files are stored in /etc/modules-load.d. On boot every file with a list of modules will be loaded. The file format is a list of modules separated by newlines and can have any name as long as it ends with .conf. The module loading can be separated by program, service or whatever way that fits personal preference. An example virtualbox.conf is listed below:

Automatic mounting of partitions at boot

Systemd is capable of automatically mounting various partitions to standardized location via systemd-gpt-auto-generator. This makes it possible to boot and automatically mount essential partitions without an fstab and without a root= paramter on the kernel command line. To use this capability, first systemd must be included in the initramfs, this is the case by default for initramfs images generated with Dracut on systems with systemd installed. And second, each partition must have the correct Partition Type GUID. A list of the most important GUIDs can be found in the systemd-gpt-auto-generator manual, the full list can be found on wikipedia.

To list the current Partition Type GUID of your partitions:

systemd-gpt-auto-generator can auto-mount partitions at the following locations, note that the correct GUID depends on the systems CPU architecture:

• / SD_GPT_ROOT_....
• /boot/ SD_GPT_ESP if no /efi/ and no XBOOTLDR partition, otherwise SD_GPT_XBOOTLDR
• /efi/ SD_GPT_ESP if /efi/ is present on the root, if not then ESP is at /boot/
• /home/ SD_GPT_HOME
• /srv/ SD_GPT_SRV
• /usr/ SD_GPT_USR_....
• /var/ SD_GPT_VAR
• /var/tmp/ SD_GPT_TMP
• Swap SD_GPT_SWAP

Below is an example of the most basic partition layout consisting of one EFI System Partition and one x86-64 root partition.

The PARTTYPE for an EFI System Partition is c12a7328-f81f-11d2-ba4b-00a0c93ec93b, it will be mounted at either /efi/ or /boot/ depending on which of these mount points is available and on if there is also an Extended Boot Loader Partition (PARTTYPE=bc13c2ff-59e6-4262-a352-b275fd6f7172) present on this disk. The PARTTYPE for an x86-64 root parition is 4f68bce3-e8cd-4db1-96e7-fbcaf984b709.

If the Partition Type GUID is not correct it can be changed without data loss using a partitioning tool such as fdisk. Note that the system must be offline to change the patition types! A system rescue image, or secondary operating system, must be used to complete the following steps.

Open the disk with the to be changed partition types in fdisk, in this exameple /dev/nvme1n1 is used:

List the current partition layout with the p command:

Change the Partition Type GUID of any partition with the t command, followed by the number of the partition to be changed, and finally the alias for the desired partition type:

Repeat the above steps for any additional partitions of which the Partition Type GUID should be changed. Once completed, save the changes with the w command:

Network

systemd is compatible with various network management tools.

systemd-networkd

See the systemd/systemd-networkd article for details on setting up a wired network on systemd systems.

systemd-resolved

See the systemd/systemd-resolved article for details on setting up address name resolution (DNS) on systemd systems.

NetworkManager

NetworkManager is often used to configure network settings. For that purpose, simply run the following command when using a graphical desktop:

If that is not the case and the network needs to be configured from console, give nmcli a try, or follow a guided configuration process through nmtui:

nmtui is a curses frontend that will guide the user in the process while running in console mode.

For more details see the dedicated article.

Handling of log files

systemd has its own way of handling log files without needing to rely on an external log system (such as app-admin/syslog-ng or app-admin/rsyslog).

If desired, the logging service be configured to pass log messages to external logging utilities such as sysklog or syslog-ng. See man journald.conf to learn how to configure the systemd-journald service to suit situational needs.

systemd's integrated logging service writes log messages in a secure, binary format. The logs are read by using the journalctl command, which is a separate executable from the systemd-journald logging service.

Some common journalctl options:

For more information and many more options, look at man journalctl.

/tmp is now in tmpfs

Unless some other filesystem is explicitly mounted to /tmp in /etc/fstab, systemd will mount /tmp as tmpfs. That means it will be emptied on every boot and its size will be limited to 50% of the system's RAM size. To know why this is the desired behavior and how to modify it, take a look at API File Systems.

Configure verbosity of boot process

When migrating to systemd users usually notice differences regarding verbosity of boot process:

• The kernel command-line option quiet not only influences the kernel output, but also that of systemd itself. Then, while setting up systemd for the machine, drop the option to see any errors could arise more easily. After that, add it back to get a quiet (and faster) boot.
• Even passing the quiet kernel command-line option, systemd can still be configured to show its status by also passing systemd.show_status=1.
• When not using the quiet kernel command-line option, some messages might be overwriting consoles. This could be caused by the kernel configuration (see man 5 proc and look for /proc/sys/kernel/printk). To tweak it pass the loglevel=5 kernel command-line parameter (and update the value according to preference, for instance set a lower value like 1).

Usage

Converting traditional home directories to systemd homed

See the systemd-homed subarticle.

Services

At some point the system will need to be rebooted in order to get systemd running (in system mode). Be sure to read all of this document to ensure systemd is configured as completely as possible before rebooting. Note that journalctl works with systemd not running, but that systemctl will not do anything useful without systemd running. Complete the service configuration (enabling and starting of services) after logging in to the system running systemd.

Preset services

Most services are disabled when systemd is first installed. A "preset" file is provided, and may be used to enable a reasonable set of default services.

OpenRC services

Although systemd originally intended to support running old init.d scripts, that support is not suited well for a dependency-based RC like OpenRC and thus is completely disabled on Gentoo. OpenRC provides additional measures to ensure that init.d scripts can't be run when OpenRC was not used to boot the system (otherwise the results would be unpredictable).

Listing available services

All available service units can be listed using the list-units argument of systemctl:

The following file suffixes are of interest:

Alternatively the systemctl tool can be used to list all services (including implicit ones):

And finally check for services that failed to start:

Enabling, disabling, starting, and stopping services

The usual way of enabling a service is using the following command:

Services can be disabled likewise:

These commands enable services using their default name in default target (both specified in "Install" section of the service file). However, sometimes services either don't provide that information or users prefer to have another name/target.

Note that these commands only enable or disable the service to be started on a next boot; to start the service right now, use:

Services can be stopped likewise:

Services implementing ExecReload= can be commanded to reload their configuration without restarting itself:

Installing custom unit files

Custom unit files can be placed in /etc/systemd/system, where they will be recognized after running systemctl daemon-reload:

The /lib/systemd/system directory is reserved for service files installed by the package manager.

Customizing unit files

When only minor changes or overrides to a unit are needed, there's no need to create a full copy of the original unit file in /etc/systemd/system/ or /lib/systemd/system/. Overriding settings in a package management provided unit can be achieved by drop-in files in a *.d directory named after the original unit (e.g. apache2.service.d) in /etc/systemd/system/.

Both the drop-in directory and config file can be created using the systemctl edit utility or manually.

The editing utility can be invoked as:

A reload of systemd is needed to inform it of the changes:

Then the service needs to be restarted to apply the changes:

Verify that the changed property was applied to the service:

Enabling a service under a custom name

When the name provided by Alias= in the unit's [Install] section does not meet the expectations and providing a permanent new value for this through a customization is not desired, a symlink can be created manually in /etc/systemd/system/*.wants/. The name of the *.wants directory can either specify a target or another service which will depend on the new one.

For example, to install mysqld.service as db.service in the multi-user.target:

To disable the service, just remove the symlink:

Native services

Some of Gentoo packages already install systemd unit files. For these services, it is enough to enable them. A quick summary of packages installing unit files can be seen on systemd eclass users list.

The following table lists systemd services matching OpenRC ones:

User services

It is possible to manage services as a per-user systemd instance. This allows users to setup their own services or timers.

User units can be located at multiple places. Users are allowed to place them to $XDG_CONFIG_HOME/systemd/user/. Installed packages place them to /usr/lib/systemd/user/.

User services use --user systemctl option. For example to start a mpd user service:

Timer services

Since version 197 systemd supports timers, making cron unnecessary on a systemd system. Since version 212 persistent services are supported, replacing even anacron. Persistent timers are run at the next opportunity if the system was powered down when the timer was scheduled to run.

The following is an example on how to make a simple timer that runs in the context of a user. It will even run if the user is not logged in. Every timed service needs a timer and a service unit file that is activated by the timer as follows:

These unit files can be created either manually or using the systemctl edit utility:

When creating the unit files manually, the files are to be placed in the ~/.config/systemd/user directory. It may need to be created for the relevant user:

To have a timer run while the user is not logged in, be sure to enable lingering sessions:

First, tell systemd to rescan the service files:

As a user, it is possible to trigger the backup manually by running the following command:

Start and stop the timer manually as follows:

Finally, to activate the timer at every system start, run:

To check the last results of running the service:

Emailing failures

If a timed service runs and fails an e-mail can be send out to inform the user or administrator. This is possible with the "OnFailure" stanza which specifies what should happen if a service fails. A failure is detected by a non-zero return code of the invoked script.

For that change the script as follows:

This requires to have the service failure-email@.service installed, which can be found in kylemanna's systemd-utils repository.

Replacing cron

The above timer and service files can also be added to /lib/systemd/system to make them available system-wide. The install section should then say WantedBy=multi-user.target to enable the service at system start.

However, cron also runs the scripts in /etc/cron.daily and other locations. Several packages place scripts there that they expect to be run daily. This behavior can be emulated with systemd by installing sys-process/systemd-cron. Then activate the new cron replacement with the following commands:

Troubleshooting

• Gentoo bugtracker: known bugs
• Freedesktop.org bugtracker: known bugs
• Upstream debugging guide
• systemd-analyze verify to get readable warnings and errors associated with the given systemd unit

Slow shutdowns or reboot times due to running services

Problem

Occasionally a systemd system or user service will cause the system to greatly delay poweroff/shutdown or reboot operation due to systemd default wait times for the operation blocking service to time out.

Solution

To greatly speed up this operation, the default timeout values can be reduced at the expense of the service (potentially) not cleanly finishing a task. In order to be effective, both of the following configuration changes must be put into effect to shorten the default timeout system and user services.

/dev/kmsg buffer overrun, some messages lost

Problem

When booting the system displays an infinite loop of /dev/kmsg buffer overrun, some messages lost. The login screen to console never appears since the system never gets to that point in the boot process.

Solution

Most of the time this issue is caused when the CONFIG_POWER_SUPPLY_DEBUG option is enabled in the kernel. The current workaround is to disable this option in the kernel, then recompile, install, and boot the new kernel. The solution can also be found in this thread on the Gentoo forums. According to one user one the forum, this issue was also seen when using I2C EEPROM on an embedded system^[1]. The solution in this case was to disable the CONFIG_I2C_DEBUG_CORE kernel option.

Graphical sessions opened in random places

By default systemd only launches a getty process when it's going to be used. This causes some display managers (like GDM) to use the remaining TTYs for opening graphical sessions on demand, which can result in having consoles and graphical sessions placed randomly depending on the order they were used.

To stick with a more "classical" behavior (i.e, consoles placed from tty1 to tty6 and graphical sessions using the remaining TTYs) force it to always launch getty on those:

LVM

When switching from OpenRC to systemd and LVM is needed to properly mount the system volumes, activate the LVM service:

While it might not be needed for activation of the root volume (if LVM is integrated into the initramfs) it might not work for other LVM volumes, unless the service is activated.

systemd-bootchart

Make sure that CONFIG_DEBUG_KERNEL, CONFIG_SCHED_DEBUG, and CONFIG_SCHEDSTATS are enabled.

Next, enable systemd-bootchart.service:

The result of the changes will produce a bootchart report in SVG format located in /run/log/ after each boot. It can be viewed using a modern web browser.

As an alternative to systemd-bootchart the starting of services can be visualized with:

syslog-ng source for systemd

There is no need to add unix-dgram('/dev/log'); to the /etc/syslog-ng/syslog-ng.conf config file. It will cause syslog-ng to fail (at least on version syslog-ng-3.7.2). Update the source src { ...; }; line mentioned in the syslog-ng article as follows:

sys-fs/cryptsetup configuration

systemd does not seem to respect /etc/conf.d/dmcrypt (see bug #429966) so it needs to be configured through the /etc/crypttab file:

Make sure to enable the cryptsetup USE flag for sys-apps/systemd. It will install /lib/systemd/system-generators/systemd-cryptsetup-generator that will automatically create a service (cryptsetup@crypt-home.service for above example) for each entry on boot.

Check for units that failed to start

Check for units that failed to start with:

Enable debug mode

To get more informations set the following in /etc/systemd/system.conf:

Or enable the debug-shell, that opens a terminal at tty9. This helps to debug services during the boot process.

e4rat usage

Please remember to edit /etc/e4rat.conf setting 'init' to /lib/systemd/systemd, otherwise it will keep booting OpenRC.

GRSecurity hardening

With grsecurity enabled, systemd-networkd might log the following error:

The error raises due to systemd-networkd working under a non-root user with grsecurity refusing access to the complete /sys structure for such users. To disable this option, disable the CONFIG_GRKERNSEC_SYSFS_RESTRICT kernel option.

logind may also have subtle permission issues with CONFIG_GRKERNSEC_PROC active, see bug #472098.

shutdown -rF does not force fsck

The systemd-fsck service is responsible of running fsck when needed. It doesn't honor shutdown's -rF option, but instead honors the following kernel boot parameters.

Optional systemd binaries

Many optional systemd binaries can be built by setting certain use flags. An incomplete mapping of USE flag to binary is below.

See also

• systemd/systemd-homed — provides instructions to migrate home directories from their traditional structure into the encrypted by default, portable concept provided by systemd's homed.
• systemd/systemd-boot — a minimal UEFI boot manager.
• systemd/systemd-nspawn — a lightweight, loosely chroot-like, OS-level OCI container environment native to systemd.
• Comparison of init systems — compares and contrasts init systems for Unix(like) OSs
• Hard dependencies on systemd — a (possibly partial) list of packages in Gentoo's repository that unconditionally require systemd
• OpenRC to systemd Cheatsheet — list of commands commonly used in OpenRC and its equivalent systemd command.

External resources

• FAQ
• Tips and tricks
• Mastering systemd: Securing and sandboxing applications and services (RedHat)

References