The first two flags are essential for being able to replicate
snapshot hierarchies across multiple hosts, which will come in
handy for supervised migrations.  It also allows a management app
to take a snapshot of a transient domain, save the metadata, stop
the domain, recreate a new transient domain by the same name,
redefine the snapshot, then revert to it.

This is not quite as convenient as leaving the metadata behind
after a domain is no longer around, but doing that has a few
problems: 1. the libvirt API can only delete snapshot metadata
if there is a valid domain handle to use to get to that snapshot
object - if stale data is left behind without a domain, there is
no way to request that the data be cleaned up. 2. creating a new
domain with the same name but different uuid than the older
domain where a snapshot existed cannot use the older snapshot
data; this risks confusing libvirt, and forbidding the stale
data is similar to the recent patch to forbid stale managed save.

The first two flags might be useful on hypervisors with no metadata,
but only for modifying the notion of the current snapshot;
however, I don't know how to do that for ESX or VBox.

The third flag is a convenience option, to combine a creation with
a delete metadata into one step.  It is trivial for hypervisors
with no metadata.

The qemu changes will be involved enough to warrant a separate patch.

* include/libvirt/libvirt.h.in
(VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE)
(VIR_DOMAIN_SNAPSHOT_CREATE_CURRENT)
(VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA): New flags.
* src/libvirt.c (virDomainSnapshotCreateXML): Document them, and
enforce mutual exclusion.
* src/esx/esx_driver.c (esxDomainSnapshotCreateXML): Trivial
implementation.
* src/vbox/vbox_tmpl.c (vboxDomainSnapshotCreateXML): Likewise.
* docs/formatsnapshot.html.in: Document re-creation.

- create a new "redirdev" element for this purpose

So that devices can be attached to hubs. Example, to attach to first
port of a usb-hub on port 1.

      <hub type='usb'>
         <address type='usb' bus='0' port='1'/>
      </hub>

      <input type='mouse' type='usb'>
         <address type='usb' bus='0' port='1.1'/>
      </hub>

also add a test entry

domain parsing and serialization code, qemu driver backend and
a couple of test

Companion controllers take an extra 'master' attribute to associate
them.

Also add tests for this

Expand the domain and the QEmu driver code
Adds a couple of tests

The model by default is piix3-uchi.

Example:
<controller type='usb' index='0' model='ich9-ehci'/>

List is: piix3-uhci piix4-uhci ehci ich9-ehci1 ich9-uhci1 ich9-uhci2
ich9-uhci3 vt82c686b-uhci pci-ohci

Newer QEMU introduced cache=directsync for -drive, this patchset
is to expose it in libvirt layer.

  * Introduced a new QEMU capability flag ($prefix_CACHE_DIRECTSYNC),
    As even $prefix_CACHE_V2 is set, we can't known if directsync
    is supported.

Includes impl of python binding since the generator was not
able to cope.

Note: Requires gendispatch.pl patch from Matthias Bolte

https://www.redhat.com/archives/libvir-list/2011-August/msg01367.html

* docs/drvqemu.html.in: Fix typo.
* src/libvirt.c (virDomainCreateXML, virDomainCreateWithFlags):
Likewise.

Audit all changes to the qemu vm->current_snapshot, and make them
update the saved xml file for both the previous and the new
snapshot, so that there is always at most one snapshot with
<active>1</active> in the xml, and that snapshot is used as the
current snapshot even across libvirtd restarts.

This patch does not fix the case of virDomainSnapshotDelete(,CHILDREN)
where one of the children is the current snapshot; that will be later.

* src/conf/domain_conf.h (_virDomainSnapshotDef): Alter member
type and name.
* src/conf/domain_conf.c (virDomainSnapshotDefParseString)
(virDomainSnapshotDefFormat): Update clients.
* docs/schemas/domainsnapshot.rng: Tighten rng.
* src/qemu/qemu_driver.c (qemuDomainSnapshotLoad): Reload current
snapshot.
(qemuDomainSnapshotCreateXML, qemuDomainRevertToSnapshot)
(qemuDomainSnapshotDiscard): Track current snapshot.

In some versions of qemu, both virtio-blk-pci and virtio-net-pci
devices can have an event_idx setting that determines some details of
event processing. When it is enabled, it "reduces the number of
interrupts and exits for the guest". qemu will automatically enable
this feature when it is available, but there may be cases where this
new feature could actually make performance worse (NB: no such case
has been found so far).

As a safety switch in case such a situation is encountered in the
field, this patch adds a new attribute "event_idx" to the <driver>
element of both disk and interface devices. event_idx can be set to
"on" (to force event_idx on in case qemu has it disabled by default)
or "off" (for force event_idx off). In the case that event_idx support
isn't present in qemu, the attribute is ignored (this on the advice of
the qemu developer).

docs/formatdomain.html.in: document the new flag (marking it as
   "don't mess with this!"
docs/schemas/domain.rng: add event_idx in appropriate places
src/conf/domain_conf.[ch]: add event_idx to parser and formatter
src/libvirt_private.syms: export
   virDomainVirtioEventIdx(From|To)String
src/qemu/qemu_capabilities.[ch]: detect and report event_idx in
   disk/net
src/qemu/qemu_command.c: add event_idx parameter to qemu commandline
    when appropriate.
tests/qemuxml2argvdata/qemuxml2argv-event_idx.args,
tests/qemuxml2argvdata/qemuxml2argv-event_idx.xml,
tests/qemuxml2argvtest.c,
tests/qemuxml2xmltest.c: test cases for event_idx.

Currently only tabs and blanks are used for tokenizing the description,
which breaks when a term is at the end of a line or has () appended to
it.
1. Use also other white space characters such as new-lines and carriage
   return for splitting.
2. Remove some common non-word characters from the token before lookup.
Signed-off-by: NPhilipp Hahn <hahn@univention.de>

* remote.html.in: Remove obsolete notes about internals of the
  RPC protocol
* internals/rpc.html.in: Extensive docs on RPC protocol/API
* sitemap.html.in: Add new page

When the description of an entry is too long and needs multiple lines,
all other table cells of the same row are currently vertically aligned
on center. Without row borders or different background colors for
alternating rows this is hard to read.

Change the style-sheet to align the table cells of a row on top.
Signed-off-by: NPhilipp Hahn <hahn@univention.de>

Someone in an IRC channel or an email pointed out a few days ago that
the examples of IPv6 addresses in the libvirt documentation were not
in the officially reserved "documentation" range. This addresses their
concern.

This should have been done with the rest of the patch for virtual
switch / network device abstraction. If documents the new elements
(and new usage of existing elements) in the <network> XML to support
libvirt networks that use existing host bridges and macvtap direct
connections, as well as the new <portgroup> element.

* configure.ac docs/news.html.in libvirt.spec.in: updates for new
  release
* po/*.po*: pulled translations from the transifex teams and regenerated
  localizations

I went with the shorter license notice used by src/libvirt.c,
rather than spelling out the full LGPLv2+ clause into each of
these files.

* configure.ac: Declare copyright.
* all Makefile.am: Likewise.

Once it's plugged in, the <listen> element will be an optional
replacement for the "listen" attribute that graphics elements already
have. If the <listen> element is type='address', it will have an
attribute called 'address' which will contain an IP address or dns
name that the guest's display server should listen on. If, however,
type='network', the <listen> element should have an attribute called
'network' that will be set to the name of a network configuration to
get the IP address from.

* docs/schemas/domain.rng: updated to allow the <listen> element

* docs/formatdomain.html.in: document the <listen> element and its
  attributes.

* src/conf/domain_conf.[hc]:

  1) The domain parser, formatter, and data structure are modified to
     support 0 or more <listen> subelements to each <graphics>
     element. The old style "legacy" listen attribute is also still
     accepted, and will be stored internally just as if it were a
     separate <listen> element. On output (i.e. format), the address
     attribute of the first <listen> element of type 'address' will be
     duplicated in the legacy "listen" attribute of the <graphic>
     element.

  2) The "listenAddr" attribute has been removed from the unions in
     virDomainGRaphicsDef for graphics types vnc, rdp, and spice.
     This attribute is now in the <listen> subelement (aka
     virDomainGraphicsListenDef)

  3) Helper functions were written to provide simple access
     (both Get and Set) to the listen elements and their attributes.

* src/libvirt_private.syms: export the listen helper functions

* src/qemu/qemu_command.c, src/qemu/qemu_hotplug.c,
  src/qemu/qemu_migration.c, src/vbox/vbox_tmpl.c,
  src/vmx/vmx.c, src/xenxs/xen_sxpr.c, src/xenxs/xen_xm.c

  Modify all these files to use the listen helper functions rather
  than directly referencing the (now missing) listenAddr
  attribute. There can be multiple <listen> elements to a single
  <graphics>, but the drivers all currently only support one, so all
  replacements of direct access with a helper function indicate index
  "0".

* tests/* - only 3 of these are new files added explicitly to test the
  new <listen> element. All the others have been modified to reflect
  the fact that any legacy "listen" attributes passed in to the domain
  parse will be saved in a <listen> element (i.e. one of the
  virDomainGraphicsListenDefs), and during the domain format function,
  both the <listen> element as well as the legacy attributes will be
  output.

Every DomainNetDef has a bandwidth, as does every portgroup.
Whenever a DomainNetDef of type NETWORK is about to be used, a call is
made to networkAllocateActualDevice(). This function chooses the "best"
bandwidth object and places it in the DomainActualNetDef.
From that point on, whenever some code needs to use the bandwidth data
for the interface, it's retrieved with virDomainNetGetActualBandwidth(),
which will always return the "best" info as determined in the
previous step.

We had a bit too many elements crammed in there. Separate it into different
headings:

- CPU Allocation (<vcpus>)
- CPU Tuning (<cputune>)
- Memory allocation (<memory> and <currentMemory>)
- Memory backing (<memoryBacking>)
- Memory tuning (<memtune>)
- Numa tuning (<numatune>)
- Block I/O tuning (<blkiotune>)

Define new 'bandwidth' element with possible child element 'inbound'
and 'outbound' addressing incoming and outgoing traffic respectively:

<bandwidth>
  <inbound average='1000' peak='2000' burst='5120'/>
  <outbound average='500'/>
</bandwidth>

Leaving any element out means not to shape traffic in that
direction.
The units for average and peak (rate) are in kilobytes per second,
for burst (size) are just in kilobytes.
This element can be inserted into domain's 'interface' and
'network'.

New optional parameter "keyfile" for ssh transport allows the user to select
the private key to be used to authenticate to the remote host.

Set up the types for the block pull functions and insert them into the
virDriver structure definition.  Symbols are exported in this patch to
prevent
documentation compile failures.

* include/libvirt/libvirt.h.in: new API
* src/driver.h: add the new entry to the driver structure
* python/generator.py: fix compiler errors, the actual python bindings
* are
  implemented later
* src/libvirt_public.syms: export symbols
* docs/apibuild.py: Extend 'unsigned long' parameter exception to this
* API

The network XML is updated in the following ways:

1) The <forward> element can now contain a list of forward interfaces:

     <forward .... >
       <interface dev='eth10'/>
       <interface dev='eth11'/>
       <interface dev='eth12'/>
       <interface dev='eth13'/>
     </forward>

   The first of these takes the place of the dev attribute that is
   normally in <forward> - when defining a network you can specify
   either one, and on output both will be present. If you specify
   both on input, they must match.

2) In addition to forward modes of 'nat' and 'route', these new modes
   are supported:

     private, passthrough, vepa - when this network is referenced by a
     domain's interface, it will have the same effect as if the
     interface had been defined as type='direct', e.g.:

        <interface type='direct'>
          <source mode='${mode}' dev='${dev}>
          ...
        </interface>

     where ${mode} is one of the three new modes, and ${dev} is an interface
     selected from the list given in <forward>.

     bridge - if a <forward> dev (or multiple devs) is defined, and
     forward mode is 'bridge' this is just like the modes 'private',
     'passthrough', and 'vepa' above. If there is no forward dev
     specified but a bridge name is given (e.g. "<bridge
     name='br0'/>"), then guest interfaces using this network will use
     libvirt's "host bridge" mode, equivalent to this:

       <interface type='bridge'>
          <source bridge='${bridge-name}'/>
          ...
       </interface>

3) A network can have multiple <portgroup> elements, which may be
   selected by the guest interface definition (by adding
   "portgroup='${name}'" in the <source> element along with the
   network name). Currently a portgroup can only contain a
   virtportprofile, but the intent is that other configuration items
   may be put there int the future (e.g. bandwidth config). When
   building a guest's interface, if the <interface> XML itself has no
   virtportprofile, and if the requested network has a portgroup with
   a name matching the name given in the <interface> (or if one of the
   network's portgroups is marked with the "default='yes'" attribute),
   the virtportprofile from that portgroup will be used by the
   interface.

4) A network can have a virtportprofile defined at the top level,
   which will be used by a guest interface when connecting in one of
   the 'direct' modes if the guest interface XML itself hasn't
   specified any virtportprofile, and if there are also no matching
   portgroups on the network.

the domain XML <interface> element is updated in the following ways:

1) <virtualportprofile> can be specified when source type='network'
(previously it was only valid for source type='direct')

2) A new attribute "portgroup" has been added to the <source>
element. When source type='network' (the only time portgroup is
recognized), extra configuration information will be taken from the
<portgroup> element of the given name in the network definition.

3) Each virDomainNetDef now also potentially has a
virDomainActualNetDef which is a private object (never
exported/imported via the public API, and not defined in the RNG) that
is used to maintain information about the physical device that was
actually used for a NetDef of type VIR_DOMAIN_NET_TYPE_NETWORK.

The virDomainActualNetDef will only be parsed/formatted if the
parse/format function is called with the
VIR_DOMAIN_XML_INTERNAL_ACTUAL_NET flag set (which is only needed when
saving/loading a running domain's state info to the stateDir).

virtPortProfiles are currently only used in the domain XML, but will
soon also be used in the network XML. To prepare for that change, this
patch moves the structure definition into util/network.h and the parse
and format functions into util/network.c (I decided that this was a
better choice than macvtap.h/c for something that needed to always be
available on all platforms).

In preparation for a future patch adding new virFile APIs.

* src/util/files.h, src/util/files.c: Move...
* src/util/virfile.h, src/util/virfile.c: ...here, and rename
functions to virFile prefix.  Macro names are intentionally
left alone.
* *.c: All '#include "files.h"' uses changed.
* src/Makefile.am (UTIL_SOURCES): Reflect rename.
* cfg.mk (exclude_file_name_regexp--sc_prohibit_close): Likewise.
* src/libvirt_private.syms: Likewise.
* docs/hacking.html.in: Likewise.
* HACKING: Regenerate.

We have added element period and quota. Document them in formatdomain.html.in.

Define the element cputune's child elements 'period' and 'quota':
<cputune>
  <period>100000</period>
  <quota>50000</quota>
</cputune>

Commit 8665f855 introduced a slight regression in doc generation,
since make only quits a rule on the first failed command ending
with a newline rather than a semicolon.

* docs/Makefile.am (html/index.html): Don't use xmllint unless
xsltproc succeeded.
* .gitignore: Ignore recently updated stamp file name.

The current API build scripts will continue and exit with a zero
status even if they find problems. This has been the cause of many
build problems, or hidden build errors, in the past. Change the
scripts so they always exit with a non-zero status for any problems
they do not understand. Also turn off all debug output by default
so they respect $(AM_V_GEN)

* docs/Makefile.am: Use $(AM_V_GEN) for API/HTML scripts
* docs/apibuild.py, python/generator.py: Exit with non-zero status
  if problems are found. Also be silent, not outputting any debug
  messages.
* src/Makefile.am: Use $(AM_V_GEN) for ESX generator
* python/Makefile.am: Tweak rule

We missed ending tag for paragraph element

The "libvirt supports:" section on the main page of libvirt.org
contains a list of hypervisors with links that point to the sites of
the underlying virt technologies.  The entry for KVM points to
http://www.linux-kvm.org/, for example.  People coming to libvirt.org
for the first time are likely to know about those sites, and they're
probably interested in how libvirt manages those technologies.  This
patch points those links to the libvirt driver pages instead.  It also
consolidates KVM and QEMU as there is only one libvirt driver page for
them.  Finally, it adds a line about networking support.

v2: incorporate Eric's feedback adding project links to driver pages.

website: Add project links to KVM/QEMU driver page
website: Add project links to Xen driver page
website: Add project links to LXC driver page
website: Add project links to OpenVZ driver page
website: Add project links to UML driver page
website: Add project links to Virtualbox driver page
website: Add project links to ESX driver page
website: Add project links to VMware driver page

Our XML prefers "shareable" over "sharable".

* docs/internals/locking.html.in: s/sharable/shareable/
* src/locking/lock_driver_sanlock.c
(virLockManagerSanlockAddResource): Likewise.

* docs/apps.html.in: Add EMOTIVE.
Reported by Alex Vaqué Brull <memfis@gmail.com>.
Signed-off-by: NEric Blake <eblake@redhat.com>

When using virCommandRunAsync and saving the pid for later, it
is useful to be able to reap that pid in the same way that it
would have been auto-reaped by virCommand if we had passed
NULL for the pid argument in the first place.

* src/util/command.c (virPidWait, virPidAbort): New functions,
created from...
(virCommandWait, virCommandAbort): ...bodies of these.
(includes): Drop duplicate <stdlib.h>.  Ensure that our pid_t
assumptions hold.
(virCommandRunAsync): Improve documentation.
* src/util/command.h (virPidWait, virPidAbort): New prototypes.
* src/libvirt_private.syms: Export them.
* docs/internals/command.html.in: Document them.