Systemd

Translate this page

Other languages:

Resources

systemd is a modern SysV-style init and rc replacement for Linux systems. It is supported in Gentoo as an alternative init system.

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.

Installation

Important
If updating from <=sys-apps/systemd-203 check the upgrade sub-article.

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:

root #emerge --ask sys-kernel/gentoo-sources

Kernel

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

KERNEL Quick setup using gentoo-sources

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:

KERNEL Mandatory options

General setup  --->
	[*] Control Group support --->
		[*]   Support for eBPF programs attached to cgroups
	[ ] 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 --->
	Networking options --->
		[*] Unix domain sockets
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

KERNEL Recommended options

General setup  --->
	[*] 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 support (supports v3, v4 and v5)
	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:

KERNEL UEFI support

[*] Enable the block layer  --->
	Partition Types  --->
		[*] Advanced partition selection
		[*]   EFI GUID Partition support
Processor type and features  --->
	[*] EFI runtime service support
Device Drivers  --->
        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 hierarchical scheduling support:

KERNEL BFQ scheduler

IO Schedulers  --->
	<*> BFQ I/O scheduler
        [*]   BFQ 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:

root #emerge --ask sys-kernel/genkernel

or

root #emerge --ask sys-kernel/dracut

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

FILE /etc/dracut.conf.d/usrmount.conf

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

FILE /etc/initramfs.mounts

/usr

root #genkernel --install all

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:

root #genkernel --lvm <target>

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

user $genkernel --help

USE flags

USE flags for sys-apps/systemd System and service manager for Linux

`+dns-over-tls`	Enable DNS-over-TLS support
`+gcrypt`	Enable use of dev-libs/libgcrypt for various features
`+kernel-install`	Enable kernel-install
`+kmod`	Enable kernel module loading via sys-apps/kmod
`+lz4`	Enable lz4 compression for the journal
`+openssl`	Enable use of dev-libs/openssl for various features
`+resolvconf`	Install resolvconf symlink for systemd-resolve
`+seccomp`	Enable seccomp (secure computing mode) to perform system call filtering at runtime to increase security of programs
`+sysv-utils`	Install sysvinit compatibility symlinks and manpages for init, telinit, halt, poweroff, reboot, runlevel, and shutdown
`+zstd`	Enable support for ZSTD compression
`acl`	Add support for Access Control Lists
`apparmor`	Enable support for the AppArmor application security system
`audit`	Enable support for sys-process/audit
`boot`	Enable EFI boot manager and stub loader
`bpf`	Enable BPF support for sandboxing and firewalling.
`cgroup-hybrid`	Default to hybrid (legacy) cgroup hierarchy instead of unified (modern).
`cryptsetup`	Enable cryptsetup tools (includes unit generator for crypttab)
`curl`	Enable support for uploading journals
`elfutils`	Enable coredump stacktraces in the journal
`fido2`	Enable FIDO2 support
`gnutls`	Prefer net-libs/gnutls as SSL/TLS provider (ineffective with USE=-ssl)
`homed`	Enable portable home directories
`http`	Enable embedded HTTP server in journald
`idn`	Enable support for Internationalized Domain Names
`importd`	Enable import daemon
`iptables`	Use libiptc from net-firewall/iptables for NAT support in systemd-networkd; this is used only if the running kernel does not support nftables
`lzma`	Support for LZMA compression algorithm
`pam`	Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
`pcre`	Add support for Perl Compatible Regular Expressions
`pkcs11`	Enable PKCS#11 support for cryptsetup and homed
`policykit`	Enable PolicyKit (polkit) authentication support
`pwquality`	Enable password quality checking in homed
`qrcode`	Enable qrcode output support in journal
`secureboot`	Automatically sign efi executables using user specified key
`selinux`	!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
`split-usr`	Enable behavior to support maintaining /bin, /lib, /sbin and /usr/sbin separately from /usr/bin and /usr/lib
`test`	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
`tpm`	Enable TPM support
`ukify`	Enable systemd-ukify
`vanilla`	Disable Gentoo-specific behavior and compatibility quirks
`xkb`	Depend on x11-libs/libxkbcommon to allow logind to control the X11 keymap

Data provided by the Gentoo Package Database · Last update: 2024-11-02 10:00 More information about 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:

root #eselect profile list

Finally update the system with the new profile:

root #emerge -avDN @world

Note
Once this command is complete, it is important follow the Configuration steps.

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:

root #

emerge --oneshot sys-apps/openrc

root #emerge --ask --depclean

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

root #emerge --deselect sys-apps/openrc sys-apps/sysvinit

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:

root #emerge --deselect sys-fs/udev

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:

root #emerge --oneshot virtual/udev virtual/libudev

Bootloader

Important
This is no longer necessary with sys-apps/systemd when the sysv-utils USE is enabled. This defaults to on with at least version 239 in Gentoo

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

Warning
The services that are set up for the previous service manager will not be automatically started. This is because the system is switching to a different service manager. In order to obtain back the functionality like networking or a login manager, these services will need to be enabled again. More information about this follows in the services section later in this article.

Note
In case the migration yields a broken state, it is always possible to boot back into the default service manager (OpenRC) by undoing this init change step. This allows safe return and a way to follow through the troubleshooting section at the end of this article to fix the problem.

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:

FILE /boot/grub/grub.confExample GRUB config for systemd

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

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:

Note
This is not needed when using an initramfs generated by dracut with systemd inside as the initramfs already starts systemd.

FILE /etc/default/grubConfigure GRUB for systemd

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

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

FILE /boot/grub/grub.cfgExample GRUB2 configuration fragment

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

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:

FILE /etc/yaboot.confExample yaboot config for systemd

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

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:

root #systemctl daemon-reexec

Configuration

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

After installing systemd, run the following:

root #

systemd-machine-id-setup

root #

systemd-firstboot --prompt

root #

systemctl preset-all

Warning
If systemd-firstboot is not ran, it will automatically run on next boot. However, it interrupts the normal boot process, preventing access to the system from users who don't have access to the interactive console - like accessing a server via SSH.

Note
While some system configuration parameters can be updated by modifying the appropriate configuration files, most settings are managed using utilities that require systemd to be running. In this case, it is safe to reboot the computer with systemd now and use the hostnamectl, localectl, and timedatectl utilities - indeed this may be required to be able to use them.

Machine ID

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

root #systemd-machine-id-setup

Note
The systemd-machine-id-setup command also has an impact on the systemd-networkd service. If this command is not run the system may exhibit strange behavior like network interfaces not coming up or network addresses not being applied.

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:

root #hostnamectl set-hostname <HOSTNAME>

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:

FILE /etc/locale.confSystem locale configuration

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:

root #localectl set-locale LANG=<LOCALE>

To change the virtual console keymap:

root #localectl set-keymap <KEYMAP>

And finally, to set the X11 layout:

root #localectl set-x11-keymap <LAYOUT>

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

root #localectl set-x11-keymap <LAYOUT> <MODEL> <VARIANT> <OPTIONS>

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

root #env-update && source /etc/profile

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:

root #timedatectl --help

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:

FILE /etc/modules-load.d/virtualbox.confExample file for the virtualbox modules

vboxdrv
vboxnetflt
vboxnetadp
vboxpci

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:

root #lsblk -o NAME,LABEL,PARTLABEL,PARTTYPE,PARTTYPENAME,MOUNTPOINT

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.

root #lsblk -o NAME,LABEL,PARTLABEL,PARTTYPE,PARTTYPENAME,MOUNTPOINT

NAME        LABEL    PARTLABEL            PARTTYPE                             PARTTYPENAME                 MOUNTPOINT
nvme1n1
├─nvme1n1p1 ESP      EFI System Partition c12a7328-f81f-11d2-ba4b-00a0c93ec93b EFI System                   /boot
└─nvme1n1p2 Gentoo   Gentoo               4f68bce3-e8cd-4db1-96e7-fbcaf984b709 Linux root (x86-64)          /

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:

root #fdisk /dev/nvme1n1

 
Welcome to fdisk (util-linux 2.39.3).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.
 
 
Command (m for help):

List the current partition layout with the p command:

Command (m for help): p

 
Disk /dev/nvme1n1: 1.82 TiB, 2000398934016 bytes, 3907029168 sectors
Disk model: Samsung SSD 970 EVO Plus 2TB
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: gpt
Disk identifier: B25D5B33-4A10-F940-826C-3CB24ADC7D86
 
Device           Start        End    Sectors  Size Type
/dev/nvme1n1p1    2048    1052671    1050624  513M EFI System
/dev/nvme1n1p2 1052672 3907028991 3905976320  1.8T Linux root (x86-64)

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:

Command (m for help): t

Partition number (1,2, default 2): 2
Partition type or alias (type L to list all): L
Partition type or alias (type L to list all): 23
 
Changed type of partition 'Linux root (x86-64)' to 'Linux root (x86-64)'.

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:

Command (m for help): w

Note
systemd-gpt-auto-generator will only auto-mount partitions that reside on the same disk as the EFI System Partition that the system is being booted from.

Tip
Some tools may become confused if there is no root= parameter on the kernel command line at all. To placate such tools add root=/dev/gpt-auto-root to the kernel command line. This trick is also usefull if a swapfile on the root partition is used instead of a swap partition for hibernation, i.e. one may specify the resume target on the kernel command line as resume=/dev/gpt-auto-root resume_offset=xxxxxxxxx.

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:

root #nm-connection-editor

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:

root #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.

Important
When using systemd's systemd-journald.service for logging, which is typically the default for systems running systemd, standard users running the journalctl command will be unable to view system logs. To view system logs as a non-root account, users must be in one of the following three user groups in order to view system logs: systemd-journal, adm, or wheel. The simplest method to allow a standard user to view logs is to use the systemd-journal group. Add a user by running the following command where larry is the desired username:

root #gpasswd --add larry systemd-journal

System logs can now be read by running journalctl --system as the user(s) added in the previous command.

Some common journalctl options:

Command-line options for journalctl	Result
journalctl without options	Show all log entries, starting with earliest.
`-b`, `--boot`	Show all log entries from the current boot.
`-r`, `--reverse`	Show the newest log entries first (reverse chronological order).
`-f`, `--follow`	Show the last few entries and display new log entries as they're being produced. This is similar to running tail -f in text logging utilities.
`-p`, `--priority=`	Specify (minimum) priority to display messages, with a choice from: "emerg" (0), "alert" (1), "crit" (2), "err" (3), "warning" (4), "notice" (5), "info" (6), "debug" (7).
`-S`, `--since=`, `-U`, `--until=`	Restrict entries by time. Accepts the format "YYYY-MM-DD hh:mm:ss" or the strings "yesterday", "today" and "tomorrow".
`-n`, `--lines=`	Restrict to a number of entries.
`-k`, `--dmesg`	Restrict to kernel messages.
`-u`, `--unit=`	Restrict to a certain systemd unit.
`--system`	View system service and kernel logs. By default, this is only possible as the root user. See man journalctl for how to grant standard users the ability to read the system journal.

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.

root #systemctl preset-all

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:

root #systemctl list-units

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:

Suffix	Description
.service	Plain service files (e.g. ones just running a daemon directly).
.socket	Socket listeners (much like inetd).
.path	Filesystem triggers for services (running services when files change, etc.).

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

root #systemctl --all --full

And finally check for services that failed to start:

root #systemctl --failed

Enabling, disabling, starting, and stopping services

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

root #systemctl enable foo.service

Services can be disabled likewise:

root #systemctl disable foo.service

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:

root #systemctl start foo.service

Services can be stopped likewise:

root #systemctl stop foo.service

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

root #systemctl reload foo.service

Installing custom unit files

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

root #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:

root #systemctl edit apache2.service

FILE /etc/systemd/system/apache2.service.d/mem-limit.confExample of adding/overriding settings in a service file

[Service]
MemoryLimit=1G

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

root #systemctl daemon-reload

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

root #systemctl restart apache2

Verify that the changed property was applied to the service:

root #systemctl show --property=MemoryLimit apache2

MemoryLimit=1074000000

Note
Drop-ins add items obtained from the unit being overridden to list entries (e.g. ExecStart=). In order to remove the obtained items, it is necessary to first clear the list entry and then add the desired items. For example:

FILE /etc/systemd/system/foo.service.d/override.confClearing ExecStart= entry in a drop-in

[Service]
ExecStart=
ExecStart=/usr/bin/bar

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:

root #ln -s /lib/systemd/system/mysqld.service /etc/systemd/system/multi-user.target.wants/db.service

To disable the service, just remove the symlink:

root #unlink /etc/systemd/system/multi-user.target.wants/db.service

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:

Service migration chart
Gentoo package	OpenRC service	systemd unit	Notes
sys-apps/openrc	bootmisc	systemd-tmpfiles-setup.service	always enabled, uses tmpfiles.d
	consolefont	systemd-vconsole-setup.service	always enabled, uses vconsole.conf
	devfs
	dmesg
	fsck	fsck*.service	pulled in implicitly by mounts
	functions.sh	See note	bug #373219
	hostname	(builtin)	/etc/hostname
	hwclock	See note	always enabled as part of systemd (i.e. it is baked in and it is not a unit)
	keymaps	systemd-vconsole-setup.service	always enabled, uses vconsole.conf
	killprocs
	local
	localmount	local-fs.target	actual units are created implicitly from /etc/fstab
	modules	systemd-modules-load.service	always enabled, uses /etc/modules-load.d/*.conf
	mount-ro
	mtab
	netmount	remote-fs.target
	numlock
	procfs	(builtin)
	root	remount-rootfs.service
	savecache	n/a	OpenRC internals
	staticroute
	swap	swap.target	actual units are created implicitly from /etc/fstab
	swclock
	sysctl	systemd-sysctl.service	sysctl.conf and sysctl.d/
	sysfs	(builtin)
	termencoding	systemd-vconsole-setup.service	always enabled, uses vconsole.conf
	urandom	systemd-random-seed-load.service
	urandom	systemd-random-seed-save.service
app-admin/rsyslog	rsyslog	rsyslog.service
app-admin/syslog-ng	syslog-ng	syslog-ng.service
media-sound/alsa-utils	alsasound	alsa-store.service	(enabled by default)
media-sound/alsa-utils	alsasound	alsa-restore.socket	(enabled by default)
net-misc/dhcpcd	dhcpcd	dhcpcd.service
net-misc/netifrc	net.*	net@.service	systemd wrapper for net.* scripts (comes with net-misc/netifrc)
		netctl@.service	net-misc/netctl is originally an Arch Linux tool.
		NetworkManager.service	For <networkmanager-0.9.8.4 : enable NetworkManager-dispatcher.service for dispatcher.d scripts to work. Enable NetworkManager-wait-online.service to detect that the system has a working internet connection. Disable all other managers (e.g., wicd, dhcpcd) and wpa_supplicant.
		dhcpcd.service	Provided by net-misc/dhcpcd
		systemd.networkd.service	Part of systemd
net-misc/openntpd	ntpd	ntpd.service
net-misc/openssh	sshd	sshd.service	runs sshd as a daemon
net-misc/openssh	sshd	sshd.socket	runs sshd on a inetd-like basis (for each incoming connection)
net-wireless/wpa_supplicant	wpa-supplicant	wpa_supplicant.service	D-Bus controlled daemon (e.g. for NetworkManager)
net-wireless/wpa_supplicant	wpa-supplicant	wpa_supplicant@.service	interface-specific wpa_supplicant (used like wpa_supplicant@wlan0.service)
net-print/cups	cupsd	cups.service	classic on-boot start up service
		cups.socket	socket and path activation (cups only started on-demand)
		cups.path	socket and path activation (cups only started on-demand)
net-wireless/bluez	bluetooth	bluetooth.service
sys-apps/dbus	dbus	dbus.service
sys-apps/dbus	dbus	dbus.socket
sys-apps/irqbalance	irqbalance	irqbalance.service	supports daemon mode only
sys-apps/microcode-ctl	microcode_ctl		Configure microcode as a module to let it load the microcode itself. Go to "Processor type and features" -> "CPU microcode loading support" and remember to add the right option based on the system having an Intel or AMD processor.
sys-fs/udev	udev	udev.service
	udev-mount	(builtin)	/dev is mounted as tmpfs
	udev-postmount	udev-trigger.service
		udev-settle.service
sys-power/acpid	acpid	acpid.service	Most of its functionality is done by systemd itself, so consider disabling this
x11-apps/xdm	(xdm)	xdm.service	OpenRC uses common xdm init.d installed by x11-base/xorg-server. With systemd the corresponding unit file for each DM (gdm.service, kdm.service...) needs to be enabled.
net-firewall/iptables	iptables	iptables-store.service
net-firewall/iptables	iptables	iptables-restore.service

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:

user $systemctl --user start mpd

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:

FILE ~/.config/systemd/user/backup-work.timerExample of a timer running every working day

[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

FILE ~/.config/systemd/user/backup-work.serviceExample of a service triggering backup

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

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

user $systemctl edit --force --full --user backup-work.timer

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:

user $mkdir -p ~/.config/systemd/user

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

user $loginctl enable-linger <username>

First, tell systemd to rescan the service files:

user $systemctl --user daemon-reload

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

user $systemctl --user start backup-work.service

Start and stop the timer manually as follows:

user $

systemctl --user start backup-work.timer

user $systemctl --user stop backup-work.timer

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

user $systemctl --user enable backup-work.timer

To check the last results of running the service:

user $systemctl --user list-timers

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:

FILE ~/.config/systemd/user/backup-work.serviceExample of a service triggering backup

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

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:

root #

systemctl enable cron.target

root #systemctl start cron.target

Troubleshooting

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.

FILE /etc/systemd/system.conf.d/system.confReduce default timeout to 10s for hanging system services

[Manager]
DefaultTimeoutStopSec=10s

FILE ~/.config/systemd/user.confReduce default timeout to 10s for hanging user services

[Manager]
DefaultTimeoutStopSec=10s

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

root #systemctl enable getty@tty{2,3,4,5,6}.service

LVM

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

root #systemctl enable lvm2-monitor.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.

KERNEL Enable systemd-bootchart support

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

Next, enable systemd-bootchart.service:

root #systemctl enable systemd-bootchart

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:

root #systemd-analyze plot > plot.svg

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:

FILE /etc/syslog-ng/syslog-ng.conf

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

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:

FILE /etc/crypttabConfiguration file for encrypted block devices

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

Check for units that failed to start with:

root #systemctl --failed

Enable debug mode

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

FILE /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.

root #systemctl enable debug-shell.service

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:

CODE systemd-networkd 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

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.

Boot parameter	Supported options	Description
`fsck.mode`	`auto` `force` `skip`	Controls the mode of operation. The default is `auto`, and ensures that file system checks are done when the file system checker deems them necessary. `force` unconditionally results in full file system checks. `skip` skips any file system checks.
`fsck.repair`	`preen` `yes` `no`	Controls the mode of operation. The default is `preen`, and will automatically repair problems that can be safely fixed. `yes` will answer yes to all questions by fsck and `no` will answer no to all questions.

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.

USE flag	Additional binary built
`curl`	/lib/systemd/systemd-journal-upload
`http`	/lib/systemd/systemd-journal-gatewayd /lib/systemd/systemd-journal-remote

External resources

References

↑ https://forums.gentoo.org/viewtopic-t-977530-postdays-0-postorder-asc-start-25.html Retrieved on March 12th, 2016

[1] ttps://forums.gentoo.org/viewtopic-t-977530-postdays-0-postorder-asc-start-25.html Retrieved on March 12th, 2016

[1]

Systemd

Installation

Kernel

Ensure /usr is present at boot time

Using LVM and initramfs

USE flags

USE flags for sys-apps/systemd System and service manager for Linux

Profile

Dependency problems

Bootloader

GRUB Legacy (0.x)

GRUB

YABOOT

In-kernel config

Upgrades

Configuration

Machine ID

Hostname

Locale

Time and date

Automatic module loading

Automatic mounting of partitions at boot

Network

systemd-networkd

systemd-resolved

NetworkManager

Handling of log files

/tmp is now in tmpfs

Configure verbosity of boot process

Usage

Converting traditional home directories to systemd homed

Services

Preset services

OpenRC services

Listing available services

Enabling, disabling, starting, and stopping services

Installing custom unit files

Customizing unit files

Enabling a service under a custom name

Native services

User services

Timer services

Emailing failures

Replacing cron

Troubleshooting

Slow shutdowns or reboot times due to running services

/dev/kmsg buffer overrun, some messages lost

Graphical sessions opened in random places

LVM

systemd-bootchart

syslog-ng source for systemd

sys-fs/cryptsetup configuration

Check for units that failed to start

Enable debug mode

e4rat usage

GRSecurity hardening

shutdown -rF does not force fsck

Optional systemd binaries

See also

External resources

References