Presenting wicked network configuration

This tool and library provides a new framework for network configuration.

One of the bigger problems with network interface management today, and with the ifup scripts in general, is that different layers of network management get jumbled together into one single script, or at most two different scripts, that interact with each other in a not-really-well-defined way, with side effects that are difficult to be aware of, obscure constraints and conventions, etc. Several layers of special hacks for a variety of different scenarios cover them like barnacles. Address configuration protocols are being used that are implemented via daemons like dhcpcd, which interact rather poorly with the rest of the infrastructure. Funky interface naming schemes that require heavy udev support are introduced to achieve persistent identification of interfaces.

In other words, a maintenance nightmare.

The idea of wicked is to decompose the problem in several ways. None of them is entirely novel, but trying to put ideas from different other projects together is hopefully going to create a better solution overall.

One approach is to use a client/server model. This allows wicked to define standardized facilities for things like address configuration that are well integrated with the overall framework. For instance, with address configuration, the admin may request that an interface should be configured via dhcp or ipv4 zeroconf, and all the respective addrconf service does is obtain the lease from its server, and pass it on to the wicked server process, which installs the requested addresses and routes.

The other approach to decomposing the problem is to enforce the layering aspect. For any type of network interface, it is possible to define a dbus service that configures the network interface's device layer - be it a vlan, a bridge, a bond, or an paravirtualized NIC. Common functionality, such as address configuration, is implemented by joint services that are layered on top of these device specific services, without having to implement them specifically.

The wicked framework implements these two aspects by using a variety of dbus services, which get attached to a network interface depending on its type.

To illustrate this point, here's a rough overview of the current object hierarchy in wicked.

Each network interface is represented via a child object of /org/opensuse/Network/Interfaces. The name of the child object is given by its ifindex, so e.g. the loopback interface, which usually gets ifindex 1, is /org/opensuse/Network/Interfaces/1, the first ethernet interface registered is /org/opensuse/Network/Interfaces/2, etc.

Each network interface has a "class" associated with it, which is used to select the dbus interfaces it supports. By default, each network interface is of class "netif", and wickedd will automatically attach all interfaces compatible with this class. In the current implementation, this includes the following interfaces

org.opensuse.Network.Interface Generic network interface functions, such as taking the link up or down, assigning an MTU, etc.

org.opensuse.Network.Addrconf.ipv4.dhcp org.opensuse.Network.Addrconf.ipv6.dhcp org.opensuse.Network.Addrconf.ipv4.auto org.opensuse.Network.Addrconf.ipv6.auto Address configuration services for DHCP, ipv6 autoconf, ipv4 zeroconf, etc.

Beyond this, network interfaces may require/offer special configuration mechanisms. For instance, for an Ethernet device, you may want to be able to control the link speed, offloading of checksumming, etc. To achieve this, ethernet devices have a class of their own, called netif-ethernet, which is a subclass of netif. As a consequence, the dbus interfaces assigned to an ethernet interface include all the services listed above, plus org.opensuse.Network.Ethernet, which is a service available only to objects belonging to the netif-ethernet class.

Similarly, there exist classes for interface types like bridges, vlans, bonds, or infiniband.

Obviously, this begs the question, how do you interact with an interface that needs to be created first - such as a VLAN, which is really a virtual network interface that sits on top of an ethernet device.

For these, wicked defines factory interfaces, such as org.opensuse.Network.VLAN.Factory. Such a factory interface offers a single function that lets you create an interface of the requested type. These factory interfaces are attached to the /org/opensuse/Network/Interfaces list node.

Frequently Asked Questions

We have a FAQ section hosted in our GitHub's wiki, be sure to check that out for common questions about usage or Wicked in general:

    https://github.com/openSUSE/wicked/wiki/FAQ

For any questions not answered on the FAQ, please read our section below: "Where to discuss or report bugs"

What's currently supported

wicked currently supports

• configuration file backends to parse SUSE style /etc/sysconfig/network files.

• an internal configuration backend to represent network interface configuration in XML. The syntax evolved out of what netcf uses.

• bring-up and shutdown of "normal" network interfaces such as Ethernet, Infiniband etc, as well as VLAN, bridges, bonds, tun, tap, dummy, macvlan, macvtap, hsi, qeth, iucv and wireless (currently limited to one wpa-psk/eap network) devices.

• A built-in DHCPv4 client

• A built-in DHCPv6 client

• The nanny daemon (if enabled) helps to automatically bring up configured interfaces as soon as the device is available (interface hotplugging) and set up IP configuration when a link (carrier) is detected.

Where to get the sources/binaries

The git source repository is hosted at:

https://github.com/openSUSE/wicked

Binary packages are build in the openSUSE build service in the network:wicked project tree and can be found via:

http://software.opensuse.org/package/wicked

The actual git master is built in the network:wicked:master project automatically.

To build wicked from sources, try following commands:

zypper in git-core rpm-build gcc make pkg-config \
    autoconf automake libtool systemd-devel \
    libnl3-devel dbus-1-devel libgcrypt-devel \
    pandoc
git clone https://github.com/openSUSE/wicked.git
cd wicked
./autogen.sh
make rpmbuild

and then install the RPMs.

Where to discuss or report bugs

Please take a look at:

http://bugs.opensuse.org

where you can find links to bugzilla and user forums.

There are currently two mailing lists:

wicked-devel@opensuse.org

for discussions about development and

wicked-commit@opensuse.org

to monitor git repository commits.

GitHub offers also an issue tracker, where you can discuss pull requests and report git master issues, which are not yet in openSUSE:Factory or any repository for released products.

What you can do

Enable wicked using:

    systemctl enable --force wicked

This enables the wicked services, creates the network.service -> wicked.service alias link and causes to start the network at the next boot.

To manually start the server process (again, as root), use:

    systemctl start wickedd.service

which starts wickedd (main server) and associated supplicants:

/usr/lib/wicked/bin/wickedd-auto4 --systemd --foreground
/usr/lib/wicked/bin/wickedd-dhcp4 --systemd --foreground
/usr/lib/wicked/bin/wickedd-dhcp6 --systemd --foreground
/usr/sbin/wickedd --systemd --foreground
/usr/sbin/wickedd-nanny --systemd --foreground

You may then bring up the network using:

    systemctl start wicked.service

also using the network.service alias:

    systemctl start network.service

These commands are using default/system configuration sources as defined in the /etc/wicked/client.xml file.

To enable debugging, you can currently set the WICKED_DEBUG variable in /etc/sysconfig/network/config file, e.g. WICKED_DEBUG="all" or to omit some, WICKED_DEBUG="all,-dbus,-objectmodel,-xpath,-xml" before the wickedd service is started.

Showing interface status

You can use the client utility to display interface information (xml):

    wicked show-xml all
    wicked show-xml <ifname>

Bringing up one interface

You can set up single interfaces, too. The easiest way is to call:

    wicked ifup eth0
    wicked ifup wlan0
    ...

since there is no configuration source specified, wicked client checks its default sources of configuration defined in /etc/wicked/client.xml that is:

    1) firmware:    ibft firmware
    2) compat:      ifcfg files - implemented for compatibility

whatever it gets from those sources for a given interface is applied. The intended order of importance is firmware > compat. But this may be changed in the future.

Please refer to the wicked(8) manpage for details.

Bringing up multiple interfaces

For bonds and bridges, it may make sense to define the entire device topology in one file (ifcfg-bondX), and bring it up in one go.

For these, you simply define the device topology in one file, and tell wicked to bring up the whole configuration by specifying the top level interface names (of the bridge or bond):

wicked ifup br0

which automatically sets up the bridge and its dependencies in the appropriate order without a need to list the dependencies (ports, ...) separately.

You can also bring up multiple interfaces in one call:

wicked ifup bond0 br0 br1 br2

or also all interfaces:

wicked ifup all

As an example, take a look at samples/suse/host5/ directory. This configuration defines an Ethernet Bridge (ifcfg-bridge42) with a Dummy port (ifcfg-dummy42).

Assuming you copy the files to standard ifcfg config directory (that is to /etc/sysconfig/network/), simply call:

wicked ifup bridge42

and the client will create and bring up the dummy42 first, create the bridge and add the dummy interface as a port to the bridge.

For testing purposes, you can even use the --ifconfig parameter:

wicked ifup --ifconfig compat:samples/suse/host5 bridge42

which will bring up the bridge using the config files directly from the sample directory, but please note: --ifconfig parameter list disables (overrides) the default configuration search path and all following commands like "wicked ifstatus" have to use the same --ifconfig parameter list.

Handling incremental changes

With wicked, there is no need to actually take down an interface to reconfigure it (unless it's required by the kernel). For instance, in order to add another IP address or route to a statically configured network interface, simply add it to the interface definition, and do another "ifup" operation. The server will try hard to update only those settings that changed. This applies to link-level options such as the device mtu or the MAC address, as well as network level settings, such as addresses, routes, or even address configuration mode (when moving from a static configuration to, say, DHCP).

Things get tricky of course with virtual interfaces combining several real devices, like bridges or bonds. For bonded devices, it's not possible to change certain parameters while the device is up. Doing that will result in an error.

However, what should still work, is the act of adding or removing the child devices of a bond or bridge, or choosing a bond's primary interface.

Wicked extensions - address configuration

It's not useful to require support for all interface types to be coded in C. Languages like C are useful when you want to do slightly complex things, but for many mundane tasks of system configuration, using shell scripts is still the most natural thing to do.

For that reason, wicked is designed to be extensible via shell scripts. These extensions can be defined in the config.xml file.

Currently, several diffent classes of extensions are supported:

• link configuration: these are scripts responsible for setting up a device's link layer according to the configuration provided by the client, and for tearing it down again.

• address configruation: these are scripts responsible for managing a device's address configuration. Usually address configuration and DHCP are managed by wicked itself, but can be implemented via extensions.

• firewall extension: these scripts can apply firewall rules

Typically, extensions have a start and a stop command, an optional "pid file", and a set of environment variables that get passed to the script.

To illustrate how this is supposed to work, let's look at how a firewall extension is defined in etc/server.xml:

The extension is attached to dbus-service interface and defines commands to execute for the actions of this interface. Further, the declaration can define and initialize environment variables passed to the actions.

Wicked extensions - configuration files

You can extend the handling of configuration files with scripts as well. For example, DNS updates from leases are ultimately handled by the extensions/resolver script, with behavior configured in server.xml:

    <system-updater name="resolver">
      <action name="backup" command="/etc/wicked/extensions/resolver backup"/>
      <action name="restore" command="/etc/wicked/extensions/resolver restore"/>
      <action name="install" command="/etc/wicked/extensions/resolver install"/>
      <action name="remove" command="/etc/wicked/extensions/resolver remove"/>
    </system-updater>

When an update arrives in wickedd, the system updater routines parse the lease and call the appropriate commands (ie. backup, install, etc) in the resolver script. This in turn configures the DNS settings using /sbin/netconfig (if it exists on the system), or by manually writing /etc/resolv.conf as a fallback.

Future wickedness

In the future, it may be useful to extend what wicked supports beyond the configuration of network interfaces itself.

A Note on the name

Only after I started to show my code to a bunch of people, I found out that there's a project called WICD, which aims to provide... a network connection manager :-)

To make this absolutely plain, wicked is in no way related to WICD, for good or bad. It's just coincidence.