mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-05 12:51:12 +00:00
83c6d80abc
Libvirt provides QMP passthrough APIs for the QEMU driver and these are
exposed in virsh. It is not especially pleasant, however, using the raw
QMP JSON syntax. QEMU has a tool 'qmp-shell' which can speak QMP and
exposes a human friendly interactive shell. It is not possible to use
this with libvirt managed guest, however, since only one client can
attach to the QMP socket at any point in time. While it would be
possible to configure a second QMP socket for a VM, it may not be
an known requirement at the time the guest is provisioned.
The virt-qmp-proxy tool aims to solve this problem. It opens a UNIX
socket and listens for incoming client connections, speaking QMP on
the connected socket. It will forward any QMP commands received onto
the running libvirt QEMU guest, and forward any replies back to the
QMP client. It will also forward back events.
$ virsh start demo
$ virt-qmp-proxy demo demo.qmp &
$ qmp-shell demo.qmp
Welcome to the QMP low-level shell!
Connected to QEMU 6.2.0
(QEMU) query-kvm
{
"return": {
"enabled": true,
"present": true
}
}
Note this tool of course has the same risks as the raw libvirt
QMP passthrough. It is safe to run query commands to fetch information
but commands which change the QEMU state risk disrupting libvirt's
management of QEMU, potentially resulting in data loss/corruption in
the worst case. Any use of this tool will cause the guest to be marked
as tainted as an warning that it could be in an unexpected state.
Since this tool introduces a python dependency it is not desirable
to include it in any of the existing RPMs in libvirt. This tool is
also QEMU specific, so isn't appropriate to bundle with the generic
tools. Thus a new RPM is introduced 'libvirt-clients-qemu', to
contain additional QEMU specific tools, with extra external deps.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
121 lines
2.8 KiB
ReStructuredText
121 lines
2.8 KiB
ReStructuredText
===================
|
|
virt-qemu-qmp-proxy
|
|
===================
|
|
|
|
--------------------------------------------------
|
|
Expose a QMP proxy server for a libvirt QEMU guest
|
|
--------------------------------------------------
|
|
|
|
:Manual section: 1
|
|
:Manual group: Virtualization Support
|
|
|
|
.. contents::
|
|
|
|
|
|
SYNOPSIS
|
|
========
|
|
|
|
``virt-qemu-qmp-proxy`` [*OPTION*]... *DOMAIN* *QMP-SOCKET-PATH*
|
|
|
|
|
|
DESCRIPTION
|
|
===========
|
|
|
|
This tool provides a way to expose a QMP proxy server that communicates
|
|
with a QEMU guest managed by libvirt. This enables standard QMP client
|
|
tools to interact with libvirt managed guests.
|
|
|
|
**NOTE: use of this tool will result in the running QEMU guest being
|
|
marked as tainted.** It is strongly recommended that this tool *only be
|
|
used to send commands which query information* about the running guest.
|
|
If this tool is used to make changes to the state of the guest, this
|
|
may have negative interactions with the QEMU driver, resulting in an
|
|
inability to manage the guest operation thereafter, and in the worst
|
|
case **potentially lead to data loss or corruption**.
|
|
|
|
The ``virt-qemu-qmp-proxy`` program will listen on a UNIX socket for incoming
|
|
client connections, and run the QMP protocol over the connection. Any
|
|
commands received will be sent to the running libvirt guest, and replies
|
|
sent back.
|
|
|
|
The ``virt-qemu-qmp-proxy`` program may be interrupted (eg Ctrl-C) when it
|
|
is no longer required. The libvirt QEMU guest will continue running.
|
|
|
|
|
|
OPTIONS
|
|
=======
|
|
|
|
*DOMAIN*
|
|
|
|
The ID or UUID or Name of the libvirt QEMU guest.
|
|
|
|
*QMP-SOCKET-PATH*
|
|
|
|
The filesystem path at which to run the QMP server, listening for
|
|
incoming connections.
|
|
|
|
``-c`` *CONNECTION-URI*
|
|
``--connect``\ =\ *CONNECTION-URI*
|
|
|
|
The URI for the connection to the libvirt QEMU driver. If omitted,
|
|
a URI will be auto-detected.
|
|
|
|
``-v``, ``--verbose``
|
|
|
|
Run in verbose mode, printing all QMP commands and replies that
|
|
are handled.
|
|
|
|
``-h``, ``--help``
|
|
|
|
Display the command line help.
|
|
|
|
|
|
EXIT STATUS
|
|
===========
|
|
|
|
Upon successful shutdown, an exit status of 0 will be set. Upon
|
|
failure a non-zero status will be set.
|
|
|
|
|
|
AUTHOR
|
|
======
|
|
|
|
Daniel P. Berrangé
|
|
|
|
|
|
BUGS
|
|
====
|
|
|
|
Please report all bugs you discover. This should be done via either:
|
|
|
|
#. the mailing list
|
|
|
|
`https://libvirt.org/contact.html <https://libvirt.org/contact.html>`_
|
|
|
|
#. the bug tracker
|
|
|
|
`https://libvirt.org/bugs.html <https://libvirt.org/bugs.html>`_
|
|
|
|
Alternatively, you may report bugs to your software distributor / vendor.
|
|
|
|
COPYRIGHT
|
|
=========
|
|
|
|
Copyright (C) 2022 by Red Hat, Inc.
|
|
|
|
|
|
LICENSE
|
|
=======
|
|
|
|
``virt-qemu-qmp-proxy`` is distributed under the terms of the GNU LGPL v2+.
|
|
This is free software; see the source for copying conditions. There
|
|
is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
PURPOSE
|
|
|
|
|
|
SEE ALSO
|
|
========
|
|
|
|
virsh(1), `https://libvirt.org/ <https://libvirt.org/>`_,
|
|
`QMP reference <https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html>`_
|