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 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 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 multiple instances, meaning that there can be multiple processes, each one
doing a different task. doing a different task.
In the default configuration, both setups are supported. The default is to run The most common use case for such a setup is to separate the graph orchestration
in single-instance mode. 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 To achieve a multi-instance setup, WirePlumber can be started multiple times
default configuration file, and from there it loads ``main.lua``, ``policy.lua`` with a different :ref:`profile<config_components_and_profiles>` loaded in each
and ``bluetooth.lua``, which are lua configuration files (deployed as directories) instance. This can be achieved using the ``--profile`` command line option to
that enable all the relevant functionality. select the profile to load:
In multi-instance mode, WirePlumber is meant to be started with the
``--config-file`` command line option 3 times:
.. code-block:: console .. code-block:: console
$ wireplumber --config-file=main.conf $ wireplumber --profile=custom
$ wireplumber --config-file=policy.conf
$ wireplumber --config-file=bluetooth.conf
That loads one process which reads ``main.conf``, which then loads ``main.lua`` When no particular profile is specified, the ``main`` profile is loaded.
and enables core functionality. Then another process that reads ``policy.conf``,
which then loads ``policy.lua`` and enables policy functionality... and so on. Systemd integration
-------------------
To make this easier to work with, a template systemd unit is provided, which is 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 meant to be started with the name of the profile as a template argument:
template argument:
.. code-block:: console .. 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@policy
$ systemctl --user enable wireplumber@audio
$ systemctl --user enable wireplumber@camera
$ systemctl --user enable wireplumber@bluetooth $ 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 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. serve a different purpose and they do not conflict with each other.