Systemd is mainly used to manage services on modern linux distributions, but it also allows non-root users to manage services running under their own account. This makes systemd a great alternative to services like supervisord as it is able to detect crashes and automatically restarts the service.
Configuring a user unit
The directory structure that holds unit files is similar to the systemwide configuration, but is located in a user’s home directory:
$ mkdir -p ~/.config/systemd/user
user folder we can create service units with a
.service extension. A unit is a ini-style file describing a service that has to be managed.
Let’s say we have a Laravel PHP queue worker that we want to be managed by systemd, called
[Unit] Description=Laravel PHP queue worker [Service] ExecStart=/usr/bin/env php /path/to/my/project/artisan queue:work --sleep=3 --tries=3 [Install] WantedBy=default.target
$ systemctl --user daemon-reload to make systemd recognize your changes.
We can now manage this service with systemd:
$ systemctl --user start workerstarts the service
$ systemctl --user stop workerstops the service
$ systemctl --user restart workerrestarts the workers
$ systemctl --user status workershows us the service status
If we want this service to start automatically when our user logs in, we have to enable it:
$ systemctl --user enable worker
$ systemctl --user disable worker
Everything our PHP script writes to stdout and stderr will be recorded by journald. We can view the logs for this specific service:
$ journalctl -u worker
On older versions of systemd (like the one shipped with Debian Jessie), you might need to use a flag specific to user units:
$ journalctl --user-unit worker
Automatically restarting on failure
Let’s be honest: things go wrong. When our worker crashes we want to make sure it’s started again. Fortunately, we can configure systemd to restart on failure:
Add the following to the
[Service] section of the unit file:
This makes systemd restart the service 10 seconds after it has stopped with a non-zero exit code. If the process exited cleanly, systemd considers the work as done and won’t restart the service until you manually start it later.
Starting user services at boot
By default, systemd starts enabled user units when the user logs in, and stops them once the user has logged out. This is great for desktop pcs where a user wants to run things while he’s using the computer. On servers, however, we may want to run those units all the time.
# loginctl enable-linger USERNAME
You can check the status for each user by:
# loginctl user-status USERNAME
It should show that the user is lingering:
vic (1000) Since: Fri 2017-09-01 21:54:29 CEST; 3s ago State: lingering Unit: user-1000.slice
When the user is not logged in and does not have lingering enabled, loginctl doesn’t know about any user sessions so it will return an error:
Failed to get user: No user 1000 known or logged in