Surprisingly, we never documented the relationship between
connection URI and the location of qemu.conf. Users might wonder
what qemu.conf is loaded when they are connecting to the session
daemon or embed URI. And what to do if the file doesn't exist for
the URI they're using.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
 docs/drvqemu.html.in        | 39 +++++++++++++++++++++++++++++++++++++
 docs/manpages/libvirtd.rst  | 20 +++++++++++++++++++
 docs/manpages/virtqemud.rst | 22 +++++++++++++++++++++
 3 files changed, 81 insertions(+)

diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in
index 31d3fee213..a784f5768c 100644
--- a/docs/drvqemu.html.in
+++ b/docs/drvqemu.html.in
@@ -162,6 +162,45 @@ qemu+ssh://root@example.com/system   (remote access, SSH tunnelled)
       of libvirt, once QMP processing moves to a dedicated thread.
     </p>
 
+    <h2><a id="configFiles">Location of configuration files</a></h2>
+
+    <p>
+      The QEMU driver comes with sane default values. However, during its
+      initialization it reads a configuration file which offers system
+      administrator or an user to override some of that default. The location
+      of the file depends on the connection URI, as follows:
+    </p>
+
+    <table>
+      <tr>
+        <td><code>qemu:///system</code></td>
+        <td><code>/etc/libvirt/qemu.conf</code></td>
+      </tr>
+      <tr>
+        <td><code>qemu:///session</code></td>
+        <td><code>$XDG_CONFIG_HOME/libvirt/qemu.conf</code></td>
+      </tr>
+      <tr>
+        <td><code>qemu:///embed</code></td>
+        <td><code>$rootdir/etc/qemu.conf</code></td>
+      </tr>
+    </table>
+
+    <p>
+      If <code>$XDG_CONFIG_HOME</code> is not set in the environment, it
+      defaults to <code>$HOME/.config</code>. For the embed URI the
+      <code>$rootdir</code> represents the specified root directory from
+      the connection URI.
+    </p>
+
+    <p>
+      Please note, that it is very likely that the only qemu.conf file that
+      will exist after installing libvirt is the
+      <code>/etc/libvirt/qemu.conf</code>, if users of the session daemon or
+      the embed driver want to override a built in value, then they need to
+      create the file before connecting to the respective URI.
+    </p>
+
     <h2><a id="security">Driver security architecture</a></h2>
 
     <p>
diff --git a/docs/manpages/libvirtd.rst b/docs/manpages/libvirtd.rst
index ed591f4778..6545dc58d3 100644
--- a/docs/manpages/libvirtd.rst
+++ b/docs/manpages/libvirtd.rst
@@ -136,6 +136,16 @@ When run as *root*
 The default configuration file used by ``libvirtd``, unless overridden on the
 command line using the ``-f`` | ``--config`` option.
 
+If QEMU driver is installed, then the following file is also read:
+
+* ``@SYSCONFDIR@/libvirt/qemu.conf``
+
+This file contains various knobs and default values for virtual machines
+created within QEMU driver, and offers a way to override the built in defaults,
+for instance (but not limited to): paths to various supplementary binaries, TLS
+certificates location, graphical consoles configuration and others. Location of
+this file can't be overridden by any command line switch.
+
 * ``@RUNSTATEDIR@/libvirt/libvirt-sock``
 * ``@RUNSTATEDIR@/libvirt/libvirt-sock-ro``
 
@@ -166,6 +176,16 @@ When run as *non-root*
 The default configuration file used by ``libvirtd``, unless overridden on the
 command line using the ``-f``|``--config`` option.
 
+If QEMU driver is installed, then the following file is also read:
+
+* ``$XDG_CONFIG_HOME/libvirt/qemu.conf``
+
+If the file exists, it can contain various knobs and default values for virtual
+machines created within QEMU driver, and offers a way to override the built in
+defaults, for instance (but not limited to): paths to various supplementary
+binaries, TLS certificates location, graphical consoles configuration and
+others. Location of this file can't be overridden by any command line switch.
+
 * ``$XDG_RUNTIME_DIR/libvirt/libvirt-sock``
 
 The socket ``libvirtd`` will use.
diff --git a/docs/manpages/virtqemud.rst b/docs/manpages/virtqemud.rst
index fbcc6e45fa..d82d09ee61 100644
--- a/docs/manpages/virtqemud.rst
+++ b/docs/manpages/virtqemud.rst
@@ -111,6 +111,17 @@ When run as *root*
 The default configuration file used by ``virtqemud``, unless overridden on the
 command line using the ``-f`` | ``--config`` option.
 
+In addition to the default configuration file, ``virtqemud`` reads
+configuration for the qemu driver from:
+
+* ``@SYSCONFDIR@/libvirt/qemu.conf``
+
+This file contains various knobs and default values for virtual machines
+created within QEMU driver, and offers a way to override the built in defaults,
+for instance (but not limited to): paths to various supplementary binaries, TLS
+certificates location, graphical consoles configuration and others. Location of
+this file can't be overridden by any command line switch.
+
 * ``@RUNSTATEDIR@/libvirt/virtqemud-sock``
 * ``@RUNSTATEDIR@/libvirt/virtqemud-sock-ro``
 * ``@RUNSTATEDIR@/libvirt/virtqemud-admin-sock``
@@ -132,6 +143,17 @@ When run as *non-root*
 The default configuration file used by ``virtqemud``, unless overridden on the
 command line using the ``-f``|``--config`` option.
 
+In addition to the default configuration file, ``virtqemud`` reads
+configuration for the qemu driver from:
+
+* ``$XDG_CONFIG_HOME/libvirt/qemu.conf``
+
+If the file exists, it can contain various knobs and default values for virtual
+machines created within QEMU driver, and offers a way to override the built in
+defaults, for instance (but not limited to): paths to various supplementary
+binaries, TLS certificates location, graphical consoles configuration and
+others. Location of this file can't be overridden by any command line switch.
+
 * ``$XDG_RUNTIME_DIR/libvirt/virtqemud-sock``
 * ``$XDG_RUNTIME_DIR/libvirt/virtqemud-admin-sock``
 
-- 
2.26.2

On Thu, 2021-03-04 at 20:55 +0100, Michal Privoznik wrote:
> Surprisingly, we never documented the relationship between
> connection URI and the location of qemu.conf. Users might wonder
> what qemu.conf is loaded when they are connecting to the session
> daemon or embed URI. And what to do if the file doesn't exist for
> the URI they're using.
> 
> Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
> ---
>  docs/drvqemu.html.in        | 39 +++++++++++++++++++++++++++++++++++++
>  docs/manpages/libvirtd.rst  | 20 +++++++++++++++++++
>  docs/manpages/virtqemud.rst | 22 +++++++++++++++++++++
>  3 files changed, 81 insertions(+)

Excellent stuff, thanks for tackling this!

  Reviewed-by: Andrea Bolognani <abologna@redhat.com>

Now, since no good deed ever goes unpunished :) how would you feel
about doing something similar for lxc.conf and libxl.conf? You can
pretty much use the exact same text for both.

We also have qemu-lockd.conf and libxl-lockd.conf, but I have no idea
what those are used for.

-- 
Andrea Bolognani / Red Hat / Virtualization

On 3/5/21 10:45 AM, Andrea Bolognani wrote:
> On Thu, 2021-03-04 at 20:55 +0100, Michal Privoznik wrote:
>> Surprisingly, we never documented the relationship between
>> connection URI and the location of qemu.conf. Users might wonder
>> what qemu.conf is loaded when they are connecting to the session
>> daemon or embed URI. And what to do if the file doesn't exist for
>> the URI they're using.
>>
>> Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
>> ---
>>   docs/drvqemu.html.in        | 39 +++++++++++++++++++++++++++++++++++++
>>   docs/manpages/libvirtd.rst  | 20 +++++++++++++++++++
>>   docs/manpages/virtqemud.rst | 22 +++++++++++++++++++++
>>   3 files changed, 81 insertions(+)
> 
> Excellent stuff, thanks for tackling this!
> 
>    Reviewed-by: Andrea Bolognani <abologna@redhat.com>
> 
> Now, since no good deed ever goes unpunished :) how would you feel
> about doing something similar for lxc.conf and libxl.conf? You can
> pretty much use the exact same text for both.

Absolutely.

> 
> We also have qemu-lockd.conf and libxl-lockd.conf, but I have no idea
> what those are used for.
> 

They are used for configuring the way we lock disks and so called leases 
(for virtlockd). This is documented in docs/kbase/locking-lockd.rst 
nevertheless, this table I'm inventing here should document those too.

Michal