libvirt/src/driver.h

139 lines
4.7 KiB
C
Raw Normal View History

/*
* driver.h: description of the set of interfaces provided by a
* entry point to the virtualization engine
maint: use LGPL correctly Several files called out COPYING or COPYING.LIB instead of using the normal boilerplate. It's especially important that we don't call out COPYING from an LGPL file, since COPYING is traditionally used for the GPL. A few files were lacking copyright altogether. * src/rpc/gendispatch.pl: Add missing copyright. * Makefile.nonreentrant: Likewise. * src/check-symfile.pl: Likewise. * src/check-symsorting.pl: Likewise. * src/driver.h: Likewise. * src/internal.h: Likewise. * tools/libvirt-guests.sh.in: Likewise. * tools/virt-pki-validate.in: Mention copyright in comment, not just code. * tools/virt-sanlock-cleanup.in: Likewise. * src/rpc/genprotocol.pl: Spell out license terms. * src/xen/xend_internal.h: Likewise. * src/xen/xend_internal.c: Likewise. * Makefile.am: Likewise. * daemon/Makefile.am: Likewise. * docs/Makefile.am: Likewise. * docs/schemas/Makefile.am: Likewise. * examples/apparmor/Makefile.am: Likewise. * examples/domain-events/events-c/Makefile.am: Likewise. * examples/dominfo/Makefile.am: Likewise. * examples/domsuspend/Makefile.am: Likewise. * examples/hellolibvirt/Makefile.am: Likewise. * examples/openauth/Makefile.am: Likewise. * examples/python/Makefile.am: Likewise. * examples/systemtap/Makefile.am: Likewise. * examples/xml/nwfilter/Makefile.am: Likewise. * gnulib/lib/Makefile.am: Likewise. * gnulib/tests/Makefile.am: Likewise. * include/Makefile.am: Likewise. * include/libvirt/Makefile.am: Likewise. * python/Makefile.am: Likewise. * python/tests/Makefile.am: Likewise. * src/Makefile.am: Likewise. * tests/Makefile.am: Likewise. * tools/Makefile.am: Likewise. * configure.ac: Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-14 23:42:12 +00:00
*
blockcopy: virDomainBlockCopy with XML destination, typed params This commit (finally) adds the virDomainBlockCopy API, with the intent that it will provide more power to the existing 'virsh blockcopy' command. 'virsh blockcopy' was first added in Apr 2012 (v0.9.12), which corresponds to the upstream qemu 1.2 timeframe. It was done as a hack on top of the existing virDomainBlockRebase() API call, for two reasons: 1) it was targetting a feature that landed first in downstream RHEL qemu, but had not stabilized in upstream qemu at the time (and indeed, 'drive-mirror' only landed upstream in qemu 1.3 with slight differences to the first RHEL attempt, and later gained further parameters like granularity and buf-size that are also worth exposing), and 2) extending an existing API allowed it to be backported without worrying about bumping .so versions. A virDomainBlockCopy() API was proposed at that time [1], but we decided not to accept it into libvirt until after upstream qemu stabilized, and it ended up getting scrapped. Whether or not RHEL should have attempted adding a new feature without getting it upstream first is a debate that can be held another day; but enough time has now elapsed that we are ready to do the interface cleanly. [1] https://www.redhat.com/archives/libvir-list/2012-April/msg00768.html Delaying the creation of a clean API until now has also had a benefit: we've only recently learned of a few shortcomings in the original design: 1) it is unable to target a network destination (such as a gluster volume) because it hard-coded the assumption that the destination is a local file name. Because of all the refactoring we've done to add virStorageSourcePtr, we are in a better position to declare an API that parses XML describing a host storage source as the copy destination, which was not possible had we implemented virDomainBlockCopy as it had been originally envisioned (although a network target will have to wait until a later libvirt release compared to the API addition to actually be implemented). 2) the design of using MiB/sec as the bandwidth throttle is rather coarse; qemu is actually tuned to bytes/second, and libvirt is preventing access to that level of detail. A later patch will add flags to existing block job API that can request bytes/second instead of back-compat MiB/s, but as this is a new API, we can get it right to begin with. At least I had the foresight to create 'virsh blockcopy' as a separate command at the UI level (commit 1f06c00) rather than leaking the underlying API overload of virDomainBlockRebase onto shell users. A further note on the bandwidth option: virTypedParameters intentionally lacks unsigned long (since variable-width interaction between mixed 32- vs. 64-bit client/server setups is nasty), but we have to deal with the fact that we are interacting with existing older code that mistakenly chose unsigned long bandwidth at a point before we decided to prohibit it in all new API. The typed parameter is therefore unsigned long long, but the implementation (in a later patch) will have to do overflow detection on 32-bit platforms, as well as capping the value to match the LLONG_MAX>>20 cap of the existing MiB/s interfaces. * include/libvirt/libvirt.h.in (virDomainBlockCopy): New API. (virDomainBlockJobType, virConnectDomainEventBlockJobStatus): Update related documentation. * src/libvirt.c (virDomainBlockCopy): Implement it. * src/libvirt_public.syms (LIBVIRT_1.2.8): Export it. * src/driver.h (_virDriver): New driver callback. Signed-off-by: Eric Blake <eblake@redhat.com>
2014-08-26 21:16:48 +00:00
* Copyright (C) 2006-2014 Red Hat, Inc.
maint: use LGPL correctly Several files called out COPYING or COPYING.LIB instead of using the normal boilerplate. It's especially important that we don't call out COPYING from an LGPL file, since COPYING is traditionally used for the GPL. A few files were lacking copyright altogether. * src/rpc/gendispatch.pl: Add missing copyright. * Makefile.nonreentrant: Likewise. * src/check-symfile.pl: Likewise. * src/check-symsorting.pl: Likewise. * src/driver.h: Likewise. * src/internal.h: Likewise. * tools/libvirt-guests.sh.in: Likewise. * tools/virt-pki-validate.in: Mention copyright in comment, not just code. * tools/virt-sanlock-cleanup.in: Likewise. * src/rpc/genprotocol.pl: Spell out license terms. * src/xen/xend_internal.h: Likewise. * src/xen/xend_internal.c: Likewise. * Makefile.am: Likewise. * daemon/Makefile.am: Likewise. * docs/Makefile.am: Likewise. * docs/schemas/Makefile.am: Likewise. * examples/apparmor/Makefile.am: Likewise. * examples/domain-events/events-c/Makefile.am: Likewise. * examples/dominfo/Makefile.am: Likewise. * examples/domsuspend/Makefile.am: Likewise. * examples/hellolibvirt/Makefile.am: Likewise. * examples/openauth/Makefile.am: Likewise. * examples/python/Makefile.am: Likewise. * examples/systemtap/Makefile.am: Likewise. * examples/xml/nwfilter/Makefile.am: Likewise. * gnulib/lib/Makefile.am: Likewise. * gnulib/tests/Makefile.am: Likewise. * include/Makefile.am: Likewise. * include/libvirt/Makefile.am: Likewise. * python/Makefile.am: Likewise. * python/tests/Makefile.am: Likewise. * src/Makefile.am: Likewise. * tests/Makefile.am: Likewise. * tools/Makefile.am: Likewise. * configure.ac: Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-05-14 23:42:12 +00:00
*
* 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/>.
*/
#pragma once
#include <unistd.h>
#include "internal.h"
#include "libvirt_internal.h"
#include "viruri.h"
/* Status codes returned from driver open call. */
typedef enum {
/* Opened successfully. */
VIR_DRV_OPEN_SUCCESS = 0,
/* 'name' is not for us. */
VIR_DRV_OPEN_DECLINED = -1,
/* 'name' is for us, but there was some error. virConnectOpen will
* return an error rather than continue probing the other drivers.
*/
VIR_DRV_OPEN_ERROR = -2,
} virDrvOpenStatus;
/* Internal feature-detection macro. Don't call drv->supports_feature
* directly if you don't have to, because it may be NULL, use this macro
* instead.
*
* Note that this treats a possible error returned by drv->supports_feature
* the same as not supported. If you care about the error, call
* drv->supports_feature directly.
*
* Returns:
* != 0 Feature is supported.
* 0 Feature is not supported.
*/
#define VIR_DRV_SUPPORTS_FEATURE(drv, conn, feature) \
((drv)->connectSupportsFeature ? \
(drv)->connectSupportsFeature((conn), (feature)) > 0 : 0)
#define __VIR_DRIVER_H_INCLUDES___
#include "driver-hypervisor.h"
#include "driver-interface.h"
#include "driver-network.h"
#include "driver-nodedev.h"
#include "driver-nwfilter.h"
#include "driver-secret.h"
#include "driver-state.h"
#include "driver-stream.h"
#include "driver-storage.h"
#undef __VIR_DRIVER_H_INCLUDES___
typedef struct _virConnectDriver virConnectDriver;
typedef virConnectDriver *virConnectDriverPtr;
struct _virConnectDriver {
/* Whether driver permits a server in the URI */
bool localOnly;
/* Whether driver needs a server in the URI */
bool remoteOnly;
libvirt: support an "embed" URI path selector for opening drivers The driver URI scheme: "$drivername:///embed?root=/some/path" enables a new way to use the drivers by embedding them directly in the calling process. To use this the process must have a thread running the libvirt event loop. This URI will then cause libvirt to dynamically load the driver module and call its global initialization function. This syntax is applicable to any driver, but only those will have been modified to support a custom root directory and embed URI path will successfully open. The application can now make normal libvirt API calls which are all serviced in-process with no RPC layer involved. It is required to specify an explicit root directory, and locks will be acquired on this directory to avoid conflicting with another app that might accidentally pick the same directory. Use of '/' is not explicitly forbidden, but note that the file layout used underneath the embedded driver root does not match the file layout used by system/session mode drivers. So this cannot be used as a backdoor to interact with, or fake, the system/session mode drivers. Libvirt will create arbitrary files underneath this root directory. The root directory can be kept untouched across connection open attempts if the application needs persistence. The application is responsible for purging everything underneath this root directory when finally no longer required. Even when a virt driver is used in embedded mode, it is still possible for it to in turn use functionality that calls out to other secondary drivers in libvirtd. For example an embedded instance of QEMU can open the network, secret or storage drivers in the system libvirtd. That said, the application would typically want to at least open an embedded secret driver ("secret:///embed?root=/some/path"). Note that multiple different embedded drivers can use the same root prefix and co-operate just as they would inside a normal libvirtd daemon. A key thing to note is that for this to work, the application that links to libvirt *MUST* be built with -Wl,--export-dynamic to ensure that symbols from libvirt.so are exported & thus available to the dynamically loaded driver module. If libvirt.so itself was dynamically loaded then RTLD_GLOBAL must be passed to dlopen(). Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-05-17 11:42:04 +00:00
/* Whether driver can be used in embedded mode */
bool embeddable;
/*
* NULL terminated list of supported URI schemes.
* - Single element { NULL } list indicates no supported schemes
* - NULL list indicates wildcard supporting all schemes
*/
const char **uriSchemes;
virHypervisorDriverPtr hypervisorDriver;
virInterfaceDriverPtr interfaceDriver;
virNetworkDriverPtr networkDriver;
virNodeDeviceDriverPtr nodeDeviceDriver;
virNWFilterDriverPtr nwfilterDriver;
virSecretDriverPtr secretDriver;
virStorageDriverPtr storageDriver;
};
int virRegisterConnectDriver(virConnectDriverPtr driver,
bool setSharedDrivers) G_GNUC_WARN_UNUSED_RESULT;
int virRegisterStateDriver(virStateDriverPtr driver) G_GNUC_WARN_UNUSED_RESULT;
int virSetSharedInterfaceDriver(virInterfaceDriverPtr driver) G_GNUC_WARN_UNUSED_RESULT;
int virSetSharedNetworkDriver(virNetworkDriverPtr driver) G_GNUC_WARN_UNUSED_RESULT;
int virSetSharedNodeDeviceDriver(virNodeDeviceDriverPtr driver) G_GNUC_WARN_UNUSED_RESULT;
int virSetSharedNWFilterDriver(virNWFilterDriverPtr driver) G_GNUC_WARN_UNUSED_RESULT;
int virSetSharedSecretDriver(virSecretDriverPtr driver) G_GNUC_WARN_UNUSED_RESULT;
int virSetSharedStorageDriver(virStorageDriverPtr driver) G_GNUC_WARN_UNUSED_RESULT;
remote: enable connecting to the per-driver daemons Historically URIs handled by the remote driver will always connect to the libvirtd UNIX socket. There will now be one daemon per driver, and each of these has its own UNIX sockets to connect to. It will still be possible to run the traditional monolithic libvirtd though, which will have the original UNIX socket path. In addition there is a virproxyd daemon that doesn't run any drivers, but provides proxying for clients accessing libvirt over IP sockets, or tunnelling to the legacy libvirtd UNIX socket path. Finally when running inside a daemon, the remote driver must not reject connections unconditionally. For example, the QEMU driver needs to be able to connect to the network driver. The remote driver must thus be willing to handle connections even when inside the daemon, provided no local driver is registered. This refactoring enables the remote driver to be able to connect to the per-driver daemons. The URI parameter "mode" accepts the values "auto", "direct" and "legacy" to control which daemons are connected to. The client side libvirt.conf config file also supports a "remote_mode" setting which is used if the URI parameter is not set. If neither the config file or URI parameter set a mode, then "auto" is used, whereby the client looks to see which sockets actually exist right now. The remote driver will only ever spawn the per-driver daemons, or the legacy libvirtd. It won't ever try to spawn virtproxyd, as that is only there for IP based connectivity, or for access from legacy remote clients. If connecting to a remote host over any kind of ssh tunnel, for now we must assume only the legacy socket exists. A future patch will introduce a netcat replacement that is tailored for libvirt to make remote tunnelling easier. The configure arg '--with-remote-default-mode=legacy|direct' allows packagers to set a default at build time. If not given, it will default to legacy mode. Eventually the default will switch to direct mode. Distros can choose to do the switch earlier if desired. The main blocker is testing and suitable SELinux/AppArmor policies. Reviewed-by: Andrea Bolognani <abologna@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2019-07-04 08:41:34 +00:00
bool virHasDriverForURIScheme(const char *scheme);
int virDriverLoadModule(const char *name,
const char *regfunc,
bool required);
int virDriverShouldAutostart(const char *name,
bool *autostart);
virConnectPtr virGetConnectInterface(void);
virConnectPtr virGetConnectNetwork(void);
virConnectPtr virGetConnectNWFilter(void);
virConnectPtr virGetConnectNodeDev(void);
virConnectPtr virGetConnectSecret(void);
virConnectPtr virGetConnectStorage(void);
int virSetConnectInterface(virConnectPtr conn);
int virSetConnectNetwork(virConnectPtr conn);
int virSetConnectNWFilter(virConnectPtr conn);
int virSetConnectNodeDev(virConnectPtr conn);
int virSetConnectSecret(virConnectPtr conn);
int virSetConnectStorage(virConnectPtr conn);
bool virConnectValidateURIPath(const char *uriPath,
const char *entityName,
bool privileged);