Systemd

Kernel[edit | edit source]

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):

Gentoo Linux --->
   Support for init systems, system and service managers --->
      [*] systemd

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:

General setup  --->
	[*] Control Group support --->
		[*]   Support for eBPF programs attached to cgroup
	[ ] Enable deprecated sysfs features to support old userspace tools
	[*] Configure standard kernel features (expert users)  --->
		[*] open by fhandle syscalls
		[*] Enable eventpoll support
		[*] Enable signalfd() system call
		[*] Enable timerfd() system call
	[*] Enable bpf() system call
[*] Networking support --->
Device Drivers  --->
	Generic Driver Options  --->
		[*] Maintain a devtmpfs filesystem to mount at /dev
File systems  --->
	[*] Inotify support for userspace
	Pseudo filesystems  --->
		[*] /proc file system support
		[*] sysfs file system support

General setup  --->
	[*] Configure standard kernel features (expert users)  --->
		[*] Checkpoint/restore support
	[*] Namespaces support  --->
		[*] Network namespace
[*] Enable the block layer  --->
	[*] Block layer SG support v4
Processor type and features  --->
	[*] Enable seccomp to safely compute untrusted bytecode
Networking support --->
	Networking options --->
		<*> The IPv6 protocol
Device Drivers  --->
	Generic Driver Options  --->
		()  path to uevent helper
		[ ] Fallback user-helper invocation for firmware loading
Firmware Drivers  --->
	[*] Export DMI identification via sysfs to userspace
File systems --->
	<*> Kernel automounter version 4 support (also supports v3)
	Pseudo filesystems --->
		[*] Tmpfs virtual memory file system support (former shm fs)
		[*]   Tmpfs POSIX Access Control Lists
		[*]   Tmpfs extended attributes

For an UEFI system also enable the following:

[*] Enable the block layer  --->
	Partition Types  --->
		[*] Advanced partition selection
		[*]   EFI GUID Partition support
Processor type and features  --->
	[*] EFI runtime service support
Firmware Drivers  --->
        EFI (Extensible Firmware Interface) Support -->
	        <*> EFI Variable Support via sysfs

If the system is using the BFQ scheduler, it's recommended by BFQ upstream to enable "BFQ hierarchical scheduling support" under "Enable the block layer -> IO Schedulers".

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

/etc/mtab[edit | edit source]

Upstream only supports the /etc/mtab file being a symlink to /proc/self/mounts. Not creating this symlink will also cause problems with mount (bug #434090) and df (bug #477240). In the past some utilities wrote information (like mount options) into /etc/mtab and thus it was supposed to be a regular file. Nowadays all software is supposed to avoid this problem. Still, before switching the file to become a symbolic link, please check bug #477498 to be sure that the system is not affected by any reported regressions.

To create the symlink, run:

Ensure /usr is present at boot time[edit | edit source]

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:

or

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

# Dracut modules to add to the default
add_dracutmodules+="usrmount"

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:

/usr

See the Initramfs guide for more alternatives.

Using LVM and initramfs[edit | edit source]

When sys-fs/lvm2 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:

When LVM is used, the lvmetad daemon needs to be started as well. Otherwise systemd will be unable to mount LVM volumes. lvmetad can be enabled in /etc/lvm/lvm.conf:

# Set use_lvmetad to '1' for systemd
use_lvmetad = 1

USE flags[edit | edit source]

Profile[edit | edit source]

Enable the systemd USE flag globally (in make.conf). The consolekit 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:

Bootloader[edit | edit source]

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.

title=Gentoo with systemd
root (hd0,0)
kernel /vmlinuz root=/dev/sda2 init=/lib/systemd/systemd

# Append parameters to the linux kernel command line
GRUB_CMDLINE_LINUX="init=/lib/systemd/systemd"

linux /vmlinuz-3.10.9 root=UUID=508868e4-54c6-4e6b-84b0-b3b28b1656b6 init=/lib/systemd/systemd

image=/vmlinux 
   append="init=/lib/systemd/systemd" 
   label=Linux 
   read-only 
   initrd=/initramfs 
   initrd-size=8192

Machine ID[edit | edit source]

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

Hostname[edit | edit source]

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[edit | edit source]

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:

LANG="en_US.utf8"

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[edit | edit source]

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[edit | edit source]

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:

vboxdrv
vboxnetflt
vboxnetadp
vboxpci

Network[edit | edit source]

[Match]
Name=en*
 
[Network]
DHCP=yes

[Match]
Name=enp1s0
 
[Network]
Address=192.168.1.10/24
Gateway=192.168.1.1
DNS=192.168.1.1

Handling of log files[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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).

Preset services[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

UNIT                               LOAD   ACTIVE SUB       DESCRIPTION
boot.automount                     loaded active waiting   EFI System Partition Automount
proc-sys-fs-binfmt_misc.automount  loaded active waiting   Arbitrary Executable File Formats File System Automount Point
...

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[edit | edit source]

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:

Installing custom unit files[edit | edit source]

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

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

Customizing unit files[edit | edit source]

When only minor changes to a unit are needed, there's no need to create a full copy of the original unit file in /etc/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.d) in /etc/systemd/system/.

[Service]
MemoryLimit=1G

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:

MemoryLimit=1074000000

Enabling a service under a custom name[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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 file that is activated by the timer as follows:

[Unit]
Description=daily backup work
RefuseManualStart=no
RefuseManualStop=no
 
[Timer]
Persistent=false
OnCalendar=Mon-Fri *-*-* 11:30:00
Unit=backup-work.service
 
[Install]
WantedBy=default.target

[Unit]
Description=daily backup work
RefuseManualStart=no
RefuseManualStop=yes
 
[Service]
Type=oneshot
ExecStart=/home/<user>/scripts/backup-work.sh

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:

[Unit]
Description=daily backup work
RefuseManualStart=no
RefuseManualStop=yes
OnFailure=failure-email@%i.service
 
[Service]
Type=oneshot
ExecStart=/home/<user>/scripts/backup-work.sh

/dev/kmsg buffer overrun, some messages lost[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

File systems  --->
	Pseudo filesystems --->
	[*] /proc file system support
Kernel hacking  --->
	[*] Kernel debugging
	[*] Collect scheduler debugging info
	[*] Collect scheduler statistics

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[edit | edit source]

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:

# default config for openrc
#source src { system(); internal(); };
 
# systemd
source src { systemd-journal(); internal(); };

sys-fs/cryptsetup configuration[edit | edit source]

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

crypt-home UUID=c25dd0f3-ecdd-420e-99a8-0ff2eaf3f391 -

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[edit | edit source]

Check for units that failed to start with:

Enable debug mode[edit | edit source]

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

LogLevel=debug

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

e4rat usage[edit | edit source]

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

GRSecurity hardening[edit | edit source]

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

could not find udev device: Permission denied

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[edit | edit source]

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.