wicked - Man Page

#include <wicked/wicked.h>

Wicked provides a new, experimental framework for network configuration.

The idea is to replace much of the shell scripting that happens in /sbin/ifup and the related init scripts with a combination of C code that handles most of the basic interface configuration tasks, and a powerful, extensible XML representation of the network configuration. The major motivation in choosing XML was the ability to represent and manipulate complex nested configurations.

At this time, Wicked does not provide a stable development API.

This implementation uses a DBus based server and a command line utility. If you're familiar with DBus terminology, you will recall that the DBus concept revolves around "objects" that can have one or more "interfaces" associated with them; pretty much like in any object oriented model. Since we're talking a lot about "network interfaces" in this manual page and other documentation, I would like to avoid the term "DBus interface" as much as possible, and refer to "DBus APIs" instead.

The wicked server is called wickedd, and offers a variety of APIs to manage network interfaces, to create and delete virtual interfaces, etc. These APIs are structured in a layered fashion that matches the different layers in the network stack. For instance, there is an Ethernet API for accessing the link-layer properties of an Ethernet API; there is an API class that represents the properties of a generic kernel network device; and there are APIs for address configuration.

For every network interface in the system, the server creates an object and attaches the appropriate DBus APIs to it. The DBus object path is formed by concatenating /org/opensuse/Network/Interface with the interface index. This allows the object handle to be unaffected when the interface is renamed.

In addition to the wickedd server itself, there are several auxiliary services that handle various dynamic address configuration, and propel interface bring-up. For instance, there are daemons to handle DHCP4, DHCP6 and IPv4 link-layer autoconfiguration (aka ipv4ll, or IP zeroconf) as well as a wickedd-nanny daemon that communicates interface configuration policies to wikcedd, thus driving interface bring-up. The main goal for introducing wickedd-nanny is to handle use cases for interface hotplugging and wireless roaming. The reason to create these anew is to be able to integrate them more closely with wickedd.

Wicked strictly separates configuration files stored somewhere in the system from the current configuration state maintained by the kernel and closely related system daemons like pppd(8) or openvpn(8). The server only knows about the latter, but does not parse any configuration files, and does not maintain any state besides what is actually in effect. On the other hand, the client never probes the kernel directly to obtain the current system state. The client's job is to parse the configuration file(s) handed to it by the user, process and convert them to policies, and hand them off to wickedd-nanny. wickedd-nanny then performs device configuration when policy conditions have been met.

Currently, the wicked client supports the original sysconfig ifcfg- file format and converts the data found to it's native xml format.

 <interface>
   <name>eth0</name>
   <control>
    <mode>boot</mode>
   </control>

   <ipv4:dhcp>
     <enabled>true</enabled>
   </ipv4:dhcp>
 </interface>

The wicked client utility supports a number of different activities, but its most important job is probably to generate policies from configuration files and initiate bring up of network interfaces. This is performed by calling wicked ifup, which takes a number of parameters to select which interfaces to bring up, and how. If you want to learn about the details, please refer to wicked(8).

For the sake of this discussion, let's assume we're asking wicked to bring up a VLAN interface. After parsing the configuration file and generating a suitable policy, the wicked will do several things in preparation of bringing up the device:

*

Build a hierarchy of devices depending on each other. In this example, let's assume that the VLAN device depends on the underlying interface eth0. In order to bring up the VLAN, the Ethernet interface must be brought up as well (at least in terms of the link-layer).

*

Pass the policies for the specified interfaces to wickedd-nanny

With these steps performed, wickedd-nanny will work its way through all

layers of network configuration to activate the devices.

Device creation

Since the VLAN interface is a virtual interface which does not exist yet, it has to be created first. wickedd-nanny does this by calling a device factory service for VLAN devices.

Link-layer configuration

Next, it will apply any link-layer configurations specified. For Ethernet interfaces, this could include any ethtool settings, or a change of the MAC address.

Network protocol selection

This step is used to change the per-device settings of IPv4 and IPv6, such as packet forwarding. This steps also takes care of disabling IPv6 on the device, if requested.

Firewall

This step will bring up the firewall.

Link layer configuration and authentication

These steps will take care of bringing up the link layer. In the case of an Ethernet device, this will wait for the link layer negotiation to complete.  In the case of an authenticated link layer, such as 802.11 WiFi or 802.1x Ethernet authentication, care would be taken to perform the required authentication steps.

In our example, wickedd-nanny directs wickedd to first bring up eth0 and wait for its link layer negotiation to complete. The configuration of the VLAN device is not allowed to proceed until the subordinate device is up. Once that is the case, wickedd would also bring up the VLAN device.

As we've reached the desired state for the eth0 device with this step, no further action is taken.

Address Configuration

Finally, wickedd would configure addresses for all requested modes. In the given example, it would just assign the given static addresses. If we had also requested say DHCPv6, it would start the DHCPv6 protocol on this device and wait for it to come back with an address lease.

Note that in the wicked universe, address assignment should happen through wickedd so that it can track which addresses are active, and have been assigned through which protocol. This prevents different address configuration mechanisms to step on each other's toes.

wickedd(8), wicked(8), wicked(7), wicked-config(5).

Copyright (C) 2014 SUSE LINUX Products GmbH, Nuernberg, Germany.

Please report bugs at <https://bugzilla.novell.com/index.cgi>

Olaf Kirch