[PATCH v2] Improve error message in remoteGetUNIXSocket
By adding a link to an explanation in the kbase. Signed-off-by: Martin Kletzander <mkletzan@redhat.com> --- v2: - Do not print first socket path - Add a kbase article explaining the details and solutions - Add a link to said article v1: https://lists.libvirt.org/archives/list/devel@lists.libvirt.org/thread/WGEVY... .../kbase/failed_connection_after_install.rst | 58 +++++++++++++++++++ docs/kbase/index.rst | 3 + docs/kbase/meson.build | 1 + src/remote/remote_sockets.c | 2 +- 4 files changed, 63 insertions(+), 1 deletion(-) create mode 100644 docs/kbase/failed_connection_after_install.rst diff --git a/docs/kbase/failed_connection_after_install.rst b/docs/kbase/failed_connection_after_install.rst new file mode 100644 index 000000000000..cea57c460e10 --- /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 896ececdf258..e51b35cbfce5 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 5b608293e27c..6d4ca90215a5 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 4ab3d72933e2..8d403b6f014a 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; } -- 2.43.0
On Thu, Dec 21, 2023 at 03:48:30PM +0100, Martin Kletzander wrote:
By adding a link to an explanation in the kbase.
Signed-off-by: Martin Kletzander <mkletzan@redhat.com> --- v2: - Do not print first socket path - Add a kbase article explaining the details and solutions - Add a link to said article
v1: https://lists.libvirt.org/archives/list/devel@lists.libvirt.org/thread/WGEVY...
.../kbase/failed_connection_after_install.rst | 58 +++++++++++++++++++ docs/kbase/index.rst | 3 + docs/kbase/meson.build | 1 + src/remote/remote_sockets.c | 2 +- 4 files changed, 63 insertions(+), 1 deletion(-) create mode 100644 docs/kbase/failed_connection_after_install.rst
diff --git a/docs/kbase/failed_connection_after_install.rst b/docs/kbase/failed_connection_after_install.rst new file mode 100644 index 000000000000..cea57c460e10 --- /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 896ececdf258..e51b35cbfce5 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 5b608293e27c..6d4ca90215a5 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 4ab3d72933e2..8d403b6f014a 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; }
--
This is really good, thanks. Reviewed-by: Richard W.M. Jones <rjones@redhat.com> -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com Fedora Windows cross-compiler. Compile Windows programs, test, and build Windows installers. Over 100 libraries supported. http://fedoraproject.org/wiki/MinGW
participants (2)
-
Martin Kletzander -
Richard W.M. Jones