libvirt/src/libvirt-qemu.c

344 lines
11 KiB
C
Raw Normal View History

/*
* libvirt-qemu.c: Interfaces for the libvirt library to handle qemu-specific
* APIs.
*
* Copyright (C) 2010-2014 Red Hat, Inc.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library. If not, see
* <http://www.gnu.org/licenses/>.
*
* Author: Chris Lalancette <clalance@redhat.com>
*/
#include <config.h>
#include "virerror.h"
2012-12-12 17:59:27 +00:00
#include "virlog.h"
#include "viruuid.h"
#include "datatypes.h"
#define VIR_FROM_THIS VIR_FROM_NONE
VIR_LOG_INIT("libvirt-qemu");
/**
* virDomainQemuMonitorCommand:
* @domain: a domain object
* @cmd: the qemu monitor command string
* @result: a string returned by @cmd
* @flags: bitwise-or of supported virDomainQemuMonitorCommandFlags
*
* This API is QEMU specific, so it will only work with hypervisor
* connections to the QEMU driver.
*
* Send an arbitrary monitor command @cmd to @domain through the
* qemu monitor. There are several requirements to safely and
* successfully use this API:
*
* - A @cmd that queries state without making any modifications is safe
* - A @cmd that alters state that is also tracked by libvirt is unsafe,
* and may cause libvirtd to crash
* - A @cmd that alters state not tracked by the current version of
* libvirt is possible as a means to test new qemu features before
* they have support in libvirt, but no guarantees are made to safety
*
* If VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP is set, the command is
* considered to be a human monitor command and libvirt will automatically
* convert it into QMP if needed. In that case the @result will also
* be converted back from QMP.
*
* If successful, @result will be filled with the string output of the
* @cmd, and the caller must free this string.
*
* Returns 0 in case of success, -1 in case of failure
*
*/
int
virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd,
char **result, unsigned int flags)
{
virConnectPtr conn;
VIR_DOMAIN_DEBUG(domain, "cmd=%s, result=%p, flags=0x%x",
cmd, result, flags);
virResetLastError();
virCheckDomainReturn(domain, -1);
conn = domain->conn;
virCheckNonNullArgGoto(result, error);
2013-12-20 14:02:49 +00:00
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver->domainQemuMonitorCommand) {
int ret;
ret = conn->driver->domainQemuMonitorCommand(domain, cmd, result,
flags);
if (ret < 0)
goto error;
return ret;
}
maint: improve VIR_ERR_NO_SUPPORT usage We weren't very consistent in our use of VIR_ERR_NO_SUPPORT; many users just passed __FUNCTION__ on, while others passed "%s" to silence over-eager compilers that warn about __FUNCTION__ not containing any %. It's nicer to route all these uses through a single macro, so that if we ever need to change the reporting, we can do it in one place. I verified that 'virsh -c test:///default qemu-monitor-command test foo' gives the same error message before and after this patch: error: this function is not supported by the connection driver: virDomainQemuMonitorCommand Note that in libvirt.c, we were inconsistent on whether virDomain* API used virLibConnError() (with VIR_FROM_NONE) or virLibDomainError() (with VIR_FROM_DOMAIN); this patch unifies these errors to all use VIR_FROM_NONE, on the grounds that it is unlikely that a caller learning that a call is unimplemented can do anything in particular with extra knowledge of which error domain it belongs to. One particular change to note is virDomainOpenGraphics which was trying to fail with VIR_ERR_NO_SUPPORT after a failed VIR_DRV_SUPPORTS_FEATURE check; all other places that fail a feature check report VIR_ERR_ARGUMENT_UNSUPPORTED. * src/util/virerror.h (virReportUnsupportedError): New macro. * src/libvirt-qemu.c: Use new macro. * src/libvirt-lxc.c: Likewise. * src/lxc/lxc_driver.c: Likewise. * src/security/security_manager.c: Likewise. * src/util/virinitctl.c: Likewise. * src/libvirt.c: Likewise. (virDomainOpenGraphics): Use correct error for unsupported feature. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-20 01:38:59 +00:00
virReportUnsupportedError();
error:
virDispatchError(conn);
return -1;
}
/**
* virDomainQemuAttach:
* @conn: pointer to a hypervisor connection
build: use correct type for pid and similar types No thanks to 64-bit windows, with 64-bit pid_t, we have to avoid constructs like 'int pid'. Our API in libvirt-qemu cannot be changed without breaking ABI; but then again, libvirt-qemu can only be used on systems that support UNIX sockets, which rules out Windows (even if qemu could be compiled there) - so for all points on the call chain that interact with this API decision, we require a different variable name to make it clear that we audited the use for safety. Adding a syntax-check rule only solves half the battle; anywhere that uses printf on a pid_t still needs to be converted, but that will be a separate patch. * cfg.mk (sc_correct_id_types): New syntax check. * src/libvirt-qemu.c (virDomainQemuAttach): Document why we didn't use pid_t for pid, and validate for overflow. * include/libvirt/libvirt-qemu.h (virDomainQemuAttach): Tweak name for syntax check. * src/vmware/vmware_conf.c (vmwareExtractPid): Likewise. * src/driver.h (virDrvDomainQemuAttach): Likewise. * tools/virsh.c (cmdQemuAttach): Likewise. * src/remote/qemu_protocol.x (qemu_domain_attach_args): Likewise. * src/qemu_protocol-structs (qemu_domain_attach_args): Likewise. * src/util/cgroup.c (virCgroupPidCode, virCgroupKillInternal): Likewise. * src/qemu/qemu_command.c(qemuParseProcFileStrings): Likewise. (qemuParseCommandLinePid): Use pid_t for pid. * daemon/libvirtd.c (daemonForkIntoBackground): Likewise. * src/conf/domain_conf.h (_virDomainObj): Likewise. * src/probes.d (rpc_socket_new): Likewise. * src/qemu/qemu_command.h (qemuParseCommandLinePid): Likewise. * src/qemu/qemu_driver.c (qemudGetProcessInfo, qemuDomainAttach): Likewise. * src/qemu/qemu_process.c (qemuProcessAttach): Likewise. * src/qemu/qemu_process.h (qemuProcessAttach): Likewise. * src/uml/uml_driver.c (umlGetProcessInfo): Likewise. * src/util/virnetdev.h (virNetDevSetNamespace): Likewise. * src/util/virnetdev.c (virNetDevSetNamespace): Likewise. * tests/testutils.c (virtTestCaptureProgramOutput): Likewise. * src/conf/storage_conf.h (_virStoragePerms): Use mode_t, uid_t, and gid_t rather than int. * src/security/security_dac.c (virSecurityDACSetOwnership): Likewise. * src/conf/storage_conf.c (virStorageDefParsePerms): Avoid compiler warning.
2012-02-10 23:08:11 +00:00
* @pid_value: the UNIX process ID of the external QEMU process
* @flags: optional flags, currently unused
*
* This API is QEMU specific, so it will only work with hypervisor
* connections to the QEMU driver.
*
* This API will attach to an externally launched QEMU process
* identified by @pid. There are several requirements to successfully
* attach to an external QEMU process:
*
* - It must have been started with a monitor socket using the UNIX
* domain socket protocol.
* - No device hotplug/unplug, or other configuration changes can
* have been made via the monitor since it started.
* - The '-name' and '-uuid' arguments should have been set (not
* mandatory, but strongly recommended)
*
build: use correct type for pid and similar types No thanks to 64-bit windows, with 64-bit pid_t, we have to avoid constructs like 'int pid'. Our API in libvirt-qemu cannot be changed without breaking ABI; but then again, libvirt-qemu can only be used on systems that support UNIX sockets, which rules out Windows (even if qemu could be compiled there) - so for all points on the call chain that interact with this API decision, we require a different variable name to make it clear that we audited the use for safety. Adding a syntax-check rule only solves half the battle; anywhere that uses printf on a pid_t still needs to be converted, but that will be a separate patch. * cfg.mk (sc_correct_id_types): New syntax check. * src/libvirt-qemu.c (virDomainQemuAttach): Document why we didn't use pid_t for pid, and validate for overflow. * include/libvirt/libvirt-qemu.h (virDomainQemuAttach): Tweak name for syntax check. * src/vmware/vmware_conf.c (vmwareExtractPid): Likewise. * src/driver.h (virDrvDomainQemuAttach): Likewise. * tools/virsh.c (cmdQemuAttach): Likewise. * src/remote/qemu_protocol.x (qemu_domain_attach_args): Likewise. * src/qemu_protocol-structs (qemu_domain_attach_args): Likewise. * src/util/cgroup.c (virCgroupPidCode, virCgroupKillInternal): Likewise. * src/qemu/qemu_command.c(qemuParseProcFileStrings): Likewise. (qemuParseCommandLinePid): Use pid_t for pid. * daemon/libvirtd.c (daemonForkIntoBackground): Likewise. * src/conf/domain_conf.h (_virDomainObj): Likewise. * src/probes.d (rpc_socket_new): Likewise. * src/qemu/qemu_command.h (qemuParseCommandLinePid): Likewise. * src/qemu/qemu_driver.c (qemudGetProcessInfo, qemuDomainAttach): Likewise. * src/qemu/qemu_process.c (qemuProcessAttach): Likewise. * src/qemu/qemu_process.h (qemuProcessAttach): Likewise. * src/uml/uml_driver.c (umlGetProcessInfo): Likewise. * src/util/virnetdev.h (virNetDevSetNamespace): Likewise. * src/util/virnetdev.c (virNetDevSetNamespace): Likewise. * tests/testutils.c (virtTestCaptureProgramOutput): Likewise. * src/conf/storage_conf.h (_virStoragePerms): Use mode_t, uid_t, and gid_t rather than int. * src/security/security_dac.c (virSecurityDACSetOwnership): Likewise. * src/conf/storage_conf.c (virStorageDefParsePerms): Avoid compiler warning.
2012-02-10 23:08:11 +00:00
* To date, the only platforms we know of where pid_t is larger than
* unsigned int (64-bit Windows) also lack UNIX sockets, so the choice
* of @pid_value as an unsigned int should not present any difficulties.
*
* If successful, then the guest will appear in the list of running
* domains for this connection, and other APIs should operate
* normally (provided the above requirements were honored).
*
* Returns a new domain object on success, NULL otherwise
*/
virDomainPtr
virDomainQemuAttach(virConnectPtr conn,
build: use correct type for pid and similar types No thanks to 64-bit windows, with 64-bit pid_t, we have to avoid constructs like 'int pid'. Our API in libvirt-qemu cannot be changed without breaking ABI; but then again, libvirt-qemu can only be used on systems that support UNIX sockets, which rules out Windows (even if qemu could be compiled there) - so for all points on the call chain that interact with this API decision, we require a different variable name to make it clear that we audited the use for safety. Adding a syntax-check rule only solves half the battle; anywhere that uses printf on a pid_t still needs to be converted, but that will be a separate patch. * cfg.mk (sc_correct_id_types): New syntax check. * src/libvirt-qemu.c (virDomainQemuAttach): Document why we didn't use pid_t for pid, and validate for overflow. * include/libvirt/libvirt-qemu.h (virDomainQemuAttach): Tweak name for syntax check. * src/vmware/vmware_conf.c (vmwareExtractPid): Likewise. * src/driver.h (virDrvDomainQemuAttach): Likewise. * tools/virsh.c (cmdQemuAttach): Likewise. * src/remote/qemu_protocol.x (qemu_domain_attach_args): Likewise. * src/qemu_protocol-structs (qemu_domain_attach_args): Likewise. * src/util/cgroup.c (virCgroupPidCode, virCgroupKillInternal): Likewise. * src/qemu/qemu_command.c(qemuParseProcFileStrings): Likewise. (qemuParseCommandLinePid): Use pid_t for pid. * daemon/libvirtd.c (daemonForkIntoBackground): Likewise. * src/conf/domain_conf.h (_virDomainObj): Likewise. * src/probes.d (rpc_socket_new): Likewise. * src/qemu/qemu_command.h (qemuParseCommandLinePid): Likewise. * src/qemu/qemu_driver.c (qemudGetProcessInfo, qemuDomainAttach): Likewise. * src/qemu/qemu_process.c (qemuProcessAttach): Likewise. * src/qemu/qemu_process.h (qemuProcessAttach): Likewise. * src/uml/uml_driver.c (umlGetProcessInfo): Likewise. * src/util/virnetdev.h (virNetDevSetNamespace): Likewise. * src/util/virnetdev.c (virNetDevSetNamespace): Likewise. * tests/testutils.c (virtTestCaptureProgramOutput): Likewise. * src/conf/storage_conf.h (_virStoragePerms): Use mode_t, uid_t, and gid_t rather than int. * src/security/security_dac.c (virSecurityDACSetOwnership): Likewise. * src/conf/storage_conf.c (virStorageDefParsePerms): Avoid compiler warning.
2012-02-10 23:08:11 +00:00
unsigned int pid_value,
unsigned int flags)
{
build: use correct type for pid and similar types No thanks to 64-bit windows, with 64-bit pid_t, we have to avoid constructs like 'int pid'. Our API in libvirt-qemu cannot be changed without breaking ABI; but then again, libvirt-qemu can only be used on systems that support UNIX sockets, which rules out Windows (even if qemu could be compiled there) - so for all points on the call chain that interact with this API decision, we require a different variable name to make it clear that we audited the use for safety. Adding a syntax-check rule only solves half the battle; anywhere that uses printf on a pid_t still needs to be converted, but that will be a separate patch. * cfg.mk (sc_correct_id_types): New syntax check. * src/libvirt-qemu.c (virDomainQemuAttach): Document why we didn't use pid_t for pid, and validate for overflow. * include/libvirt/libvirt-qemu.h (virDomainQemuAttach): Tweak name for syntax check. * src/vmware/vmware_conf.c (vmwareExtractPid): Likewise. * src/driver.h (virDrvDomainQemuAttach): Likewise. * tools/virsh.c (cmdQemuAttach): Likewise. * src/remote/qemu_protocol.x (qemu_domain_attach_args): Likewise. * src/qemu_protocol-structs (qemu_domain_attach_args): Likewise. * src/util/cgroup.c (virCgroupPidCode, virCgroupKillInternal): Likewise. * src/qemu/qemu_command.c(qemuParseProcFileStrings): Likewise. (qemuParseCommandLinePid): Use pid_t for pid. * daemon/libvirtd.c (daemonForkIntoBackground): Likewise. * src/conf/domain_conf.h (_virDomainObj): Likewise. * src/probes.d (rpc_socket_new): Likewise. * src/qemu/qemu_command.h (qemuParseCommandLinePid): Likewise. * src/qemu/qemu_driver.c (qemudGetProcessInfo, qemuDomainAttach): Likewise. * src/qemu/qemu_process.c (qemuProcessAttach): Likewise. * src/qemu/qemu_process.h (qemuProcessAttach): Likewise. * src/uml/uml_driver.c (umlGetProcessInfo): Likewise. * src/util/virnetdev.h (virNetDevSetNamespace): Likewise. * src/util/virnetdev.c (virNetDevSetNamespace): Likewise. * tests/testutils.c (virtTestCaptureProgramOutput): Likewise. * src/conf/storage_conf.h (_virStoragePerms): Use mode_t, uid_t, and gid_t rather than int. * src/security/security_dac.c (virSecurityDACSetOwnership): Likewise. * src/conf/storage_conf.c (virStorageDefParsePerms): Avoid compiler warning.
2012-02-10 23:08:11 +00:00
pid_t pid = pid_value;
VIR_DEBUG("conn=%p, pid=%u, flags=0x%x", conn, pid_value, flags);
virResetLastError();
virCheckConnectReturn(conn, NULL);
virCheckPositiveArgGoto(pid_value, error);
if (pid != pid_value) {
virReportInvalidArg(pid_value,
_("pid_value in %s is too large"),
__FUNCTION__);
goto error;
}
2013-12-20 14:02:49 +00:00
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver->domainQemuAttach) {
virDomainPtr ret;
ret = conn->driver->domainQemuAttach(conn, pid_value, flags);
if (!ret)
goto error;
return ret;
}
maint: improve VIR_ERR_NO_SUPPORT usage We weren't very consistent in our use of VIR_ERR_NO_SUPPORT; many users just passed __FUNCTION__ on, while others passed "%s" to silence over-eager compilers that warn about __FUNCTION__ not containing any %. It's nicer to route all these uses through a single macro, so that if we ever need to change the reporting, we can do it in one place. I verified that 'virsh -c test:///default qemu-monitor-command test foo' gives the same error message before and after this patch: error: this function is not supported by the connection driver: virDomainQemuMonitorCommand Note that in libvirt.c, we were inconsistent on whether virDomain* API used virLibConnError() (with VIR_FROM_NONE) or virLibDomainError() (with VIR_FROM_DOMAIN); this patch unifies these errors to all use VIR_FROM_NONE, on the grounds that it is unlikely that a caller learning that a call is unimplemented can do anything in particular with extra knowledge of which error domain it belongs to. One particular change to note is virDomainOpenGraphics which was trying to fail with VIR_ERR_NO_SUPPORT after a failed VIR_DRV_SUPPORTS_FEATURE check; all other places that fail a feature check report VIR_ERR_ARGUMENT_UNSUPPORTED. * src/util/virerror.h (virReportUnsupportedError): New macro. * src/libvirt-qemu.c: Use new macro. * src/libvirt-lxc.c: Likewise. * src/lxc/lxc_driver.c: Likewise. * src/security/security_manager.c: Likewise. * src/util/virinitctl.c: Likewise. * src/libvirt.c: Likewise. (virDomainOpenGraphics): Use correct error for unsupported feature. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-20 01:38:59 +00:00
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
/**
* virDomainQemuAgentCommand:
* @domain: a domain object
* @cmd: the guest agent command string
* @timeout: timeout seconds
* @flags: execution flags
*
* Execute an arbitrary Guest Agent command.
*
* Issue @cmd to the guest agent running in @domain.
* @timeout must be -2, -1, 0 or positive.
* VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK(-2): meaning to block forever waiting for
* a result.
* VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT(-1): use default timeout value.
* VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT(0): does not wait.
* positive value: wait for @timeout seconds
*
* Returns strings if success, NULL in failure.
*/
char *
virDomainQemuAgentCommand(virDomainPtr domain,
const char *cmd,
int timeout,
unsigned int flags)
{
virConnectPtr conn;
char *ret;
VIR_DOMAIN_DEBUG(domain, "cmd=%s, timeout=%d, flags=0x%x",
cmd, timeout, flags);
virResetLastError();
virCheckDomainReturn(domain, NULL);
conn = domain->conn;
2013-12-20 14:02:49 +00:00
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver->domainQemuAgentCommand) {
ret = conn->driver->domainQemuAgentCommand(domain, cmd,
timeout, flags);
if (!ret)
goto error;
return ret;
}
maint: improve VIR_ERR_NO_SUPPORT usage We weren't very consistent in our use of VIR_ERR_NO_SUPPORT; many users just passed __FUNCTION__ on, while others passed "%s" to silence over-eager compilers that warn about __FUNCTION__ not containing any %. It's nicer to route all these uses through a single macro, so that if we ever need to change the reporting, we can do it in one place. I verified that 'virsh -c test:///default qemu-monitor-command test foo' gives the same error message before and after this patch: error: this function is not supported by the connection driver: virDomainQemuMonitorCommand Note that in libvirt.c, we were inconsistent on whether virDomain* API used virLibConnError() (with VIR_FROM_NONE) or virLibDomainError() (with VIR_FROM_DOMAIN); this patch unifies these errors to all use VIR_FROM_NONE, on the grounds that it is unlikely that a caller learning that a call is unimplemented can do anything in particular with extra knowledge of which error domain it belongs to. One particular change to note is virDomainOpenGraphics which was trying to fail with VIR_ERR_NO_SUPPORT after a failed VIR_DRV_SUPPORTS_FEATURE check; all other places that fail a feature check report VIR_ERR_ARGUMENT_UNSUPPORTED. * src/util/virerror.h (virReportUnsupportedError): New macro. * src/libvirt-qemu.c: Use new macro. * src/libvirt-lxc.c: Likewise. * src/lxc/lxc_driver.c: Likewise. * src/security/security_manager.c: Likewise. * src/util/virinitctl.c: Likewise. * src/libvirt.c: Likewise. (virDomainOpenGraphics): Use correct error for unsupported feature. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-20 01:38:59 +00:00
virReportUnsupportedError();
error:
virDispatchError(conn);
return NULL;
}
qemu: new API for tracking arbitrary monitor events Several times in the past, qemu has implemented a new event, but libvirt has not yet caught up to reporting that event to the user applications. While it is possible to track libvirt logs to see that an unknown event was received and ignored, it would be nicer to copy what 'virsh qemu-monitor-command' does, and expose this information to the end developer as one of our unsupported qemu-specific commands. If you find yourself needing to use this API for more than just development purposes, please ask on the libvirt list for a supported counterpart event to be added in libvirt.so. While the supported virConnectDomainEventRegisterAny() API takes an id which determines the signature of the callback, this version takes a string filter and always uses the same signature. Furthermore, I chose to expose this as a new API instead of trying to add a new eventID at the top level, in part because the generic option lacks event name filtering, and in part because the normal domain event namespace should not be polluted by a qemu-only event. I also added a flags argument; unused for now, but we might decide to use it to allow a user to request event names by glob or regex instead of literal match. This API intentionally requires full write access (while normal event registration is allowed on read-only clients); this is in part due to the fact that it should only be used by debugging situations, and in part because the design of per-event filtering in later patches ended up allowing for duplicate registrations that could potentially be abused to exhaust server memory - requiring write privileges means that such abuse will not serve as a denial of service attack against users with higher privileges. * include/libvirt/libvirt-qemu.h (virConnectDomainQemuMonitorEventCallback) (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New prototypes. * src/libvirt-qemu.c (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New functions. * src/libvirt_qemu.syms (LIBVIRT_QEMU_1.2.1): Export them. * src/driver.h (virDrvConnectDomainQemuMonitorEventRegister) (virDrvConnectDomainQemuMonitorEventDeregister): New callbacks. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-19 14:06:35 +00:00
/**
* virConnectDomainQemuMonitorEventRegister:
* @conn: pointer to the connection
* @dom: pointer to the domain, or NULL
* @event: name of the event, or NULL
* @cb: callback to the function handling monitor events
* @opaque: opaque data to pass on to the callback
* @freecb: optional function to deallocate opaque when not used anymore
* @flags: bitwise-OR of virConnectDomainQemuMonitorEventRegisterFlags
qemu: new API for tracking arbitrary monitor events Several times in the past, qemu has implemented a new event, but libvirt has not yet caught up to reporting that event to the user applications. While it is possible to track libvirt logs to see that an unknown event was received and ignored, it would be nicer to copy what 'virsh qemu-monitor-command' does, and expose this information to the end developer as one of our unsupported qemu-specific commands. If you find yourself needing to use this API for more than just development purposes, please ask on the libvirt list for a supported counterpart event to be added in libvirt.so. While the supported virConnectDomainEventRegisterAny() API takes an id which determines the signature of the callback, this version takes a string filter and always uses the same signature. Furthermore, I chose to expose this as a new API instead of trying to add a new eventID at the top level, in part because the generic option lacks event name filtering, and in part because the normal domain event namespace should not be polluted by a qemu-only event. I also added a flags argument; unused for now, but we might decide to use it to allow a user to request event names by glob or regex instead of literal match. This API intentionally requires full write access (while normal event registration is allowed on read-only clients); this is in part due to the fact that it should only be used by debugging situations, and in part because the design of per-event filtering in later patches ended up allowing for duplicate registrations that could potentially be abused to exhaust server memory - requiring write privileges means that such abuse will not serve as a denial of service attack against users with higher privileges. * include/libvirt/libvirt-qemu.h (virConnectDomainQemuMonitorEventCallback) (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New prototypes. * src/libvirt-qemu.c (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New functions. * src/libvirt_qemu.syms (LIBVIRT_QEMU_1.2.1): Export them. * src/driver.h (virDrvConnectDomainQemuMonitorEventRegister) (virDrvConnectDomainQemuMonitorEventDeregister): New callbacks. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-19 14:06:35 +00:00
*
* This API is QEMU specific, so it will only work with hypervisor
* connections to the QEMU driver.
*
* Adds a callback to receive notifications of arbitrary qemu monitor events
* occurring on a domain. Many qemu monitor events also result in a libvirt
* event which can be delivered via virConnectDomainEventRegisterAny(); this
* command is primarily for testing new qemu events that have not yet been
* given a libvirt counterpart event.
*
* If @dom is NULL, then events will be monitored for any domain. If @dom
* is non-NULL, then only the specific domain will be monitored.
*
* If @event is NULL, then all monitor events will be reported. If @event is
* non-NULL, then only specific monitor events will be reported. @flags
* controls how the filtering is performed: 0 requests an exact match, while
* VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX states that @event
* is a basic regular expression. Additionally, including
* VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE lets @event match
* case-insensitively.
qemu: new API for tracking arbitrary monitor events Several times in the past, qemu has implemented a new event, but libvirt has not yet caught up to reporting that event to the user applications. While it is possible to track libvirt logs to see that an unknown event was received and ignored, it would be nicer to copy what 'virsh qemu-monitor-command' does, and expose this information to the end developer as one of our unsupported qemu-specific commands. If you find yourself needing to use this API for more than just development purposes, please ask on the libvirt list for a supported counterpart event to be added in libvirt.so. While the supported virConnectDomainEventRegisterAny() API takes an id which determines the signature of the callback, this version takes a string filter and always uses the same signature. Furthermore, I chose to expose this as a new API instead of trying to add a new eventID at the top level, in part because the generic option lacks event name filtering, and in part because the normal domain event namespace should not be polluted by a qemu-only event. I also added a flags argument; unused for now, but we might decide to use it to allow a user to request event names by glob or regex instead of literal match. This API intentionally requires full write access (while normal event registration is allowed on read-only clients); this is in part due to the fact that it should only be used by debugging situations, and in part because the design of per-event filtering in later patches ended up allowing for duplicate registrations that could potentially be abused to exhaust server memory - requiring write privileges means that such abuse will not serve as a denial of service attack against users with higher privileges. * include/libvirt/libvirt-qemu.h (virConnectDomainQemuMonitorEventCallback) (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New prototypes. * src/libvirt-qemu.c (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New functions. * src/libvirt_qemu.syms (LIBVIRT_QEMU_1.2.1): Export them. * src/driver.h (virDrvConnectDomainQemuMonitorEventRegister) (virDrvConnectDomainQemuMonitorEventDeregister): New callbacks. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-19 14:06:35 +00:00
*
* The virDomainPtr object handle passed into the callback upon delivery
* of an event is only valid for the duration of execution of the callback.
* If the callback wishes to keep the domain object after the callback returns,
* it shall take a reference to it, by calling virDomainRef().
* The reference can be released once the object is no longer required
* by calling virDomainFree().
*
* The return value from this method is a positive integer identifier
* for the callback. To unregister a callback, this callback ID should
* be passed to the virConnectDomainQemuMonitorEventDeregister() method.
*
* Returns a callback identifier on success, -1 on failure
*/
int
virConnectDomainQemuMonitorEventRegister(virConnectPtr conn,
virDomainPtr dom,
const char *event,
virConnectDomainQemuMonitorEventCallback cb,
void *opaque,
virFreeCallback freecb,
unsigned int flags)
{
VIR_DOMAIN_DEBUG(dom,
"conn=%p, event=%s, cb=%p, opaque=%p, freecb=%p, flags=0x%x",
qemu: new API for tracking arbitrary monitor events Several times in the past, qemu has implemented a new event, but libvirt has not yet caught up to reporting that event to the user applications. While it is possible to track libvirt logs to see that an unknown event was received and ignored, it would be nicer to copy what 'virsh qemu-monitor-command' does, and expose this information to the end developer as one of our unsupported qemu-specific commands. If you find yourself needing to use this API for more than just development purposes, please ask on the libvirt list for a supported counterpart event to be added in libvirt.so. While the supported virConnectDomainEventRegisterAny() API takes an id which determines the signature of the callback, this version takes a string filter and always uses the same signature. Furthermore, I chose to expose this as a new API instead of trying to add a new eventID at the top level, in part because the generic option lacks event name filtering, and in part because the normal domain event namespace should not be polluted by a qemu-only event. I also added a flags argument; unused for now, but we might decide to use it to allow a user to request event names by glob or regex instead of literal match. This API intentionally requires full write access (while normal event registration is allowed on read-only clients); this is in part due to the fact that it should only be used by debugging situations, and in part because the design of per-event filtering in later patches ended up allowing for duplicate registrations that could potentially be abused to exhaust server memory - requiring write privileges means that such abuse will not serve as a denial of service attack against users with higher privileges. * include/libvirt/libvirt-qemu.h (virConnectDomainQemuMonitorEventCallback) (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New prototypes. * src/libvirt-qemu.c (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New functions. * src/libvirt_qemu.syms (LIBVIRT_QEMU_1.2.1): Export them. * src/driver.h (virDrvConnectDomainQemuMonitorEventRegister) (virDrvConnectDomainQemuMonitorEventDeregister): New callbacks. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-19 14:06:35 +00:00
conn, NULLSTR(event), cb, opaque, freecb, flags);
virResetLastError();
virCheckConnectReturn(conn, -1);
if (dom) {
virCheckDomainGoto(dom, error);
if (dom->conn != conn) {
virReportInvalidArg(dom,
_("domain '%s' in %s must match connection"),
dom->name, __FUNCTION__);
goto error;
}
}
virCheckNonNullArgGoto(cb, error);
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver && conn->driver->connectDomainQemuMonitorEventRegister) {
int ret;
ret = conn->driver->connectDomainQemuMonitorEventRegister(conn, dom, event, cb, opaque, freecb, flags);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
qemu: new API for tracking arbitrary monitor events Several times in the past, qemu has implemented a new event, but libvirt has not yet caught up to reporting that event to the user applications. While it is possible to track libvirt logs to see that an unknown event was received and ignored, it would be nicer to copy what 'virsh qemu-monitor-command' does, and expose this information to the end developer as one of our unsupported qemu-specific commands. If you find yourself needing to use this API for more than just development purposes, please ask on the libvirt list for a supported counterpart event to be added in libvirt.so. While the supported virConnectDomainEventRegisterAny() API takes an id which determines the signature of the callback, this version takes a string filter and always uses the same signature. Furthermore, I chose to expose this as a new API instead of trying to add a new eventID at the top level, in part because the generic option lacks event name filtering, and in part because the normal domain event namespace should not be polluted by a qemu-only event. I also added a flags argument; unused for now, but we might decide to use it to allow a user to request event names by glob or regex instead of literal match. This API intentionally requires full write access (while normal event registration is allowed on read-only clients); this is in part due to the fact that it should only be used by debugging situations, and in part because the design of per-event filtering in later patches ended up allowing for duplicate registrations that could potentially be abused to exhaust server memory - requiring write privileges means that such abuse will not serve as a denial of service attack against users with higher privileges. * include/libvirt/libvirt-qemu.h (virConnectDomainQemuMonitorEventCallback) (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New prototypes. * src/libvirt-qemu.c (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New functions. * src/libvirt_qemu.syms (LIBVIRT_QEMU_1.2.1): Export them. * src/driver.h (virDrvConnectDomainQemuMonitorEventRegister) (virDrvConnectDomainQemuMonitorEventDeregister): New callbacks. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-19 14:06:35 +00:00
virDispatchError(conn);
return -1;
}
/**
* virConnectDomainQemuMonitorEventDeregister:
* @conn: pointer to the connection
* @callbackID: the callback identifier
*
* Removes an event callback. The callbackID parameter should be the
* value obtained from a previous virConnectDomainQemuMonitorEventRegister()
* method.
*
* Returns 0 on success, -1 on failure
*/
int
virConnectDomainQemuMonitorEventDeregister(virConnectPtr conn,
int callbackID)
{
VIR_DEBUG("conn=%p, callbackID=%d", conn, callbackID);
virResetLastError();
virCheckConnectReturn(conn, -1);
virCheckNonNegativeArgGoto(callbackID, error);
virCheckReadOnlyGoto(conn->flags, error);
if (conn->driver && conn->driver->connectDomainQemuMonitorEventDeregister) {
int ret;
ret = conn->driver->connectDomainQemuMonitorEventDeregister(conn, callbackID);
if (ret < 0)
goto error;
return ret;
}
virReportUnsupportedError();
error:
qemu: new API for tracking arbitrary monitor events Several times in the past, qemu has implemented a new event, but libvirt has not yet caught up to reporting that event to the user applications. While it is possible to track libvirt logs to see that an unknown event was received and ignored, it would be nicer to copy what 'virsh qemu-monitor-command' does, and expose this information to the end developer as one of our unsupported qemu-specific commands. If you find yourself needing to use this API for more than just development purposes, please ask on the libvirt list for a supported counterpart event to be added in libvirt.so. While the supported virConnectDomainEventRegisterAny() API takes an id which determines the signature of the callback, this version takes a string filter and always uses the same signature. Furthermore, I chose to expose this as a new API instead of trying to add a new eventID at the top level, in part because the generic option lacks event name filtering, and in part because the normal domain event namespace should not be polluted by a qemu-only event. I also added a flags argument; unused for now, but we might decide to use it to allow a user to request event names by glob or regex instead of literal match. This API intentionally requires full write access (while normal event registration is allowed on read-only clients); this is in part due to the fact that it should only be used by debugging situations, and in part because the design of per-event filtering in later patches ended up allowing for duplicate registrations that could potentially be abused to exhaust server memory - requiring write privileges means that such abuse will not serve as a denial of service attack against users with higher privileges. * include/libvirt/libvirt-qemu.h (virConnectDomainQemuMonitorEventCallback) (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New prototypes. * src/libvirt-qemu.c (virConnectDomainQemuMonitorEventRegister) (virConnectDomainQemuMonitorEventDeregister): New functions. * src/libvirt_qemu.syms (LIBVIRT_QEMU_1.2.1): Export them. * src/driver.h (virDrvConnectDomainQemuMonitorEventRegister) (virDrvConnectDomainQemuMonitorEventDeregister): New callbacks. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-12-19 14:06:35 +00:00
virDispatchError(conn);
return -1;
}