[libvirt] RFC: configuring host interfaces with libvirt

[Daniel P. Berrange]

On Fri, Jan 16, 2009 at 01:13:18AM +0000, David Lutterkort wrote:
> 1. XML Format
> =============
> 
> The first question is how the user would describe the host interfaces they
> want. Below are some sketches of what an XML representation of the various
> kinds of interfaces would look like. This covers the minimal amount of
> settings for these to be useful, though I am sure we'll need to add more
> over time.
> 
> <interface device="eth0" onboot="yes">
>   <hwaddr>00:19:d2:9f:88:96</hwaddr>
>   <dhcp peerdns="yes"/>
> </interface>
> 
> <interface device="eth1" onboot="yes">
>   <hwaddr>00:19:d2:9f:88:97</hwaddr>
>   <static ipaddr="192.168.0.5" gateway="192.168.0.1" netmask="255.255.255.0"/>
> </interface>
> 
> <interface device="eth2" onboot="yes">
>   <hwaddr>00:19:d2:9f:88:98</hwaddr>
> </interface>
> 
> <bond name="bond00" onboot="yes" mode="active-backup">
>   <slave device="eth0" primary="yes"/>
>   <slave device="eth1"/>
> </bond>
> 
> <bridge name="br0" stp="off" onboot="yes">
>   <member device="eth2"/>
>   <dhcp peerdns="yes"/>
> </bridge>
> 
> <vlan device="eth0" tag="42" reorder_hdr="yes"/>

>From a style point of view I'd prefer these to all have the same
top level XML element name, and use type='phys|bond|vlan|bridge'
attribute for distinction, since this follows the pattern we use
in the XML for other objects we describe. Type speciic sub-elements
can be used where there are specific extra metadat pieces we need
for that type. Also prefer to see it follow the syntax 
used elsewhere for mac addresses, and finally agreed with te idea
that 'onboot' should actually be handled by the get/set-autostart
API, again to match the model used elsehwere in the APIs.

 <interface type='physical'>
   <name>eth0</name>
   <mac address='00:19:d2:9f:88:96'/>
   <dhcp peerdns="yes"/>
 </interface>

 <interface type='physical'
   <name>eth1</name>
   <mac address='00:19:d2:9f:88:97'/>
   <ip address="192.168.0.5" gateway="192.168.0.1" netmask="255.255.255.0"/>
 </interface>

 <interface type='physical'
   <name>eth2</name>
   <mac address='00:19:d2:9f:88:98'/>
 </interface>

 <interface type='bond'>
   <name>bond0</name>
   <bond mode='active-backup'>
     <interface name="eth0" primary="yes"/>
     <interface name="eth1"/>
   </bond>
 </bond>

 <interface type='bridge'>
   <name>br0</name>
   <bridge stp='off'>
     <interface name="eth2"/>
   </bridge>
   <dhcp peerdns="yes"/>
 </bridge>

 <interface type='vlan'>
    <name>vlan0</name>
    <vlan tag="42" reorder_hdr="yes">
      <interface name='eth0'>
    </vlan>
 </inteface>

> All of these should also allow a <uuid> element for specifying a uuid; I
> omitted that for brevity.
> 
> 2. API Changes
> ==============
> 
> There are two options for dealing with network interfaces: (1) use the
> existing virNetwork* calls or (2) add completely new API calls.
> 
> Repurposing existing virNetwork* calls
> --------------------------------------
> 
> The existing calls map well to the operations we need for managing
> interfaces, with a few exceptions:
> 
>   - virNetworkGetAutostart/SetAutostart: depending on how we implement all
>     this (see below), 'autostart' might actually mean 'on boot', not 'when
>     libvirtd starts'
>   - virNetworkGetBridgeName doesn't make sense for interfaces, and should
>     return NULL for interfaces
> 
> We'll probably also end up adding some functions to query details about an
> interface, in particular, a call to see what kind of network/interface a
> virNetworkPtr represents

I think the fact that the XML description of the devices is quite
different, and the underling impl will be quite different, suggests
that re-using existing APIs is not worthwhile.

> Add completely new virInterface* calls
> --------------------------------------
> 
> This would add roughly the same API calls as the virNetwork* calls,
> i.e. we'd have something like
> 
>   typedef struct virInterface *virInterfacePtr;
> 
>   int  virInterfaceCreate(virInterfacePtr);
>   virInterfacePtr virInterfaceCreateXML(..);
>   ...
> 
> plus some calls to extract information from a virInterfacePtr
> 
> The second option seems cleaner to me and easier to implement, and avoids
> any subtle changes in the behavior of existing API, though I don't like
> that we'll be adding another 20 or so calls to libvirt's public API, with
> attendant churn both in the drivers and in virsh.

I think the number of public API entry points is not worth
worrying about, since that's such a tiny part of the code
effort. Any saving from reusing the virNetwork API entry
points is dwarfed by the code to actually implemnent these
network capabilities internally. 

> 4. Misc issues
> ==============
> 
>   * Should interfaces have labels/roles ('data-interface') to help admins
>     make sense of the current config ?

Those are application defined semantics really, so I don't think
they need direct representation in libvirt. It would also entail
an extra look-aside config cache, because initscript / networkmanager
(or other backend impl) don't provide any means to store such
labels/roles.

>   * Do we expect interfaces to be in a specific state before we create them
>     or do we just tear them down and reconfigure them no matter what ?

I think we should expect the mgmt app to have put the device
in suitable state. eg, if you're creating a bridge containing
eth0, we should expect that the eth0 has been taken offline
already.

>   * Are there crucial config options that are not covered by the sketches
>     above (e.g., setting an explicit MTU) ? Are there things in the XML
>     sketches above that will be impossible to implement on some OS ?

There are almost certainly things we won't be able to implement for certain
backends. XenAPI's API does not allow for VLANs for example. The important
thing would be to provide a way to query what capabilities are curently
available. So akin to the host virt capabilities, we'd need network
API capabilities data.

Daniel
-- 
|: Red Hat, Engineering, London   -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org  -o-  http://virt-manager.org  -o-  http://ovirt.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-  F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|