SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from OpenSuSE wicked-0.6.40-9.1.x86_64.rpm

WICKED-CONFIG

Section: File Formats (5)
Updated: 16 July 2012
Index 

NAME

wicked-config.xml - wicked configuration file 

SYNOPSIS

/etc/wicked/common.xml
/etc/wicked/server.xml
/etc/wicked/client.xml
/etc/wicked/nanny.xml
 

DESCRIPTION

These files contain the global configuration options for the wickednetwork management service. All files follow the same XML schema.

common.xml contains common definitions that should be used by all applications.It is sourced by the other configuration files. It can be used to enabledebugging across all wicked components, for instance.

Different components of wicked will load different files on startup; forinstance, the wickedd server process will try to load server.xml. Ifthat file does not exist, it will fall back to common.xml and try to read thatdirectly.

The following table shows which wicked commands use which configuration file:

ApplicationFilename


wickedclient.xml
wickeddserver.xml
wickedd-nannynanny.xml
wickedd-auto4auto4.xml
wickedd-dhcp4dhcp4.xml
wickedd-dhcp6dhcp6.xml

 

GENERAL OPTIONS

The configuration file is an XML document; its root node must be called<config>.

include
This element can be used to refer to an additional XML configurationfile. When parsing a configuration file, wicked will traverse theXML hierarchy once, in the order in which elements occur in the file.The file referenced by an <include> element is loaded and parsedat the time the <include> element is encountered.
Note that the contents of the file will not be dqincludeddq in theway you would expect this from e.g. a macro preprocessor. Instead, thereferenced file must be a proper XML document, and its top node must alsobe a config element.
 

Common pathnames

piddir
This element specifies the directory used to write pid files.
The path attribute of this element contains the path to thisdirectory. The optional mode attribute can be used to specifythe permissions of this directory.
The default is to use /run/wicked, mode 0755.
  <statedir path=dq/run/wickeddq mode=dq0755dq />

statedir
This element specifies the location of the directory containing variousfiles relating to the state of the server. For instance, temporary filesare stored here when starting external programs like pppd(8).
The path attribute of this element contains the path to thisdirectory. The optional mode attribute can be used to specifythe permissions of this directory.
The default is to use /run/wicked, mode 0755.
  <statedir path=dq/run/wickeddq mode=dq0755dq />

storedir
This element specifies the location of the directory containing various(reboot) persistent data. For instance, the DHCP DUID and lease filesare is stored in this directory.
The path attribute of this element contains the path to thisdirectory. The optional mode attribute can be used to specifythe permissions of this directory.
The default is to use /var/lib/wicked, mode 0755.
  <statedir path=dq/var/lib/wickeddq mode=dq0755dq />

 

Nanny enablement

use-nanny
This element controls whether the client will try to apply configurationchanges immediately (one shot ifup), or whether it will forward theconfiguration to nanny.
When applying an interface configuration immediately to wickedd, it mayfail or not complete in the specified time for a variety of transient reasons,such as an Ethernet cable not being plugged in.
When managing an interface through nanny, the configuration will beapplied to nanny, which will apply it to wickedd when certainconditions are met such as when the device appears (interface hotplugging)or continue with IP setup, when the link detection was successful for adevice.Nanny will also reapply the configurations to wickedd after restart(e.g. update) and trigger lease confirmations.
The <use-nanny> element controls the default behavior. When set totrue, wicked will manage all interfaces through nanny.If set to false, all interface changes will be applied directly.The default value is false.
To enable nanny at installation time, use the nanny=1 installer(linuxrc) boot parameter.
 

Miscellaneous

debug
This element specifies the default debug facilities to be enabled.Allowed is a comma separated list of supported facility names, includingset names such as all and most and names with a "-" prependedfor negated facilities, e.g. "all,-xpath".

The 'wicked --debug help' command shows valid facility names.If a debug level is specified on the command line or via the WICKED_DEBUGenvironment variable, the setting from the XML configuration file will beignored.

 

DBus service parameters

All configuration options related to the DBus service are grouped belowthe <dbus> element. Currently, the following child elements arerecognized:
service
This element specifies the DBus service name used, and must be a validDBus API name.The default is "org.opensuse.Network".
schema
This element specifies the location of the schema files.The schema defines the various DBus APIs offered by the server,and how portions of an interface XML description map to theirarguments. The schema files do not contain user-serviceable parts,so it's best to leave this option untouched.

Here's what the default configuration looks like:

  <dbus>    <service name=dqorg.opensuse.Networkdq />    <schema name=dq/usr/share/wicked/schema/wicked.xmldq />  </dbus>
 

CLIENT ONLY OPTIONS

sources
This specifies a list of sources that the wicked client will pickup interface configurations from, and their load order. Child elementsof <sources> must be called ifconfig, and are expected tospecify a location attribute.
The location attribute takes the form type:string, wherestring may be empty.
TypeDescription


firmwareGet configuration from firmware, usually iBFT
compatLoad interface description using legacy ifcfg files
wickedLoad interface description using native wicked XML

The firmware type takes no additional string parameter.When specifying either wicked, you can optionally specify adirectory where to look for XML interface configurations. If nodirectory is given, the path defaults to /etc/wicked/ifconfig.When specifying either compat, you can optionally specify theifcfg flavor, which can be either suse or redhat. If noflavor is specified, the result is implementation dependent - butusually, it will pick the platform default it was compiled on.
The default configuration is this:
  <sources>    <ifconfig location=dqfirmware:dq />    <ifconfig location=dqcompat:dq />    <ifconfig location=dqwicked:dq />  </sources>
 

ADDRESS CONFIGURATION OPTIONS

The <addrconf> element is evaluated by server applications only, andcontrols the behavior of dynamic address configuration protocols suchas DHCP. This options to blacklist e.g. certain DHCP servers, and whichinformation provided by address configuration to apply.
default-allow-update
Most dynamic address configuration protocols, including DHCP, do not just providea list of addresses and routes to install for the managed network interface,but can be used to provide information such as a list of DNS servers, directoryinformation (for e.g. NIS), etc. A system receiving that information is freeto reconfigure some of its services based on this information.For instance, it makes a lot of sense to configure the resolver libraryto use the DNS servers specified by a DHCP server. On the other hand,for security reasons you may want to ignore any NIS information receivedvia DHCP.
The <default-allow-update> element allows you to control whichsystem services wicked will consider to update. It contains a listof empty XML elements naming system facilities to update. The specialelements <all> and <none> enable and disable any and allupdates, respectively. Other valid updaters are:
NameDescription


default-routesystem default route (IPv4 or IPv6)
hostnamesystem hostname
dnsupdate resolv.conf or dns server (via netconfig)
nisNIS client (via netconfig)
ntpNTP servers (via netconfig)
smbSMB client (not implemented)
slpSLP client (not implemented)
logsyslog servers (not implemented)

Note that administrators wishing to support currently unimplementedupdaters can do so by configuring external updaters using the<system-updater> extensions described below.
dhcp4
This element can be used to control the behavior of the DHCP4supplicant. See below for a list of options.
dhcp6
This element can be used to control the behavior of the DHCP6supplicant. See below for a list of options.
 

DHCP4 SUPPLICANT OPTIONS

The DHCP4 client can be configured through the options listed below.All of them must be nested in the config node like this:

  <addrconf>    <dhcp4>      ...    </dhcp4>  </addrconf>

or inside a device name context like:

  <addrconf>    <dhcp4>      <device name=dqeth0dq >        ...      </device>    </dhcp4>  </addrconf>

vendor-class
Specifies the string to be used as the vendor-class option in the DHCPrequest. By default, no vendor-class option is sent.
lease-time
Specifies the lease time to request in the DHCP request, in seconds. This alsocaps the lease time that can be requested in an interface configuration;any lease-time specified there will be silently limited to what wasspecified in the global configuration file. The following will set the defaultlease time to one hour:
<lease-time>3600</lease-time>

ignore-server
Using the ip attribute of this element, you can specify theIP or HW address (currently ethernet devices only) of a faulty DHCPserver that should be ignored:
<ignore-server ip=dq192.168.8.1dq /> <ignore-server mac=dq52:54:00:02:c2:67dq />
prefer-server
Specify a preferred DHCP server, together with a numeric value indicating itspreference. Again, the address of the server is specified using theip or mac attribute.
The numeric preference value is given by the weight,and should range from -1 to 100. Higher numbers indicate a higher preference.A negative value will cause the server to be ignored. If a response froma server with a weight of 100 is received, it will be selected immediately.Otherwise, the supplicant will wait for about one minute, and select theserver with the highest preference afterwards.
The special keywords never and always correspond to -1 and100, respectively. If no weight attribute is given, it defaults toalways (100).
The following example will ignore 192.168.8.1, always use the information from192.168.8.10 if available, and fall back to 192.168.8.7 if not:
  <prefer-server ip=dq192.168.8.1dq  weight=dqneverdq />  <prefer-server ip=dq192.168.8.10dq weight=dq100dq />  <prefer-server ip=dq192.168.8.7dq  weight=dq50dq />
allow-update
Specify the list of system services that wicked will configure basedon the DHCP lease received. For the syntax of this element, please referto the description of default-allow-update above.

define
Permits to define list of custom dhcp options not covered by wicked yet.The dhcp4 option codes are 8-bit (1..254) bytes.

For non-standard options, it is recommended is to use the DHCPv4 private optioncode range 224 to 254, see RFC3942 (section 4), RFC 2939 andwww.iana.org/assignments/bootp-dhcp-parameters to avoid conflicts withoptions that are or may be defined and implemented later.

To request support for a specific standard option, issue a feature requestat https://fate.suse.com/ or https://features.opensuse.org/ (hermes).See CUSTOM DHCP OPTIONS section for more details.

 

DHCP6 SUPPLICANT OPTIONS

The DHCP6 client can be configured through the options listed below.All of them must be nested in the config node like this:

  <addrconf>    <dhcp6>      ...    </dhcp6>  </addrconf>

or inside a device name context like:

  <addrconf>    <dhcp6>      <device name=dqeth0dq >        ...      </device>    </dhcp6>  </addrconf>

default-duid
DHCPv6 uses a so-called DUID to identify a DHCP client (rather than theMAC address used by DHCPv4). By default, wickedd-dhcp6 will try togenerate a DUID based on the link layer address of the device. Using the<default-duid> element, you can override this behavior and specifya global, unique DUID that will be used across all interfaces. The DUIDnotation is a string of hex octets, separated by colons - pretty similarto the standard notiation Ethernet address.
Note that wickedd-dhcp6 stores the generated DUIDs in/run/wicked/duid.xml. If you change the default DUID, you shouldmake sure to delete that file before restarting the DHCPv6 supplicant.

lease-time
Specifies the lease time to request in the DHCP request, in seconds. This alsocaps the lease time that can be requested in an interface configuration;any lease-time specified there will be silently limited to what wasspecified in the global configuration file. The following will set the defaultlease time to one hour:
<lease-time>3600</lease-time>

ignore-server
Using the ip attribute of this element, you can specify theIP address of a faulty DHCP server that should be ignored:
prefer-server
Specify a preferred DHCP server, together with a numeric value indicating itspreference. The server is identified using its DUID, which has to be specifiedvia the id attribute.
The numeric preference value is given by the weight,and should range from -1 to 100.Higher numbers indicate a higher preference.A negative value will cause the server to be ignored. If a response froma server with a weight of 100 is received, it will be selected immediately.Otherwise, the supplicant will wait for about one minute, and select theserver with the highest preference afterwards.
The special keywords never and always correspond to -1 and100, respectively. If no weight attribute is given, it defaults toalways (100).
The following example will ignore DHCP offers from the first server,always use the information from the second (if available), and fall backto the third if not:
  <prefer-server id=dq00:44:01:02:04:00dq weight=dqneverdq />  <prefer-server id=dq00:44:01:02:04:01dq weight=dq100dq />  <prefer-server id=dq00:44:01:02:04:02dq weight=dq50dq />
allow-update
Specify the list of system services that wicked will configure basedon the DHCP lease received. For the syntax of this element, please referto the description of default-allow-update above.

define
Permits to define list of custom dhcp options not covered by wicked yet.The dhcp6 option codes are 16-bit (1..65534) integers.

See http://www.iana.org/assignments/dhcpv6-parameters and RFC7227.

To request support for a specific standard option, issue a feature requestat https://fate.suse.com/ or https://features.opensuse.org/ (hermes).See CUSTOM DHCP OPTIONS section for more details.

Note:
The DHCPv6 protocol does not define any routing options, which are appliedby IPv6 Router Advertisement (RA) or require static configuration.The current NIS / ypbind implementation on linux does supported IPv6 at all.

 

CUSTOM DHCP OPTIONS

A custom option defines a name for a dhcp option code anda format how to interpret raw data of the dhcp option. This option definition isused to parse and format lease-xml files, (format) leaseinfo dump files and thename can be used to request options (oro alias option-request-option).

The name has to be a valid keyword and is restricted to a word of 1..63alphanumeric and dq-dq characters (same to a hostname without any dots).

The current implementation supports the following simple types (scalars):

opaque [fixed-length=dq<length in bytes>dq | embedded-length=dq1|2|uint8|uint16dq]
Opaque data or not printable string formatted as a hex-string (xx:xx:xx) withvariable length. The fixed-length attribute permits adjust it to a \0padded fixed-length data field and the embedded-length attribute tointerpret the initial 1 (uint8) or 2 (uint16) bytes as data length (RFC7227).
string [fixed-length=dq<length in bytes>dq | embedded-length=dq1|2|uint8|uint16dq]
A printable variable-length string (without a \0 null-termination).The fixed-length attribute permits to adjust it to a \0 paddedfixed-length string and the embedded-length attribute to interpretthe initial 1 (uint8) or 2 (uint16) bytes as the string length (RFC7227).
bool
A single byte value interpeted as boolean (0 is dqfalsedq, otherwise dqtruedq).
int8 | int16 | int32 | int64 uint8 | uint16 | uint32 | uint64 [notation=dqhexdq]
A signed or unsigned interger in decimal or optionally, in a 0x.. hex notation.
ipv4-address | ipv6-address
IPv4 and IPv6 address types
ipv4-prefix | ipv6-prefix
An RFC3442 / RFC7227 prefix (destination descriptor) with compact encodedprefix-length byte followed by the significant octets of the network address.

These simple types can be combined together in structs and arrays.

A structs consists of one or more members, which contain a nameand a member type, struct or array. The last member in a structis allowed to contain be variable length type.An array contains an element name and fixed-length type or struct.

A simple type can be specified in the node name (<string/>) or in the data of the typenode (<type>string</type>).

Examples:

  <!--       global or device specific definitions of dhcp4/dhcp6 options       under <config><addrconf><dhcp4> or <config><addrconf><dhcp6>  -->  <define>    <option>      <code>224</code>      <name>foo-server</name>      <type>ipv4-address</type>    </option>    <option>      <code>225</code>      <name>foo-path</name>      <string/>    </option>    <option>      <code>250</code>      <name>test-cls-routes</name> <!-- RFC3442 classless route format -->      <array>        <name>route</name>        <struct>          <member>            <name>destination</name>            <ipv4-prefix/>          </member>          <member>            <name>gateway</name>            <ipv4-address/>          </member>        </struct>      </array>    </option>    <option>      <code>251</code>      <name>six-addresses</code>      <array>        <name>ip</name>        <ipv6-address/>      </array>    </option>  </define>

To test the option definition, the dqwicked testdq call can be used:

 wicked test dhcp4 --request - eth1 <<EOF  <request type=offer>    <request-options>      <option>224</option>      <option>test-cls-routes</option>    </request-options>  </request> EOF
before adding the option requests to the ifcfg or xml configuration andrestarting wickedd (dqrcwickedd restartdq) to apply to the supplicant.

 

SERVER ONLY OPTIONS

teamd
The <teamd> element permits to enable or disable teamd support(inclusive discovery of team device details) in its <enable>sub-element. Disabled by default, server.xml config enables it.Further, it permits to specify the control interface to communicatewith teamd in the <ctl> sub-element, using the following options:
OptionDescription


detect-oncedetect the control interface to use, once (default)
detectdetect the control interface to use in each call
dbuscommunicate directly with teamd via dbus
unixuse unix socket control interface via teamdctl tool

bonding
The <bonding> element permits to specify whether to use netlink orsysfs to configure the bonding in its <ctl> sub-element:
OptionDescription


netlinkconfigure bonding via netlink (default)
sysfsconfigure bonding via sysfs (the old way)

 

EXTENSIONS

The functionality of wickedd can be extended throughexternal commands and shell scripts. All of these extensionsare declared in server.xml, and all of them follow the same pattern.

Script extensions
Scripts are specified via the <script> element, which needs to providea name attribute and a command attribute. Again, the name servesas an identifier, while the command specifies the command to be invoked.wicked comes with a (simple) parser for this, which splits up this commandinto a argument array which is passed to execve(2) eventually.
An example would look like this:
  <script name=dqinstalldq          command=dq/etc/wicked/extensions/hostname installdq/>
When defininig script extensions, it is possible to define additional environmentvariables that get passed to the script. This mechanism is explained in moredetail below.

Extensions are always grouped under a parent element. The following configurationelements can contain extensions: 

System updaters

These specify extensions for managing files like resolv.conf, or the systemhostname, based on information contained through an address configuration protocollike DHCP. The configuration element must have a name attribute that specifiesthe system service to configure, and include extensions for backing up the currentconfiguration, for installing new settings, and for restoring the backup.

The configuration for the hostname updater might look like this:

  <system-updater name=hostname>    <script name=dqbackupdq command=dq/etc/wicked/extensions/hostnane backupdq/>    <script name=dqrestoredq command=dq/etc/wicked/extensions/hostname restoredq/>    <script name=dqinstalldq command=dq/etc/wicked/extensions/hostname installdq/>    <script name=dqinstalldq command=dq/etc/wicked/extensions/hostname removedq/>  </system-updater>

Currently, wicked supports generic and hostname system updaters.The generic updater operates on data which can be set via netconfig (referto netconfig(7). The hostname updater sets the system hostname.

This extension class supports shell scripts only. 

Firmware discovery

Some platforms support iBFT or similar mechanisms to provide the configuration fora network device through the firmware (so that it's possible to boot off that device).In order to support these mechanisms, wicked supports extensions to discover suchconfiguration through firmware discovery extensions.

  <netif-firmware-discovery>    <script name=ibft command=/etc/wicked/extensions/ibft />  </netif-firmware-discovery>

When looking for firmware interface configuration, wicked will invoke all these scriptsin turn and parse their output. Scripts are expected to return XML documents that containzero or more <interface> elements describing the configuration.

This extension class supports shell scripts only.

 

SEE ALSO

wickedd(8),netconfig(8),RFC3942 

COPYRIGHT

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

BUGS

Please report bugs at <https://bugzilla.suse.com/> 

AUTHORS

Olaf Kirch


 

Index

NAME
SYNOPSIS
DESCRIPTION
GENERAL OPTIONS
Common pathnames
Nanny enablement
Miscellaneous
DBus service parameters
CLIENT ONLY OPTIONS
ADDRESS CONFIGURATION OPTIONS
DHCP4 SUPPLICANT OPTIONS
DHCP6 SUPPLICANT OPTIONS
CUSTOM DHCP OPTIONS
SERVER ONLY OPTIONS
EXTENSIONS
System updaters
Firmware discovery
SEE ALSO
COPYRIGHT
BUGS
AUTHORS

This document was created byman2html,using the manual pages.