~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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|