[PATCH v2 0/3] kbase: debuglogs: Include guidance how to setup logging with modular daemons
v2 includes changes suggested by Erik. Patches 2/8 - 7/8 of the original series were pushed. 1/3 corresponds to 1/8. The issue of which daemons are actually provided by libvirt was solved by linking to a chapter above where the daemons are enumerated. 2/3 corresponds to 8/8. Eriks changes were incorporated (hopefully). 3/3 is new in this series Improve the 'virt-admin' man page to mention how URIs are constructed. Processed output is at: https://pipo.sk.gitlab.io/-/libvirt/-/jobs/1997481301/artifacts/website/kbas... https://pipo.sk.gitlab.io/-/libvirt/-/jobs/1997481301/artifacts/website/daem... https://pipo.sk.gitlab.io/-/libvirt/-/jobs/1997481301/artifacts/website/manp... Peter Krempa (3): docs: daemons: Add section on figuring out whether modular or monolithic daemon is in use kbase: debuglogs: Fix for modular daemons man: virt-admin: Mention monolithic daemon URIs docs/daemons.rst | 52 +++++++++++++++++++ docs/kbase/debuglogs.rst | 98 +++++++++++++++++++++++++++++------- docs/manpages/virt-admin.rst | 22 +++++--- 3 files changed, 147 insertions(+), 25 deletions(-) -- 2.34.1
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@redhat.com> --- 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
On Thu, Jan 20, 2022 at 04:34:01PM +0100, Peter Krempa wrote:
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@redhat.com> --- 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
For ^these 2 checks, simple bulleted list would do even better. Also, for some reason ^this hunk resulted in: 1. Check ``.socket``... 1. Check ``.service``...
+ + :: + + # 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
...same ^here as above :) with bulleted lists: Reviewed-by: Erik Skultety <eskultet@redhat.com>
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@redhat.com> --- 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
On Thu, Jan 20, 2022 at 04:34:02PM +0100, Peter Krempa wrote:
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@redhat.com> --- 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)
s/on/in the/
+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.
Okay, so you didn't want to go with my lengthy suggestion :), but we still need to improve ^this sentence a little, how about: "Each modular daemon has its own dedicated configuration file named after itself, e.g. ..." Reviewed-by: Erik Skultety <eskultet@redhat.com>
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@redhat.com> --- 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
On Thu, Jan 20, 2022 at 04:34:03PM +0100, Peter Krempa wrote:
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@redhat.com> --- 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.
^This last paragraph is not true with virt-admin, because it's not subject to any authentication mechanism we use by design, especially with socket activation where the socket will always have 0600 permissions and only root can access it. Without socket activation there's the 'unix_sock_admin_perms' setting (beats me why we/I introduced it in the first place), but there is no group ownership whatsoever and indeed if you look at remoteAdmClientNew, you'll see we're doing the following: if (geteuid() != clientuid) ... With the last paragraph about socket ownership removed: Reviewed-by: Erik Skultety <eskultet@redhat.com>
On Thu, Jan 20, 2022 at 18:14:08 +0100, Erik Skultety wrote:
On Thu, Jan 20, 2022 at 04:34:03PM +0100, Peter Krempa wrote:
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@redhat.com> --- docs/manpages/virt-admin.rst | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-)
[...]
+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.
^This last paragraph is not true with virt-admin, because it's not subject to any authentication mechanism we use by design, especially with socket activation where the socket will always have 0600 permissions and only root can access it. Without socket activation there's the 'unix_sock_admin_perms' setting (beats me why we/I introduced it in the first place), but there is no group ownership whatsoever and indeed if you look at remoteAdmClientNew, you'll see we're doing the following:
if (geteuid() != clientuid) ...
Hmm, this commit is merely re-indenting and moving the text. I think I'll be able to justtify it better if I remove it first by a separate commit and let this commit just do the URI changes.
On Thu, Jan 20, 2022 at 06:16:43PM +0100, Peter Krempa wrote:
On Thu, Jan 20, 2022 at 18:14:08 +0100, Erik Skultety wrote:
On Thu, Jan 20, 2022 at 04:34:03PM +0100, Peter Krempa wrote:
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@redhat.com> --- docs/manpages/virt-admin.rst | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-)
[...]
+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.
^This last paragraph is not true with virt-admin, because it's not subject to any authentication mechanism we use by design, especially with socket activation where the socket will always have 0600 permissions and only root can access it. Without socket activation there's the 'unix_sock_admin_perms' setting (beats me why we/I introduced it in the first place), but there is no group ownership whatsoever and indeed if you look at remoteAdmClientNew, you'll see we're doing the following:
if (geteuid() != clientuid) ...
Hmm, this commit is merely re-indenting and moving the text. I think I'll be able to justtify it better if I remove it first by a separate commit and let this commit just do the URI changes.
Sure, feel free to push 1 and 2 and post one just with the URI changes. Erik
On Thu, Jan 20, 2022 at 04:34:00PM +0100, Peter Krempa wrote:
v2 includes changes suggested by Erik. Patches 2/8 - 7/8 of the original series were pushed.
1/3 corresponds to 1/8.
The issue of which daemons are actually provided by libvirt was solved by linking to a chapter above where the daemons are enumerated.
Oh yeah, this is actually better, I missed the fact that they're already enumerated above...
participants (2)
-
Erik Skultety -
Peter Krempa