[libvirt] [PATCH 00/10] new virNetworkUpdate API

[Laine Stump]

This patchset implements a new API function called virNetworkUpdate
which enables updating certain parts of a libvirt network's definition
without the need to destroy/re-start the network. This is especially
useful, for example, to add/remove hosts from the dhcp static hosts
table, or change portgroup settings.

This was previously discussed in this thread:

 https://www.redhat.com/archives/libvir-list/2012-August/msg01535.html

continuing here in September:

 https://www.redhat.com/archives/libvir-list/2012-September/msg00328.html

with the final form here:

 https://www.redhat.com/archives/libvir-list/2012-September/msg00465.html

In short, the single function has a "section" specifier which tells
the part of the network definition to be updated, a "parentIndex" that
gives the index of the *parent* element containing this section (when
there are multiples - in particular in the case of the <ip> element),
and a fully formed XML element which will be added as-is in the case
of VIR_NETWORK_UPDATE_ADD_* (after checking for a duplicate), used to
search for the specific element to delete in case of
VIR_NETWORK_UPDATE_DELETE, and used both to find the existing element
and replace its current contents in the case of VIR_UPDATE_EXISTING
(this implies that you can't change the change the attribute used for
indexing, e.g. the name of a portgroup, or mac address of a dhcp host
entry).

An example of use: to add a dhcp host entry to network "net", you would do this:

   virNetworkUpdate(net, VIR_NETWORK_SECTION_IP_DHCP_HOST, -1,
                    "<host mac='00:11:22:33:44:55' ip='192.168.122.5'/>",
                    VIR_NETWORK_UPDATE_AFFECT_LIVE
                    | VIR_NETWORK_UPDATE_AFFECT_CONFIG
                    | VIR_NETWORK_UPDATE_ADD_LAST);

To delete that same entry:

   virNetworkUpdate(net, VIR_NETWORK_SECTION_IP_DHCP_HOST, -1,
                    "<host mac='00:11:22:33:44:55'/>",
                    VIR_NETWORK_UPDATE_AFFECT_LIVE
                    | VIR_NETWORK_UPDATE_AFFECT_CONFIG
                    | VIR_NETWORK_UPDATE_DELETE);

If you wanted to force any of these to affect the dhcp host list in
the 3rd <ip> element of the network, you would replace "-1" with "2".

Another example: to modify the portgroup named "engineering" (e.g. to
increase the inbound average bandwidth from 1000 to 2000):

    virNetworkUpdate(net, VIR_NETWORK_SECTION_PORTGROUP, -1,
                     "<portgroup name='engineering' default='yes'>"
                     "  <virtualport type='802.1Qbh'>"
                     "    <parameters profileid='test'/>"
                     "  </virtualport>"
                     "  <bandwidth>"
                     "    <inbound average='2000' peak='5000' burst='5120'/>"
                     "    <outbound average='1000' peak='5000' burst='5120'/>"
                     "  </bandwidth>"
                     "</portgroup>",
                     VIR_NETWORK_UPDATE_EXISTING | VIR_NETWORK_UPDATE_LIVE
                     | VIR_NETWORK_UPDATE_CONFIG)

(note that parentIndex is irrelevant for PORTGROUP, since they are in
the toplevel of <network>, so there aren't multiple instances of
parents. In such cases, the caller *must* set parentIndex to -1 or 0 -
any other value indicates that they don't understand the purpose/usage
of parentIndex, so it must result in an error. Also note that the
above function would fail if it couldn't find an existing portgroup
with name='engineering' (i.e. it wouldn't automatically add a new one).)

Adding support for each of the different sections has been reduced to
a single function that handles the update of a virNetworkDef; all the
logic to determine which virNetworkDef (def or newDef) and to
restart/SIGHUP the appropriate daemons is in higher levels and is 100%
complete. The low level functions aren't yet finished, although the
function for IP_DHCP_HOST is nearly done.

As usual, several of the patches are re-factoring existing code, and a
couple are bugfixes that are only peripherally related:

1/10 - splits out parsing of dhcp related elements to separate functions
2/10 - fixes a small bug that would probably never be encountered IRL anyway
3/10+4/10 - actual API
5/10 - utility functions to simplify API implementation
6/10 - framework for backend that updates the virNetworkDef
7/10 - refactoring in bridge_driver
8/10 - virNetworkUpdate for bridge_driver
9/10 - virNetworkUpdate for test_driver
10/10 - simple troubleshooting aid - restart dnsmasq/radvd
        when libvirtd is restarted (if its process is missing).

I'll try to have the following additional patches posted later today:

11/10 - backend for IP_DHCP_HOST update
12/10 - backend for PORTGROUP update
13/10 - virsh "net-update" command

Differences from email thread:

1) Aside from being actual code instead of just pseudo code, I've
changed the "index" arg into "parentIndex" to avoid confusion between
the index of the element we're looking at (e.g. which host in the list
of hosts in a <dhcp> element) and the index of the parent (e.g. which
<ip> element will contain the <dhcp> with the list of <hosts> we want
to update).

I also changed this from a unsigned into to an int so that it can hold
the special value "-1", which means "pick the most useful/only
item". Again, in the case of VIR_NETWORK_SECTION_IP_DHCP_HOST, this
would mean to pick the one <ip> element that actually has a <dhcp>
section (may not be the first, but there can only be one).

2) added VIR_NETWORK_UPDATE_AFFECT_CURRENT similar to
   VIR_DOMAIN_AFFECT_CURRENT