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

.. include:: prologue.rst

.. |default user configuration directory| replace:: /etc
.. |default system unit directory| replace:: |default user configuration directory|/systemd/system
.. |service unit| replace:: brltty.service
.. |service instance unit| replace:: brltty@.service
.. |wrapper directory| replace:: /sbin
.. |wrapper script| replace:: brltty-systemd-wrapper

Installing the Service Units
============================

You need to copy both the service unit and the service instance unit
into Systemd's system unit directory.
You can find out where this directory is on your system with this command::

   pkg-config systemd --variable=systemdsystemunitpath

The output from this command is a colon-delimited list of directories.
Look for the one that starts with |default user configuration directory|.
Assuming that Systemd's system unit directory is |default system unit directory|
(please ensure to use whatever it really is on your system):

1) Define the service instance unit for BRLTTY as follows:

  .. parsed-literal:: cp |service instance unit| |default system unit directory|/|service instance unit|

2) Define the service unit for BRLTTY as follows:

  .. parsed-literal:: cp |service unit| |default system unit directory|/|service unit|

3) Tell Systemd that these units have been defined as follows::

     systemctl daemon-reload

You also need to install a wrapper script that's used by the service units:

  .. parsed-literal:: cp |wrapper script| |wrapper directory|/|wrapper script|
  .. parsed-literal:: chmod 755 |wrapper directory|/|wrapper script|

Managing the BRLTTY Service
===========================

Once the unit file is in the right place, you'll be able to use standard 
Systemd commands to manage the ``brltty`` service. The most common ones are:

systemctl start brltty
   Explicitly start the ``brltty`` service.

systemctl stop brltty
   Explicitly stop the ``brltty`` service.

systemctl enable brltty
   Automatically start the ``brltty`` service on system boot.

systemctl disable brltty
   Don't automatically start the ``brltty`` service on system boot.

systemctl status brltty
   Show the current status of the ``brltty`` service.

journalctl -u brltty
   Show system log messages pertaining to the ``brltty`` service.

Nothing is implicit. If you'd like to start the ``brltty`` service right away
then use the ``start`` function. If you'd like the ``brltty`` service to be
automatically started when the system is booted then use the ``enable``
function.
