Documents/README.Systemd

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using Systemd Service Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: prologue.rst

.. |configuration directory| replace:: /usr/lib
.. |unit directory| replace:: |configuration directory|/systemd/system
.. |users directory| replace:: |configuration directory|/sysusers.d
.. |files directory| replace:: |configuration directory|/tmpfiles.d
.. |commands directory| replace:: /usr/libexec/brltty
.. |build subdirectory| replace:: Autostart/Systemd
.. |default configuration file| replace:: ``/etc/brltty.conf``

Initial Setup
=============

The following steps need to be performed:

* Systemd service and path units need to be installed
  into the |unit directory| directory:

  + brltty@.service
  + brltty-device@.service
  + brltty.path
  + brltty@.path

* A wrapper script needs to be installed
  into the |commands directory| directory:

  + systemd-wrapper

* A file defining the non-root user that BRLTTY is to run as,
  including the supplementary groups that it needs access to,
  needs to be installed into the |users directory| directory:

  + sysusers -> brltty.conf

* A file defining the files and directories that should exist
  needs to be installed into the |files directory| directory:

  + tmpfiles -> brltty.conf

A make file has been provided in order to make this easy to do.
It can be found within the |build subdirectory| subdirectory
of BRLTTY's build tree.
To install all of these files, change to this directory and run the command::

  make install

You then need to tell Systemd that the files have been installed.
To do this, run the command::

  systemctl daemon-reload

That's all you need to do.
Your system is now able to manage BRLTTY instances via Systemd.

Managing BRLTTY Instances
=========================

Systemd manages BRLTTY instances on your system in a number of ways.

USB Braille Devices
-------------------

If BRLTTY's Udev rules have also been installed
then a BRLTTY instance will be automatically started
when a USB braille device is connected,
and automatically stopped when it's disconnected.
Several braille devices can be managed in this way at the same time.
They can be connected and disconnected at any time and in any order.

The default configuration file - |default configuration file| - is used
except that any ``braille-device`` and ``braille-driver`` directives
that it specifies are ignored because they're overridden by the Udev rules.
It's safe, therefore, to specify a default non-USB braille device
within |default configuration file|.

The Default Instance
--------------------

The default BRLTTY instance is the one that's configured
via the file |default configuration file|.
It's managed by applying standard Systemd commands to BRLTTY's path unit.
For example::

  systemctl enable brltty.path
  systemctl start brltty.path
  systemctl stop brltty.path
  systemctl disable brltty.path

Additional Instances
--------------------

Additional BRLTTY instances can be managed via path instance references.
Each of them has its own configuration file.

If, for example, the name of an instance is ``iname``, then
its Systemd path name would be ``brltty@iname``,
its configuration file would be ``/etc/brltty_iname.conf``,
and it'd be managed via Systemd commands like these::

  systemctl enable brltty@iname.path
  systemctl start brltty@iname.path
  systemctl stop brltty@iname.path
  systemctl disable brltty@iname.path

Any number of instances may be managed in this way.
These instances don't implicitly also read the default configuration file
(|default configuration file|).
You can, however, explicitly include it
from within any instance-specific configuration file:

.. parsed-literal:: include |default configuration file|