colin/wireplumber
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update multi-instance documentation

Browse Source
This commit is contained in:
George Kiagiadakis
2024-01-26 12:12:30 +02:00
parent a511c54c5c
commit 4c94cee54c
1 changed files with 34 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
docs/rst/daemon/configuration/multi_instance.rst
View File

@@ -3,43 +3,57 @@
Running multiple instances
==========================
.. warning::
Multi-instance mode has not been extensively tested in 0.5.0, so it is
possible that some features are not working as expected. An update on this is
planned for a subsequent 0.5.x release.
WirePlumber has the ability to run either as a single instance daemon or as
multiple instances, meaning that there can be multiple processes, each one
doing a different task.
In the default configuration, both setups are supported. The default is to run
in single-instance mode.
The most common use case for such a setup is to separate the graph orchestration
tasks from the device monitoring and object creation ones. This can be useful
for robustness and security reasons, as it allows restarting the device monitors
or running them in different security contexts without affecting the rest of the
session management functionality.
In single-instance mode, WirePlumber reads ``wireplumber.conf``, which is the
default configuration file, and from there it loads ``main.lua``, ``policy.lua``
and ``bluetooth.lua``, which are lua configuration files (deployed as directories)
that enable all the relevant functionality.
In multi-instance mode, WirePlumber is meant to be started with the
``--config-file`` command line option 3 times:
To achieve a multi-instance setup, WirePlumber can be started multiple times
with a different :ref:`profile<config_components_and_profiles>` loaded in each
instance. This can be achieved using the ``--profile`` command line option to
select the profile to load:
.. code-block:: console
$ wireplumber --config-file=main.conf
$ wireplumber --config-file=policy.conf
$ wireplumber --config-file=bluetooth.conf
$ wireplumber --profile=custom
That loads one process which reads ``main.conf``, which then loads ``main.lua``
and enables core functionality. Then another process that reads ``policy.conf``,
which then loads ``policy.lua`` and enables policy functionality... and so on.
When no particular profile is specified, the ``main`` profile is loaded.
Systemd integration
-------------------
To make this easier to work with, a template systemd unit is provided, which is
meant to be started with the name of the main configuration file as a
template argument:
meant to be started with the name of the profile as a template argument:
.. code-block:: console
$ systemctl --user disable wireplumber # disable the single instance
$ systemctl --user disable wireplumber # disable the "main" instance
$ systemctl --user enable wireplumber@main
$ systemctl --user enable wireplumber@policy
$ systemctl --user enable wireplumber@audio
$ systemctl --user enable wireplumber@camera
$ systemctl --user enable wireplumber@bluetooth
.. note::
In WirePlumber 0.4, the template argument was the name of the configuration
file to load, since profiles did not exist. In WirePlumber 0.5, the template
argument is the name of the profile and the configuration file is always
``wireplumber.conf``. To change the name of the configuration file you need
to craft custom systemd unit files and use the ``--config-file`` command line
option as needed.
It is obviously possible to start as many instances as desired, with manually
crafted configuration files, as long as it is ensured that these instances
crafted profiles, as long as it is ensured that these instances
serve a different purpose and they do not conflict with each other.