Commit Graph

23 Commits

Author SHA1 Message Date
Michal Privoznik
70b67c98d9 libvirt-storage: Document volume upload/download stream format
For libvirt, the volume is just a binary blob and it doesn't
interpret data on volume upload/download. But as it turns out,
this unspoken assumption is not clear to our users. Document it
explicitly.

Suggested in: https://bugzilla.redhat.com/show_bug.cgi?id=1851023#c17

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
2020-08-24 13:32:53 +02:00
Daniel P. Berrangé
a9fa62f327 src: don't include ref count in debug messages / probes
The ref count will be private to the GObject base class
and we must not peek at it, even for debugging messages.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2020-06-03 10:20:17 +01:00
Erik Skultety
d6064e2759 libvirt-<module>: Check caller-provided buffers to be NULL with size > 0
Pre-Glib era which used malloc allowed the size of the client-side
buffers to be declared as 0, because malloc documents that it can either
return 0 or a unique pointer on 0 size allocations.
With glib this doesn't work anymore, because glib documents that for
such allocation requests NULL is always returned which results in an
error in our public API checks server-side.
This patch complements the fix in the RPC layer by explicitly erroring
out on the following combination of args used by our legacy APIs (their
moder equivalents don't suffer from this):

function(caller-allocated-array, size, ...) {
    if (!caller-allocated-array && size > 0)
        return error;
}

treating everything else as a valid input and potentially let that fail
on the server-side rather than client-side.

https://bugzilla.redhat.com/show_bug.cgi?id=1772842

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2019-11-21 18:16:35 +01:00
Han Han
3efdffc450 storage: Add iscsi-direct pool list type flag
Add pool list type flag VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI_DIRECT,
which was forgotten when introducing iscsi-direct pool at f0bf1be3.

https://bugzilla.redhat.com/show_bug.cgi?id=1726609

Signed-off-by: Han Han <hhan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2019-07-13 17:40:09 +02:00
Han Han
8462467cf7 storage: Add missing pool type flags in comment
Signed-off-by: Han Han <hhan@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
2019-07-13 17:39:06 +02:00
John Ferlan
6696155ae6 libvirt: Introduce virConnectGetStoragePoolCapabilities
Introduce the API to expose the storage pool capabilities along
with all the remote munglement required to hook up the client.

Signed-off-by: John Ferlan <jferlan@redhat.com>
ACKed-by: Michal Privoznik <mprivozn@redhat.com>
2019-03-06 11:12:48 -05:00
Dan Kenigsberg
d88a87d6c4 src: storage: Provide a better explanation of virStoragePoolSetAutostart
The former documentation was an unhelpful tautology. The suggested doc
borrows the wording from virDomainSetAutostart.

Signed-off-by: Dan Kenigsberg <danken@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
2018-08-22 09:46:10 +02:00
Michal Privoznik
4e42981b36 src: Unify virObject member name
Whenever we declare a new object the first member of the struct
has to be virObject (or any other member of that family). Now, up
until now we did not care about the name of the struct member.
But lets unify it so that we can do some checks at compile time
later.

The unified name is 'parent'.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
2018-04-18 10:04:55 +02:00
Daniel P. Berrangé
7aa0e8c0cb storage: export virStoragePoolLookupByTargetPath as a public API
The storagePoolLookupByTargetPath() method in the storage driver is used
by the QEMU driver during block migration. If there's a valid use case
for this in the QEMU driver, then external apps likely have similar
needs. Exposing it in the public API removes the direct dependancy from
the QEMU driver to the storage driver.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2018-02-09 11:05:10 +00:00
John Ferlan
2dd70901db storage: Resolve storage driver crash
Resolve a storage driver crash as a result of a long running
storageVolCreateXML when the virStorageVolPoolRefreshThread is
run as a result of when a storageVolUpload completed and ran the
virStoragePoolObjClearVols without checking if the creation
code was currently processing a buildVol after incrementing
the driver->asyncjob count.

The refreshThread will now check the pool asyncjob count before
attempting to pursue the pool refresh. Adjust the documentation
to describe the condition.

Crash from valgrind is as follows (with a bit of editing):

==21309== Invalid read of size 8
==21309==    at 0x153E47AF: storageBackendUpdateVolTargetInfo
==21309==    by 0x153E4C30: virStorageBackendUpdateVolInfo
==21309==    by 0x153E52DE: virStorageBackendVolRefreshLocal
==21309==    by 0x153DE29E: storageVolCreateXML
==21309==    by 0x562035B: virStorageVolCreateXML
==21309==    by 0x147366: remoteDispatchStorageVolCreateXML
...
==21309==  Address 0x2590a720 is 64 bytes inside a block of size 336 free'd
==21309==    at 0x4C2F2BB: free
==21309==    by 0x54CB9FA: virFree
==21309==    by 0x55BC800: virStorageVolDefFree
==21309==    by 0x55BF1D8: virStoragePoolObjClearVols
==21309==    by 0x153D967E: virStorageVolPoolRefreshThread
...
==21309==  Block was alloc'd at
==21309==    at 0x4C300A5: calloc
==21309==    by 0x54CB483: virAlloc
==21309==    by 0x55BDC1F: virStorageVolDefParseXML
==21309==    by 0x55BDC1F: virStorageVolDefParseNode
==21309==    by 0x55BE5A4: virStorageVolDefParse
==21309==    by 0x153DDFF1: storageVolCreateXML
==21309==    by 0x562035B: virStorageVolCreateXML
==21309==    by 0x147366: remoteDispatchStorageVolCreateXML
...
2017-11-16 11:34:26 -05:00
Daniel P. Berrange
32d6c7386d Print hex values with '0x' prefix and octal with '0' in debug messages
Seeing a log message saying 'flags=93' is ambiguous & confusing unless
you happen to know that libvirt always prints flags as hex.  Change our
debug messages so that they always add a '0x' prefix when printing flags,
and '0' prefix when printing mode. A few other misc places gain a '0x'
prefix in error messages too.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-09-25 13:34:53 +01:00
Daniel P. Berrange
10e277a432 Remove bogus warning about vir$OBJECTGetConnect functions
The API docs for the various vir$OBJECTGetConnect functions
contain a warning

  WARNING: When writing libvirt bindings in other languages, do
  not use this function.  Instead, store the connection and
  the domain object together.

There is no reason why language bindings should not use this
method, and indeed the Perl, Python, and Go bindings all use
these methods.

This warning was originally added back in

  commit 3edb4bc9fb
  Author: Daniel Veillard <veillard@redhat.com>
  Date:   Tue Jul 24 15:32:55 2007 +0000

    * libvirt.spec.in NEWS docs/* po/*: preparing release 0.3.1
    * src/libvirt.c python/generator.py: some cleanup and warnings
      from Richard W.M. Jones

IIUC, the rational was that these APIs do not need to be
directly exposed to the non-C language, as the language
can expose the same concept itself by storing the original
virConnectPtr object alongside the virDomainPtr.  There's
no reason to mandate such an approach though - it is valid
for languages to expose this directly if that suits their
needs better.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-08-07 13:39:28 +01:00
Michal Privoznik
1f43aa67c5 Introduce virStorageVol{Download,Upload}Flags
These flags to APIs will tell if caller wants to use sparse
stream for storage transfer. At the same time, it's safe to
enable them in storage driver frontend and rely on our backends
checking the flags. This way we can enable specific flags only on
some specific backends, e.g. enable
VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM for filesystem backend but
not iSCSI backend.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2017-05-18 07:42:13 +02:00
John Ferlan
0c234889c4 storage: Introduce virStorageVolInfoFlags
https://bugzilla.redhat.com/show_bug.cgi?id=1332019

This function will essentially be a wrapper to virStorageVolInfo in order
to provide a mechanism to have the "physical" size of the volume returned
instead of the "allocation" size. This will provide similar capabilities to
the virDomainBlockInfo which can return both allocation and physical of a
domain storage volume.

NB: Since we're reusing the _virStorageVolInfo and not creating a new
_virStorageVolInfoFlags structure, we'll need to generate the rpc APIs
remoteStorageVolGetInfoFlags and remoteDispatchStorageVolGetInfoFlags
(although both were originally created from gendispatch.pl and then
just copied into daemon/remote.c and src/remote/remote_driver.c).

The new API will allow the usage of a VIR_STORAGE_VOL_GET_PHYSICAL flag
and will make the decision to return the physical or allocation value
into the allocation field.

In order to get that physical value, virStorageBackendUpdateVolTargetInfoFD
adds logic to fill in physical value matching logic in qemuStorageLimitsRefresh
used by virDomainBlockInfo when the domain is inactive.

Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-12-20 13:52:39 -05:00
Martin Kletzander
fa4eea8063 storage: Document wiping formatted volume types
When wiping a volume we just rewrite all the data of the volume, not
only the content.  Since format gets overridden, we need to recreate the
volume.  However we can't do that for every possible format out there.
Since it was only coded for the ploop volume type, let's document what
might be the consequences instead of forbidding it for every other
format out there.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=868771

Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
2016-08-02 07:01:57 +02:00
Jovanka Gulicoska
1328f98224 Introduce storage lifecycle event APIs
Storage pool lifecycle event API entry points for registering and deregistering
storage pool events, as well as types of events associated with storage pools.
These entry points will be used for implementing asynchronous lifecycle events.

Storage pool API:
virConnectStoragePoolEventRegisterAny
virConnectStoragePoolEventDeregisterAny
virStoragePoolEventLifecycleType which has events STARTED, STOPPED, DEFINED,
UNDEFINED, and REFRESHED
2016-06-16 12:22:11 -04:00
Michal Privoznik
eec91958b4 virStorageVolWipe: Document that wiping journaled FS is useless
So you have a libvirt volume that you want to wipe out. But lets
say that the volume is actually a file stored on a journaled
filesystem. Overwriting it with zeroes or a pattern does not mean
that corresponding physical location on the disk is overwritten
too, due to journaling. It's the same story with network based
volumes, copy-on-write filesystems, and so on. Since there is no
way that an userland application can write onto specific areas on
disk, all that we can do is document the fact.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2015-12-24 18:02:58 +01:00
John Ferlan
7d792b99b8 libvirt: Add virStorageVolDeleteFlags to virStorageVolDelete
Although they've been present for quite a while, they weren't added
to the API definition, so add them there to make it clearer.

Currently only the RBD backend even checks for any flags.
2015-12-18 10:51:08 -05:00
John Ferlan
aeb1078ab5 storage: Add flags to allow building pool during create processing
https://bugzilla.redhat.com/show_bug.cgi?id=830056

Add flags handling to the virStoragePoolCreate and virStoragePoolCreateXML
API's which will allow the caller to provide the capability for the storage
pool create API's to also perform a pool build during creation rather than
requiring the additional buildPool step. This will allow transient pools
to be defined, built, and started.

The new flags are:

    * VIR_STORAGE_POOL_CREATE_WITH_BUILD
      Perform buildPool without any flags passed.

    * VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE
      Perform buildPool using VIR_STORAGE_POOL_BUILD_OVERWRITE flag.

    * VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE
      Perform buildPool using VIR_STORAGE_POOL_BUILD_NO_OVERWRITE flag.

It is up to the backend to handle the processing of build flags. The
overwrite and no-overwrite flags are mutually exclusive.

NB:
This patch is loosely based upon code originally authored by Osier
Yang that were not reviewed and pushed, see:

https://www.redhat.com/archives/libvir-list/2012-July/msg01328.html
2015-12-17 11:56:18 -05:00
Laine Stump
e983e62514 debug: assure NULLSTR() around all %s args in debug at top of public APIs
There are also a couple that were very uninformatively just logging
the value of the pointer rather than the string itself:

* the "name" arg to virNodeDeviceLookupByName()
* wwnn and wwpn args to virNodeDeviceLookupSCSIHostByWWN()

All char*'s that make sense should now have their contents logged
rather than the pointer, and all %s args should now be inside
NULLSTR().
2015-05-28 13:13:45 -04:00
Pavel Hrdina
03369d9643 pool-define: update and unify documentation
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=1127045

Signed-off-by: Pavel Hrdina <phrdina@redhat.com>
2015-03-09 14:47:53 +01:00
Martin Kletzander
138c2aee01 Remove unnecessary curly brackets in rest of src/[a-n]*/
Signed-off-by: Martin Kletzander <mkletzan@redhat.com>
2014-11-14 17:13:36 +01:00
Daniel P. Berrange
36b5d006c1 Move virStorage{Pool,Vol} related APIs out of libvirt.c
Introduce a src/libvirt-storage.c file to hold all the
methods related to the virStorage{Pool,Vol} types.
2014-10-24 16:49:10 +01:00