Using Systemd on Flatcar Container Linux on Flatcar Container Linux

Getting started with systemd

Mon, 01 Jan 0001 00:00:00 +0000

systemd is an init system that provides many powerful features for starting, stopping, and managing processes. Within Flatcar Container Linux, you will almost exclusively use systemd to manage the lifecycle of your Docker containers.

Terminology

systemd consists of two main concepts: a unit and a target. A unit is a configuration file that describes the properties of the process that you’d like to run. This is normally a docker run command or something similar. A target is a grouping mechanism that allows systemd to start up groups of processes at the same time. This happens at every boot as processes are started at different run levels.

Overview of systemctl

Mon, 01 Jan 0001 00:00:00 +0000

systemctl is your interface to systemd, the init system used in Flatcar Container Linux. All processes on a single machine are started and managed by systemd, including your Docker containers. You can learn more in our Getting Started with systemd guide. Let’s explore a few helpful systemctl commands. You must run all of these commands locally on the Flatcar Container Linux machine:

Find the status of a container

The first step to troubleshooting with systemctl is to find the status of the item in question. If you have multiple Exec commands in your service file, you can see which one of them is failing and view the exit code. Here’s a failing service that starts a private Docker registry in a container:

Using systemd drop-in units

Mon, 01 Jan 0001 00:00:00 +0000

There are two methods of overriding default Flatcar Container Linux settings in unit files: copying the unit file from /usr/lib64/systemd/system to /etc/systemd/system and modifying the chosen settings. Alternatively, one can create a directory named unit.d within /etc/systemd/system and place a drop-in file name.conf there that only changes the specific settings one is interested in. Note that multiple such drop-in files are read if present.

The advantage of the first method is that one easily overrides the complete unit, the default Flatcar Container Linux unit is not parsed at all anymore. It has the disadvantage that improvements to the unit file supplied by Flatcar Container Linux are not automatically incorporated on updates.

Scheduling tasks with systemd timers

Mon, 01 Jan 0001 00:00:00 +0000

Flatcar Container Linux uses systemd timers (cron replacement) to schedule tasks. Here we will show you how you can schedule a periodic job.

Let’s create an alternative for this crontab job:

*/10 * * * * /usr/bin/date >> /tmp/date

Timers work directly with services’ units. So we have to create /etc/systemd/system/date.service first:

[Unit]
Description=Prints date into /tmp/date file

[Service]
Type=oneshot
ExecStart=/usr/bin/sh -c '/usr/bin/date >> /tmp/date'

Then we have to create timer unit with the same name but with *.timer suffix /etc/systemd/system/date.timer:

Using environment variables in systemd units

Mon, 01 Jan 0001 00:00:00 +0000

Environment directive

systemd has an Environment directive which sets environment variables for executed processes. It takes a space-separated list of variable assignments. This option may be specified more than once in which case all listed variables will be set. If the same variable is set twice, the later setting will override the earlier setting. If the empty string is assigned to this option, the list of environment variables is reset, all prior assignments have no effect. Environments directives are used in built-in Flatcar Container Linux systemd units, for example in etcd2 and flannel.

Using systemd and udev rules

Mon, 01 Jan 0001 00:00:00 +0000

In our example we will use libvirt VM with Flatcar Container Linux and run systemd unit on disk attach event. First of all we have to create systemd unit file /etc/systemd/system/device-attach.service:

[Service]
Type=oneshot
ExecStart=/usr/bin/echo 'device has been attached'

This unit file will be triggered by our udev rule.

Then we have to start udevadm monitor --environment to monitor kernel events.

Once you’ve attached virtio libvirt device (i.e. virsh attach-disk coreos /dev/VG/test vdc) you’ll see similar udevadm output:

User Units

Mon, 01 Jan 0001 00:00:00 +0000

Flatcar Container Linux supports the use of systemd user units. These are unit files located in a users home directory, managed by the user, and executed with their permission.

User units are stored in ~/.config/systemd/user/. When using Butane to configure these during provisioning you must create this entire path, level by level as demonstrated here. This is adapated from documentation for Fedora CoreOS .

variant: flatcar
version: 1.0.0
storage:
  directories:
    # Path for $user's systemd units
    - path: /home/$user/.config
      mode: 0755
      user:
        name: $user
      group:
        name: $user
    - path: /home/$user/.config/systemd
      mode: 0755
      user:
        name: $user
      group:
        name: $user
    - path: /home/$user/.config/systemd/user
      mode: 0755
      user:
        name: $user
      group:
        name: $user

    # Path to manually enable $user's systemd units - these are links back to the unit file
    - path: /home/$user/.config/systemd/user/default.target.wants
      mode: 0755
      user:
        name: $user
      group:
        name: $user

    # Path for $user's podman quadlets
    - path: /home/$user/.config/containers/systemd
      mode: 0755
      user:
        name: $user
      group:
        name: $user

Network Access

In some cases the network will not be online when the user units are executed. This may happen when there is no network requiring component in the boot process. For example, requiring a network mounted home directory would cause user units to execute after the network was online. If you have no such requirements or wish to gurantee that the network is online before user units are excuted you can use the following systemd dropin to modify the systemd-user-sessions.service to run after the network is online. This affects all users.