contrib/systemd: add systemd services

Signed-off-by: Stefan Wiehler <stefan.wiehler@missinglinkelectronics.com>

Author: Stefan Wiehler

contrib/systemd/labgrid-coordinator.service

@@ -0,0 +1,13 @@
+[Unit]
+Description=Labgrid Coordinator
+After=network.target
+
+[Service]
+ExecStart=/path/to/labgrid-coordinator/venv/bin/crossbar start --logformat=syslogd --cbdir /var/lib/labgrid-coordinator --config /etc/labgrid/coordinator.yaml
+ExecStop=/usr/bin/labgrid-coordinator stop --cbdir /var/lib/labgrid-coordinator
+Restart=on-abort
+DynamicUser=yes
+StateDirectory=labgrid-coordinator
+
+[Install]
+WantedBy=multi-user.target

contrib/systemd/labgrid-exporter.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=Labgrid Exporter
+After=network.target
+
+[Service]
+ExecStart=/path/to/labgrid/venv/bin/labgrid-exporter /etc/labgrid/exporter.yaml
+Restart=on-abort
+User=labgrid
+Group=labgrid
+# Adjust to your distribution (most often "dialout" or "tty")
+SupplementaryGroups=dialout
+CacheDirectory=labgrid
+CacheDirectoryMode=1775
+
+[Install]
+WantedBy=multi-user.target

contrib/systemd/sysusers.d/labgrid.conf

@@ -0,0 +1,2 @@
+# Type	Name	ID	GECOS		Home directory Shell
+u	labgrid	-	"Labgrid"

contrib/systemd/tmpfiles.d/labgrid.conf

@@ -3,4 +3,4 @@
 # it is advised to at least change the group from the default for your
 # environment
 # Path			Mode	UID	GID	Age Argument
-d /var/cache/labgrid	1775	root	users	2d
+d /var/cache/labgrid	1775	labgrid	labgrid	2d

doc/getting_started.rst

@@ -176,6 +176,8 @@ same machine. The client is used to access functionality provided by an
 exporter. Over the course of this tutorial we will set up a coordinator and
 exporter, and learn how to access the exporter via the client.
 
+.. _remote-getting-started-coordinator:
+
 Coordinator
 ~~~~~~~~~~~
 
@@ -327,6 +329,75 @@ See :ref:`remote-usage` for some more advanced features.
 For a complete reference have a look at the :doc:`labgrid-client(1) <man/client>`
 man page.
 
+Systemd files
+~~~~~~~~~~~~~
+
+Labgrid comes with several systemd files in :file:`contrib/systemd`:
+
+- service files for coordinator and exporter
+- tmpfiles.d file to regularly remove files uploaded to the exporter in
+  :file:`/var/cache/labgrid`
+- sysusers.d file to create the ``labgrid`` user and group, enabling members of
+  the ``labgrid`` group to upload files to the exporter in :file:`/var/cache/labgrid`
+
+Follow these instructions to install the systemd files on your machine(s):
+
+#. Copy the service, tmpfiles.d and sysusers.d files to the respective
+   installation paths of your distribution.
+#. Adapt the ``ExecStart`` paths of the service files to the respective Python
+   virtual environments of the coordinator and exporter.
+#. Create the coordinator configuration file referenced in the ``ExecStart``
+   option of the :file:`systemd-coordinator.service` file by using
+   :file:`.crossbar/config.yaml` as a starting point. You most likely want to
+   make sure that the ``workdir`` option matches the path given via the
+   ``--cbdir`` option in the service file; see
+   :ref:`remote-getting-started-coordinator` for further information.
+#. Adjust the ``SupplementaryGroups`` option in the
+   :file:`labgrid-exporter.service` file to your distribution so that the
+   exporter gains read and write access on TTY devices (for ``ser2net``); most
+   often, this group is called ``dialout`` or ``tty``.
+#. Set the coordinator URL the exporter should connect to by overriding the
+   exporter service file; i.e. execute ``systemctl edit
+   labgrid-exporter.service`` and add the following snippet:
+
+   .. code-block::
+
+      [Service]
+      Environment="LG_CROSSBAR=ws://<your-host>:<your-port>/ws"
+
+#. Create the ``labgrid`` user and group:
+
+   .. code-block:: console
+
+      # systemd-sysusers
+
+#. Reload the systemd manager configuration:
+
+   .. code-block:: console
+
+      # systemctl daemon-reload
+
+#. Start the coordinator, if applicable:
+
+   .. code-block:: console
+
+      # systemctl start labgrid-coordinator
+
+#. After creating the exporter configuration file referenced in the
+   ``ExecStart`` option of the :file:`systemd-exporter.service` file, start the
+   exporter:
+
+   .. code-block:: console
+
+      # systemctl start labgrid-exporter
+
+#. Optionally, for users being able to upload files to the exporter, add them
+   to the `labgrid` group on the exporter machine:
+
+   .. code-block:: console
+
+      # usermod -a -G labgrid <user>
+
 .. _udev-matching:
 
 udev Matching