docs: Document qemu.conf locations

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>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>

diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in
index 31d3fee213b326b3c92157537e4b1ff5adf510da..a784f5768c1103932d8d6ebc07de1c8f67f46ab2 100644 (file)
--- 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 ed591f47787d757aeaf38b520a76b7aeeb92e34e..6545dc58d3777fb9ae521ffb314f2511d4fa5cfd 100644 (file)
--- 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 fbcc6e45fa32090b8147d9f10d06d6c5573ffa71..d82d09ee6196c54990ee2e7df18b74a12f83d751 100644 (file)
--- 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``