Kira's Web-Treehouse for Plants 🌱

& Other Wayward Beings

🖥️ Simple systemd Service Unit

Have you wanted to have a program start when you boot up your machine, and not want to have to start it manually, or have it hanging around in a terminal window?

This brief article shows how to create a simple systemd user service unit for such a program. It will start automatically when the machine boots, and log its output to a persistent journalling system.

It is also, I think, a nice, easy first step into the perhaps intimidating world of systemd.

In systemd a service unit is "A unit configuration file whose name ends in ".service" encodes information about a process controlled and supervised by systemd." (from man systemd.service)

A user service unit is a service unit that can be created, maintained, and controlled entirely by a non-root user.

Here, simple means just running an executable file, like one runs ls or grep in a terminal shell.

Let's assume the executable file we want to run on system start-up is called my-program.

Table of Contents

  1. Step 1: Create service file
  2. Step 2: Reload Definitions and Enable the Service Unit
  3. Step 3: Keep Learning!

Step 1: Create service file

User service definitions live in

$HOME/.config/systemd/user/

Create a file in this directory named my-service.service. This file name will be the one used to refer to this service.

Put the following inside:

[Unit]
Description=Runs my-program, which does X, Y and Z.

[Service]
Type=exec
WorkingDirectory=/home/kira/bin/
StandardOutput=journal
ExecStart=my-program

[Install]
WantedBy=default.target

Here is an explanation of some of the keys:

Type: There are several types of services. simple is the default, but exec is nicer, I think, because it will report failure if the program failed to start because e.g. it couldn't be found, whereas simple would report success.

WorkingDirectory: The working directory of the executed process.

StandardOutput: Controls where the process' standard out is directed. journal writes to the systemd journal, which can be viewed using journalctl --user -u my-program.service.

ExecStart: The command that the service is to run.

WantedBy: A space-separated list of units that will depend on this unit. default.target is the unit that gets started when the system boots up. The effect is that the system is only considered "started up" once this new service unit we made is (attempted to be) started.

Step 2: Reload Definitions and Enable the Service Unit

systemd needs to be informed that there is a new service unit definition. To do this, run

systemd --user daemon-reload

You'll need to do this any time you edit a systemd service unit definition file, too.

Lastly, activate the service unit:

systemctl --user enable my-program.service

This will also start the service. Let's check!

ps x | grep my-program

 307062 ?        Ss     0:00 /bin/bash /home/kira/bin/my-program
 307067 ?        S      0:00 /bin/bash /home/kira/bin/my-program

Well done! You're all finished.

Step 3: Keep Learning!

To learn even more, check out these pages:

man systemd

man systemd.service

man systemd.exec

You can also further explore the rest of the systemd reading materials:

man -k systemd

Thanks for reading! Please email me any comments or questions.