From: Martin Kletzander <mkletzan@redhat.com>
Date: Thu, 7 Dec 2023 10:28:23 +0000 (+0100)
Subject: Improve error message in remoteGetUNIXSocket
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=fbf5fc0fb220530d4b046cdac0d9cfbb1bcf5824;p=libvirt.git

Improve error message in remoteGetUNIXSocket

By adding a link to an explanation in the kbase.

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
Reviewed-by: Richard W.M. Jones <rjones@redhat.com>
---

diff --git a/docs/kbase/failed_connection_after_install.rst b/docs/kbase/failed_connection_after_install.rst
new file mode 100644
index 0000000000..cea57c460e
--- /dev/null
+++ b/docs/kbase/failed_connection_after_install.rst
@@ -0,0 +1,58 @@
+========================================
+Libvirt does not work after installation
+========================================
+
+.. contents::
+
+TL;DR
+=====
+
+Most probably you want to start a virtqemud socket:
+
+::
+
+   # systemctl start virtqemud.socket
+
+If you are unsure whether to do this, please read the rest of this document.
+
+Symptom
+=======
+
+After installing libvirt or a virt tool that uses libvirt, commands do
+not work when run as root:
+
+::
+
+   # virsh list
+   error: failed to connect to the hypervisor
+   error: Operation not supported: Cannot use direct socket mode if no URI is set.
+   For more information see https://libvirt.org/kbase/failed_connection_after_install.html
+
+Root cause
+==========
+
+Distribution guidelines and/or configurations may discourage or prohibit
+starting services as part of a package installation.  And because libvirt cannot
+know where you might want to connect it cannot start it on its own.
+
+Solution
+========
+
+After installing libvirt you may need to start a particular libvirt daemon on
+the local machine, set a (default) URI to connect to or, alternatively,
+rebooting the machine might work.
+
+If you are trying to connect to a remote libvirt daemon you need to specify a `connection URI <../uri.html>`__.
+
+If you are trying to control a local hypervisor, then the solution depends on various factors. You should know:
+
+- what hypervisor driver you want to connect to, whether it is ``virtqemud`` for QEMU, ``virtchd`` for Cloud Hypervisor, etc. and
+- how to start a service or socket (in case of systemd) on you system.
+
+Example of the most common solution, trying to use QEMU/KVM on Linux with systemd as an init system, is:
+
+::
+
+   # systemctl start virtqemud.socket
+
+also provided on the top of the page.
diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst
index 896ececdf2..e51b35cbfc 100644
--- a/docs/kbase/index.rst
+++ b/docs/kbase/index.rst
@@ -64,6 +64,9 @@ Usage
 `Secure Boot <secureboot.html>`__
     Enable and disable the Secure Boot feature
 
+`Connection fail after installation <failed_connection_after_install.html>`__
+    Explanation of a common issue users stumble upon after installation
+
 
 Debugging
 ---------
diff --git a/docs/kbase/meson.build b/docs/kbase/meson.build
index 5b608293e2..6d4ca90215 100644
--- a/docs/kbase/meson.build
+++ b/docs/kbase/meson.build
@@ -2,6 +2,7 @@ docs_kbase_files = [
   'backing_chains',
   'debuglogs',
   'domainstatecapture',
+  'failed_connection_after_install',
   'index',
   'kvm-realtime',
   'launch_security_sev',
diff --git a/src/remote/remote_sockets.c b/src/remote/remote_sockets.c
index 4ab3d72933..8d403b6f01 100644
--- a/src/remote/remote_sockets.c
+++ b/src/remote/remote_sockets.c
@@ -398,7 +398,7 @@ remoteGetUNIXSocket(remoteDriverTransport transport,
 
         if (!direct_sock_name) {
             virReportError(VIR_ERR_OPERATION_UNSUPPORTED, "%s",
-                           _("Cannot use direct socket mode if no URI is set"));
+                           _("Cannot use direct socket mode if no URI is set. For more information see https://libvirt.org/kbase/failed_connection_after_install.html"));
             return NULL;
         }