wicked-config - Man Page

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 wicked network 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 enable debugging across all wicked components, for instance.

Different components of wicked will load different files on startup; for instance, the wickedd server process will try to load server.xml. If that file does not exist, it will fall back to common.xml and try to read that directly.

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 configuration file. When parsing a configuration file, wicked will traverse the XML hierarchy once, in the order in which elements occur in the file. The file referenced by an <include> element is loaded and parsed at the time the <include> element is encountered.

Note that the contents of the file will not be "included" in the way you would expect this from e.g. a macro preprocessor. Instead, the referenced file must be a proper XML document, and its top node must also be 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 this directory. The optional mode attribute can be used to specify the permissions of this directory.

The default is to use /run/wicked, mode 0755.

  <statedir path="/run/wicked" mode="0755" />
statedir

This element specifies the location of the directory containing various files relating to the state of the server. For instance, temporary files are stored here when starting external programs like pppd(8).

The path attribute of this element contains the path to this directory. The optional mode attribute can be used to specify the permissions of this directory.

The default is to use /run/wicked, mode 0755.

  <statedir path="/run/wicked" mode="0755" />
storedir

This element specifies the location of the directory containing various (reboot) persistent data. For instance, the DHCP DUID and lease files are is stored in this directory.

The path attribute of this element contains the path to this directory. The optional mode attribute can be used to specify the permissions of this directory.

The default is to use /var/lib/wicked, mode 0755.

  <statedir path="/var/lib/wicked" mode="0755" />

Nanny enablement

use-nanny

This element controls whether the client will try to apply configuration changes immediately (one shot ifup), or whether it will forward the configuration to nanny.

When applying an interface configuration immediately to wickedd, it may fail 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 be applied to nanny, which will apply it to wickedd when certain conditions are met such as when the device appears (interface hotplugging) or continue with IP setup, when the link detection was successful for a device. 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 to true, 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, including set names such as all and most and names with a "-" prepended for 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_DEBUG environment variable, the setting from the XML configuration file will be ignored.

DBus service parameters

All configuration options related to the DBus service are grouped below the <dbus> element. Currently, the following child elements are recognized:

service

This element specifies the DBus service name used, and must be a valid DBus 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 their arguments. 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="org.opensuse.Network" />
    <schema name="/usr/share/wicked/schema/wicked.xml" />
  </dbus>

Client Only Options

sources

This specifies a list of sources that the wicked client will pick up interface configurations from, and their load order. Child elements of <sources> must be called ifconfig, and are expected to specify a location attribute.

The location attribute takes the form type:string, where string 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 a directory where to look for XML interface configurations. If no directory is given, the path defaults to /etc/wicked/ifconfig. When specifying either compat, you can optionally specify the ifcfg flavor, which can be either suse or redhat. If no flavor is specified, the result is implementation dependent - but usually, it will pick the platform default it was compiled on.

The default configuration is this:

  <sources>
    <ifconfig location="firmware:" />
    <ifconfig location="compat:" />
    <ifconfig location="wicked:" />
  </sources>

Address Configuration Options

The <addrconf> element is evaluated by server applications only, and controls the behavior of dynamic address configuration protocols such as DHCP. This options to blacklist e.g. certain DHCP servers, and which information provided by address configuration to apply.

default-allow-update

Most dynamic address configuration protocols, including DHCP, do not just provide a 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, directory information (for e.g. NIS), etc. A system receiving that information is free to reconfigure some of its services based on this information. For instance, it makes a lot of sense to configure the resolver library to use the DNS servers specified by a DHCP server. On the other hand, you may want to ignore any NIS information received via DHCP.

The <default-allow-update> is applied to static and intrinsic leases, which do not have an own, type and address family specific <allow-update> element as available under the <dhcp6>, <dhcp4>, <auto6> and <auto4> sub-elements, which support a sub-set of the possible facilities listed here. The <default-allow-update> and the type specific <allow-update> elements enable you to control which system services wicked will (request and) consider to update in the system.

It contains a list of either empty XML elements e.g. (<dns/><ntp/>) naming system the facilities or alternatively, a space separated string list (dns ntp) with the facility names. The special elements default, none and all enable and disable the default, none and all updates, respectively. A no- or a - in the front of a facility name permits to remove/disable a facility from the currently applied set and enable further supported facilities, e.g. default,-nis,slp is applying a modified default set with disabled nis and the optional slp facility enabled additionally.

The following updater facilities are currently defined:

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 settings (no netconfig module implemented)
ndsNDS servers (no netconfig module implemented)
slpSLP client (no netconfig module implemented)
sipSIP client (no netconfig module implemented)
logsyslog servers (no netconfig module implemented)
lprprint servers (no netconfig module implemented)
tzposix time zone (no netconfig module implemented)
mtuadjust interface mtu (dhcp4)
bootroot-path (dhcp4)/boot-url (dhcp6) used in the initrd

Note that administrators wishing to support currently unimplemented updaters 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 DHCP4 supplicant. See below for a list of options.

dhcp6

This element can be used to control the behavior of the DHCP6 supplicant. See below for a list of options.

auto6

This element can be used to control the behavior of AUTO6 processing.

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="eth0" >
        ...
      </device>
    </dhcp4>
  </addrconf>
create-cid

Specifies the standard client-id type to use:

TypeAliasDescription
rfc4361dhcp6use 0xff as type, followed by DHCPv6 IAID and DUID
rfc2132hwaddruse hardware/link layer type, followed by the address
disablenonedisables creation (custom client-id is send if given)

When the interface configuration does not provide an explicit client-id (DHCLIENT_CLIENT_ID in ifcfg files or <client-id> xml config/policy node), wicked will generate a DHCPv4 client-id as specified in this option.

When set to rfc4361, wicked will create a DHCPv4 client-id using the DHCPv6 IAID and DUID (see <dhcp6><default-duid> option). This new rfc4361 client-id is required to perform DDNS updates for ipv4 (A) and ipv6 (AAAA) address records in the same DNS zone (domain) and mandatory to use on infiniband interfaces.

When set to rfc2132, wicked will create a DHCPv4 client-id using the network interface hardware-type and address. This may be needed to maintain compatibility to e.g. DHCPv4 servers with static leases explicitly bound to a rfc2132 client-id or having trouble to provide a lease to a dhcp4 client using the new and longer rfc4361 client-id.

When set to disable, no client-id is created and send by default (except when the interface config request to acquire a lease contains a custom/explicit one).

When unspecified, the default behavior depends on the --enable-dhcp4-rfc4361-cid (default) and --disable-dhcp4-rfc4361-cid configure options, allowing to revert to use the old rfc2132 client-id at compile time, i.e. to prereserve behavior like in older releases, but permit to change to enable the new rfc4361 client-id default at runtime.

Note, that a change of the client-id usually causes to disassociate the lease and/or DNS records, because it is used in the DHCID DNS record (see rfc4701).

vendor-class

Specifies the string to be used as the vendor-class option in the DHCP request. By default, no vendor-class option is sent.

lease-time

Specifies the lease time to request in the DHCP request, in seconds. This also caps the lease time that can be requested in an interface configuration; any lease-time specified there will be silently limited to what was specified in the global configuration file. The following will set the default lease time to one hour:

 <lease-time>3600</lease-time>

ignore-server

Using the ip attribute of this element, you can specify the IP or HW address (currently ethernet devices only) of a faulty DHCP server that should be ignored:

 <ignore-server ip="192.168.8.1" />  <ignore-server mac="52:54:00:02:c2:67" />

prefer-server

Specify a preferred DHCP server, together with a numeric value indicating its preference. Again, the address of the server is specified using the ip 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 from a server with a weight of 100 is received, it will be selected immediately. Otherwise, the supplicant will wait for about one second, and select the server with the highest preference afterwards.

The special keywords never and always correspond to -1 and 100, respectively. If no weight attribute is given, it defaults to always (100).

The following example will ignore 192.168.8.1, always use the information from 192.168.8.10 if available, and fall back to 192.168.8.7 if not:

  <prefer-server ip="192.168.8.1"  weight="never" />
  <prefer-server mac="02:03:04:05:06:07" weight="always" />
  <prefer-server ip="192.168.8.7"  weight="50" />
allow-update

Specify the list of system services that wicked will configure based on the DHCP lease received. For the syntax of this element, please refer to the description of default-allow-update above. dhcp4 supports all update facilities.

route-options

Specify a space separated list of routing options to request from dhcp4 server.

NameAliasDescription
classlesscsrRFC 3442 classless static route option 121
ms-classlessmscsrMS classless static route option code 249 (pre RFC 3442)
static-routesclassObsolete option 33 requesting static class routes

The RFC 3442 classless static route option provides all routes with a netmask, includes the default routers and has priority over other routing options. By default, wicked requests classless (121) as well as class static routes (33) and the default routers option (3) (when enabled in allow-update) to be compatible to old servers or servers not configured to provide classless, but only a default router option.

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 option code range 224 to 254, see RFC3942 (section 4), RFC 2939 and www.iana.org/assignments/bootp-dhcp-parameters to avoid conflicts with options that are or may be defined and implemented later.

To request support for a specific standard option, issue a feature request at 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="eth0" >
        ...
      </device>
    </dhcp6>
  </addrconf>
default-duid

DHCPv6 uses a so-called DUID to identify a DHCP client and an IAID, that refers to an interface.
DHCPv4 now also defaults to construct its client-id using the DHCPv6 IAID and DUID as well (see <dhcp4><create-cid> option).
By default, wickedd-dhcp6 will try to generate a DUID based on the link layer address (MAC) of the device and time (DUID-LLT).

The default-duid element permits to override this behavior and either specify an explicit DUID as a string of colon separated hex octets, e.g.:

      <default-duid>00:03:00:01:02:00:00:00:00:02</default-duid>

or an advise which duid type to construct or import expressed in a child element:

      <default-duid><duid type element/></default-duid>

using one of the following duid type elements:

llt, DUID type 1, Link-layer address plus time:

Permits to specify the link/hardware type and address in its hardware and address elements, e.g.:

        <llt>
          <hardware>ethernet</hardware><address>02:00:00:00:00:02</address>
        </llt>

Without arguments, wicked will create the duid-llt using the hardware type and address of the actual device that requests a duid first. The time inside of the DUID is set automatically to the duid creation time.

en, DUID type 2, Vendor Based on IANA Enterprise Number:

Permits to specify a vendor type DUID-EN based on the IANA assigned enterprise number and an machine identifier specified in the enterprise-number and identifier elements, e.g. using IANA number 7057 assigned to SUSE:

        <en>
          <enterprise-number>7057</enterprise-number>
          <identifier>02:00:00:00:00:02</identifier>
        </en>
ll, DUID type 3, Link-layer address (without time):

Usage is as for type 1 duid llt, the duid does not contain a time.

uuid, DUID type 4, UUID-Based Unique Identifier:

Permits to specify the effective UUID to use, e.g.:

        <uuid>80d732e7-b8dc-45ef-bdae-f9f5e6925cef</uuid>

or import it from /etc/machine-id file:

        <uuid><machine-id/></uuid>
or using an explicit path to the machine-id file:
        <uuid><machine-id>/etc/machine-id</machine-id></uuid>

or the DMI product id (problematic, may be not available or not unique):

        <uuid><dmi-product-id/></uuid>

Without arguments, wicked will try to import the machine-id with a fallback to the DMI product id when no machine-id file exists.

Additionally, the default-duid element supports a per-device attribute. When enabled via <default-duid per-device="true"/>, wicked changes to a non-standard behavior and maintains a separate duid for each device instead of the same ("default") DUID for all interfaces and a per device/interface IAID.

This permits to workaround some special cases, where the hosts should appear to the server using multiple identities, that is to behave as multiple machines instead as one with multiple interfaces.

The wickedd daemons store the generated DUIDs in /run/wicked/duid.xml file. The wicked duid utility command permits to review and modify the duid as needed.

Note: When you change the DUID, make sure to restart the wickedd service.

lease-time

Specifies the lease time to request in the DHCP request, in seconds. This also caps the lease time that can be requested in an interface configuration; any lease-time specified there will be silently limited to what was specified in the global configuration file. The following will set the default lease time to one hour:

 <lease-time>3600</lease-time>

release-retransmits

Specifies the number of lease release retransmissions in the range 1..5. Default is to send up to 5 (REL_MAX_RC) retransmissions.

info-refresh-time

Specifies a different default for the RFC4242 info refresh time used when the dhcp6 server does not provide any and permits also to adjust the acceptable time range in the min and max attributes, e.g.:

 <info-refresh-time min= 600" max="604800">86400</info-refresh-time>

prefer-server

Specify a preferred DHCP server, together with a numeric value indicating its preference. The server is identified using its DUID, which has to be specified via the id attribute.

The numeric preference value is given by the weight, and should range from -1 to 255. Higher numbers indicate a higher preference. A negative value will cause the server to be ignored. If a response from a server with a weight of 255 is received, it will be selected immediately. Otherwise, the supplicant will wait for about one second, and select the server providing an offer with the best request match and the highest preference afterwards.

The special keywords never and always correspond to -1 and 255, respectively. If no weight attribute is given, it defaults to always (255).

The following example will ignore DHCP offers from the first server, always use the information from the second (if available), and fall back to the third if not:

  <prefer-server id="00:03:00:01:02:03:04:05:06:07" weight="never" />
  <prefer-server ip="2001:DB8::1" weight="always" />
  <prefer-server ip="2001:DB8::2" weight="50" />
allow-update

Specify the list of system services that wicked will configure based on the DHCP lease received. For the syntax of this element, please refer to the description of default-allow-update above. DHCPv6 allows the following update facilities:

NameDescription
hostnamesystem hostname (fqdn)
dnsupdate resolv.conf or dns server (via netconfig)
ntpNTP servers (via netconfig)
sipSIP client (optional, no netconfig module implemented)
nisNIS client (optional, no netconfig module, not supported by ypbind)
tzposix time zone (no netconfig module implemented)
bootboot-url used in the initrd

Note: DHCPv6 protocol does not provide any options to request routing settings, which are applied via a router advertisement (IPv6 RA).

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 request at 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 applied by 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 and a format how to interpret raw data of the dhcp option. This option definition is used to parse and format lease-xml files, (format) leaseinfo dump files and the name 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..63 alphanumeric and "-" characters (same to a hostname without any dots).

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

opaque [fixed-length="<length in bytes>" | embedded-length="1|2|uint8|uint16"]

Opaque data or not printable string formatted as a hex-string (xx:xx:xx) with variable length. The fixed-length attribute permits adjust it to a \0 padded fixed-length data field and the embedded-length attribute to interpret the initial 1 (uint8) or 2 (uint16) bytes as data length (RFC7227).

string [fixed-length="<length in bytes>" | embedded-length="1|2|uint8|uint16"]

A printable variable-length string (without a \0 null-termination). The fixed-length attribute permits to adjust it to a \0 padded fixed-length string and the embedded-length attribute to interpret the initial 1 (uint8) or 2 (uint16) bytes as the string length (RFC7227).

bool

A single byte value interpreted as boolean (0 is "false", otherwise "true").

int8 | int16 | int32 | int64 uint8 | uint16 | uint32 | uint64 [notation="hex"]

A signed or unsigned integer 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 encoded prefix-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 name and a member type, struct or array. The last member in a struct is 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 type node (<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 "wicked test" 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 and restarting wickedd ("rcwickedd restart") 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 communicate with 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 or sysfs 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 through external commands and shell scripts. All of these extensions are declared in server.xml, and all of them follow the same pattern.

Script extensions

Scripts are specified via the <script> element, which needs to provide a name attribute and a command attribute. Again, the name serves as an identifier, while the command specifies the command to be invoked. wicked comes with a (simple) parser for this, which splits up this command into a argument array which is passed to execve(2) eventually.

An example would look like this:

  <script name="install"
          command="/etc/wicked/extensions/hostname install"/>

When defining script extensions, it is possible to define additional environment variables that get passed to the script. This mechanism is explained in more detail below.

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

System updaters

These specify extensions for managing files like resolv.conf, or the system hostname, based on information contained through an address configuration protocol like DHCP. The configuration element must have a name attribute that specifies the system service to configure, and include extensions for backing up the current configuration, 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="backup" command="/etc/wicked/extensions/hostname backup"/>
    <script name="restore" command="/etc/wicked/extensions/hostname restore"/>
    <script name="install" command="/etc/wicked/extensions/hostname install"/>
    <script name="install" command="/etc/wicked/extensions/hostname remove"/>
  </system-updater>

Currently, wicked supports generic and hostname system updaters. The generic updater operates on data which can be set via netconfig (refer to 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 for a 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 such configuration 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 scripts in turn and parse their output. Scripts are expected to return XML documents that contain zero or more <interface> elements describing the configuration.

This extension class supports shell scripts only.

See Also

wickedd(8), netconfig(8), RFC3942

Bugs

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

Authors

Olaf Kirch

Referenced By

wicked(7), wicked(8), wickedd(8).

16 July 2012