Merge branch 'weston-systemd' into 'main'

doc/systemd: system service example

Closes #7

See merge request wayland/weston!439

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