Features/Network Interface Management

Network Interface Management

Summary

Provide tools to easily set up commonly used network configurations, like bridges, bonds, vlan's and sensible combinations thereof, in particular for virtualized hosts.

Owner

• Name: DavidLutterkort
• email: lutter@redhat.com

Current status

• Targeted release: Fedora 12
• Last updated: 2009-08-05
• Percentage of completion: 100%

Completed

• netcf library design
• Initial discussion on libvir-list on the XML format, API and implementation options.
• netcf library and ncftool command line tool
• Design of the libvirt API and virsh commands
• Implementation included in libvirt-0.7.0

Detailed Description

Configuring the network interfaces on a machine for moderately complicated yet common scenarios is generally only accessible to advanced users, and very poorly supported by existing tools. Such scenarios include creating a bridge and enslaving a physical NIC to it, or bonding two NIC's, adding a VLAN interface to the bond and enslaving that to a bridge.

Complicated bridge setups are commonly needed on virtualized hosts, and often have to be performed remotely by higher-level management tools, rather than a human user.

This feature addresses these needs by providing a general-purpose network configuration library (netcf) and additions to the libvirt API to expose netcf's local API through libvirt's remoting facilities.

With netcf, a logical network interface (e.g. a bridge and its slaves) is described as a unit, and netcf takes care of translating that description into the appropriate ifcfg-* files. To guarantee the happy coexistence of netcf with other network configuration utilities, including vi, netcf is bidirectional: it modifies ifcfg-* files based on a netcf interface description, but also reads ifcfg-* files to generate such a description. It is therefore possible to use netcf side-by-side with any other method of changing network configuration, and many of the pitfalls of earlier attempts to do this, e.g., the Xen networking scripts, are avoided.

It is planned to switch NetworkManager to netcf as the backend for system-wide network configuration in a future release; while it's not part of this feature, it will further unify the user experience around network configuration. In the same vein, it is planned to expose network configuration functionality in a future release of virt-manager

Benefit to Fedora

Configuring network interfaces, especially for virtualization, is considerably simplified; for example, the very common setup described in the libvirt documentation now boils down to running a couple of netcf commands or their libvirt equivalents.

Complex setups, like bonding physical NIC's and enslaving a VLAN of that bond in a bridge, which are so far considered expert uses, can now be easily performed by non-experts.

Remote management of network configuration is now possible out-of-the-box.

Scope

As described above, most of the feature is complete; still missing is some of the plumbing in libvirt to expose netcf through its API. That work is slated to land in the next libvirt release, planned in time for the Fedora 12 Feature Freeze.

How To Test

• Use a machine with at least one Ethernet NIC
• Install the netcf and/orlibvirt package
• Create a file describing an interface, for example

  cat > /tmp/bridge.xml <<EOF
<interface type="bridge" name="br0">
  <start mode="onboot"/>
  <mtu size="1500"/>
  <protocol family="ipv4">
    <dhcp/>
  </protocol>
  <bridge stp="off" delay="0.01">
    <interface type="ethernet" name="eth0">
      <mac address="ab:bb:cc:dd:ee:ff"/>
    </interface>
    <interface type="ethernet" name="eth1"/>
  </bridge>
</interface>
EOF

• Start ncftool

  ncftool> ifdown eth0    # Only needed if it is up
  ncftool> ifdown br0     # Only needed if it is up
  ncftool> define /tmp/bridge.xml
  ncftool> ifup br0
  ncftool> exit

• Inspect the ifcfg-* files and check network status with netstat, brctl and similar

• Modify /etc/sysconfig/network-scripts/ifcfg-br0 and change, e.g., DELAY to 7

• Start ncftool and issue the command dumpxml br0 and notice how the changed DELAY is reflected in the XML representation

Examples of more complex setups can be found in the netcf git repo

User Experience

See the previous two sections

Dependencies

Changes are confined to netcf and libvirt.

Contingency Plan

If the libvirt API work can not be finished in time for Fedora 12, users will have to use netcf directly, and lose the ability to remotely configure networking.

Documentation

• initial proposal and design discussion
• netcf public API
• netcf XML schema
• virInterface* functions in the libvirt API

Release Notes

Fedora 12 adds the ability to easily create complex network configurations, either directly through the new netcf library or through libvirt

Comments and Discussion

• See Talk:Features/Network_Interface_Management