We document that calling any public API wipes out all prior
libvirt errors in the same thread; but weren't obeying this
style in a few functions.

There are a couple of nested uses of virConnectRef (in lxc
and qemu reboot paths), but they should not be affected by
this change in semantics since there should not be any
previous error getting nuked (a later patch will clean up
the nested calls, along with abuse of virConnectClose on
cleanup paths which DOES nuke errors).

* src/libvirt.c (virGetVersion, virConnectRef, virDomainRef)
(virDomainGetSecurityLabel, virDomainGetSecurityLabelList)
(virDomainSetMetadata, virDomainGetMetadata)
(virNodeGetSecurityModel, virNetworkRef, virInterfaceRef)
(virStoragePoolRef, virStorageVolRef, virNodeDeviceGetName)
(virNodeDeviceRef, virSecretRef, virStreamRef, virNWFilterRef)
(virDomainSnapshotRef): Reset error on entrance.
(do_open): Drop redundant error reset.
* src/libvirt-qemu.c (virDomainQemuAgentCommand): Likewise.
* src/libvirt-lxc.c (virDomainLxcEnterNamespace)
(virDomainLxcEnterSecurityLabel): Likewise.
Signed-off-by: NEric Blake <eblake@redhat.com>

While auditing error messages in libvirt.c, I found a couple
instances that had not been converted to modern error styles,
and a few places that failed to dispatch the error through
the known-good connection.

* src/libvirt.c (virDomainPinEmulator, virDomainGetDiskErrors)
(virDomainSendKey, virDomainGetSecurityLabelList)
(virDomainGetEmulatorPinInfo): Use typical error reporting.
(virConnectGetCPUModelNames, virConnectRegisterCloseCallback)
(virConnectUnregisterCloseCallback, virDomainGetUUID): Report
error through connection.
Signed-off-by: NEric Blake <eblake@redhat.com>

Style only.  In particular, the message on "flags 'affect live'
and 'affect config'" being mutually exclusive was already split
in some instances.

* src/libvirt.c: Wrap some long error messages to fit in 80 columns.
Signed-off-by: NEric Blake <eblake@redhat.com>

Most of our public APIs emit a debug log on entry, prior to anything
else.  There were a few exceptions where obvious failures were not
logged, so fix those.  When moving a debug earlier, this patch also
makes sure to avoid any NULL dereference during the log (the APIs
are supposed to gracefully fail if the user passes NULL for the object).

However, do NOT use VIR_DEBUG prior to virInitialize, since setting
up the error reporting can change where VIR_DEBUG output would be
routed.  Instead add documentation to virGlobalInit, virInitialize,
and virGetVersion that better explains initialization.

* src/libvirt.c (virGetVersion, virConnectRef, virDomainRef)
(virNetworkRef, virInterfaceRef, virStoragePoolRef)
(virStorageVolRef, virNodeDeviceRef, virSecretRef, virStreamRef)
(virNWFilterRef, virDomainSnapshotRef): Debug on function entry.
* src/libvirt-lxc.c (virDomainLxcEnterNamespace)
(virDomainLxcEnterSecurityLabel): Likewise.
Signed-off-by: NEric Blake <eblake@redhat.com>

I noticed that the virDomainQemuMonitorCommand debug output wasn't
telling me the name of the domain it was working on.  While it was
easy enough to determine which pointer matches the domain based on
other log messages, it is nicer to be consistent.

* src/util/viruuid.h (VIR_UUID_DEBUG): Moved here from...
* src/libvirt.c (VIR_UUID_DEBUG): ...here.
(VIR_ARG15, VIR_HAS_COMMA, VIR_DOMAIN_DEBUG_EXPAND)
(VIR_DOMAIN_DEBUG_PASTE, VIR_DOMAIN_DEBUG_0, VIR_DOMAIN_DEBUG_1)
(VIR_DOMAIN_DEBUG_2, VIR_DOMAIN_DEBUG): Move...
* src/datatypes.h: ...here.
* src/libvirt-qemu.c (virDomainQemuMonitorCommand)
(virDomainQemuAgentCommand): Better debug messages.
* src/libvirt-lxc.c (virDomainLxcOpenNamespace): Likewise.
Signed-off-by: NEric Blake <eblake@redhat.com>

Preliminary cleanups to make search-and-replace easier in later
patches.  Many of these were done by grepping for (multiline)
pattern violations, then bundled all into one patch.

* src/libvirt.c: Uniform two spaces between functions, return
type and open brace on separate line, avoid blank lines around
open brace, label in column 1, drop redundant (), consistent
indentation for function headers split across lines.
Signed-off-by: NEric Blake <eblake@redhat.com>

Since libvirt 0.9.3, the entire virevent.c file has been a public
API, so improve the documentation in this file.  Also, fix a
potential core dump - it could only be triggered by bogus use of
the API and would only affect the caller (not libvirtd), but we
might as well be nice.

* src/libvirt.c (virConnectSetKeepAlive)
(virConnectDomainEventRegister, virConnectDomainEventRegisterAny)
(virConnectNetworkEventRegisterAny): Document event loop requirement.
* src/util/virevent.c (virEventAddHandle, virEventRemoveHandle)
(virEventAddTimeout, virEventRemoveTimeout): Likewise.
(virEventUpdateHandle, virEventUpdateTimeout): Likewise, and avoid
core dump if caller didn't register handler.
(virEventRunDefaultImpl): Expand example, and set up code block in
html docs.
(virEventRegisterImpl, virEventRegisterDefaultImpl): Document more
on the use of the event loop.
Signed-off-by: NEric Blake <eblake@redhat.com>

Commit eb70ceba tried to create a code block for
libvirt-libvirt.html#virConnectGetType, but failed to note
that our doc generator treats everything after "Returns" as
part of the return description rather than looking for
paragraph and code layout.  Fix some other API that also had
generic details crammed into the return type paragraph.

* src/libvirt.c (virConnectOpen, virConnectOpenReadOnly)
(virConnectOpenAuth, virConnectListAllDomains): Fit doc pattern.
Signed-off-by: NEric Blake <eblake@redhat.com>

Similar to commit 52dbeac8, we should indent code snippets in
other places to ensure they appear correctly in html.  See
http://libvirt.org/html/libvirt-libvirt.html#virNodeGetCPUStats
for an example improved by this patch.  Also fix some missing
semicolons in the examples.

* src/libvirt.c: Indent code samples in comments.
Signed-off-by: NEric Blake <eblake@redhat.com>

While looking at event code, I noticed that the documentation was
trying to refer me to functions that don't exist.  Also fix some
typos and poor formatting.

* src/libvirt.c (virConnectDomainEventDeregister)
(virConnectDomainEventRegisterAny)
(virConnectDomainEventDeregisterAny)
(virConnectNetworkEventRegisterAny)
(virConnectNetworkEventDeregisterAny): Link to correct function.
* include/libvirt.h.in (VIR_DOMAIN_EVENT_CALLBACK)
(VIR_NETWORK_EVENT_CALLBACK): Likewise.
(virDomainEventID, virConnectDomainEventGenericCallback)
(virNetworkEventID, virConnectNetworkEventGenericCallback):
Improve docs.
Signed-off-by: NEric Blake <eblake@redhat.com>

Recent changes to events (commit 8a29ffcf) resulted in new compile
failures on some targets (such as ARM OMAP5):
conf/domain_event.c: In function 'virDomainEventDispatchDefaultFunc':
conf/domain_event.c:1198:30: error: cast increases required alignment of
target type [-Werror=cast-align]
conf/domain_event.c:1314:34: error: cast increases required alignment of
target type [-Werror=cast-align]
cc1: all warnings being treated as errors

The error is due to alignment; the base class is merely aligned
to the worst of 'int' and 'void*', while the child class must
be aligned to a 'long long'.  The solution is to include a
'long long' (and for good measure, a function pointer) in the
base class to ensure correct alignment regardless of what a
child class may add, but to wrap the inclusion in a union so
as to not incur any wasted space.  On a typical x86_64 platform,
the base class remains 16 bytes; on i686, the base class remains
12 bytes; and on the impacted ARM platform, the base class grows
from 12 bytes to 16 bytes due to the increase of alignment from
4 to 8 bytes.

Reported by Michele Paolino and others.

* src/util/virobject.h (_virObject): Use a union to ensure that
subclasses never have stricter alignment than the parent.
* src/util/virobject.c (virObjectNew, virObjectUnref)
(virObjectRef): Adjust clients.
* src/libvirt.c (virConnectRef, virDomainRef, virNetworkRef)
(virInterfaceRef, virStoragePoolRef, virStorageVolRef)
(virNodeDeviceRef, virSecretRef, virStreamRef, virNWFilterRef)
(virDomainSnapshotRef): Likewise.
* src/qemu/qemu_monitor.c (qemuMonitorOpenInternal)
(qemuMonitorClose): Likewise.
Signed-off-by: NEric Blake <eblake@redhat.com>

Define the public API for (de-)registering network events
and the callbacks for receiving lifecycle events. The lifecycle
event includes a 'detail' parameter to match the domain lifecycle
event data, but this is currently unused.

The network events related code goes into its own set of internal
files src/conf/network_event.[ch]

Delete the extra article 'the'.
Signed-off-by: NWang Yufei <james.wangyufei@huawei.com>
Signed-off-by: NEric Blake <eblake@redhat.com>

Though trying to destroy a physical HBA doesn't make sense at all,
it's still a bit misleading with saying "only works for HBA".
Signed-off-by: NOsier Yang <jyang@redhat.com>

The virDomainGetBlockJobInfo method did not zero out the
virDomainBlockJobInfo pointer arg, so when block jobs were
not active it would return garbage for the bandwidth/cur/end
fields.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

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

If a domain is rebooting and a migrate API is called meanwhile we would
have to transfer the fakeReboot attribute to the destination in order to
prevent domain doing plain shutdown over there. We shouldn't try to do
anything clever about it other than documenting this as a known
limitation.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>

delete extra character 'p' from the comment of virInterfaceCreate
Signed-off-by: NWang Yufei <james.wangyufei@huawei.com>

The connection pointer in the closeCallback data was never
initialized, making the unref in remoteClientCloseFunc a no-op.

This fixes the following leak in virsh when the daemon closes
the connection unexpectedly:

1,179 (288 direct, 891 indirect) bytes in 1 blocks are
   definitely lost in loss record 745 of 792
  at 0x4C2A6D0: calloc (in vgpreload_memcheck-amd64-linux.so)
  by 0x4E9643D: virAllocVar (viralloc.c:558)
  by 0x4ED2425: virObjectNew (virobject.c:190)
  by 0x4F675AC: virGetConnect (datatypes.c:116)
  by 0x4F6EA06: do_open (libvirt.c:1136)
  by 0x4F71017: virConnectOpenAuth (libvirt.c:1481)
  by 0x129FFA: vshReconnect (virsh.c:337)
  by 0x128310: main (virsh.c:2470)

Noticed while revieweing the patches for qemu's new migration state.

* include/libvirt/libvirt.h.in (_virDomainJobInfo): Fix typo,
grammar.
* src/libvirt.c (virDomainGetJobInfo): Add cross reference.
Signed-off-by: NEric Blake <eblake@redhat.com>

In virDomainRestoreFlags with VIR_DOMAIN_SAVE_BYPASS_CACHE, it risks
slowing restores from NFS, but not saves to NFS.
Signed-off-by: NWang Yufei <james.wangyufei@huawei.com>

By indenting code inside of comments, it gets recognized as a
code block when generating the HTML documentation.

See libvirt-libvirt.html#virStreamSend for the effect.

Avoid people introducing security flaws in their apps by
forbidding the use of libvirt.so in setuid programs, with
a check in virInitialize.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

Most of the usage of getuid()/getgid() is in cases where we are
considering what privileges we have. As such the code should be
using the effective IDs, not real IDs.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

We don't know enough about quality of external libraries used
for non-UNIX transports, nor do we want to spawn external
commands when setuid. Restrict to the bare minimum which is
UNIX transport for local usage. Users shouldn't need to be
running setuid if connecting to remote hypervisors in any
case.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

Unconditional use of getenv is not secure in setuid env.
While not all libvirt code runs in a setuid env (since
much of it only exists inside libvirtd) this is not always
clear to developers. So make all the code paranoid, even
if it only ever runs inside libvirtd.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

The libvirt.so library has far too many library deps to allow
linking against it from setuid programs. Those libraries can
do stuff in __attribute__((constructor) functions which is
not setuid safe.

The virt-login-shell needs to link directly against individual
files that it uses, with all library deps turned off except
for libxml2 and libselinux.

Create a libvirt-setuid-rpc-client.la library which is linked
to by virt-login-shell. A config-post.h file allows this library
to disable all external deps except libselinux and libxml2.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

The virConnectDomainXMLToNative API should require 'connect:write'
not 'connect:read', since it will trigger execution of the QEMU
binaries listed in the XML.

Also make virConnectDomainXMLFromNative API require a full
read-write connection and 'connect:write' permission. Although the
current impl doesn't trigger execution of QEMU, we should not
rely on that impl detail from an API permissioning POV.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

The new function virConnectGetCPUModelNames allows to retrieve the list
of CPU models known by the hypervisor for a specific architecture.
Signed-off-by: NGiuseppe Scrivano <gscrivan@redhat.com>
Signed-off-by: NEric Blake <eblake@redhat.com>

virDomainSetMetadata when operating on the metadata element was
requesting the @key argument to be passed even if @metadata was NULL
used to delete the corresponding metadata element. This is not needed as
the key is only used when adding the element and matching is done via
the XML namespace.

An off-list bug report mentioned some confusion where the public
documentation of libvirt.c:virConnectGetHostname did not match
the private documentation of util/virutil.c:virGetHostname.

* src/libvirt.c (virConnectGetHostname): Tweak docs.
Signed-off-by: NEric Blake <eblake@redhat.com>

This fixes the description of virConnectGetType() API function in
API documentation to match the real functionality that it can be
used to get driver name, and provide a hint on how to learn about
full capabilities.
Signed-off-by: NMichal Novotny <minovotn@redhat.com>
Signed-off-by: NEric Blake <eblake@redhat.com>

Signed-off-by: NOskari Saarenmaa <os@ohmu.fi>
Signed-off-by: NEric Blake <eblake@redhat.com>

Currently the virConnectBaselineCPU API does not expose the CPU features
that are part of the CPU's model.  This patch adds a new flag,
VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES, that causes the API to explicitly
list all features that are part of that model.
Signed-off-by: NDon Dugger <donald.d.dugger@intel.com>
Signed-off-by: NEric Blake <eblake@redhat.com>

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

Newer gnutls uses nettle, rather than gcrypt, which is a lot nicer
regarding initialization.  Yet we were unconditionally initializing
gcrypt even when gnutls wouldn't be using it, and having two crypto
libraries linked into libvirt.so is pointless, but mostly harmless
(it doesn't crash, but does interfere with certification efforts).

There are three distinct version ranges to worry about when
determining which crypto lib gnutls uses, per these gnutls mails:
2.12: http://lists.gnu.org/archive/html/gnutls-devel/2011-03/msg00034.html
3.0: http://lists.gnu.org/archive/html/gnutls-devel/2011-07/msg00035.html

If pkg-config can prove version numbers and/or list the crypto
library used for static linking, we have our proof; if not, it
is safer (even if pointless) to continue to use gcrypt ourselves.

* configure.ac (WITH_GNUTLS): Probe whether to add -lgcrypt, and
define a witness WITH_GNUTLS_GCRYPT.
* src/libvirt.c (virTLSMutexInit, virTLSMutexDestroy)
(virTLSMutexLock, virTLSMutexUnlock, virTLSThreadImpl)
(virGlobalInit): Honor the witness.
* libvirt.spec.in (BuildRequires): Make gcrypt usage conditional,
no longer needed in Fedora 19.
Signed-off-by: NEric Blake <eblake@redhat.com>

Separation allows for dependent drivers to be make a connection during
the AutoStart phase of state initialization.

The description seems to be copied from virNodeGetCpuState.
Change wrong 'cpu' to 'memory'.
Signed-off-by: NPhilipp Hahn <hahn@univention.de>

With container based virt, it is useful to be able to pass
pre-opened file descriptors to the container init process.
This allows for containers to be auto-activated from incoming
socket connections, passing the active socket into the container.

To do this, introduce a pair of new APIs, virDomainCreateXMLWithFiles
and virDomainCreateWithFiles, which accept an array of file
descriptors. For the LXC driver, UNIX file descriptor passing
will be used to send them to libvirtd, which will them pass
them down to libvirt_lxc, which will then pass them to the container
init process.

This will only be implemented for LXC right now, but the design
is generic enough it could work with other hypervisors, hence
I suggest adding this to libvirt.so, rather than libvirt-lxc.so
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

Add new API in order to set the balloon memory driver statistics collection
period in order to allow dynamic period adjustment for the virsh dommemstats to
display balloon stats data