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