Since we are at a transition period where some users may be running monolithic libvirtd and others already the modular topology we need a section that allows users to figure out which is in use. This will be particularly important in the document about enabling logging, as the active log file depends on which daemon is in use. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/daemons.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/daemons.rst b/docs/daemons.rst index 1f9bc34260..c3970eb89c 100644 --- a/docs/daemons.rst +++ b/docs/daemons.rst @@ -435,6 +435,58 @@ host first. $ systemctl enable virtproxyd-tls.socket $ systemctl start virtproxyd-tls.socket +Checking whether modular/monolithic mode is in use +================================================== + +New distributions are likely to use the modular mode although the upgrade +process preserves whichever mode was in use before the upgrade. + +To determine whether modular or monolithic mode is in use on a host running +``systemd`` as the init system you can take the following steps: + +#. Check whether the modular daemon infrastructure is in use + + First check whether the modular daemon you are interested (see + `Modular driver daemons`_ for a summary of which daemons are provided by + libvirt) in is running: + + #. Check ``.socket`` for socket activated services + + :: + + # systemctl is-active virtqemud.socket + active + + #. Check ``.service`` for always-running daemons + + :: + + # systemctl is-active virtqemud.service + active + + If either of the above is ``active`` your system is using the modular daemons. + +#. Check whether the monolithic daemon is in use + + #. Check ``libvirtd.socket`` + + :: + + # systemctl is-active libvirtd.socket + active + + #. Check ``libvirtd.service`` for always-running daemon + + :: + + # systemctl is-active libvirtd.service + active + + If either of the above is ``active`` your system is using the monolithic + daemon. + +#. To determine which of the above will be in use on the next boot of the system, + substitute ``is-enabled`` for ``is-active`` in the above examples. Proxy daemon ============ -- 2.34.1

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(a)redhat.com&gt; --- docs/kbase/debuglogs.rst | 98 ++++++++++++++++++++++++++++++++-------- 1 file changed, 79 insertions(+), 19 deletions(-) diff --git a/docs/kbase/debuglogs.rst b/docs/kbase/debuglogs.rst index c3d4d3a425..d2632cfff1 100644 --- a/docs/kbase/debuglogs.rst +++ b/docs/kbase/debuglogs.rst @@ -92,38 +92,94 @@ important. Libvirt daemons logging configuration ===================================== +Libvirt daemons can be configured either via a config file or via the +administration API. The configuration location depends on multiple factors. + +Session vs system daemons +------------------------- + +Libvirt daemons run either in the ``system`` mode or on ``session`` (user) +mode, depending on the configuration of the host and available permission +levels. + +The `connection URI <https://libvirt.org/uri.html>`__ influences which daemon +the client will communicate with. + +System daemon mode +~~~~~~~~~~~~~~~~~~ + * all connection URIs end in ``/system`` e.g. ``qemu:///system`` + + * config files are usually placed in ``/etc/libvirt`` + +Session daemon mode +~~~~~~~~~~~~~~~~~~~ + + * connection URIs end in ``/session`` + + * config files are usually placed in ``$XDG_CONFIG_HOME/libvirt/`` directory + +Modular vs. monolithic daemons +------------------------------ + +While there is only a single 'libvirtd.conf' configuration file in case of the +monolithic daemon setup, each of the modular daemons has their own +configuration file giving you a lot of possibilities how to configure them +individually including logging. Realistically though, logging will have to be +configured only for a single or a couple of daemons in case debug logs are +requested. + + +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 + +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 ------------------ -The daemon configuration files location is dependent on `connection -URI <https://libvirt.org/uri.html>`__. For ``qemu:///system``: - +In order to setup libvirt logging persistently, follow the steps below: +- open the appropriate daemon config file in your favourite editor :: -- open ``/etc/libvirt/libvirtd.conf`` in your favourite editor -- find & replace, or set these variables: + /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" + 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 libvirtd service - -:: +- restart the corresponding service/daemon e.g. :: - systemctl restart libvirtd.service + 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 --------------- @@ -132,9 +188,13 @@ 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`` according to the +guideline in the sections above in place of ``virt-admin`` in the examples +below if needed. + +The following command allows to query the list of currently active log filters: :: -- 2.34.1

Hint users that they can use 'virt-admin' also for the new monolithic daemons. Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2038045 Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/manpages/virt-admin.rst | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/manpages/virt-admin.rst b/docs/manpages/virt-admin.rst index 940a38bfce..21c664bb68 100644 --- a/docs/manpages/virt-admin.rst +++ b/docs/manpages/virt-admin.rst @@ -55,7 +55,7 @@ The ``virt-admin`` program understands the following *OPTIONS*. ``-c``, ``--connect`` *URI* Connect to the specified *URI*, as if by the ``connect`` command, -instead of the default connection. +instead of the default connection. See `NOTES`_. ``-d``, ``--debug`` *LEVEL* @@ -90,11 +90,19 @@ virt-admin is coming from. NOTES ===== -Running ``virt-admin`` requires root privileges due to the -communications channels used to talk to the daemon. Consider changing the -*unix_sock_group* ownership setting to grant access to specific set of users -or modifying *unix_sock_rw_perms* permissions. Daemon configuration file -provides more information about setting permissions. +The ``virt-admin`` supports both the monolithic ``libvirtd`` daemon and the +`modular daemons <https://www.libvirt.org/daemons.html#modular-driver-daemons>`__ +whichever is in use by your system. The connection *URI* used with +``-c/--connect`` or the `connect`_ command is based on the name of the +controlled daemon e.g.: ``virtqemud:///system``, ``libvirtd:///system``. + +Running ``virt-admin`` requires root privileges when communicating with the +system instance of a daemon (*URI* ending in ``/system``) due to the +communications channels used to talk to the daemon. + +Consider changing the *unix_sock_group* ownership setting to grant access to +specific set of users or modifying *unix_sock_rw_perms* permissions. Daemon +configuration file provides more information about setting permissions. GENERIC COMMANDS @@ -198,6 +206,8 @@ If *LIBVIRT_ADMIN_DEFAULT_URI* or *uri_default* (see below) were set, active connection is executed. Note that this only applies if there is no connection at all or there is an inactive one. +See `NOTES`_ on picking the correct *URI* corresponding to a libvirt daemon. + To find the currently used URI, check the *uri* command documented below. -- 2.34.1