From d9148c75e3001b2d1dfbf2ade62badcddd6c6a71 Mon Sep 17 00:00:00 2001 From: Stefan Agner Date: Sun, 7 Jun 2020 22:24:03 +0200 Subject: [PATCH] doc/systemd: system service example There are many bad and even worse attempts to make Weston run as a systemd service, and very few good ones. Let's add a good one as an example in upstream: does not use weston-launch, does not run weston as root, does not need wrapper scripts, and relies on logind and PAM. This example has been composed from a couple of real-world Weston unit files used in production. The service file is not installed by the build. It would likely need small adjustments for each distribution or system to be deplyed on. Fixes: https://gitlab.freedesktop.org/wayland/weston/-/issues/7 Signed-off-by: Pekka Paalanen Signed-off-by: Stefan Agner --- doc/systemd/README.md | 82 +++++++++++++++++++++++++++++++++++++ doc/systemd/weston@.service | 65 +++++++++++++++++++++++++++++ doc/systemd/weston@.socket | 9 ++++ 3 files changed, 156 insertions(+) create mode 100644 doc/systemd/README.md create mode 100644 doc/systemd/weston@.service create mode 100644 doc/systemd/weston@.socket diff --git a/doc/systemd/README.md b/doc/systemd/README.md new file mode 100644 index 000000000..194a37034 --- /dev/null +++ b/doc/systemd/README.md @@ -0,0 +1,82 @@ +systemd integration examples +============================ + +These examples rely on Weston's logind and systemd support. Weston needs to be +built with options: `--enable-dbus --enable-systemd-login +--enable-systemd-notify` + +Furthermore, Weston needs to be configured to load systemd-notify.so plugin. +This can be done on the Weston command line: + + $ weston --modules=systemd-notify.so + +or in weston.ini: + +~~~ +[core] +modules=systemd-notify.so +~~~ + +The plugin implements the systemd service notification protocol, watchdog +protocol, and also allows socket activation and configuring listening sockets +via systemd. + + +weston@.service +--------------- + +`weston@.service` is an example systemd service file on how to run Weston as a +system service. The service starts a user session of the named user on the given +virtual terminal. This is useful for running a login manager or for dedicated +systems that do not have personal user accounts and do not need the user to log +in. + +The service uses the PAM service name `weston-autologin` to setup the user +session. Make sure to install a suitable PAM configuration file in +`/etc/pam.d/weston-autologin`. A basic configuration file could look like this: + +~~~ +auth required pam_nologin.so +auth required pam_unix.so try_first_pass nullok + +account required pam_nologin.so +account required pam_unix.so + +session required pam_env.so +session required pam_unix.so +-session optional pam_systemd.so type=wayland class=user desktop=weston +-session optional pam_loginuid.so +~~~ + +Install the service template to `/etc/systemd/system`. You should at the very +least customize the user, but likely also the weston command line. You can edit +the service template before installing, or use `systemctl edit` if the service +template is already installed. The tty can be customized by the instance name +(the portion after the @ symbol). To enable and start the service use: + + systemctl enable weston@tty7.service + systemctl start weston@tty7.service + +Note: With this unit pam_systemd creates a new user session and session scope +with it. With that systemd now longer considers Weston to be part of the +weston@ttyX.service unit, but the newly created session slice. Use `loginctl` to +find the session name. Logs can be found in `journalctl +--unit=session-.scope`. + +weston@.socket +-------------- + +`weston@.socket` shows how to start Weston on-demand using systemd's socket +activation for the Wayland UNIX domain stream socket. The example creates a UNIX +domain socket with the name `wayland-`, hence clients need to use +this name as `WAYLAND_DISPLAY`. + +Install the socket template to `/etc/systemd/system`. Make sure the user id +matches your setup. To enable the socket use: + + systemctl enable weston@tty7.socket + systemctl start weston@tty7.socket + +With that, starting a Wayland client with the environment set to +`WAYLAND_DISPLAY=wayland-tty7` will start the `weston@tty7.service` and display +the client once started. diff --git a/doc/systemd/weston@.service b/doc/systemd/weston@.service new file mode 100644 index 000000000..521562164 --- /dev/null +++ b/doc/systemd/weston@.service @@ -0,0 +1,65 @@ +# This is a system unit for launching Weston with auto-login as the +# user configured here. +# +# Weston must be built with "launcher-logind" and "systemd" support. + +[Unit] +Description=Weston, a Wayland compositor, as a system service +Documentation=man:weston(1) man:weston.ini(5) +Documentation=http://wayland.freedesktop.org/ + +# Make sure we are started after logins are permitted. +After=systemd-user-sessions.service + +# If Plymouth is used, we want to start when it is on its way out. +After=plymouth-quit-wait.service + +# D-Bus is necessary for contacting logind. Logind is required. +Wants=dbus.socket +After=dbus.socket + +# Since we are part of the graphical session, make sure we are started before +# it is complete. +Before=graphical.target + +# Prevent starting on systems without virtual consoles, Weston requires one +# for now. +ConditionPathExists=/dev/tty0 + +[Service] + +# Requires systemd-notify.so Weston plugin. +Type=notify +ExecStart=/usr/bin/weston --modules=systemd-notify.so + +# Optional watchdog setup +TimeoutStartSec=60 +WatchdogSec=20 + +# The user to run Weston as. +User=westonuser + +# Make sure working directory is users home directory +WorkingDirectory=~ + +# Set up a full user session for the user, required by Weston. +PAMName=weston-autologin + +# A virtual terminal is needed. +TTYPath=/dev/%I +TTYReset=yes +TTYVHangup=yes +TTYVTDisallocate=yes + +# Fail to start if not controlling the tty. +StandardInput=tty-fail +StandardOutput=journal +StandardError=journal + +# Log this user with utmp, letting it show up with commands 'w' and 'who'. +UtmpIdentifier=%I +UtmpMode=user + +[Install] +WantedBy=graphical.target +DefaultInstance=tty7 diff --git a/doc/systemd/weston@.socket b/doc/systemd/weston@.socket new file mode 100644 index 000000000..26ad2b764 --- /dev/null +++ b/doc/systemd/weston@.socket @@ -0,0 +1,9 @@ +[Unit] +Description=Weston Wayland socket +After=user-runtime-dir@1000.service + +[Socket] +ListenStream=/run/user/1000/wayland-%I + +[Install] +WantedBy=sockets.target