Porting NetCF to Debian/Ubuntu, Suse and Windows

The NetCF library provides a simple API for managing network interface configuration files. Libvirt has used NetCF for several releases now to provide the internal implementation of the virInterface APIs. This allows libvirt based applications to configure plain ethernet devices, bridging, bonding and VLANs, which covers all the network configurations required for a typical virtualization host. The problem is that nearly every single OS distro has a different format for its configuration files, and NetCF has only had an implementation that works with Fedora and RHEL. This has led to a perception that NetCF is a project that is “Red Hat specific”, which is not at all the intention when NetCF was created. To try to address this problem, I have spent the last couple of weeks hacking on a driver for NetCF that knows how to deal with the Debian /etc/network/interfaces file format. As of last night, I pushed the code into the upstream NetCF git repository, so Debian & Ubuntu users have something nice to try out in the next release. Indeed, it would be good if any interested persons were to try out the latest NetCF GIT code before the next release to make sure it works for someone other than myself :-)

In the course of porting to Debian, we also became aware that there was a port of NetCF to Suse distributions, found as a patch in the netcf RPM for OpenSuse 11. We have not had chance to test it ourselves yet, but on the assumption that it must have been at least partially functional when added to OpenSuse 11 RPMs, we have merged that patch into the latest NetCF GIT. If anyone is using Suse and wants to try it out and report what works & what doesn’t, we’d appreciate the feedback.  If someone wants to actually do further development work for the Suse driver to finish it off, that would be even better !

Finally, a few months ago, there was work on creating a Windows driver for NetCF. This was posted a few times to the NetCF mailing lists, but was never completed because the original submitter ran out of time to work on it. In the hope that it will be a useful starting point for other interested developers, we have also merged the most recent Windows patch into the NetCF GIT repository. This is by no means useful yet, only able to list interfaces and bring them up/down – it can’t report their config, or create new interfaces.

Supported Debian driver configurations

Back to the Debian driver now. The Debian /etc/network/interfaces configuration file is quite nicely structured and reasonably well documented, but one of the problems faced is that there is often more than one way to get to the same end result. To make the development of a Debian driver a tractable problem, I decided to pick one specific configuration approach for each desired network interface arrangement. So while NetCF should be able to read back any configuration that it wrote itself, it may not be able to correctly read arbitrary configurations that a user created manually. I expect that over time the driver will iteratively improve its configuration parsing to cope with other styles.

AFAICT, the Debian best practice for setting up vlans, bonding & bridging is to use the extra configuration syntax offered by certain add in packages, rather than custom post scripts. So for the NetCF Debian driver to work, it is necessary to have the following DPKGs installed:

  - ifenslave    (required for any bonding config)
  - bridge-utils (required for any bridging config)
  - vlan         (required for any vlan config)

Ethernet Devices

Loopback:

  auto lo
  iface lo inet loopback

DHCP:

  auto eth0
  iface eth0 inet dhcp

Static config:

  auto eth0
  iface eth0 inet static
     address 196.168.1.1
     netmask 255.255.255.0
     gateway 196.168.1.255

No IP config

  auto eth0
  iface eth0 inet manual

Config with MTU / MAC addres

  auto eth0
  iface eth0 inet dhcp
     hwaddr ether 00:11:22:33:44:55
     mtu 150

Bonding

With miimon

  iface bond0 inet dhcp
     bond_slaves eth1 eth2
     bond_primary eth1
     bond_mode active-backup
     bond_miimon 100
     bond_updelay 10
     bond_use_carrier 0

With arpmon

  iface bond2 inet dhcp
     bond_slaves eth6
     bond_primary eth6
     bond_mode active-backup
     bond_arp_interval 100
     bond_arp_ip_target 198.168.1.1

VLANs

  auto eth0.42
  iface eth0.42 inet static
     address 196.168.1.1
     netmask 255.255.255.0
     vlan_raw_device eth0

Bridging

With single interface and IP addr

  auto br0
  iface br0 inet static
     address 192.68.2.3
     netmask 255.255.255.0
     mtu 1500
     bridge_ports eth3
     bridge_stp off
     bridge_fd 0.01

With no IP addr

  auto br0
  iface br0 inet manual
     bridge_ports eth3
     bridge_stp off
     bridge_fd 0.01

With multiple interfaces

  auto br0
  iface br0 inet static
     address 192.68.2.3
     netmask 255.255.255.0
     mtu 1500
     bridge_ports eth3 eth4
     bridge_stp off
     bridge_fd 0.01

With no interface or addr

  auto br0
  iface br0 inet manual
     mtu 1500
     bridge_ports none
     bridge_stp off
     bridge_fd 0.01

Complex Bridging

Bridging a bond:

  auto br1
  iface br1 inet manual
     mtu 1500
     bridge_ports bond1
     bridge_stp off
     pre-up ifup bond1
     post-down ifdown bond1
  iface bond1 inet manual
     bond_slaves eth4
     bond_primary eth4
     bond_mode active-backup
     bond_miimon 100
     bond_updelay 10
     bond_use_carrier 0

Bridging a VLAN:

  auto br2
  iface br2 inet manual
     mtu 1500
     bridge_ports eth0.42
     bridge_stp off
  iface eth0.42 inet manual
     vlan_raw_device eth0

IPv6

Static addressing, with multiple addresses:

  auto eth5
  iface eth5 inet6 static
     address 3ffe:ffff:0:5::1
     netmask 128
     pre-up echo 0 > /proc/sys/net/ipv6/conf/eth5/autoconf
     post-down echo 1 > /proc/sys/net/ipv6/conf/eth5/autoconf
     up /sbin/ifconfig eth5 inet6 add 3ffe:ffff:0:5::5/128
     down /sbin/ifconfig eth5 inet6 del 3ffe:ffff:0:5::5/128

Stateless autoconf

  auto eth5
  iface eth5 inet6 manual

DHCPv6 with autoconf

  auto eth5
  iface eth5 inet6 dhcp

DHCPv6 without autoconf

  auto eth5
  iface eth5 inet6 dhcp
     pre-up echo 0 > /proc/sys/net/ipv6/conf/eth5/autoconf
     post-down echo 1 > /proc/sys/net/ipv6/conf/eth5/autoconf

The most recent set of example configurations can be found in the documentation in GIT.