1WICKED(7)              Miscellaneous Information Manual              WICKED(7)
2
3
4

NAME

6       wicked - network management service
7

SYNOPSIS

9       #include <wicked/wicked.h>
10

DESCRIPTION

12       Wicked  provides  a  new, experimental framework for network configura‐
13       tion.
14
15       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

NOTE

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

DBus Services

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
35       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
43       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
49       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

File format

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
72       Currently, the wicked client supports  the  original  sysconfig  ifcfg-
73       file format and converts the data found to it's native xml format.
74
75   Simple Ethernet Example (ifcfg-eth0)
76       STARTMODE="onboot" BOOTPROTO="dhcp4"
77
78   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
83        <interface>
84          <name>eth0</name>
85          <control>
86           <mode>boot</mode>
87          </control>
88
89          <ipv4:dhcp>
90            <enabled>true</enabled>
91          </ipv4:dhcp>
92        </interface>
93
94       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
98       For further information on the file syntax, refer to wicked-config(5).
99

Mode of Operation

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
108       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
113       *      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
119       *      Pass the policies for the specified interfaces to wickedd-nanny
120
121       With these steps performed, wickedd-nanny will work its way through all
122              layers of network configuration to activate the devices.
123
124       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
129       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
134       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
139       Firewall
140              This step will bring up the firewall.
141
142       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
150              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
156              As we've reached the desired state for the eth0 device with this
157              step, no further action is taken.
158
159       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
166              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

SEE ALSO

173       wickedd(8), wicked(8), wicked(7), wicked-config(5).
174
176       Copyright (C) 2014 SUSE LINUX Products GmbH, Nuernberg, Germany.
177

BUGS

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

AUTHORS

182       Olaf Kirch
183
184
185
186                                 16 July 2012                        WICKED(7)
Impressum