1 /* 2 * libvirt-storage.h 3 * Summary: APIs for management of storage pools and volumes 4 * Description: Provides APIs for the management of storage pools and volumes 5 * 6 * Copyright (C) 2006-2016 Red Hat, Inc. 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see 20 * <http://www.gnu.org/licenses/>. 21 */ 22 23 #ifndef LIBVIRT_STORAGE_H 24 # define LIBVIRT_STORAGE_H 25 26 # ifndef __VIR_LIBVIRT_H_INCLUDES__ 27 # error "Don't include this file directly, only use libvirt/libvirt.h" 28 # endif 29 30 31 /** 32 * virStoragePool: 33 * 34 * a virStoragePool is a private structure representing a storage pool 35 */ 36 typedef struct _virStoragePool virStoragePool; 37 38 /** 39 * virStoragePoolPtr: 40 * 41 * a virStoragePoolPtr is pointer to a virStoragePool private structure, this is the 42 * type used to reference a storage pool in the API. 43 */ 44 typedef virStoragePool *virStoragePoolPtr; 45 46 47 typedef enum { 48 VIR_STORAGE_POOL_INACTIVE = 0, /* Not running */ 49 VIR_STORAGE_POOL_BUILDING = 1, /* Initializing pool, not available */ 50 VIR_STORAGE_POOL_RUNNING = 2, /* Running normally */ 51 VIR_STORAGE_POOL_DEGRADED = 3, /* Running degraded */ 52 VIR_STORAGE_POOL_INACCESSIBLE = 4, /* Running, but not accessible */ 53 54 # ifdef VIR_ENUM_SENTINELS 55 VIR_STORAGE_POOL_STATE_LAST 56 # endif 57 } virStoragePoolState; 58 59 typedef enum { 60 VIR_STORAGE_POOL_BUILD_NEW = 0, /* Regular build from scratch */ 61 VIR_STORAGE_POOL_BUILD_REPAIR = (1 << 0), /* Repair / reinitialize */ 62 VIR_STORAGE_POOL_BUILD_RESIZE = (1 << 1), /* Extend existing pool */ 63 VIR_STORAGE_POOL_BUILD_NO_OVERWRITE = (1 << 2), /* Do not overwrite existing pool */ 64 VIR_STORAGE_POOL_BUILD_OVERWRITE = (1 << 3), /* Overwrite data */ 65 } virStoragePoolBuildFlags; 66 67 typedef enum { 68 VIR_STORAGE_POOL_DELETE_NORMAL = 0, /* Delete metadata only (fast) */ 69 VIR_STORAGE_POOL_DELETE_ZEROED = 1 << 0, /* Clear all data to zeros (slow) */ 70 } virStoragePoolDeleteFlags; 71 72 typedef enum { 73 /* Create the pool but do not perform pool build */ 74 VIR_STORAGE_POOL_CREATE_NORMAL = 0, 75 76 /* Create the pool and perform pool build without any flags */ 77 VIR_STORAGE_POOL_CREATE_WITH_BUILD = 1 << 0, 78 79 /* Create the pool and perform pool build using the 80 * VIR_STORAGE_POOL_BUILD_OVERWRITE flag. This is mutually 81 * exclusive to VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE */ 82 VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE = 1 << 1, 83 84 /* Create the pool and perform pool build using the 85 * VIR_STORAGE_POOL_BUILD_NO_OVERWRITE flag. This is mutually 86 * exclusive to VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE */ 87 VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE = 1 << 2, 88 } virStoragePoolCreateFlags; 89 90 typedef struct _virStoragePoolInfo virStoragePoolInfo; 91 92 struct _virStoragePoolInfo { 93 int state; /* virStoragePoolState flags */ 94 unsigned long long capacity; /* Logical size bytes */ 95 unsigned long long allocation; /* Current allocation bytes */ 96 unsigned long long available; /* Remaining free space bytes */ 97 }; 98 99 typedef virStoragePoolInfo *virStoragePoolInfoPtr; 100 101 102 /** 103 * virStorageVol: 104 * 105 * a virStorageVol is a private structure representing a storage volume 106 */ 107 typedef struct _virStorageVol virStorageVol; 108 109 /** 110 * virStorageVolPtr: 111 * 112 * a virStorageVolPtr is pointer to a virStorageVol private structure, this is the 113 * type used to reference a storage volume in the API. 114 */ 115 typedef virStorageVol *virStorageVolPtr; 116 117 118 typedef enum { 119 VIR_STORAGE_VOL_FILE = 0, /* Regular file based volumes */ 120 VIR_STORAGE_VOL_BLOCK = 1, /* Block based volumes */ 121 VIR_STORAGE_VOL_DIR = 2, /* Directory-passthrough based volume */ 122 VIR_STORAGE_VOL_NETWORK = 3, /* Network volumes like RBD (RADOS Block Device) */ 123 VIR_STORAGE_VOL_NETDIR = 4, /* Network accessible directory that can 124 * contain other network volumes */ 125 VIR_STORAGE_VOL_PLOOP = 5, /* Ploop based volumes */ 126 127 # ifdef VIR_ENUM_SENTINELS 128 VIR_STORAGE_VOL_LAST 129 # endif 130 } virStorageVolType; 131 132 typedef enum { 133 VIR_STORAGE_VOL_DELETE_NORMAL = 0, /* Delete metadata only (fast) */ 134 VIR_STORAGE_VOL_DELETE_ZEROED = 1 << 0, /* Clear all data to zeros (slow) */ 135 VIR_STORAGE_VOL_DELETE_WITH_SNAPSHOTS = 1 << 1, /* Force removal of volume, even if in use */ 136 } virStorageVolDeleteFlags; 137 138 typedef enum { 139 VIR_STORAGE_VOL_WIPE_ALG_ZERO = 0, /* 1-pass, all zeroes */ 140 VIR_STORAGE_VOL_WIPE_ALG_NNSA = 1, /* 4-pass NNSA Policy Letter 141 NAP-14.1-C (XVI-8) */ 142 VIR_STORAGE_VOL_WIPE_ALG_DOD = 2, /* 4-pass DoD 5220.22-M section 143 8-306 procedure */ 144 VIR_STORAGE_VOL_WIPE_ALG_BSI = 3, /* 9-pass method recommended by the 145 German Center of Security in 146 Information Technologies */ 147 VIR_STORAGE_VOL_WIPE_ALG_GUTMANN = 4, /* The canonical 35-pass sequence */ 148 VIR_STORAGE_VOL_WIPE_ALG_SCHNEIER = 5, /* 7-pass method described by 149 Bruce Schneier in "Applied 150 Cryptography" (1996) */ 151 VIR_STORAGE_VOL_WIPE_ALG_PFITZNER7 = 6, /* 7-pass random */ 152 153 VIR_STORAGE_VOL_WIPE_ALG_PFITZNER33 = 7, /* 33-pass random */ 154 155 VIR_STORAGE_VOL_WIPE_ALG_RANDOM = 8, /* 1-pass random */ 156 157 VIR_STORAGE_VOL_WIPE_ALG_TRIM = 9, /* 1-pass, trim all data on the 158 volume by using TRIM or DISCARD */ 159 160 # ifdef VIR_ENUM_SENTINELS 161 VIR_STORAGE_VOL_WIPE_ALG_LAST 162 /* 163 * NB: this enum value will increase over time as new algorithms are 164 * added to the libvirt API. It reflects the last algorithm supported 165 * by this version of the libvirt API. 166 */ 167 # endif 168 } virStorageVolWipeAlgorithm; 169 170 typedef enum { 171 VIR_STORAGE_VOL_USE_ALLOCATION = 0, 172 173 /* Return the physical size in allocation */ 174 VIR_STORAGE_VOL_GET_PHYSICAL = 1 << 0, 175 176 } virStorageVolInfoFlags; 177 178 typedef struct _virStorageVolInfo virStorageVolInfo; 179 180 struct _virStorageVolInfo { 181 int type; /* virStorageVolType flags */ 182 unsigned long long capacity; /* Logical size bytes */ 183 unsigned long long allocation; /* Current allocation bytes */ 184 }; 185 186 typedef virStorageVolInfo *virStorageVolInfoPtr; 187 188 typedef enum { 189 VIR_STORAGE_XML_INACTIVE = (1 << 0), /* dump inactive pool/volume information */ 190 } virStorageXMLFlags; 191 192 /* 193 * Get connection from pool. 194 */ 195 virConnectPtr virStoragePoolGetConnect (virStoragePoolPtr pool); 196 197 /* Storage Pool capabilities */ 198 char *virConnectGetStoragePoolCapabilities(virConnectPtr conn, 199 unsigned int flags); 200 201 /* 202 * List active storage pools 203 */ 204 int virConnectNumOfStoragePools (virConnectPtr conn); 205 int virConnectListStoragePools (virConnectPtr conn, 206 char **const names, 207 int maxnames); 208 209 /* 210 * List inactive storage pools 211 */ 212 int virConnectNumOfDefinedStoragePools(virConnectPtr conn); 213 int virConnectListDefinedStoragePools(virConnectPtr conn, 214 char **const names, 215 int maxnames); 216 217 /* 218 * virConnectListAllStoragePoolsFlags: 219 * 220 * Flags used to tune pools returned by virConnectListAllStoragePools(). 221 * Note that these flags come in groups; if all bits from a group are 0, 222 * then that group is not used to filter results. 223 */ 224 typedef enum { 225 VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE = 1 << 0, 226 VIR_CONNECT_LIST_STORAGE_POOLS_ACTIVE = 1 << 1, 227 228 VIR_CONNECT_LIST_STORAGE_POOLS_PERSISTENT = 1 << 2, 229 VIR_CONNECT_LIST_STORAGE_POOLS_TRANSIENT = 1 << 3, 230 231 VIR_CONNECT_LIST_STORAGE_POOLS_AUTOSTART = 1 << 4, 232 VIR_CONNECT_LIST_STORAGE_POOLS_NO_AUTOSTART = 1 << 5, 233 234 /* List pools by type */ 235 VIR_CONNECT_LIST_STORAGE_POOLS_DIR = 1 << 6, 236 VIR_CONNECT_LIST_STORAGE_POOLS_FS = 1 << 7, 237 VIR_CONNECT_LIST_STORAGE_POOLS_NETFS = 1 << 8, 238 VIR_CONNECT_LIST_STORAGE_POOLS_LOGICAL = 1 << 9, 239 VIR_CONNECT_LIST_STORAGE_POOLS_DISK = 1 << 10, 240 VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI = 1 << 11, 241 VIR_CONNECT_LIST_STORAGE_POOLS_SCSI = 1 << 12, 242 VIR_CONNECT_LIST_STORAGE_POOLS_MPATH = 1 << 13, 243 VIR_CONNECT_LIST_STORAGE_POOLS_RBD = 1 << 14, 244 VIR_CONNECT_LIST_STORAGE_POOLS_SHEEPDOG = 1 << 15, 245 VIR_CONNECT_LIST_STORAGE_POOLS_GLUSTER = 1 << 16, 246 VIR_CONNECT_LIST_STORAGE_POOLS_ZFS = 1 << 17, 247 VIR_CONNECT_LIST_STORAGE_POOLS_VSTORAGE = 1 << 18, 248 VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI_DIRECT = 1 << 19, 249 } virConnectListAllStoragePoolsFlags; 250 251 int virConnectListAllStoragePools(virConnectPtr conn, 252 virStoragePoolPtr **pools, 253 unsigned int flags); 254 /* 255 * Query a host for storage pools of a particular type 256 */ 257 char * virConnectFindStoragePoolSources(virConnectPtr conn, 258 const char *type, 259 const char *srcSpec, 260 unsigned int flags); 261 262 /* 263 * Lookup pool by name or uuid 264 */ 265 virStoragePoolPtr virStoragePoolLookupByName (virConnectPtr conn, 266 const char *name); 267 virStoragePoolPtr virStoragePoolLookupByUUID (virConnectPtr conn, 268 const unsigned char *uuid); 269 virStoragePoolPtr virStoragePoolLookupByUUIDString(virConnectPtr conn, 270 const char *uuid); 271 virStoragePoolPtr virStoragePoolLookupByVolume (virStorageVolPtr vol); 272 virStoragePoolPtr virStoragePoolLookupByTargetPath(virConnectPtr conn, 273 const char *path); 274 275 typedef enum { 276 VIR_STORAGE_POOL_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema */ 277 } virStoragePoolDefineFlags; 278 279 /* 280 * Creating/destroying pools 281 */ 282 virStoragePoolPtr virStoragePoolCreateXML (virConnectPtr conn, 283 const char *xmlDesc, 284 unsigned int flags); 285 virStoragePoolPtr virStoragePoolDefineXML (virConnectPtr conn, 286 const char *xmlDesc, 287 unsigned int flags); 288 int virStoragePoolBuild (virStoragePoolPtr pool, 289 unsigned int flags); 290 int virStoragePoolUndefine (virStoragePoolPtr pool); 291 int virStoragePoolCreate (virStoragePoolPtr pool, 292 unsigned int flags); 293 int virStoragePoolDestroy (virStoragePoolPtr pool); 294 int virStoragePoolDelete (virStoragePoolPtr pool, 295 unsigned int flags); 296 int virStoragePoolRef (virStoragePoolPtr pool); 297 int virStoragePoolFree (virStoragePoolPtr pool); 298 int virStoragePoolRefresh (virStoragePoolPtr pool, 299 unsigned int flags); 300 301 /* 302 * StoragePool information 303 */ 304 const char* virStoragePoolGetName (virStoragePoolPtr pool); 305 int virStoragePoolGetUUID (virStoragePoolPtr pool, 306 unsigned char *uuid); 307 int virStoragePoolGetUUIDString (virStoragePoolPtr pool, 308 char *buf); 309 310 int virStoragePoolGetInfo (virStoragePoolPtr vol, 311 virStoragePoolInfoPtr info); 312 313 char * virStoragePoolGetXMLDesc (virStoragePoolPtr pool, 314 unsigned int flags); 315 316 int virStoragePoolGetAutostart (virStoragePoolPtr pool, 317 int *autostart); 318 int virStoragePoolSetAutostart (virStoragePoolPtr pool, 319 int autostart); 320 321 /* 322 * List/lookup storage volumes within a pool 323 */ 324 int virStoragePoolNumOfVolumes (virStoragePoolPtr pool); 325 int virStoragePoolListVolumes (virStoragePoolPtr pool, 326 char **const names, 327 int maxnames); 328 int virStoragePoolListAllVolumes (virStoragePoolPtr pool, 329 virStorageVolPtr **vols, 330 unsigned int flags); 331 332 virConnectPtr virStorageVolGetConnect (virStorageVolPtr vol); 333 334 /* 335 * Lookup volumes based on various attributes 336 */ 337 virStorageVolPtr virStorageVolLookupByName (virStoragePoolPtr pool, 338 const char *name); 339 virStorageVolPtr virStorageVolLookupByKey (virConnectPtr conn, 340 const char *key); 341 virStorageVolPtr virStorageVolLookupByPath (virConnectPtr conn, 342 const char *path); 343 344 345 const char* virStorageVolGetName (virStorageVolPtr vol); 346 const char* virStorageVolGetKey (virStorageVolPtr vol); 347 348 typedef enum { 349 VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA = 1 << 0, 350 VIR_STORAGE_VOL_CREATE_REFLINK = 1 << 1, /* perform a btrfs lightweight copy */ 351 } virStorageVolCreateFlags; 352 353 virStorageVolPtr virStorageVolCreateXML (virStoragePoolPtr pool, 354 const char *xmldesc, 355 unsigned int flags); 356 virStorageVolPtr virStorageVolCreateXMLFrom (virStoragePoolPtr pool, 357 const char *xmldesc, 358 virStorageVolPtr clonevol, 359 unsigned int flags); 360 361 typedef enum { 362 VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM = 1 << 0, /* Use sparse stream */ 363 } virStorageVolDownloadFlags; 364 365 int virStorageVolDownload (virStorageVolPtr vol, 366 virStreamPtr stream, 367 unsigned long long offset, 368 unsigned long long length, 369 unsigned int flags); 370 typedef enum { 371 VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM = 1 << 0, /* Use sparse stream */ 372 } virStorageVolUploadFlags; 373 374 int virStorageVolUpload (virStorageVolPtr vol, 375 virStreamPtr stream, 376 unsigned long long offset, 377 unsigned long long length, 378 unsigned int flags); 379 int virStorageVolDelete (virStorageVolPtr vol, 380 unsigned int flags); 381 int virStorageVolWipe (virStorageVolPtr vol, 382 unsigned int flags); 383 int virStorageVolWipePattern (virStorageVolPtr vol, 384 unsigned int algorithm, 385 unsigned int flags); 386 int virStorageVolRef (virStorageVolPtr vol); 387 int virStorageVolFree (virStorageVolPtr vol); 388 389 int virStorageVolGetInfo (virStorageVolPtr vol, 390 virStorageVolInfoPtr info); 391 int virStorageVolGetInfoFlags (virStorageVolPtr vol, 392 virStorageVolInfoPtr info, 393 unsigned int flags); 394 char * virStorageVolGetXMLDesc (virStorageVolPtr pool, 395 unsigned int flags); 396 397 char * virStorageVolGetPath (virStorageVolPtr vol); 398 399 typedef enum { 400 VIR_STORAGE_VOL_RESIZE_ALLOCATE = 1 << 0, /* force allocation of new size */ 401 VIR_STORAGE_VOL_RESIZE_DELTA = 1 << 1, /* size is relative to current */ 402 VIR_STORAGE_VOL_RESIZE_SHRINK = 1 << 2, /* allow decrease in capacity */ 403 } virStorageVolResizeFlags; 404 405 int virStorageVolResize (virStorageVolPtr vol, 406 unsigned long long capacity, 407 unsigned int flags); 408 409 int virStoragePoolIsActive(virStoragePoolPtr pool); 410 int virStoragePoolIsPersistent(virStoragePoolPtr pool); 411 412 /** 413 * VIR_STORAGE_POOL_EVENT_CALLBACK: 414 * 415 * Used to cast the event specific callback into the generic one 416 * for use for virConnectStoragePoolEventRegisterAny() 417 */ 418 # define VIR_STORAGE_POOL_EVENT_CALLBACK(cb)((virConnectStoragePoolEventGenericCallback)(cb)) 419 420 /** 421 * virStoragePoolEventID: 422 * 423 * An enumeration of supported eventId parameters for 424 * virConnectStoragePoolEventRegisterAny(). Each event id determines which 425 * signature of callback function will be used. 426 */ 427 typedef enum { 428 VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE = 0, /* virConnectStoragePoolEventLifecycleCallback */ 429 VIR_STORAGE_POOL_EVENT_ID_REFRESH = 1, /* virConnectStoragePoolEventGenericCallback */ 430 431 # ifdef VIR_ENUM_SENTINELS 432 VIR_STORAGE_POOL_EVENT_ID_LAST 433 /* 434 * NB: this enum value will increase over time as new events are 435 * added to the libvirt API. It reflects the last event ID supported 436 * by this version of the libvirt API. 437 */ 438 # endif 439 } virStoragePoolEventID; 440 441 /** 442 * virConnectStoragePoolEventGenericCallback: 443 * @conn: the connection pointer 444 * @pool: the pool pointer 445 * @opaque: application specified data 446 * 447 * A generic storage pool event callback handler, for use with 448 * virConnectStoragePoolEventRegisterAny(). Specific events usually 449 * have a customization with extra parameters, often with @opaque being 450 * passed in a different parameter position; use 451 * VIR_STORAGE_POOL_EVENT_CALLBACK() when registering an appropriate handler. 452 */ 453 typedef void (*virConnectStoragePoolEventGenericCallback)(virConnectPtr conn, 454 virStoragePoolPtr pool, 455 void *opaque); 456 457 /* Use VIR_STORAGE_POOL_EVENT_CALLBACK() to cast the 'cb' parameter */ 458 int virConnectStoragePoolEventRegisterAny(virConnectPtr conn, 459 virStoragePoolPtr pool, /* optional, to filter */ 460 int eventID, 461 virConnectStoragePoolEventGenericCallback cb, 462 void *opaque, 463 virFreeCallback freecb); 464 465 int virConnectStoragePoolEventDeregisterAny(virConnectPtr conn, 466 int callbackID); 467 468 /** 469 * virStoragePoolEventLifecycleType: 470 * 471 * a virStoragePoolEventLifecycleType is emitted during storage pool 472 * lifecycle events 473 */ 474 typedef enum { 475 VIR_STORAGE_POOL_EVENT_DEFINED = 0, 476 VIR_STORAGE_POOL_EVENT_UNDEFINED = 1, 477 VIR_STORAGE_POOL_EVENT_STARTED = 2, 478 VIR_STORAGE_POOL_EVENT_STOPPED = 3, 479 VIR_STORAGE_POOL_EVENT_CREATED = 4, 480 VIR_STORAGE_POOL_EVENT_DELETED = 5, 481 482 # ifdef VIR_ENUM_SENTINELS 483 VIR_STORAGE_POOL_EVENT_LAST 484 # endif 485 } virStoragePoolEventLifecycleType; 486 487 /** 488 * virConnectStoragePoolEventLifecycleCallback: 489 * @conn: connection object 490 * @pool: pool on which the event occurred 491 * @event: The specific virStoragePoolEventLifeCycleType which occurred 492 * @detail: contains some details on the reason of the event. 493 * @opaque: application specified data 494 * 495 * This callback is called when a pool lifecycle action is performed, like start 496 * or stop. 497 * 498 * The callback signature to use when registering for an event of type 499 * VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE with 500 * virConnectStoragePoolEventRegisterAny() 501 */ 502 typedef void (*virConnectStoragePoolEventLifecycleCallback)(virConnectPtr conn, 503 virStoragePoolPtr pool, 504 int event, 505 int detail, 506 void *opaque); 507 508 #endif /* LIBVIRT_STORAGE_H */ 509