1WICKED(7) Miscellaneous Information Manual WICKED(7)
2
6 wicked - network management service
7
9 #include <wicked/wicked.h>
10
12 Wicked provides a new, experimental framework for network configura‐
13 tion.
14 The idea is to replace much of the shell scripting that happens in
16 /sbin/ifup and the related init scripts with a combination of C code
17 that handles most of the basic interface configuration tasks, and a
18 powerful, extensible XML representation of the network configuration.
19 The major motivation in choosing XML was the ability to represent and
20 manipulate complex nested configurations.
21
23 At this time, Wicked does not provide a stable development API.
24
26 This implementation uses a DBus based server and a command line util‐
27 ity. If you're familiar with DBus terminology, you will recall that
28 the DBus concept revolves around "objects" that can have one or more
29 "interfaces" associated with them; pretty much like in any object ori‐
30 ented model. Since we're talking a lot about "network interfaces" in
31 this manual page and other documentation, I would like to avoid the
32 term "DBus interface" as much as possible, and refer to "DBus APIs"
33 instead.
34 The wicked server is called wickedd, and offers a variety of APIs to
36 manage network interfaces, to create and delete virtual interfaces,
37 etc. These APIs are structured in a layered fashion that matches the
38 different layers in the network stack. For instance, there is an Ether‐
39 net API for accessing the link-layer properties of an Ethernet API;
40 there is an API class that represents the properties of a generic ker‐
41 nel network device; and there are APIs for address configuration.
42 For every network interface in the system, the server creates an object
44 and attaches the appropriate DBus APIs to it. The DBus object path is
45 formed by concatenating /org/opensuse/Network/Interface with the inter‐
46 face index. This allows the object handle to be unaffected when the
47 interface is renamed.
48 In addition to the wickedd server itself, there are several auxiliary
50 services that handle various dynamic address configuration, and propel
51 interface bring-up. For instance, there are daemons to handle DHCP4,
52 DHCP6 and IPv4 link-layer autoconfiguration (aka ipv4ll, or IP zero‐
53 conf) as well as a wickedd-nanny daemon that communicates interface
54 configuration policies to wikcedd, thus driving interface bring-up. The
55 main goal for introducing wickedd-nanny is to handle use cases for
56 interface hotplugging and wireless roaming. The reason to create these
57 anew is to be able to integrate them more closely with wickedd.
58
60 Wicked strictly separates configuration files stored somewhere in the
61 system from the current configuration state maintained by the kernel
62 and closely related system daemons like pppd(8) or openvpn(8). The
63 server only knows about the latter, but does not parse any configura‐
64 tion files, and does not maintain any state besides what is actually in
65 effect. On the other hand, the client never probes the kernel directly
66 to obtain the current system state. The client's job is to parse the
67 configuration file(s) handed to it by the user, process and convert
68 them to policies, and hand them off to wickedd-nanny. wickedd-nanny
69 then performs device configuration when policy conditions have been
70 met.
71 Currently, the wicked client supports the original sysconfig ifcfg-
73 file format and converts the data found to it's native xml format.
74 Simple Ethernet Example (ifcfg-eth0)
76 STARTMODE="onboot" BOOTPROTO="dhcp4"
77 Resulting Ethernet Configuration in Native XML
79 In its simplest format, an interface description consists of little
80 more than an <interface> element specifying the interface name and the
81 requested address configuration:
82 <interface>
84 <name>eth0</name>
85 <control>
86 <mode>boot</mode>
87 </control>
88 <ipv4:dhcp>
90 <enabled>true</enabled>
91 </ipv4:dhcp>
92 </interface>
93 Just like DHCPv4, there are elements for other address configuration
95 modes as well, such as <ipv6:dhcp>, or <ipv4:static> — you get the
96 idea.
97 For further information on the file syntax, refer to wicked-config(5).
99
101 The wicked client utility supports a number of different activities,
102 but its most important job is probably to generate policies from con‐
103 figuration files and initiate bring up of network interfaces. This is
104 performed by calling wicked ifup, which takes a number of parameters to
105 select which interfaces to bring up, and how. If you want to learn
106 about the details, please refer to wicked(8).
107 For the sake of this discussion, let's assume we're asking wicked to
109 bring up a VLAN interface. After parsing the configuration file and
110 generating a suitable policy, the wicked will do several things in
111 preparation of bringing up the device:
112 * Build a hierarchy of devices depending on each other. In this
114 example, let's assume that the VLAN device depends on the under‐
115 lying interface eth0. In order to bring up the VLAN, the Ether‐
116 net interface must be brought up as well (at least in terms of
117 the link-layer).
118 * Pass the policies for the specified interfaces to wickedd-nanny
120 With these steps performed, wickedd-nanny will work its way through all
122 layers of network configuration to activate the devices.
123 Device creation
125 Since the VLAN interface is a virtual interface which does not
126 exist yet, it has to be created first. wickedd-nanny does this
127 by calling a device factory service for VLAN devices.
128 Link-layer configuration
130 Next, it will apply any link-layer configurations specified. For
131 Ethernet interfaces, this could include any ethtool settings, or
132 a change of the MAC address.
133 Network protocol selection
135 This step is used to change the per-device settings of IPv4 and
136 IPv6, such as packet forwarding. This steps also takes care of
137 disabling IPv6 on the device, if requested.
138 Firewall
140 This step will bring up the firewall.
141 Link layer configuration and authentication
143 These steps will take care of bringing up the link layer. In the
144 case of an Ethernet device, this will wait for the link layer
145 negotiation to complete. In the case of an authenticated link
146 layer, such as 802.11 WiFi or 802.1x Ethernet authentication,
147 care would be taken to perform the required authentication
148 steps.
149 In our example, wickedd-nanny directs wickedd to first bring up
151 eth0 and wait for its link layer negotiation to complete. The
152 configuration of the VLAN device is not allowed to proceed until
153 the subordinate device is up. Once that is the case, wickedd
154 would also bring up the VLAN device.
155 As we've reached the desired state for the eth0 device with this
157 step, no further action is taken.
158 Address Configuration
160 Finally, wickedd would configure addresses for all requested
161 modes. In the given example, it would just assign the given
162 static addresses. If we had also requested say DHCPv6, it would
163 start the DHCPv6 protocol on this device and wait for it to come
164 back with an address lease.
165 Note that in the wicked universe, address assignment should hap‐
167 pen through wickedd so that it can track which addresses are
168 active, and have been assigned through which protocol. This pre‐
169 vents different address configuration mechanisms to step on each
170 other's toes.
171
173 wickedd(8), wicked(8), wicked(7), wicked-config(5).
174
176 Copyright (C) 2014 SUSE LINUX Products GmbH, Nuernberg, Germany.
177
179 Please report bugs at <https://bugzilla.novell.com/index.cgi>
180
182 Olaf Kirch
183 16 July 2012 WICKED(7)