[PATCH 8/8] kbase: debuglogs: Fix for modular daemons

[Peter Krempa]

Modular daemons are now the default in many new installations, thus we
need to include steps how to determine that modular daemons are used and
modular-daemon specific locations for the config files and admin URIs.

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/kbase/debuglogs.rst | 94 +++++++++++++++++++++++++++++++---------
 1 file changed, 73 insertions(+), 21 deletions(-)

diff --git a/docs/kbase/debuglogs.rst b/docs/kbase/debuglogs.rst
index fc75ef14a4..ea7c2c1d52 100644
--- a/docs/kbase/debuglogs.rst
+++ b/docs/kbase/debuglogs.rst
@@ -87,38 +87,87 @@ more information than lack something important.
 Libvirt daemons logging configuration
 =====================================

-Persistent setting
-------------------
+Libvirt daemons can be configured either via a config file or via the
+administration API. The configuration location depends on multiple factors.

-The daemon configuration files location is dependent on `connection
-URI <https://libvirt.org/uri.html>`__. For ``qemu:///system``:
+Session vs. system daemons
+--------------------------

+The libvirt daemons run either on ``system`` level or on ``session`` (user)
+level, depending on the configuration of the host and the available permission
+levels.

+The `connection URI <https://libvirt.org/uri.html>`__ influences which daemon
+the client is communicating with.

--  open ``/etc/libvirt/libvirtd.conf`` in your favourite editor
--  find & replace, or set these variables:
+``system`` daemon e.g ``qemu:///system`` URI

-::
+  * config files are usually placed in ``/etc/libvirt/``

-   log_filters="3:remote 4:event 3:util.json 3:rpc 1:*"
-   log_outputs="1:file:/var/log/libvirt/libvirtd.log"
+  * ``virt-admin`` URI ending in ``/system`` should be used.

--  save and exit
--  restart libvirtd service
+``session`` daemon e.g. ``qemu:///session`` URI

-::
+  * config files are usually placed in ``$XDG_CONFIG_HOME/libvirt/`` directory
+
+  * ``virt-admin`` URI ending in ``/session`` should be used
+
+Modular vs. monolithic daemons
+------------------------------
+
+While the config file name for the monolithic daemon is simple, in case when
+modular daemons are used, there's a lot of options.
+
+All libvirt daemons support the logging configuration per this document, but
+in most cases it's required to configure logging for the appropriate.
+
+Refer to `documentation about daemons <../daemons.html#checking-whether-modular-monolithic-mode-is-in-use>`__
+to figure out which is in use by your system.
+
+ Modular daemons
+
+   The configuration of modular daemons is in file named after the daemon. E.g.
+   for ``qemu:///system`` connection this is the ``virtqemud`` daemon and
+   correspondingly:
+
+     * ``virtqemud.conf`` config file is used
+
+     * ``virtqemud:///system`` or ``virtqemud:///session`` admin URI is used

-   systemctl restart libvirtd.service
+ Monolithic daemon
+
+     * ``libvirtd.conf`` config file is used
+
+     * ``libvirtd:///system`` or ``libvirtd:///session`` admin URI is used
+       when the modular qemu hypervisor driver ``virtqemud``
+
+Persistent setting
+------------------
+
+-  open the appropriate daemon config file in your favourite editor ::
+
+     /etc/libvirt/virtqemud.conf
+     /etc/libvirt/libvirtd.conf
+     $XDG_CONFIG_HOME/libvirt/libvirtd.conf
+     $XDG_CONFIG_HOME/libvirt/virtqemud.conf
+
+-  find & replace, or set the apropriate `Log outputs`_ and `Log filters`_, e.g ::
+
+     log_filters="3:remote 4:event 3:util.json 3:rpc 1:*"
+     log_outputs="1:file:/var/log/libvirt/libvirtd.log"
+
+-  save and exit
+-  restart the corresponding service/daemon e.g. ::
+
+    systemctl restart virtqemud.socket
+    systemctl restart libvirtd.socket
+    systemctl restart libvirtd.service


 *Note:* Libvirt prior to the ``libvirt-4.4.0`` release didn't support globbing
 patterns and thus requires more configuration. See
 `Legacy (pre-4.4.0) libvirt daemon logging configuration`_.

-However, when you are using the session mode ``qemu:///session`` or you run the
-``libvirtd`` as unprivileged user you will find configuration file under
-``$XDG_CONFIG_HOME/libvirt/libvirtd.conf``.
-
 Runtime setting
 ---------------

@@ -127,13 +176,16 @@ after the daemon restarts, since the new session can make the anomaly
 "disappear". Therefore, it's possible to enable the debug logs during runtime
 using libvirt administration API. To use it conveniently, there's the
 ``virt-admin`` client provided by the ``libvirt-admin`` package. Use the
-package manager provided by your distribution to install this package. Once you
-have it installed, run the following as root to see the set of log filters
-currently being active:
+package manager provided by your distribution to install this package.
+
+**Important**: Substitute ``virt-admin -c $ADMIN_URI`` per above guidance in
+place of ``virt-admin`` in the examples below if needed.
+
+The following command allows to query the list of log filters currently active:

 ::

-   # virt-admin daemon-log-filters
+   # virt-admin  daemon-log-filters
     Logging filters: 3:remote 4:util.json 4:rpc

 In order to change this set, run the same command as root, this time with your
-- 
2.34.1