Systemd

systemd is a modern SysV-style init and rc (run command) replacement for Linux systems. It is supported in Gentoo as an alternate init system.

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

The directory
The directory is used by systemd and other applications as a non-persistent storage for runtime data like  files, sockets and state files.

The systemd package will create the directory itself. However, please note that this change will trigger automatic mounting of it in OpenRC as well, and may trigger its use by different software packages.

Upstream only supports the file being a symlink to. Not creating this symlink will also cause problems with  and. In the past some utilities wrote information (like mount options) into 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 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
For a split configuration, use an initramfs to mount  before starting systemd. For now, this means using or  until support for  is available in. Set aside time now to migrate:

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

When genkernel-next is used, before rebuilding the kernel, be sure to set the UDEV variable in 's configuration file to. This will pull into the initramfs:

See the Initramfs guide for more alternatives.

Using LVM2 and initramfs
When sys-fs/lvm2 is used and the system is booted using an initramfs, the initramfs will have to be created using by running:

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

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

Installation
contains udev. Once installed, can be removed as systemd will be the provider for.

Enable the  USE flag globally (in ). The  USE flag should also be disabled to prevent conflicts with the  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 :

Finally update the system with the new flags:

When dependency problems occur (such as blocking ),  might be registered in the world file. Try to resolve this by deselecting it:

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

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

Grub Legacy (0.x)
The  argument should be added to the kernel command-line. An example excerpt from would look like so:

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

Grub 2
When is used, add the init option to GRUB_CMDLINE_LINUX :

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

When using genkernel-next's initrd, use  instead of.

In kernel config
The init configuration can also be hard-coded in the kernel configuration. See. Note that this technique works for both and.

Setting root password
At this point don't forget to set the system's root password. If something goes wrong, systemd will prompt for the root password to go into maintenance mode.

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

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

When booted using systemd, a tool called exists for editing  and. To change the hostname, run:

Refer to for more options.

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

Once booted with systemd, the tool 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:

Time and date
Time and date can be set using the utility. That will also allow users to set up synchronization without needing to rely on or other providers than systemd's own implementation.

To learn how to use 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. 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. The module loading can be separated by program, service or whatever way that fits personal preference. An example is listed below:

systemd-networkd
systemd-networkd is useful for simple configuration of wired network interfaces. It is disabled by default.

To configure systemd-networkd, create a file under. See systemd.network(5) for reference. A simple DHCP configuration is given below:

Note that systemd-networkd does not update by default. To have systemd manage the DNS settings, replace with a symlink and start systemd-resolved.

NetworkManager
Often NetworkManager is used to configure network settings. For that purpose, simply run the following command when using an X11-powered 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 is a curses frontend that will guide the user in the process while running in console mode.

Handling of log files
systemd has its own way of handling log files without needing to rely on any external log system (like or ). Messages can now be read with. It can still be configured to use a preferred external tool for handling them. See to learn how to configure journald to suit personal needs.

Some common options:

For more information and many more options, look at.

/tmp is now in tmpfs
Unless some other filesystem is explicitly mounted to in, systemd will mount  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 boot option  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  boot option, systemd can still be configured to show its status by also passing.
 * When not using the  boot option, some messages might be overwriting consoles. That is caused by the kernel configuration (see  and look for ). To tweak it pass the   boot parameter to the kernel (and update the value according to preference, for instance set a lower value like 1).

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 works with systemd not running, but that  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.

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

The following file suffixes are of interest:

Alternatively the 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 system to be started on a next boot; to start the service right now, use:

Services can be stopped likewise:

Installing custom unit files
Custom unit files can be placed in, where they will be recognized after running :

is reserved for service files installed by the package manager.

Customizing unit files
When only minor changes to a unit are needed, there's no need to create a full copy of the original unit file in. Overriding settings in a package management provided unit can be achieved by drop-in files in a directory named after the original unit (e.g. ) in.

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. The name of the directory can either specify a target or another service which will depend on the new one.

For example, to install as  in the :

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:

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.

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:

Firstly, tell systemd to rescan the service files:

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 installed, which can be found in kylemanna's systemd-utils repository.

Replacing cron
The above timer and service files can also be added to to make them available system-wide. The install section should then say  to enable the service at system start.

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

Troubleshooting

 * Upstream debugging guide
 * Upstream debugging guide
 * Upstream debugging guide

/dev/kmsg buffer overrun, some messages lost

 * Problem: When booting the system displays an infinite loop of . 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 . 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 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 to  and graphical sessions using the remaining TTYs) force it to always launch  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
As systemd-bootchart attempts to start, reconfigure it to invoke systemd instead:

The result of the bootchart is a report in SVG format located in.

syslog-ng conflicts with systemd
systemd creates as datagram socket  so syslog-ng needs to be told to read from a unix-dgram instead of a unix-stream as otherwise syslog-ng would be using a "wrong" stream:

syslog-ng source for systemd
There is no need to add  to the  config file. It will cause to fail (at least on version syslog-ng-3.7.2). Update the  line mentioned in the syslog-ng article as follows:

sys-fs/cryptsetup configuration
systemd does not seem to respect (see ) so it needs to be configured through the  file:

Based on the system's file, a new service file might need to be created. To do this, enable the  USE flag for. It will install. Executing it will create a service file in, which can now be copied to , adjusted manually and added to the desired runlevel.

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 :

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 setting 'init' to, 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 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, as: https://bugs.gentoo.org/show_bug.cgi?id=472098

External resources

 * FAQ
 * Tips and tricks