libvirt/src/storage/storage_backend.h

320 lines
14 KiB
C
Raw Normal View History

/*
* storage_backend.h: internal storage driver backend contract
*
* Copyright (C) 2007-2010, 2012-2014 Red Hat, Inc.
* Copyright (C) 2007-2008 Daniel P. Berrange
*
* 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: Daniel P. Berrange <berrange@redhat.com>
*/
#ifndef __VIR_STORAGE_BACKEND_H__
# define __VIR_STORAGE_BACKEND_H__
# include <sys/stat.h>
# include "internal.h"
# include "storage_conf.h"
# include "vircommand.h"
# include "storage_driver.h"
typedef char * (*virStorageBackendFindPoolSources)(virConnectPtr conn,
const char *srcSpec,
unsigned int flags);
typedef int (*virStorageBackendCheckPool)(virStoragePoolObjPtr pool,
bool *active);
typedef int (*virStorageBackendStartPool)(virConnectPtr conn,
virStoragePoolObjPtr pool);
typedef int (*virStorageBackendBuildPool)(virConnectPtr conn,
virStoragePoolObjPtr pool,
unsigned int flags);
typedef int (*virStorageBackendRefreshPool)(virConnectPtr conn,
virStoragePoolObjPtr pool);
typedef int (*virStorageBackendStopPool)(virConnectPtr conn,
virStoragePoolObjPtr pool);
typedef int (*virStorageBackendDeletePool)(virConnectPtr conn,
virStoragePoolObjPtr pool,
unsigned int flags);
/* A 'buildVol' backend must remove any volume created on error since
* the storage driver does not distinguish whether the failure is due
* to failure to create the volume, to reserve any space necessary for
* the volume, to get data about the volume, to change it's accessibility,
* etc. This avoids issues arising from a creation failure due to some
* external action which created a volume of the same name that libvirt
* was not aware of between checking the pool and the create attempt. It
* also avoids extra round trips to just delete a file.
*/
typedef int (*virStorageBackendBuildVol)(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
unsigned int flags);
typedef int (*virStorageBackendCreateVol)(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol);
typedef int (*virStorageBackendRefreshVol)(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol);
typedef int (*virStorageBackendDeleteVol)(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
unsigned int flags);
typedef int (*virStorageBackendBuildVolFrom)(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr origvol,
virStorageVolDefPtr newvol,
unsigned int flags);
typedef int (*virStorageBackendVolumeResize)(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
unsigned long long capacity,
unsigned int flags);
typedef int (*virStorageBackendVolumeDownload)(virConnectPtr conn,
virStoragePoolObjPtr obj,
virStorageVolDefPtr vol,
virStreamPtr stream,
unsigned long long offset,
unsigned long long length,
unsigned int flags);
typedef int (*virStorageBackendVolumeUpload)(virConnectPtr conn,
virStoragePoolObjPtr obj,
virStorageVolDefPtr vol,
virStreamPtr stream,
unsigned long long offset,
unsigned long long len,
unsigned int flags);
typedef int (*virStorageBackendVolumeWipe)(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
unsigned int algorithm,
unsigned int flags);
/* File creation/cloning functions used for cloning between backends */
int virStorageBackendCreateRaw(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
virStorageVolDefPtr inputvol,
unsigned int flags);
int virStorageBackendCreateQemuImg(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
virStorageVolDefPtr inputvol,
unsigned int flags);
int virStorageBackendCreatePloop(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
virStorageVolDefPtr inputvol,
unsigned int flags);
int virStoragePloopResize(virStorageVolDefPtr vol,
unsigned long long capacity);
int virStorageBackendRedoPloopUpdate(virStorageSourcePtr target,
struct stat *sb, int *fd,
unsigned int flags);
bool virStorageBackendIsPloopDir(char *path);
virStorageBackendBuildVolFrom
virStorageBackendGetBuildVolFromFunction(virStorageVolDefPtr vol,
virStorageVolDefPtr inputvol);
int virStorageBackendFindGlusterPoolSources(const char *host,
int pooltype,
virStoragePoolSourceListPtr list);
int virStorageBackendVolUploadLocal(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
virStreamPtr stream,
unsigned long long offset,
unsigned long long len,
unsigned int flags);
int virStorageBackendVolDownloadLocal(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
virStreamPtr stream,
unsigned long long offset,
unsigned long long len,
unsigned int flags);
int virStorageBackendVolWipeLocal(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
unsigned int algorithm,
unsigned int flags);
typedef struct _virStorageBackend virStorageBackend;
typedef virStorageBackend *virStorageBackendPtr;
storage: initial support for linking with libgfapi We support gluster volumes in domain XML, so we also ought to support them as a storage pool. Besides, a future patch will want to take advantage of libgfapi to handle the case of a gluster device holding qcow2 rather than raw storage, and for that to work, we need a storage backend that can read gluster storage volume contents. This sets up the framework. Note that the new pool is named 'gluster' to match a <disk type='network'><source protocol='gluster'> image source already supported in a <domain>; it does NOT match the <pool type='netfs'><source><target type='glusterfs'>, since that uses a FUSE mount to a local file name rather than a network name. This and subsequent patches have been tested against glusterfs 3.4.1 (available on Fedora 19); there are likely bugs in older versions that may prevent decent use of gfapi, so this patch enforces the minimum version tested. A future patch may lower the minimum. On the other hand, I hit at least two bugs in 3.4.1 that will be fixed in 3.5/3.4.2, where it might be worth raising the minimum: glfs_readdir is nicer to use than glfs_readdir_r [1], and glfs_fini should only return failure on an actual failure [2]. [1] http://lists.gnu.org/archive/html/gluster-devel/2013-10/msg00085.html [2] http://lists.gnu.org/archive/html/gluster-devel/2013-10/msg00086.html * configure.ac (WITH_STORAGE_GLUSTER): New conditional. * m4/virt-gluster.m4: new file. * libvirt.spec.in (BuildRequires): Support gluster in spec file. * src/conf/storage_conf.h (VIR_STORAGE_POOL_GLUSTER): New pool type. * src/conf/storage_conf.c (poolTypeInfo): Treat similar to sheepdog and rbd. (virStoragePoolDefFormat): Don't output target for gluster. * src/storage/storage_backend_gluster.h: New file. * src/storage/storage_backend_gluster.c: Likewise. * po/POTFILES.in: Add new file. * src/storage/storage_backend.c (backends): Register new type. * src/Makefile.am (STORAGE_DRIVER_GLUSTER_SOURCES): Build new files. * src/storage/storage_backend.h (_virStorageBackend): Documet assumption. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-11-19 23:26:05 +00:00
/* Callbacks are optional unless documented otherwise; but adding more
* callbacks provides better pool support. */
struct _virStorageBackend {
int type;
virStorageBackendFindPoolSources findPoolSources;
virStorageBackendCheckPool checkPool;
virStorageBackendStartPool startPool;
virStorageBackendBuildPool buildPool;
storage: initial support for linking with libgfapi We support gluster volumes in domain XML, so we also ought to support them as a storage pool. Besides, a future patch will want to take advantage of libgfapi to handle the case of a gluster device holding qcow2 rather than raw storage, and for that to work, we need a storage backend that can read gluster storage volume contents. This sets up the framework. Note that the new pool is named 'gluster' to match a <disk type='network'><source protocol='gluster'> image source already supported in a <domain>; it does NOT match the <pool type='netfs'><source><target type='glusterfs'>, since that uses a FUSE mount to a local file name rather than a network name. This and subsequent patches have been tested against glusterfs 3.4.1 (available on Fedora 19); there are likely bugs in older versions that may prevent decent use of gfapi, so this patch enforces the minimum version tested. A future patch may lower the minimum. On the other hand, I hit at least two bugs in 3.4.1 that will be fixed in 3.5/3.4.2, where it might be worth raising the minimum: glfs_readdir is nicer to use than glfs_readdir_r [1], and glfs_fini should only return failure on an actual failure [2]. [1] http://lists.gnu.org/archive/html/gluster-devel/2013-10/msg00085.html [2] http://lists.gnu.org/archive/html/gluster-devel/2013-10/msg00086.html * configure.ac (WITH_STORAGE_GLUSTER): New conditional. * m4/virt-gluster.m4: new file. * libvirt.spec.in (BuildRequires): Support gluster in spec file. * src/conf/storage_conf.h (VIR_STORAGE_POOL_GLUSTER): New pool type. * src/conf/storage_conf.c (poolTypeInfo): Treat similar to sheepdog and rbd. (virStoragePoolDefFormat): Don't output target for gluster. * src/storage/storage_backend_gluster.h: New file. * src/storage/storage_backend_gluster.c: Likewise. * po/POTFILES.in: Add new file. * src/storage/storage_backend.c (backends): Register new type. * src/Makefile.am (STORAGE_DRIVER_GLUSTER_SOURCES): Build new files. * src/storage/storage_backend.h (_virStorageBackend): Documet assumption. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-11-19 23:26:05 +00:00
virStorageBackendRefreshPool refreshPool; /* Must be non-NULL */
virStorageBackendStopPool stopPool;
virStorageBackendDeletePool deletePool;
virStorageBackendBuildVol buildVol;
virStorageBackendBuildVolFrom buildVolFrom;
virStorageBackendCreateVol createVol;
virStorageBackendRefreshVol refreshVol;
virStorageBackendDeleteVol deleteVol;
virStorageBackendVolumeResize resizeVol;
virStorageBackendVolumeUpload uploadVol;
virStorageBackendVolumeDownload downloadVol;
virStorageBackendVolumeWipe wipeVol;
};
virStorageBackendPtr virStorageBackendForType(int type);
storage: Check for invalid storage mode before opening If a directory pool contains pipes or sockets, a pool start can fail or hang: https://bugzilla.redhat.com/show_bug.cgi?id=589577 We already try to avoid these special files, but only attempt after opening the path, which is where the problems lie. Unify volume opening into helper functions, which use the proper open() flags to avoid error, followed by fstat to validate storage mode. Previously, virStorageBackendUpdateVolTargetInfoFD attempted to enforce the storage mode check, but allowed callers to detect this case and silently continue. In practice, only the FS backend was using this feature, the rest were treating unknown mode as an error condition. Unfortunately the InfoFD function wasn't raising an error message here, so error reporting was busted. This patch adds 2 functions: virStorageBackendVolOpen, and virStorageBackendVolOpenModeSkip. The latter retains the original opt out semantics, the former now throws an explicit error. This patch maintains the previous volume mode checks: allowing specific modes for specific pool types requires a bit of surgery, since VolOpen is called through several different helper functions. v2: Use ATTRIBUTE_NONNULL. Drop stat check, just open with O_NONBLOCK|O_NOCTTY. v3: Move mode check logic back to VolOpen. Use 2 VolOpen functions with different error semantics. v4: Make second VolOpen function more extensible. Didn't opt to change FS backend defaults, this can just be to fix the original bug. v5: Prefix default flags with VIR_, use ATTRIBUTE_RETURN_CHECK
2010-05-20 18:25:01 +00:00
/* VolOpenCheckMode flags */
enum {
VIR_STORAGE_VOL_OPEN_NOERROR = 1 << 0, /* don't error if unexpected type
* encountered, just warn */
VIR_STORAGE_VOL_OPEN_REG = 1 << 1, /* regular files okay */
VIR_STORAGE_VOL_OPEN_BLOCK = 1 << 2, /* block files okay */
VIR_STORAGE_VOL_OPEN_CHAR = 1 << 3, /* char files okay */
VIR_STORAGE_VOL_OPEN_DIR = 1 << 4, /* directories okay */
storage: Check for invalid storage mode before opening If a directory pool contains pipes or sockets, a pool start can fail or hang: https://bugzilla.redhat.com/show_bug.cgi?id=589577 We already try to avoid these special files, but only attempt after opening the path, which is where the problems lie. Unify volume opening into helper functions, which use the proper open() flags to avoid error, followed by fstat to validate storage mode. Previously, virStorageBackendUpdateVolTargetInfoFD attempted to enforce the storage mode check, but allowed callers to detect this case and silently continue. In practice, only the FS backend was using this feature, the rest were treating unknown mode as an error condition. Unfortunately the InfoFD function wasn't raising an error message here, so error reporting was busted. This patch adds 2 functions: virStorageBackendVolOpen, and virStorageBackendVolOpenModeSkip. The latter retains the original opt out semantics, the former now throws an explicit error. This patch maintains the previous volume mode checks: allowing specific modes for specific pool types requires a bit of surgery, since VolOpen is called through several different helper functions. v2: Use ATTRIBUTE_NONNULL. Drop stat check, just open with O_NONBLOCK|O_NOCTTY. v3: Move mode check logic back to VolOpen. Use 2 VolOpen functions with different error semantics. v4: Make second VolOpen function more extensible. Didn't opt to change FS backend defaults, this can just be to fix the original bug. v5: Prefix default flags with VIR_, use ATTRIBUTE_RETURN_CHECK
2010-05-20 18:25:01 +00:00
};
/* VolReadErrorMode flags
* If flag is present, then operation won't cause fatal error for
* specified operation, rather a VIR_WARN will be issued and a -2 returned
* for function call
*/
enum {
VIR_STORAGE_VOL_READ_NOERROR = 1 << 0, /* ignore *read errors */
};
# define VIR_STORAGE_VOL_OPEN_DEFAULT (VIR_STORAGE_VOL_OPEN_REG |\
VIR_STORAGE_VOL_OPEN_BLOCK)
storage: Check for invalid storage mode before opening If a directory pool contains pipes or sockets, a pool start can fail or hang: https://bugzilla.redhat.com/show_bug.cgi?id=589577 We already try to avoid these special files, but only attempt after opening the path, which is where the problems lie. Unify volume opening into helper functions, which use the proper open() flags to avoid error, followed by fstat to validate storage mode. Previously, virStorageBackendUpdateVolTargetInfoFD attempted to enforce the storage mode check, but allowed callers to detect this case and silently continue. In practice, only the FS backend was using this feature, the rest were treating unknown mode as an error condition. Unfortunately the InfoFD function wasn't raising an error message here, so error reporting was busted. This patch adds 2 functions: virStorageBackendVolOpen, and virStorageBackendVolOpenModeSkip. The latter retains the original opt out semantics, the former now throws an explicit error. This patch maintains the previous volume mode checks: allowing specific modes for specific pool types requires a bit of surgery, since VolOpen is called through several different helper functions. v2: Use ATTRIBUTE_NONNULL. Drop stat check, just open with O_NONBLOCK|O_NOCTTY. v3: Move mode check logic back to VolOpen. Use 2 VolOpen functions with different error semantics. v4: Make second VolOpen function more extensible. Didn't opt to change FS backend defaults, this can just be to fix the original bug. v5: Prefix default flags with VIR_, use ATTRIBUTE_RETURN_CHECK
2010-05-20 18:25:01 +00:00
int virStorageBackendVolOpen(const char *path, struct stat *sb,
unsigned int flags)
ATTRIBUTE_RETURN_CHECK
ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2);
# define VIR_STORAGE_DEFAULT_POOL_PERM_MODE 0755
# define VIR_STORAGE_DEFAULT_VOL_PERM_MODE 0600
int virStorageBackendUpdateVolInfo(virStorageVolDefPtr vol,
bool withBlockVolFormat,
unsigned int openflags,
unsigned int readflags);
int virStorageBackendUpdateVolTargetInfo(virStorageSourcePtr target,
bool withBlockVolFormat,
unsigned int openflags,
unsigned int readflags);
int virStorageBackendUpdateVolTargetInfoFD(virStorageSourcePtr target,
int fd,
struct stat *sb);
bool virStorageBackendPoolPathIsStable(const char *path);
char *virStorageBackendStablePath(virStoragePoolObjPtr pool,
const char *devpath,
bool loop);
2008-02-20 15:38:29 +00:00
virCommandPtr
virStorageBackendCreateQemuImgCmdFromVol(virConnectPtr conn,
virStoragePoolObjPtr pool,
virStorageVolDefPtr vol,
virStorageVolDefPtr inputvol,
unsigned int flags,
const char *create_tool,
int imgformat);
/* ------- virStorageFile backends ------------ */
typedef struct _virStorageFileBackend virStorageFileBackend;
typedef virStorageFileBackend *virStorageFileBackendPtr;
struct _virStorageDriverData {
virStorageFileBackendPtr backend;
void *priv;
uid_t uid;
gid_t gid;
};
typedef int
(*virStorageFileBackendInit)(virStorageSourcePtr src);
typedef void
(*virStorageFileBackendDeinit)(virStorageSourcePtr src);
typedef int
(*virStorageFileBackendCreate)(virStorageSourcePtr src);
typedef int
(*virStorageFileBackendUnlink)(virStorageSourcePtr src);
typedef int
(*virStorageFileBackendStat)(virStorageSourcePtr src,
struct stat *st);
typedef ssize_t
(*virStorageFileBackendReadHeader)(virStorageSourcePtr src,
ssize_t max_len,
char **buf);
typedef const char *
(*virStorageFileBackendGetUniqueIdentifier)(virStorageSourcePtr src);
typedef int
(*virStorageFileBackendAccess)(virStorageSourcePtr src,
int mode);
typedef int
(*virStorageFileBackendChown)(virStorageSourcePtr src,
uid_t uid,
gid_t gid);
virStorageFileBackendPtr virStorageFileBackendForType(int type, int protocol);
virStorageFileBackendPtr virStorageFileBackendForTypeInternal(int type,
int protocol,
bool report);
struct _virStorageFileBackend {
int type;
int protocol;
/* All storage file callbacks may be omitted if not implemented */
/* The following group of callbacks is expected to set a libvirt
* error on failure. */
virStorageFileBackendInit backendInit;
virStorageFileBackendDeinit backendDeinit;
virStorageFileBackendReadHeader storageFileReadHeader;
virStorageFileBackendGetUniqueIdentifier storageFileGetUniqueIdentifier;
/* The following group of callbacks is expected to set errno
* and return -1 on error. No libvirt error shall be reported */
virStorageFileBackendCreate storageFileCreate;
virStorageFileBackendUnlink storageFileUnlink;
virStorageFileBackendStat storageFileStat;
virStorageFileBackendAccess storageFileAccess;
virStorageFileBackendChown storageFileChown;
};
#endif /* __VIR_STORAGE_BACKEND_H__ */