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 <pekka.paalanen@collabora.co.uk>
Signed-off-by: Stefan Agner <stefan@agner.ch>

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-<name>.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-<instance-name>`, 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.

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

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